+build tools
+ +## Table of contents + +- [What this project does?](#what-this-project-does) +- [What do you need to get started?](#what-do-you-need-to-get-started) +- [How to build an image or a kernel?](#how-to-build-an-image-or-a-kernel) +- [Build parameter examples](#build-parameter-examples) +- [Compare with industry standards](#compare-with-industry-standards) +- [Where to download prebuilt images?](#where-to-download-prebuilt-images) +- [Additional information](#additional-information) +- [Build tools overview](#build-tools-overview) +- [Support](#support) +- [Contribute](#contribute) +- [Social](#social) +- [Credits](#credits) +- [Sponsors](#sponsors) + +
+ +## What this project does? + +- builds custom Debian based Linux system optimised for [supported single board computers](https://www.armbian.com/download/), +- covers root filesystem generation, kernel image compilation and bootloader compilation, +- maintains low-level control software for a [selection of hardware](https://www.armbian.com/download/), +- provides a consistent user experience by keeping system standards across different SBC platforms. + +
+ +## What do you need to get started? + +- x64 machine with at least 2GB of memory and ~30GB of disk space for the VM, container or native OS, +- Ubuntu Bionic 18.04 / Focal 20.04 x64 for native building or any [Docker](https://docs.armbian.com/Developer-Guide_Building-with-Docker/) capable x64 Linux for containerised, +- superuser rights (configured sudo or root access). + + + +## How to build an image or a kernel? + +```text +apt -y install git +git clone https://github.com/armbian/build +cd build +./compile.sh +``` +
+
+
+
+## Build parameter examples
+
+Show work in progress areas in interactive mode:
+
+```text
+./compile.sh EXPERT="yes"
+```
+
+Run build tools inside Docker container:
+
+```text
+./compile.sh docker
+```
+
+Build minimal CLI Debian buster based image for Odroid XU4. Use modern kernel and write image to the SD card:
+
+```text
+./compile.sh BOARD="odroidxu4" BRANCH="current" RELEASE="buster" CARD_DEVICE="/dev/sda" \
+KERNEL_ONLY="no" KERNEL_CONFIGURE="no" INSTALL_HEADERS="yes" BUILD_DESKTOP="no" BUILD_MINIMAL="yes"
+```
+
+[Build parameters, advanced build options, user defined configuration, build with Docker?](#additional-information)
+
+
+
+## Compare with industry standards
+
+Check similarity, advantages and disadvantages compared with leading industry standard build software.
+
+Function | Armbian | Yocto | Buildroot |
+|:--|:--|:--|:--|
+| Target | general purpose | embedded | embedded / IOT |
+| U-boot and kernel | compiled from sources | compiled from sources | compiled from sources |
+| Hardware support maintenance | complete | outside | outside |
+| Root file system | Debian or Ubuntu based| custom | custom |
+| Package manager | APT | any | none |
+| Configurability | limited | large | large |
+| Initramfs support | yes | yes | yes |
+| Getting started | quick | very slow | slow |
+| Cross compilation | yes | yes | yes |
+
+
+
+## Where to download prebuilt images?
+
+https://www.armbian.com/download/
+
+Armbian [releases](https://docs.armbian.com/Release_Changelog/) quarterly at the end of [February, May, August, November](https://github.com/armbian/documentation/blob/master/docs/Process_Release-Model.md). You are welcome to propose changes to our default [images build list](https://github.com/armbian/build/blob/master/config/targets.conf).
-# How to build an image or a kernel?
-Supported build environment is **Ubuntu Bionic 18.04 x64** ([minimal iso image](http://archive.ubuntu.com/ubuntu/dists/bionic/main/installer-amd64/current/images/netboot/mini.iso)).
+
-- guest inside a [VirtualBox](https://www.virtualbox.org/wiki/Downloads) or other virtualization software,
-- guest managed by [Vagrant](https://docs.armbian.com/Developer-Guide_Using-Vagrant/). This uses Virtualbox (as above) but does so in an easily repeatable way,
-- inside a [Docker](https://docs.armbian.com/Developer-Guide_Building-with-Docker/), [systemd-nspawn](https://www.freedesktop.org/software/systemd/man/systemd-nspawn.html) or other container environment [(example)](https://github.com/armbian/build/pull/255#issuecomment-205045273),
-- running natively on a dedicated PC or a server (**not** recommended),
-- **25GB disk space** or more and **2GB RAM** or more available for the VM, container or native OS,
-- superuser rights (configured `sudo` or root access).
+## Additional information
-**Execution**
+- [Build parameters and advanced build options](https://docs.armbian.com/Developer-Guide_Build-Options/),
+- [Make use of user defined configurations](https://docs.armbian.com/Developer-Guide_User-Configurations/),
+- [Docker](https://docs.armbian.com/Developer-Guide_Building-with-Docker/) and [Vagrant](https://docs.armbian.com/Developer-Guide_Using-Vagrant/) building guides,
+- Engage in [Armbian build framework forums](https://forum.armbian.com/forum/4-development/),
+- Check [Jira project management application](https://armbian.atlassian.net/browse/AR) status,
+- Make use of [central project search engine](https://www.armbian.com/search),
+- Browse [IRC channel logs](http://irc.armbian.com) or interact at #armbian on [freenode](https://freenode.net/).
- apt -y install git
- git clone https://github.com/armbian/build
- cd build
- ./compile.sh
+
-Make sure that full path to the build script does not contain spaces.
+## Build tools overview
-You will be prompted with a selection menu for a build option, a board name, a kernel branch and an OS release. Please check the documentation for [advanced options](https://docs.armbian.com/Developer-Guide_Build-Options/) and [additional customization](https://docs.armbian.com/Developer-Guide_User-Configurations/).
+```text
+├── cache Work / cache directory
+│ ├── rootfs Compressed vanilla Debian and Ubuntu rootfilesystem cache
+│ ├── sources Kernel, u-boot and various drivers sources. Mainly C code
+│ ├── toolchains External cross compilers from Linaro™ or ARM™
+├── config Packages repository configurations
+│ ├── targets.conf Board build target configuration
+│ ├── boards Board configurations
+│ ├── bootenv Initial boot loaders environments per family
+│ ├── bootscripts Initial Boot loaders scripts per family
+│ ├── kernel Kernel build configurations per family
+│ ├── sources Kernel and u-boot sources locations and scripts
+│ ├── templates User configuration templates which populate userpatches
+│ └── torrents External compiler and rootfs cache torrents
+├── lib Main build tools libraries
+├── output Build artifact
+│ └── deb Deb packages
+│ └── images Bootable images - RAW or compressed
+│ └── debug Patch and build logs
+│ └── config Kernel configuration export location
+│ └── patch Created patches location
+├── packages Support scripts, binary blobs, packages
+│ ├── blobs Wallpapers, various configs, closed source bootloaders
+│ ├── bsp Scripts and configs overlay for rootfs
+│ └── extras-buildpkgs Optional compilation and packaging engine
+├── patch Collection of patches
+│ ├── atf ARM trusted firmware
+│ ├── kernel Linux kernel patches
+| | └── family-branch Per kernel family and branch
+│ ├── misc Linux kernel packaging patches
+│ └── u-boot Universal boot loader patches
+| ├── u-boot-board For specific board
+| └── u-boot-family For entire kernel family
+└── userpatches User: configuration patching area
+ ├── lib.config User: tools common config/override file
+ ├── config-default.conf User: default user config file
+ ├── customize-image.sh User: script will execute just before closing the image
+ ├── atf User: ARM trusted firmware
+ ├── kernel User: Linux kernel per kernel family
+ ├── misc User: various
+ └── u-boot User: universal boot loader patches
+```
-Build process uses caching for the compilation and the debootstrap process, so consecutive runs with similar settings will be much faster.
+
-# How to report issues?
+## Support
-Please read [this](https://github.com/igorpecovnik/lib/blob/master/.github/ISSUE_TEMPLATE.md) notice first before opening an issue.
+- Have you found a bug in the **build tools**?
-# How to contribute?
+ Try to recreate it with a clean build tools clone. Then search for [existing and closed issues](https://github.com/armbian/build/issues). If you don't find it there, [open a new issue](https://github.com/armbian/build/issues/new).
+
+- Do you have troubles **elsewhere**?
+
+ Armbian is free software and provides **best effort help** through [community forums](https://forum.armbian.com/). If you can't find answer there and/or with help of [general project search](https://www.armbian.com/search) engine, consider [hiring an expert](https://www.debian.org/consultants/).
-- [Fork](https://help.github.com/articles/fork-a-repo/) the project
-- Make one or more well commented and clean commits to the repository.
-- Perform a [pull request](https://help.github.com/articles/creating-a-pull-request/) in github's web interface.
+- Personalized support?
-If it is a new feature request, don't start the coding first. Remember to [open an issue](https://guides.github.com/features/issues/) to discuss the new feature.
+ It is limited to active project supporters and sponsors. The shortest way to become one and receive our attention is a four figure [donation to our non-profit project](https://www.armbian.com/donate).
-If you are struggling, check [this detailed step by step guide on contributing](https://www.exchangecore.com/blog/contributing-concrete5-github/).
+
-## Where to get more info?
+## Contribute
-- [Documentation](https://docs.armbian.com/Developer-Guide_Build-Preparation/ "Developer resources")
-- [Prebuilt images](https://www.armbian.com/download/ "Download section")
-- [Support forums](https://forum.armbian.com/ "Armbian support forum")
+- Adding a new feature?
+
+ You are welcome to suggest or contribute directly to the code with a pull request. In case your proposed changes are large, remember to discuss them prior to development.
+
+- Join development?
+
+ Join regulars on their active missions, start maintaining any part of the code: patches, drivers or scripted applications like [armbian-config](https://github.com/armbian/config), address [community wishes](https://github.com/armbian/build/issues),
+
+- Help elsewhere?
+
+ Maintain and develop [documentation](https://github.com/armbian/documentation), [CI](https://github.com/armbian/ci-testing-tools), [autotests](https://github.com/armbian/autotests), [seed torrents](https://forum.armbian.com/topic/4198-seed-our-torrents/), help on [forum moderating](https://forum.armbian.com/topic/12631-help-on-forum-moderating/), [project administration](https://forum.armbian.com/forum/39-armbian-project-administration/), [costs](https://www.armbian.com/donate).
+
+
+
+## Social
+
+- [Participate in Armbian forums](https://forum.armbian.com),
+- Chat with fellow users on IRC [#armbian](https://webchat.freenode.net/?channels=armbian) on Freenode,
+- Follow [@armbian on Twitter](https://twitter.com/armbian) or [LinkedIN](https://www.linkedin.com/company/armbian).
+
+
+
+## Credits
+
+- [Current and past contributors](https://github.com/armbian/build/graphs/contributors), our families and friends,
+- [Support staff that keeps forums usable](https://forum.armbian.com/members/2-moderators/),
+- [Individuals that help with their ideas](https://forum.armbian.com/), reports and [donations](https://www.armbian.com/donate).
+
+
+
+## Sponsors
+
+Most of the project is sponsored with a work done by volunteer collaborators, while some part of the project costs are being covered by the industry. We would not be able to get this far without their help.
+
+[Do you want to see yourself below?](https://www.armbian.com/#contact)
+
+
+
+
+
+
+