mirror of
https://github.com/armbian/build
synced 2025-09-24 19:47:06 +07:00
Improve welcome readme file (#1779)
This commit is contained in:
Igor Pečovnik
BIN
.github/README.gif
vendored
Normal file
BIN
.github/README.gif
vendored
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 176 KiB |
BIN
.github/armbian-logo.png
vendored
Normal file
BIN
.github/armbian-logo.png
vendored
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 37 KiB |
238
README.md
238
README.md
@@ -1,50 +1,224 @@
|
||||
# Armbian #
|
||||
<h3 align=center><a href="#armbian-build-tools"><img src=".github/armbian-logo.png" alt="Armbian logo" width="144"></a><br>
|
||||
build tools</h3>
|
||||
|
||||
Debian based Linux for ARM based single-board computers
|
||||
|
||||
[https://www.armbian.com](https://www.armbian.com "Armbian")
|
||||
<p align=right> </p>
|
||||
|
||||
## 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)
|
||||
|
||||
<p align=right> </p>
|
||||
|
||||
## 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.
|
||||
|
||||
<p align=right> </p>
|
||||
|
||||
## 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).
|
||||
|
||||
<p align=right><a href=#table-of-contents>⇧</a></p>
|
||||
|
||||
## How to build an image or a kernel?
|
||||
|
||||
```text
|
||||
apt -y install git
|
||||
git clone https://github.com/armbian/build
|
||||
cd build
|
||||
./compile.sh
|
||||
```
|
||||
<a href="#how-to-build-an-image-or-a-kernel"><img src=".github/README.gif" alt="Armbian logo" width="100%"></a>
|
||||
|
||||
<p align=right><a href=#table-of-contents>⇧</a></p>
|
||||
|
||||
## 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)
|
||||
|
||||
<p align=right><a href=#table-of-contents>⇧</a></p>
|
||||
|
||||
## 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 |
|
||||
|
||||
<p align=right><a href=#table-of-contents>⇧</a></p>
|
||||
|
||||
## 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)).
|
||||
<p align=right><a href=#table-of-contents>⇧</a></p>
|
||||
|
||||
- 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
|
||||
<p align=right><a href=#table-of-contents>⇧</a></p>
|
||||
|
||||
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.
|
||||
<p align=right><a href=#table-of-contents>⇧</a></p>
|
||||
|
||||
# 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/).
|
||||
<p align=right><a href=#table-of-contents>⇧</a></p>
|
||||
|
||||
## 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).
|
||||
|
||||
<p align=right><a href=#table-of-contents>⇧</a></p>
|
||||
|
||||
## 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).
|
||||
|
||||
<p align=right><a href=#table-of-contents>⇧</a></p>
|
||||
|
||||
## 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).
|
||||
|
||||
<p align=right><a href=#table-of-contents>⇧</a></p>
|
||||
|
||||
## 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)
|
||||
|
||||
<img src="https://www.armbian.com/wp-content/uploads/2018/03/orangepi-logo-150x150.png" alt="Armbian logo" width="144" height="144"><img src="https://www.armbian.com/wp-content/uploads/2018/02/friendlyelec-logo-150x150.png" alt="Armbian logo" width="144" height="144">
|
||||
<img src="https://www.armbian.com/wp-content/uploads/2018/03/kspace-150x150.png" width="144" height="144">
|
||||
<img src="https://www.armbian.com/wp-content/uploads/2018/02/olimex-logo-150x150.png" width="144" height="144">
|
||||
<img src="https://www.armbian.com/wp-content/uploads/2018/03/helios4_logo-150x150.png" width="144" height="144">
|
||||
|
||||
<p align=right><a href=#table-of-contents>⇧</a></p>
|
||||
|
||||
Reference in New Issue
Block a user