From fec304948096dfc0d58136bab5bb86c2cee1b450 Mon Sep 17 00:00:00 2001 From: Evgenii Zheltonozhskii Date: Thu, 15 Aug 2024 11:40:31 +0300 Subject: [PATCH] Add `KERNEL_COMPILER` option description and fix some typos --- docs/Developer-Guide_Build-Options.md | 131 ++++++++++++++------------ 1 file changed, 70 insertions(+), 61 deletions(-) diff --git a/docs/Developer-Guide_Build-Options.md b/docs/Developer-Guide_Build-Options.md index 790b59c9..5ef6a7b4 100644 --- a/docs/Developer-Guide_Build-Options.md +++ b/docs/Developer-Guide_Build-Options.md @@ -2,7 +2,7 @@ ### kernel -Builds kernel and device tree (where applicable) and place it to the `output/debs` +Builds kernel and device tree (where applicable) and places it to the `output/debs` Usage: ```bash @@ -11,9 +11,9 @@ Usage: ### dts-check -Validate dts files and improve board & patch development overall +Validate dts files and improve board & patch development overall. -This option validates the dts/dtb file for the selected board against the device tree bindings, and outputs the validation logs to the user. It can be used when adding a new board, developing or improving a dts file. +This option validates the dts/dtb file for the selected board against the device tree bindings and outputs the validation logs to the user. It can be used when adding a new board, developing or improving a dts file. Usage: ```bash @@ -21,7 +21,7 @@ Usage: ``` ### inventory-boards -Outputs a one board per-line CSV inventory of boards. +Outputs a one-board-per-line CSV inventory of boards. Sets `TARGETS_FILE` to something that doesn't exist, so the `default-targets.yaml` is used (so same list for everyone, save for userpatched-boards) @@ -33,10 +33,10 @@ Outputs /info/boards-inventory.csv ### kernel-dtb -Builds only DTB, and output full preprocessed dts source +Builds only DTB and outputs full preprocessed dts source -Outputs preprocessed DTS source for board in question to `output/` -also outputs same preprocessed DTS source, ran through `dtc` with input and output DTS formats for "normalized" comparisions +Outputs preprocessed DTS source for the board in question to `output/` +also outputs the same preprocessed DTS source, ran through `dtc` with input and output DTS formats for "normalized" comparisons Usage: ```bash @@ -45,10 +45,10 @@ Usage: ### rewrite-uboot-patches -Prepares git, applies patches to git, and re-writes them back from git +Prepares git, applies patches to git, and rewrites them back from git same as kernel, it does git archeology for mbox-less patches, etc. -- uboot-patches-to-git alias is also added, but my guess is rewrite is more useful. +- uboot-patches-to-git alias is also added, but my guess is that the rewrite is more useful. - refactor a common config function for both kernel and uboot. Usage: @@ -58,9 +58,9 @@ Usage: ### targets -Generates output/info/git_sources.json file that will contain url, branch and commit hash combo. +Generates output/info/git_sources.json file containing URL, branch, and commit hash combo. -The easiest way to generate file for all devices is to run `./compile.sh targets`. Then at the time of release we will copy the output/info/git_sources.json file to config/sources/git_sources.json. Once the file is copied, the hash information from the file will be used to fetch resources for git repositories where branches are specified instead of tags or commits. +The easiest way to generate file for all devices is to run `./compile.sh targets`. Then, at the time of release, we will copy the output/info/git_sources.json file to config/sources/git_sources.json. Once the file is copied, the hash information from the file will be used to fetch resources for git repositories where branches are specified instead of tags or commits. Usage: ```bash @@ -78,14 +78,14 @@ These parameters are meant to be applied to the `./compile.sh` command. They are - systemd-networkd - none (to not-add any networking extensions) -Installs desired networking stack. If parameter is undefined, it sets `systemd-networkd` for minimal images (MINIMAL=yes) and `network-manager` for the rest. Time syncrhonisation is also changed, chrony is installed with network-manager, while systemd-timesyncd is used with systemd-networkd. In both cases we control network settings with **Netplan**. +Installs desired networking stack. If the parameter is undefined, it sets `systemd-networkd` for minimal images (MINIMAL=yes) and `network-manager` for the rest. Time synchronization is also changed; chrony is installed with network-manager, while systemd-timesyncd is used with systemd-networkd. In both cases, we control network settings using **Netplan**. - **DOCKER_ARMBIAN_BASE_IMAGE** ( string ) - **ubuntu:jammy** - ubuntu:noble - debian:bookworm -Defines build host when using Docker container (default). [Here](https://github.com/armbian/docker-armbian-build/pkgs/container/docker-armbian-build) you can see which other options are available. +Defines the build host when using a Docker container (default). [Here](https://github.com/armbian/docker-armbian-build/pkgs/container/docker-armbian-build), you can see which other options are available. - **CI** ( string ) - true @@ -98,24 +98,33 @@ If enabled (`true`), the Docker build container will receive Docker credentials - url/to/container_registry/path - **${GHCR_SOURCE}/armbian/*** (GHCR_SOURCE is defined in `lib/functions/configuration/main-config.sh`) -Select target for pull/push OCI cached images. If not set, default is used. +Select the target for pull/push OCI cached images. If not set, default is used. - **GHCR_MIRROR_ADDRESS** (string) -Default mirror address for ghcr.io, set by `GHCR_MIRROR=dockerproxy`, is ghcr.dockerproxy.com. When this address is not available, an alternative address can be set with `GHCR_MIRROR_ADDRESS`. +The default mirror address for ghcr.io, set by `GHCR_MIRROR=dockerproxy`, is ghcr.dockerproxy.com. When this address is unavailable, an alternative address can be set with `GHCR_MIRROR_ADDRESS`. Example: ``` ./compile.sh GHCR_MIRROR=dockerproxy GHCR_MIRROR_ADDRESS=ghcr.libcuda.so +``` + +- **KERNEL_COMPILER** (string) + +The compiler used to compile the kernel. Usually, this option is set by the board config, but it can be set to `clang` to use LLVM to compile the kernel. + +Example: +``` +./compile.sh KERNEL_COMPILER=clang ``` -# Build options below needs to be-retested and added above (COULD BE DEPRECATED) +# Build options below need to be retested and added above (COULD BE DEPRECATED) -:warning: DO NOT USE! Obsolete documentation, new documentation in progress.. +:warning: DO NOT USE! Obsolete documentation, new documentation in progress. -- **BUILD_ONLY** (comma-separated list): defines what artifacts should be built. Default value is empty string - will build all artifacts. Changing this option can be useful to build partial artifacts only. +- **BUILD_ONLY** (comma-separated list): defines what artifacts should be built. The default value is an empty string - it will build all artifacts. Changing this option can be useful to build partial artifacts only. - u-boot: build U-Boot - - kernel: build Kernel + - kernel: build kernel - armbian-config: build Armbian config - armbian-zsh: build Armbian zsh - plymouth-theme-armbian: build Armbian Plymouth theme @@ -128,29 +137,29 @@ Example: - prebuilt: use precompiled packages (only for maintained hardware) - yes: automatically call kernel's `make menuconfig` (add or remove modules or features) - no: use provided kernel configuration provided by Armbian - - leave empty to display selection dialog each time + - leave empty to display the selection dialog each time - **CLEAN_LEVEL** (comma-separated list): defines what should be cleaned. Default value is `"make,debs"` - clean sources and remove all packages. Changing this option can be useful when rebuilding images or building more than one image - make-atf = make clean for ATF, if it is built. - make-uboot = make clean for uboot, if it is built. - - make-kernel = make clean for kernel, if it is built. very slow.
- *important*: "make" by itself has disabled, since Armbian knows how to handle Make timestamping now. + - make-kernel = make clean for the kernel if it is built. very slow.
+ *important*: "make" by itself has been disabled since Armbian now knows how to handle Make timestamping. - debs, alldebs = delete all packages in "./output/debs" - images = delete "./output/images" - cache = delete "./output/cache" - sources: delete `cache/sources` (all downloaded sources) - oldcache = remove old cached rootfs except for the newest 8 files - - extras: delete additional packages for current release in `output/debs/extra` -- **REPOSITORY_INSTALL** (comma-separated list): list of core packages which will be installed from repository + - extras: delete additional packages for the current release in `output/debs/extra` +- **REPOSITORY_INSTALL** (comma-separated list): list of core packages that will be installed from the repository - Available options: `u-boot`, `kernel`, `bsp`, `armbian-bsp-cli`,`armbian-bsp-desktop`,`armbian-desktop`,`armbian-config`, `armbian-firmware` - Set to "" to use packages one from local output or build if not available - **KERNEL\_KEEP\_CONFIG** ( yes | no ): - - yes: use kernel config file from previous compilation for the same branch, device family and version + - yes: use kernel config file from previous compilation for the same branch, device family, and version - no: use default or user-provided config file - **BUILD_MINIMAL** ( yes | no ): - - yes: build bare CLI image suitable for application deployment. This option is **not compatible** with `BUILD_DESKTOP="yes"` and `BUILD_EXTERNAL="yes"` + - yes: build a bare CLI image suitable for application deployment. This option is **not compatible** with `BUILD_DESKTOP="yes"` and `BUILD_EXTERNAL="yes"` - no: default CLI package selection - **BUILD_DESKTOP** ( yes | no ): - - yes: build image with minimal desktop environment + - yes: build an image with a minimal desktop environment - no: build image with console interface only - **EXTERNAL** ( yes | no ): - yes: compile and install extra applications and firmware @@ -159,10 +168,10 @@ Example: - **INSTALL_HEADERS** ( **no** | yes ): - yes: install kernel headers - **EXTERNAL_NEW** ( no | prebuilt | compile ): - - prebuilt: install extra applications from repository + - prebuilt: install extra applications from the repository - compile: compile extra applications in chroot - **CREATE_PATCHES** ( yes | **no** ) :warning: **Warning:** This option is deprecated and may be removed in future releases - use the new `kernel-patch` / `uboot-patch` / `atf-patch` CLI commands instead. - - yes: prompt right before the compilation starts to make changes to the source code for both U-Boot and kernel. From these changes patch files will be created and placed in `output` directory. If you want these patches included in a normal run (without CREATE_PATCHES to say) these files need to be copied to the appropriate directories. Also see [user provided patches](https://docs.armbian.com/Developer-Guide_User-Configurations/#user-provided-patches). + - yes: prompt right before the compilation starts to make changes to the source code for both U-Boot and kernel. From these changes, patch files will be created and placed in the `output` directory. If you want these patches included in a normal run (without CREATE_PATCHES to say), these files must be copied to the appropriate directories. Also, see [user-provided patches](https://docs.armbian.com/Developer-Guide_User-Configurations/#user-provided-patches). - **BUILD_ALL** ( yes | no | demo ): cycle through all available board and kernel configurations and make images for all combinations - **CARD_DEVICE** ( /dev/sdX ): set to the device of your SD card. The image will be burned and verified using Etcher for CLI. - **EXT=rkdevflash** to flash Rockchip images to eMMC either during image build or separately with flash CLI command ([only works bare Linux, not Docker](https://github.com/armbian/build/pull/5058)) @@ -171,74 +180,74 @@ Example: - `CRYPTROOT_SSH_UNLOCK=yes` Default: `yes` - `CRYPTROOT_SSH_UNLOCK_PORT=2222` Default: `2022` - `CRYPTROOT_PARAMETERS="custom cryptsetup options"` Default: `--pbkdf pbkdf2` (May not contain `=`; separate with spaces) - - **Note:** This function might not work well with all distributions. Debian Buster and Stretch were tested. For building under Docker you have to use privileged mode which can be enable in `userpatches/config-docker`. - - **Warning:** This feature was added as community contribution and mostly functional. Under some circumstances though the prompt will not be shown. Therefore it should be considered experimental. Check [here](https://github.com/armbian/build/commit/681e58b6689acda6a957e325f12e7b748faa8330) and [here](https://github.com/armbian/build/issues/1183) - - **Hint:** If you want to do the encryption part from scratch check out [this](https://forum.armbian.com/topic/15618-full-root-filesystem%C2%A0encryption%C2%A0on-an-armbian-system-new-replaces-2017-tutorial-on-this-topic/) forum post. + - **Note:** This function might not work well with all distributions. Debian Buster and Stretch were tested. For building under Docker, you have to use privileged mode, which can be enabled in `userpatches/config-docker`. + - **Warning:** This feature was added as a community contribution and is mostly functional. Under some circumstances, though, the prompt will not be shown. Therefore, it should be considered experimental. Check [here](https://github.com/armbian/build/commit/681e58b6689acda6a957e325f12e7b748faa8330) and [here](https://github.com/armbian/build/issues/1183) + - **Hint:** If you want to do the encryption part from scratch, check out [this](https://forum.armbian.com/topic/15618-full-root-filesystem%C2%A0encryption%C2%A0on-an-armbian-system-new-replaces-2017-tutorial-on-this-topic/) forum post. ## Hidden options to minimize user input for build automation -- **BOARD** ( `string` ): set name of board manually to skip dialog prompt +- **BOARD** ( `string` ): set the name of the board manually to skip the dialog prompt - **BRANCH** ( `legacy` | `current` | `edge` ): set kernel and U-Boot branch manually to skip dialog prompt; some options may not be available for all devices - **RELEASE** ( `bullseye` | `bookworm` | `jammy` ): set OS release manually to skip dialog prompt; use this option with `KERNEL_ONLY=yes` to create board support package - **ARMBIAN_CACHE_ROOTFS_PATH** ( `string` ): bind mount cache/rootfs to defined folder - **ARMBIAN_CACHE_TOOLCHAIN_PATH** ( `string` ): bind mount cache/toolchain path to defined folder ## Hidden options for advanced users (default values are marked **bold**) -- **EXPERT** ( yes | **no** ): show development features and boards regardless of its status in interactive mode -- **USERPATCHES_PATH** ( **userpatches/** ): set alternate path for location of `userpatches` folder +- **EXPERT** ( yes | **no** ): show development features and boards regardless of their status in interactive mode +- **USERPATCHES_PATH** ( **userpatches/** ): set alternate path for the location of the `userpatches` folder - **USE_CCACHE** ( **yes** | no ): use a C compiler cache to speed up the build process -- **PRIVATE_CCACHE** ( yes | **no** ) use `$DEST/ccache` as ccache home directory -- **SKIP_EXTERNAL_TOOLCHAINS** ( yes | **no** ) don't download and use Linaro toolchains, by default placed in cache/toolchain (and configurable with **ARMBIAN_CACHE_TOOLCHAIN_PATH**) +- **PRIVATE_CCACHE** ( yes | **no** ): use `$DEST/ccache` as ccache home directory +- **SKIP_EXTERNAL_TOOLCHAINS** ( yes | **no** ): don't download and use Linaro toolchains, by default placed in cache/toolchain (and configurable with **ARMBIAN_CACHE_TOOLCHAIN_PATH**) - **PROGRESS_DISPLAY** ( none | **plain** | dialog ): way to display output of verbose processes - compilation, packaging, debootstrap -- **PROGRESS_LOG_TO_FILE** ( yes | **no** ): duplicate output, affected by previous option, to log files `output/debug/*.log` +- **PROGRESS_LOG_TO_FILE** ( yes | **no** ): duplicate output, affected by the previous option, to log files `output/debug/*.log` - **NO_APT_CACHER** ( **yes** | no ): disable usage of APT cache. Default `yes` in containers, but can be overridden - **DISABLE_IPV6** ( **true** | false ): The distant future, the year Two-Thousand. Set false to allow Aria2c to use a modern ip protocol. - **NO_HOST_RELEASE_CHECK** ( yes | **no** ): overrides the check for a supported host system -- **USE_MAINLINE_GOOGLE_MIRROR** ( yes | **no** ): use `googlesource.com` mirror for downloading mainline kernel sources, may be faster than `git.kernel.org` depending on your location -- **USE_GITHUB_UBOOT_MIRROR** ( yes | **no** ): use unofficial Github mirror for downloading mainline U-Boot sources, may be faster than `git.denx.de` depending on your location +- **USE_MAINLINE_GOOGLE_MIRROR** ( yes | **no** ): use the `googlesource.com` mirror for downloading mainline kernel sources, which may be faster than `git.kernel.org` depending on your location +- **USE_GITHUB_UBOOT_MIRROR** ( yes | **no** ): use an unofficial GitHub mirror for downloading mainline U-Boot sources, may be faster than `git.denx.de` depending on your location - **SYNC_CLOCK** ( **yes** | no ): sync system clock on builder before start image creation process -- **OFFLINE_WORK** ( yes | **no** ): skip downloading and updating sources as well as time and host check. Set to "yes" and you can collect packages without accessing the internet +- **OFFLINE_WORK** ( yes | **no** ): skip downloading and updating sources and time and host check. Set to "yes," and you can collect packages without accessing the internet - **FORCE_USE_RAMDISK** ( yes | no ): overrides autodetect for using tmpfs in new debootstrap and image creation process -- **FIXED_IMAGE_SIZE** ( `integer` ): create image file of this size (in megabytes) instead of minimal +- **FIXED_IMAGE_SIZE** ( `integer` ): create an image file of this size (in megabytes) instead of minimal - **BOOTSIZE** ( `integer` **96** ): set size (in megabytes) for separate /boot filesystem. Used if **ROOTFS_TYPE** set to non-ext4 -- **COMPRESS_OUTPUTIMAGE** (comma-separated list): create compressed archive with image file and GPG signature for redistribution +- **COMPRESS_OUTPUTIMAGE** (comma-separated list): create a compressed archive with an image file and GPG signature for redistribution - sha: generate SHA256 hash for image - gpg: sign image using gpg - - 7z: compress image, hash and signature to 7z archive + - 7z: compress image, hash, and signature to 7z archive - gz: compress image only using gz format - xz: compress image only using xz format - - yes: compatibility shorcut for `sha,gpg,7z` + - yes: compatibility shortcut for `sha,gpg,7z` - **IMAGE_XZ_COMPRESSION_RATIO** ( **1** - 9 ) images compression levels when using xz compressor. Beware of memory consumption when going higher - **SEVENZIP** ( yes | **no** ): create .7z archive with extreme compression ratio instead of .zip - **BUILD_KSRC** ( **yes** | no ): create kernel source packages while building... - **INSTALL_KSRC** ( yes | **no** ): ... and pre-install these kernel sources on the image - **ROOTFS_TYPE** ( **ext4** | f2fs | btrfs | nilfs2 | xfs | nfs ): create image with different root filesystems instead of default `ext4`. Requires setting `FIXED_IMAGE_SIZE` to something smaller than the size of your SD card for `F2FS` -- **BTRFS_COMPRESSION** ( lzo | none | **zlib** | zstd ): when choosing `ROOTFS_TYPE=btrfs` select `btrfs` filesystem compression method and compression level. By default the compression is `zlib`. +- **BTRFS_COMPRESSION** ( lzo | none | **zlib** | zstd ): when choosing `ROOTFS_TYPE=btrfs`, select `btrfs` filesystem compression method and compression level. By default, the compression is `zlib`. When selecting `zstd` or setting zlib compression level(`zlib:[1-9]`) user must ensure kernel version is **>=4.14.x**. -When selecting zstd compression level (`zstd:[1-15]`) both the host and the target kernel version must be **>=5.1.x** since kernel started supporting zstd compression ratio only from 5.1 on. -*Note:* The script does not check the legality of input variable (compression ratio). Input like `zlib:1234` is legal to the script but illegal to the kernel. Beware that setting this option does affect image creation only (shrinking disk size) and will not adjust `/etc/fstab` so it is up to the user to later edit `/etc/fstab` if compression in daily operation is also wanted (beware of serious performance penalties with random IO patterns and heavy compression algorithms!). +When selecting the zstd compression level (`zstd:[1-15]`), both the host and the target kernel version must be **>=5.1.x** since the kernel started supporting the zstd compression ratio only from 5.1 on. +*Note:* The script does not check the legality of the input variable (compression ratio). Input like `zlib:1234` is legal to the script but illegal to the kernel. Beware that setting this option does affect image creation only (shrinking disk size) and will not adjust `/etc/fstab`, so it is up to the user to later edit `/etc/fstab` if compression in daily operation is also wanted (beware of severe performance penalties with random IO patterns and heavy compression algorithms!). - **FORCE_BOOTSCRIPT_UPDATE** ( yes | no ): - yes: force bootscript to get updated during bsp package upgrade - **NAMESERVER** ( `IPv4 address` ): the DNS resolver used inside the build chroot. Does not affect the final image. Default: `1.0.0.1` - **DOWNLOAD_MIRROR** ( `china` | `bfsu` ): select download mirror for `toolchain` and `debian/ubuntu packages` - - `china`: use `mirrors.tuna.tsinghua.edu.cn`, it will be very fast thanks to Tsinghua University - - `bfsu`: use `mirrors.bfsu.edu.cn`, mirror of Beijing Foreign Studies University + - `china`: use `mirrors.tuna.tsinghua.edu.cn`; it will be very fast thanks to Tsinghua University + - `bfsu`: use `mirrors.bfsu.edu.cn`, the mirror of Beijing Foreign Studies University - leave empty to use official source - **ARMBIAN_MIRROR** (auto): override automated mirror selection, example 'ARMBIAN_MIRROR="https://yourlocalmirror.com"' - **MAINLINE_MIRROR** ( `google` | `tuna` | `bfsu` ): select mainline mirror of `linux-stable.git` - - `google`: use mirror provided by Google, the same as `USE_MAINLINE_GOOGLE_MIRROR=yes` - - `tuna`: use mirror provided by Tsinghua University - - `bfsu`: use mirror provided by Beijing Foreign Studies University which is similar to `tuna` - - leave empty to use offical `git.kernel.org`, may be very slow for mainland China users + - `google`: use the mirror provided by Google, the same as `USE_MAINLINE_GOOGLE_MIRROR=yes` + - `tuna`: use the mirror provided by Tsinghua University + - `bfsu`: use the mirror provided by Beijing Foreign Studies University, which is similar to `tuna` + - leave empty to use the official `git.kernel.org`, which may be very slow for mainland China users - **UBOOT_MIRROR** （ `github` | `gitee` : select mainline mirror of `u-boot.git` - - `github`: use mirror provided by github, the same as `USE_GITHUB_UBOOT_MIRROR=yes` - - `gitee`: use mirror provided by Gitee, a Chinese git services - - leave empty to use offical `source.denx.de`, may be very slow for mainland China users + - `github`: use the mirror provided by github, the same as `USE_GITHUB_UBOOT_MIRROR=yes` + - `gitee`: use the mirror provided by Gitee, a Chinese git services + - leave empty to use the official `source.denx.de`, which may be very slow for mainland China users - **GITHUB_MIRROR** ( `fastgit` | `gitclone` | `cnpmjs` ): select download mirror for GitHub hosted repository - - `fastgit`: use mirror provided by fastgit.org - - `gitclone`: use mirror provided by gitclone.com - - `cnpmjs`: use mirror provided by cnpmjs.org - - leave empty to connect directly to GitHub, may be very slow for mainland China users + - `fastgit`: use the mirror provided by fastgit.org + - `gitclone`: use the mirror provided by gitclone.com + - `cnpmjs`: use the mirror provided by cnpmjs.org + - leave empty to connect directly to GitHub, which may be very slow for mainland China users - **REGIONAL_MIRROR** ( `china` ): select mirrors based on regional setting, will not overwrite explicitly specified mirror option - `china`: MAINLINE_MIRROR=`tuna`, UBOOT_MIRROR=`gitee`, GITHUB_MIRROR=`fastgit`, DOWNLOAD_MIRROR=`china` - leave empty to use default settings