Build Switches¶
These parameters are meant to be applied to the ./compile.sh
command. They are all optional. They can also be added to your build configuration file to save time. Default values are marked bold if applicable.
User space¶
BOARD ( string
)
Set the name of the board manually to skip the dialog prompt. Name of the board is a filename without extension.
BRANCH ( string
)
vendor
legacy
current
(recommended)edge
Set kernel and U-Boot branch manually to skip dialog prompt
Note
Some branches may not be available for all devices.
RELEASE ( string
)
bookworm
trixie
sid
jammy
noble
Set packages release base manually to skip dialog prompt. Check here for currently available releases.
Note
Only stable and/or LTS upstream Debian or Ubuntu releases are officially supported. Others might work or not.
BUILD_MINIMAL ( string
)
yes
: build a bare CLI image suitable for application deployment. This option is not compatible withBUILD_DESKTOP="yes"
no
: (default)
BSPFREEZE ( string
)
yes
: freeze (from upgrade) armbian firmware packages when building images (U-Boot, kernel, DTB, BSP)no
: (default)
INSTALL_HEADERS ( string
)
yes
: pre-install kernel headersno
: (default)
Networking¶
NETWORKING_STACK ( string
)
network-manager
systemd-networkd
none
(to not-add any networking extensions)
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.
Build switch example
Text Only | |
---|---|
Host environment¶
EXPERT
yes
Show development features and boards regardless of their support status in interactive mode.
CLEAN_LEVEL (comma-separated list)
Defines what should be cleaned. 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 the kernel if it is built. very slow.debs
,alldebs
= delete all packages in “./output/debs”images
= delete “./output/images”cache
= delete “./output/cache”sources
= deletecache/sources
(all downloaded sources)oldcache
= remove old cached rootfs except for the newest 8 filesextras
= delete additional packages for the current release inoutput/debs/extra
CARD_DEVICE ( string )
/dev/sdX
Set to the device of your flash media / SD card. The image will be burned and verified.
PREFER_DOCKER ( string )
yes
(default)no
Docker assisted compilation is on by default. Set to no
if you prefer running compilation natively.
DOCKER_ARMBIAN_BASE_IMAGE ( string )
ubuntu:jammy
(default)ubuntu:noble
debian:bookworm
Defines the build host when using a Docker container (default). Here, you can see which other options are available.
- CI ( string )
- true
- false
If enabled (true
), the Docker build container will receive Docker credentials from the host
(${HOME}/.docker/config.json
) and the OCI_TARGET_BASE
environment variable.
- OCI_TARGET_BASE ( string )
- url/to/container_registry/path
- ${GHCR_SOURCE}/armbian/* (GHCR_SOURCE is defined in
lib/functions/configuration/main-config.sh
)
Select the target for pull/push OCI cached images. If not set, default is used.
- GHCR_MIRROR_ADDRESS (string)
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:
Text Only | |
---|---|
- 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:
Text Only | |
---|---|
- OPENSSHD_REGENERATE_HOST_KEYS (boolean) - false (skip armbian-firstrun’s OpenSSH host keys deletion and regeneration (eg: to let cloud-init set the SSH host keys) - true (execute armbian-firstrun’s OpenSSH host keys deletion + regeneration)
Manage OpenSSH host key regeneration at armbian-firstrun service.
Example:
Text Only | |
---|---|
Filesystem¶
ROOTFS_TYPE ( string )
ext4
(default)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 ( string )
lzo
none
zlib
(default)zstd
When choosing ROOTFS_TYPE=btrfs
, select btrfs
filesystem compression method and compression level. By default, the compression is zlib
.
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!).
CRYPTROOT_ENABLE ( string )
- yes
- no
LUKS (Linux Unified Key Setup) is a specification for block device encryption. It establishes an on-disk format for the data, as well as a passphrase/key management policy. LUKS uses the kernel device mapper subsystem via the dm-crypt module.
When enabled, you need to provide additional information: | |
---|---|
Tips and warnings
- Private key can be placed in
$USERPATCHES_PATH/dropbear_authorized_keys
or they will be generated inoutput/images/*.key
file - If you want to do the encryption part from scratch, check out this forum post.
- This function might not work well with all distributions.
- CRYPTROOT_MAPPER name might affect parallel image building
- CRYPTROOT_PARAMETERS may not contain
=
; separate switches with spaces
Advanced¶
INCLUDE_HOME_DIR ( string )
yes
no
(default)
Include directories created inside /home in final image.
ENABLE_EXTENSIONS (c omma-separated list )
Extensions allows to extend the Armbian build system without overloading the core with specific functionality. Extensions, stored in folder extensions
are called
Build switch example
CONSOLE_AUTOLOGIN
yes
(default)no
Automatically login as root for local consoles at first run. Disable if your security threat model requires.
Build options below need to be retested and added above (COULD BE DEPRECATED)¶
DO NOT USE! Obsolete documentation, new documentation above is in progress.
- KERNEL_KEEP_CONFIG ( yes | no ): - 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_DESKTOP ( yes | no ): - yes: build an image with a minimal desktop environment - no: build image with console interface only
- CREATE_PATCHES ( yes | no ) 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 theoutput
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. - EXT=rkdevflash to flash Rockchip images to eMMC either during image build or separately with flash CLI command (only works bare Linux, not Docker)
Hidden options to minimize user input for build automation¶
- 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)¶
- 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)
- 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 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 the
googlesource.com
mirror for downloading mainline kernel sources, which may be faster thangit.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 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 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 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
- gz: compress image only using gz format
- xz: compress image only using xz format
- 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
- 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 fortoolchain
anddebian/ubuntu packages
-china
: usemirrors.tuna.tsinghua.edu.cn
; it will be very fast thanks to Tsinghua University -bfsu
: usemirrors.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 oflinux-stable.git
-google
: use the mirror provided by Google, the same asUSE_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 totuna
- leave empty to use the officialgit.kernel.org
, which may be very slow for mainland China users - UBOOT_MIRROR (
github
|gitee
: select mainline mirror ofu-boot.git
-github
: use the mirror provided by github, the same asUSE_GITHUB_UBOOT_MIRROR=yes
-gitee
: use the mirror provided by Gitee, a Chinese git services - leave empty to use the officialsource.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 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 - ROOT_FS_CREATE_ONLY ( yes | no ): set to yes to force local cache creation
- EXTRAWIFI ( yes | no ): include several drivers for WiFi adapters
- WIREGUARD ( yes | no ): include Wireguard for kernels before it got upstreamed to mainline. Will lose functionality soon.