armbian/documentation
0
0
Fork 0
mirror of https://github.com/armbian/documentation.git synced 2026-01-06 10:13:36 -08:00
Code Issues Packages Projects Releases Wiki Activity

Add KERNEL_COMPILER option description and fix some typos

Browse Source
This commit is contained in:
Evgenii Zheltonozhskii
2024-08-15 11:40:31 +03:00
committed by Igor
parent edf36c48ae
commit fec3049480
1 changed files with 70 additions and 61 deletions
Download Patch File Download Diff File Expand all files Collapse all files

131
docs/Developer-Guide_Build-Options.md
View File

@@ -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.<br>
*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.<br>
*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