| Both sides previous revision Previous revision Next revision | Previous revision |
| docs:guide-developer:toolchain:buildsystem_essentials [2021/10/15 08:19] – ↷ Page moved from docs:guide-developer:build-system:buildsystem_essentials to docs:guide-developer:toolchain:buildsystem_essentials bobafetthotmail | docs:guide-developer:toolchain:buildsystem_essentials [2024/02/26 08:23] (current) – [Description] grammar issue juyongchun |
|---|
| The **build system** is a set of [[wp>Make_(software)#Makefiles|Makefiles]] and [[wp>Patch_(computing)|patches ]] that automates the process of building a [[wp>Cross_compiler|cross-compilation]] [[wp>Toolchain|toolchain]] and then using it to build the Linux kernel, the [[http://gnulinux.in/forum/what-root-file-system|root filesystem]] and possibly other pieces of software (such as [[wp>Das_U-Boot|uboot]]) required to run OpenWrt on a specific device. | The **build system** is a set of [[wp>Make_(software)#Makefiles|Makefiles]] and [[wp>Patch_(computing)|patches ]] that automates the process of building a [[wp>Cross_compiler|cross-compilation]] [[wp>Toolchain|toolchain]] and then using it to build the Linux kernel, the [[http://gnulinux.in/forum/what-root-file-system|root filesystem]] and possibly other pieces of software (such as [[wp>Das_U-Boot|uboot]]) required to run OpenWrt on a specific device. |
| A typical toolchain consists of: | A typical toolchain consists of: |
| * a compiler, such as [[wp>GNU Compiler Collection|gcc]] | * A compiler, such as [[wp>GNU Compiler Collection|gcc]] |
| * binary utilities such as an assembler and a linker; for example [[wp>GNU Binutils|binutils]] | * Binary utilities such as an assembler and a linker; for example [[wp>GNU Binutils|binutils]] |
| * a [[wp>C standard library]], such as glibc, musl, uClibc or dietlibc | * A [[wp>C standard library]], such as glibc, musl, uClibc or dietlibc |
| |
| Usually a toolchain generates code for the same instruction set architecture (ISA) that it runs on ([[wp>x86_64]] in the case of most PCs and servers). | Usually a toolchain generates code for the same instruction set architecture (ISA) that it runs on ([[wp>x86_64]] in the case of most PCs and servers). |
| |
| The process of creating a cross compiler can be tricky. | The process of creating a cross compiler can be tricky. |
| It's not something that's regularly attempted and so the there's a certain amount of mystery and black magic associated with it. | It's not something that's regularly attempted and so there's a certain amount of mystery and black magic associated with it. |
| When you're dealing with embedded devices you'll often be provided with a binary copy of a compiler and basic libraries rather than instructions for creating your own - it's a time saving step but at the same time often means you'll be using a rather dated set of tools. | When you're dealing with embedded devices you'll often be provided with a binary copy of a compiler and basic libraries rather than instructions for creating your own - it's a time saving step but at the same time often means you'll be using a rather dated set of tools. |
| It's also common to be provided with a patched copy of the Linux kernel from the board or chip vendor, but this is also dated and it can be difficult to spot exactly what has been changed to make the kernel run on the embedded platform. | It's also common to be provided with a patched copy of the Linux kernel from the board or chip vendor, but this is also dated and it can be difficult to spot exactly what has been changed to make the kernel run on the embedded platform. |
| ===== Directory structure ===== | ===== Directory structure ===== |
| There are four key directories in the build system: | There are four key directories in the build system: |
| * ''tools'' - needs to be written about. | * ''tools'' - contains various utilities required for building toolchain and packages (e.g. autoconf automake), or for image generation (e.g. mkimage, squashfs). Some of these utilities could also be installed in the host system, but we include them in the OpenWrt source so that we don't have to worry about different versions used in various Linux distributions causing breakage, or to support building on macOS. |
| * ''toolchain'' - refers to the compiler, the c library, and common tools which will be used to build the firmware image. The result of this is two new directories, ''toolchain_build_<arch>'' which is a temporary directory used for building the toolchain for a specific architecture, and ''staging_dir_<arch>'' where the resulting toolchain is installed. You won't need to do anything with the ''toolchain'' directory unless you intend to add a new version of one of the components above. | * ''toolchain'' - refers to the compiler, the c library, and common tools which will be used to build the firmware image. The result of this is two new directories, ''toolchain_build_<arch>'' which is a temporary directory used for building the toolchain for a specific architecture, and ''staging_dir_<arch>'' where the resulting toolchain is installed. You won't need to do anything with the ''toolchain'' directory unless you intend to add a new version of one of the components above. |
| * ''target'' - refers to the embedded platform, this contains items which are specific to a specific embedded platform. Of particular interest here is the ''target/linux'' directory which is broken down by platform and contains the kernel config and patches to the kernel for a particular platform. There's also the ''target/image'' directory which describes how to package a firmware for a specific platform. | * ''target'' - refers to the embedded platform, this contains items which are specific to a specific embedded platform. Of particular interest here is the ''target/linux'' directory which is broken down by platform and contains the kernel config and patches to the kernel for a particular platform. There's also the ''target/image'' directory which describes how to package a firmware for a specific platform. |
| |
| There are three areas under ''build_dir'': | There are three areas under ''build_dir'': |
| * ''build_dir/host'', for compiling all the tools that run on the host computer (OpenWRT builds its own version of ''sed'' and many other tools from source). This area will be use for compiling programs that run only on your host. | * ''build_dir/host'', for compiling all the tools that run on the host computer (OpenWrt builds its own version of ''sed'' and many other tools from source). This area will be used for compiling programs that run only on your host. |
| * ''build_dir/toolchain...'' for compiling the cross-C compiler and C standard library components that will be used to build the packages. This area will be use for compiling programs that run only on your host (the cross C compiler, for example) and also, libraries designed to run on the target that are linked to - e.g. uClibc, libm, pthreads, etc. | * ''build_dir/toolchain...'' for compiling the cross-C compiler and C standard library components that will be used to build the packages. This area will be used for compiling programs that run only on your host (the cross C compiler, for example) and also, libraries designed to run on the target that are linked to - e.g. uClibc, libm, pthreads, etc. |
| * ''build_dir/target...'' for compiling the actual packages, and the Linux kernel, for the target system | * ''build_dir/target...'' for compiling the actual packages, and the Linux kernel, for the target system |
| |
| Under staging, there are also three areas: | Under staging, there are also three areas: |
| * ''staging_dir/host'' is a mini Linux root with its own ''bin/'', ''lib/'', etc. that the host tools are installed into; the rest of the build system then prefixes its PATH with directories in this area | * ''staging_dir/host'' is a mini Linux root with its own ''bin/'', ''lib/'', etc. that the host tools are installed into; the rest of the build system then prefixes its PATH with directories in this area |
| * ''staging_dir/toolchain...'' is a mini Linux root with its own ''bin/'', ''lib/'', etc that contains the cross C compiler used to build the rest of the firmware. You can actually use that to compile simple C programs outside of OpenWRT that can be loaded onto the firmware. The C compiler might be something like: ''staging_dir/toolchain-mips_34kc_gcc-4.8-linaro_uClibc-0.9.33.2/bin/mips-openwrt-linux-uclibc-gcc''. You can see the version of the CPU, the C library and gcc encoded into it; this allows multiple targets to be built in the same area concurrently. | * ''staging_dir/toolchain...'' is a mini Linux root with its own ''bin/'', ''lib/'', etc that contains the cross C compiler used to build the rest of the firmware. You can actually use that to compile simple C programs outside of OpenWrt that can be loaded onto the firmware. The C compiler might be something like: ''staging_dir/toolchain-mips_34kc_gcc-4.8-linaro_uClibc-0.9.33.2/bin/mips-openwrt-linux-uclibc-gcc''. You can see the version of the CPU, the C library and gcc encoded into it; this allows multiple targets to be built in the same area concurrently. |
| * ''staging_dir/target.../root-...'' contains "installed" versions of each target package again arranged with ''bin/'', ''lib/'', this will become the actual root directory that with some tweaking will get zipped up into the firmware image, something like ''root-ar71xx''. There are some other files in ''staging_dir/target...'' primarily used for generating the packages and development packages, etc. | * ''staging_dir/target.../root-...'' contains "installed" versions of each target package again arranged with ''bin/'', ''lib/'', this will become the actual root directory that with some tweaking will get zipped up into the firmware image, something like ''root-ar71xx''. There are some other files in ''staging_dir/target...'' primarily used for generating the packages and development packages, etc. |
| |
| ===== Patch management ===== | ===== Patch management ===== |
| * Many packages will not work as-is and need patches to work on the target or to even compile | * Many packages will not work as-is and need patches to work on the target or to even compile |
| * the build system integrates [[wp>Quilt (software)|quilt]] for easy patch management | * The build system integrates [[wp>Quilt (software)|quilt]] for easy patch management |
| * Turn package patches into quilt series: ''make package/foo/prepare QUILT=1'' | * Turn package patches into quilt series: ''make package/foo/prepare QUILT=1'' |
| * Update patches from modified series: ''make package/foo/update'' | * Update patches from modified series: ''make package/foo/update'' |
| * Main objective is small memory and size footprint | * Main objective is small memory and size footprint |
| * Features that make no sense on embedded systems are disabled through configure or patched out | * Features that make no sense on embedded systems are disabled through configure or patched out |
| * Packages must be compilable regardless of the host system, they should be self contained | * Packages must be compatible regardless of the host system, they should be self contained |
| * Shipped "configure" scripts are often faulty or unusable in a cross-compile setting, autoreconf or patching is often needed | * Shipped "configure" scripts are often faulty or unusable in a cross-compile setting, autoreconf or patching is often needed |
| * Build variants and kconfig includes allow for configurable compile-time settings | * Build variants and kconfig includes allow for configurable compile-time settings |