You will need to setup development environment within [Ubuntu 14.04 LTS x64 server image](http://releases.ubuntu.com/14.04/) and cca. 20G of free space.
- set to "yes" to compile only kernel, u-boot and other packages for installing on existing Armbian system
- set to "no" to build complete OS image for writing to SD card
- **KERNEL_CONFIGURE** (yes|no):
- set to "yes" to configure kernel (add or remove modules or features). Kernel configuration menu will be brought up before compilation
- set to "no" to compile kernel without changing default or custom provided configuration
- **CLEAN_LEVEL** (comma-separated list): defines what should be cleaned. Default value is "make,debs" - remove all packages and clean sources. Changing this option can be useful when rebuilding images or building more than one image
- "make" = execute _make clean_ for selected kernel and u-boot sources,
- "images" = delete "./output/images" (complete OS images),
- "debs" = delete "./output/debs" (kernel, u-boot and other packages),
- **BRANCH** (default|next|dev): you can set kernel and u-boot branch manually to skip dialog prompt; some options may not be available for all devices
- **RELEASE** (wheezy|jessie|trusty): you can set OS release manually to skip dialog prompt; use this option with KERNEL_ONLY=yes to create board support package
- **USE_CCACHE** (**yes**|no): use a C compiler cache to speed up the build process
- **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 file (./output/debug/*.log)
- **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
- **EXPERIMENTAL_DEBOOTSTRAP** (yes|**no**): use new debootstrap and image creation process. NOTE: work in progress, it may not create proper images for some boards yet
- **FORCE_USE_RAMDISK** (yes|no): overrides autodetect for using tmpfs in new debootstrap and image creation process. Takes effect only if EXPERIMENTAL_DEBOOTSTRAP is set to "yes"
- **FIXED_IMAGE_SIZE** (integer): create image file of this size (in megabytes) instead of minimal. Takes effect only if EXPERIMENTAL_DEBOOTSTRAP is set to "yes"
- **USE_F2FS_ROOT** (yes|**no**): create image with [F2FS](https://en.wikipedia.org/wiki/F2FS) root filesystem instead of ext4. Requires setting FIXED_IMAGE_SIZE to actual size of your SD card. Takes effect only if EXPERIMENTAL_DEBOOTSTRAP is set to "yes"
You can add your own patches outside build script. Place your patches inside appropriate directory, for kernel or u-boot. There are no limitations except all patches must have ending **.patch**. User patches directory structure mirrors directory structure of "lib/patch". Look for the hint at the beginning of patching process to select proper directory for patches. Example:
[ o.k. ] Started patching process for [ kernel sunxi-dev 4.4.0-rc6 ]
[ o.k. ] Looking for user patches in [ userpatches/kernel/sunxi-dev ]
Patch with same file name in "userpatches" directory tree substitutes one in "lib/patch". To _replace_ a patch provided by Armbian maintainers, copy it from "lib/patch" to corresponding directory in "userpatches" and edit it to your needs. To _disable_ a patch, create empty file in corresponding directory in "userpatches".
## User provided kernel config
If file **"userpatches/linux-KERNELFAMILY-KERNELBRANCH.config"** exists, it will be used instead of default one from "lib/config". Look for the hint at the beginning of kernel compilation process to select proper config file name. Example:
[ o.k. ] Compiling dev kernel [ @host ]
[ o.k. ] Using kernel config file [ lib/config/linux-sunxi-dev.config ]
## User provided image customization script
You can run custom commands to customize created image. Edit file:
userpatches/customize-image.sh
and place your custom code here. You may test values of variables noted in the file to use different commands for different configurations. Those commands will be executed in a process of building just before closing image.
# What is behind the build process?
Build process summary:
- creates development environment on the top of X86/AMD64 Ubuntu 14.04 LTS,
- downloads proven sources, applies patches and uses tested configurations,
- cross-compiles universal boot loader (u-boot), kernel and other tools and drivers,
- packs kernel, uboot, dtb and root customizations into debs,
- debootstraps minimalistic Debian Wheezy, Jessie and Ubuntu Trusty into SD card image,
- installs additional packets, applies customizations and shrinks image to its actual size.
At first run we are downloading all necessary dependencies.
## Using board configuration ##
We need to get some predefined variables about selected board. Which kernel & uboot source to use, modules to load, which is the build number, do we need to have a single partition or dual with boot on fat, which extra drivers to compile out of the kernel tree, ...
**Board configuration example:**
BOOTSIZE="16" # FAT boot partition in MB, 0 for none
Note that in this case, all main config options (kernel and uboot source) are covered within FAMILY. Check [configuration.sh](https://github.com/igorpecovnik/lib/blob/master/configuration.sh) for more config options.
This **isn't ment to be user configurable** but you can alter variables if you know what you are doing.
## Downloading sources ##
When we know where are the sources and where they need to be the download / update process starts. This might take from several minutes to several hours.
## Patching ##
In patching process we are appling patches to sources. The process is defined in:
Debootstrap creates fresh Debian / Ubuntu root filesystem templates or use cached under:
output/cache/rootfs/$DISTRIBUTION.tgz
To recreate those files you need to remove them manually.
## Kernel install ##
When root filesystem is ready we need to instal kernel image with modules, board definitions, firmwares. Along with this we set the CPU frequency min/max, hostname, modules, network interfaces templates. Here is also the place to install headers and fix + native compile them on the way.
## Distribution fixes ##
Each distributin has it's own way of doing things:
- serial console
- different packets
- configuration locations
## Board fixes ##
Each board has their own tricks: **different device names, firmware loaders, configuration (de)compilers, hardware configurators**
## Desktop installation ##
You can build a desktop withing the image. Consider this feature as experimental. Hardware acceleration on Allwinner boards is working within kernel 3.4.x only.
## External applications ##
This place is reserved for custom applications. There is one example of application - USB redirector.
## Closing image ##
There is an option to add some extra commands just before closing an image which is also automaticaly shrink to it's actual size with some small reserve.
