Differences

This shows you the differences between two versions of the page.

doc:howto:build [2012/09/21 18:02]
hnyman add directory example
doc:howto:build [2014/07/08 18:13] (current)
theoradicus pretty mark on buil fail
Line 3: Line 3:
===== Prerequisites ===== ===== Prerequisites =====
 +to generate an [[doc:howto:generic.flashing|installable]] OpenWrt firmware image file with a size of e.g. 8MB:
  - **[[buildroot.exigence|Install OpenWrt Buildroot and its prerequisites]]** on your OS.   - **[[buildroot.exigence|Install OpenWrt Buildroot and its prerequisites]]** on your OS.
 +  - ca. 3-4 GB of available hard disk space
 +  - environment variables:
 +    * ''SED'' should not be set.  If it is, run ''`unset SED`'' before compiling. (See [[https://dev.openwrt.org/ticket/10612|Ticket 10612]].)
 +    * ''GREP_OPTIONS'' should not have ''--initial-tab'' or other options affecting its output
===== Procedure ===== ===== Procedure =====
| {{:meta:icons:tango:48px-emblem-important.svg.png?nolink}} | 1. Do everything as //non//-root user\\ 2. Issue all commands in the ''<buildroot dir>'' directory, e.g. ''~/openwrt/trunk/'' | | {{:meta:icons:tango:48px-emblem-important.svg.png?nolink}} | 1. Do everything as //non//-root user\\ 2. Issue all commands in the ''<buildroot dir>'' directory, e.g. ''~/openwrt/trunk/'' |
-    - Update OpenWrt sources. +  - Update OpenWrt sources. 
-   - Update and install package feeds. + - Update and install package feeds. 
-   - Configure the build+ - Configure the firmware image you want to obtain
-   - Start the build. This will automatically compile toolchain, cross-compile sources, package packages, and finally generate an image ready to be flashed. + - Start the build. This will automatically compile toolchain, cross-compile sources, package packages, and finally generate an image ready to be flashed. 
-   - Proceed to [[generic.flashing|Installing OpenWrt]]+ - Proceed to [[generic.flashing|Installing OpenWrt]] 
 + 
==== Updating Sources ==== ==== Updating Sources ====
 +You can check the currently installed revision with
 +<code>
 +svn info
 +</code>
 +
 +
Update sources: Update sources:
<code> <code>
Line 23: Line 36:
==== Updating Feeds ==== ==== Updating Feeds ====
- 
  - Update feeds: <code>./scripts/feeds update -a</code>   - Update feeds: <code>./scripts/feeds update -a</code>
-  - Install the downloaded packages: +  - Make downloaded package/packages available in ''make menuconfig''
-Note that //installing// in context of ''./scripts/feeds'' script means &quot;making package available in ''make menuconfig''&quot; rather than really installing or compiling package.+   * single package:<code>./scripts/feeds install <PACKAGENAME></code> 
 +    * all packages:<code>./scripts/feeds install -a&lt;/code&gt;
-    * To install single package:<code>./scripts/feeds install <PACKAGENAME></code> +Please note that //installing// in context of ''./scripts/feeds'' script means &quot;making package available in ''make menuconfig''&quot; rather than really installing or compiling package.
-    * Alternatively, install all packages:<code>./scripts/feeds install -a&lt;/code&gt;+
===== Image Configuration ===== ===== Image Configuration =====
-Start OpenWrt Buildroot's [[wp>ncurses]] [[wp>Text-based user interface|text-based]] configuration interface:\\+==== Make menuconfig ==== 
 +The **OpenWrt Buildroot configuration interface** handles the selection of the target platform, packages to be compiled, packages to be included in the firmware file, some kernel options, etc. \\ Start the OpenWrt Buildroot configuration interface by issuing the following command:\\
<code> <code>
make menuconfig make menuconfig
</code> </code>
-Similar to the Linux kernel config, almost every option has three choices, **y**, **m**, **n** which are represented as follows: +This will update the dependencies of your existing configuration automatically, and you can now proceed to build your updated images.
-  * pressing **y** yields to ''<*>'' label \\ This package will be included in the firmware image +
-  * pressing **m** yields to ''<M>'' label \\ This package will be compiled (to be installed with ''[[doc:techref:opkg]]'' after [[doc:howto:generic.flashing|Flashing OpenWrt]]) but the package will **not** be included in the firmware-image +
-  * pressing **n** yields to ''< >'' label \\ This package will not be compiled.   +
- +
-When you save your configuration, the file ''~/openwrt/trunk/.config'' will be created according to your configuration. +
- +
-The devs offer such a file for OpenWrt 'Backfire' 10.03.1-RC5, e.g. [[http://downloads.openwrt.org/backfire/10.03.1-rc5/ar71xx/config|for ar71xx]]. +
{{ OpenWrt Buildroot TUI.gif}} {{ OpenWrt Buildroot TUI.gif}}
-  * The menu above allows you to select the target platform, which version of toolchain you want to use to build and what packages you want included in the firmware image. +You have three options: 
 +''y'', ''m'', ''n'' which are represented as follows: 
 +  * pressing ''**y**'' sets the ''**<*>**'' built-in label\\ This package will be compiled and included in the firmware image file. 
 +  * pressing ''**m**'' sets the ''**<M>**'' package label\\ This package will be compiled, but **not** included in the firmware image file. (E.g. to be installed with ''[[doc:techref:opkg]]'' after [[doc:howto:generic.flashing|flashing]] the firmware image file to the device.) 
 +  * pressing ''**n**'' sets the ''**< >**'' excluded label\\ The source code will not be processed.
-  * Run this configuration interface after updating sources and feeds to ensure that the latest packages are included in your configuration. +When you save your configuration, the file **''<buildroot dir>/.config''** will be created according to your configuration.
- +=== Explanations === 
- +It has been the intention from the beginning, with the development of ''menuconfig'', to create a simple, yet powerful, environment for the configuration of individual OpenWrt builds. ''menuconfig'' is more or less self-explanatory, and even the most specialized configuration requirements can be met by using it. Depending on the the particular target platform, package requirements and kernel module needs, the standard configuration process will include modifying:
-==== Defconfig ==== +
-[[https://forum.openwrt.org/viewtopic.php?pid=140470#p140470|select your target before issuing defconfig]] +
-<code> +
-make defconfig +
-</code> +
-will produce a general purpose configuration of the build system including a check of dependencies and prerequisites for the build environment etc +
- +
-will check for dependencies. Install missing and run again. +
-  +
- +
-==== Overall configuration ==== +
-''Menuconfig'' has a TUI, which handles the selection of the target, packages to be compiled, packages to be included in the firmware file, some kernel options etc. +
- +
-<code> +
-make menuconfig +
-</code> +
- +
-This will update the dependencies of your existing configuration automatically and you can now proceed to build your updated images.  +
- +
-It has from the beginning on been the intention, with the development of 'menuconfig', to create a simple yet powerful environment for the configuration of individual OpenWrt images. Menuconfig is more or less self-explanatory, and even the most specialized configuration needs can be solved with its help. Depending on the the particular target platform, package requirements and kernel module needs, the standard process of configuration will include modifying:+
  - Target system   - Target system
Line 82: Line 72:
Target system is selected from the extensive list of supported platforms, with the numerous target profiles – ranging from specific devices to generic profiles, all depending on the particular device at hand. Package selection has the option of either 'selecting all package', which might be un-practical in certain situation, or relying on the default set of packages will be adequate or make an individual selection. It is here needed to mention that some package combinations might break the build process, so it can take some experimentation before the expected result is reached. Added to this, the OpenWrt developers are themselves only maintaining a smaller set of packages – which includes all default packages – but, the feeds-script makes it very simple to handle a locally maintained set of packages and integrate them in the build-process. Target system is selected from the extensive list of supported platforms, with the numerous target profiles – ranging from specific devices to generic profiles, all depending on the particular device at hand. Package selection has the option of either 'selecting all package', which might be un-practical in certain situation, or relying on the default set of packages will be adequate or make an individual selection. It is here needed to mention that some package combinations might break the build process, so it can take some experimentation before the expected result is reached. Added to this, the OpenWrt developers are themselves only maintaining a smaller set of packages – which includes all default packages – but, the feeds-script makes it very simple to handle a locally maintained set of packages and integrate them in the build-process.
-You have three option at most: +The final step before the process of compiling the intended image(s) is to exit ''menuconfig'' – this also includes the option to save a specific configuration or load an already existing, and pre-configured, version.
-  * < > the source code will not be processed +
-  * <M> the source code of the package will be crosscompiled into binaries and a opkg package will be built and placed in ''/buildsystem/bla/bla/bla'', but the ImageGenerator will not put it onto the Firmware-Image! +
-  * <*> that the package will built into the firmware (on the SqashFS partition) +
- +
-The final step before the process of compiling the intended image(s) is to exit 'menuconfig' – this also includes the option to save a specific configuration or load an already existing, and pre-configured, version.+
Exit the TUI, and choose to ''save'' your settings. Exit the TUI, and choose to ''save'' your settings.
=== Kernel configuration === === Kernel configuration ===
-While you won't typically need to do this, you can do it:+Note that ''make kernel_menuconfig'' modifies the Kernel configuration templates of the build tree and clearing the build_dir will not revert them:
 +While you won't typically need to do this, you can do it:
<code> <code>
make kernel_menuconfig make kernel_menuconfig
 +</code>
 +The changes can be reviewed with
 +<code>
 +svn diff target/linux/
 +</code>
 +and reverted with
 +<code>
 +svn revert -R target/linux/
</code> </code>
-Note that ''make kernel_menuconfig'' modifies the Kernel configuration templates of the build tree, clearing the build_dir will not revert them. 
-The changes can be reviewed with ''svn diff target/linux/'' and reverted with ''svn revert -R target/linux/''. 
- 
-See: [[doc:techref:buildroot#Customizing the kernel options]] 
=== Source Mirrors === === Source Mirrors ===
Line 109: Line 99:
  - Download folder   - Download folder
-In the case of the first option, you simply enter a full URL to the web or ftp server on which the package sources are hosted. Download folder would in the same way be the path to a local folder on the build system (or network). If you have a web/ftp-server hosting the tarballs, the OpenWrt build system will try this one before trying to download from the location(s) mentioned in the Makefiles . Similar if a local 'download folder', residing on the build system, has been specified. +In the case of the first option, you simply enter a full URL to the HTTP or FTP server on which the package sources are hosted. Download folder would in the same way be the path to a local folder on the build system (or network). If you have a web/ftp-server hosting the tarballs, the OpenWrt build system will try this one before trying to download from the location(s) mentioned in the Makefiles . Similar if a local 'download folder', residing on the build system, has been specified.
The 'Kernel modules' option is required if you need specific (non-standard) drivers and so forth – this would typically be things like modules for USB or particular network interface drivers etc. The 'Kernel modules' option is required if you need specific (non-standard) drivers and so forth – this would typically be things like modules for USB or particular network interface drivers etc.
 +
 +
 +==== Patches ====
 +OpenWrt Buildroot integrates //[[wp>Quilt (software)|quilt]]// for easy patch management:\\
 +->[[doc/devel/patches]]
==== Custom files ==== ==== Custom files ====
-In many cases, you may want to have a custom image that has been pre-configured. If so, place your custom files in  +| {{:meta:icons:tango:48px-dialog-warning.svg.png?nolink}} | <color red>**Warning! Be carefull!**</color> [[doc/howto/generic.failsafe|OpenWrt failsafe]] relies on 100%-working base files on the [[doc/techref/flash.layout#partitioning.of.squashfs-images|SquashFS-partition]] (i.e. the <color magenta>''/rom''</color>-directory), so in case you mis-configure or misspell something, you will end up with a non-working OpenWrt failsafe and be forced to used more rudimentary methods to [[doc/howto/generic.debrick|debrick]] your device again! | 
-<code><buildroot dir>/files/</code>+ 
 +In case you want to include some custom configuration files, the correct place to put them is: 
 + * **''<buildroot dir>/files/''** 
 + 
 +For example, let's say that you want an image with a custom **''/etc/config/firewall''** or a custom **''etc/sysctl.conf''**, then create this files as: 
 +  * ''**<buildroot dir>/files/**etc/config/firewall'' 
 +  * ''**<buildroot dir>/files/**etc/sysctl.conf''
-For example, let's say that you want an image with a pre-configured ''/etc/config/firewall'', then place your modified firewall config in here: 
-<code><buildroot dir>/files/etc/config/</code> 
E.g. if your <buildroot dir> is /openwrt/trunk and you want some files to be copied into firmware image's /etc/config directory, the correct place to put them is /openwrt/trunk/files/etc/config. E.g. if your <buildroot dir> is /openwrt/trunk and you want some files to be copied into firmware image's /etc/config directory, the correct place to put them is /openwrt/trunk/files/etc/config.
 +==== Defconfig ====
 +[[https://forum.openwrt.org/viewtopic.php?pid=140470#p140470|select your target before issuing defconfig]]
 +<code>
 +make defconfig
 +</code>
 +will produce a general purpose configuration of the build system including a check of dependencies and prerequisites for the build environment etc
 +will check for dependencies. Install missing and run again.
 +
===== Building Images ===== ===== Building Images =====
Everything is now ready for building the image(s), which is done with one single command: Everything is now ready for building the image(s), which is done with one single command:
Line 133: Line 140:
  - then crosscompile the sources with this toolchain   - then crosscompile the sources with this toolchain
  - create opkg-packages   - create opkg-packages
-  - create a firmware image file ready to be [[generic.flashing|flashed]].+  - generate a firmware image file ready to be [[generic.flashing|flashed]].
==== Make options ==== ==== Make options ====
=== Building on multi-core CPU === === Building on multi-core CPU ===
 +:!: **Build may FAIL**
The build process can be accelerated by running multiple concurrent job processes using the ''-j''-option: The build process can be accelerated by running multiple concurrent job processes using the ''-j''-option:
Line 142: Line 150:
make -j 3 make -j 3
</code> </code>
-  * Use the standard formula ''<your number of CPUs + 1>''+  * Use the standard formula ''<your number of CPU cores + 1>''
  * If this produces random build errors try compiling again without the ''-j''-option   * If this produces random build errors try compiling again without the ''-j''-option
Line 149: Line 157:
<code> <code>
-ionice -c 3 nice -n 20 make -j 2+ionice -c 3 nice -n19 make -j 2
</code> </code>
Line 156: Line 164:
<code> <code>
-make package/cups/compile V=99+make package/cups/compile V=s
</code> </code>
-For the package ''mc (midnight commander)'', which is contained the feed //packages// it looks like this:+For a rebuild:
<code> <code>
-make package/feeds/packages/mc/compile V=99+make package/cups/{clean,compile,install} V=s
</code> </code>
-//Note that the path start in ''package'' directory and ''package/feeds'' may not have exactly the same structure as ''feeds''. For example package in ''~/openwrt/trunk/feeds/packages/**net**/snort'' will be compiled using ''make ~/openwrt/trunk/**package**/feeds/packages/snort/**compile** V=99''.// +It doesn't matter what feed the package is located in, this same syntax works for any installed package.
- +
=== Spotting build errors === === Spotting build errors ===
Line 172: Line 178:
<code> <code>
-make V=99 2>&1 | tee build.log | grep -i error+make V=s 2>&1 | tee build.log | grep -i error
</code> </code>
Line 180: Line 186:
<code> <code>
-ionice -c 3 nice -n 20 make -j 2 V=99 CONFIG_DEBUG_SECTION_MISMATCH=y 2>&1 | tee build.log | egrep -i '(warn|error)'+ionice -c 3 nice -n 20 make -j 2 V=s CONFIG_DEBUG_SECTION_MISMATCH=y 2>&1 | tee build.log | egrep -i '(warn|error)'
</code> </code>
The above saves a full verbose copy of the build output (with stdout piped to stderr) in build.log and outputs only warnings and errors while building using only background resources on a dual core CPU. The above saves a full verbose copy of the build output (with stdout piped to stderr) in build.log and outputs only warnings and errors while building using only background resources on a dual core CPU.
 +
 +Yet another way to focus on the problem without having to wade through tons of output from Make as described above is to check the corresponding log in 'logs' folder.
 +IE: if the build fails at "make[3] -C package/kernel/mac80211 compile", then you can go to <buildroot>/logs/package/kernel/mac80211 and view the compile.txt found there.
=== Getting beep notification === === Getting beep notification ===
Line 189: Line 198:
<code> <code>
-make V=99 ; echo -e '\a'+make V=s ; echo -e '\a'
</code> </code>
===== Locating Images ===== ===== Locating Images =====
-After a successful build, the freshly built image(s) can be found in the newly created ''<buildroot dir>/bin'' directory. The compiled files are additionally classfied by the target platform, so e.g. a firmware built for an ar71xx device will be located in ''<buildroot dir>/bin/ar71xx'' directory.+After a successful build, the freshly built image(s) can be found in the newly created ''<buildroot_dir>/bin'' directory. The compiled files are additionally classified by the target platform, so e.g. a firmware built for an ar71xx device will be located in ''<buildroot_dir>/bin/ar71xx'' directory.
-E.g. if your <buildroot dir> is /openwrt/trunk, the binaries are in /openwrt/trunk/bin/ar71xx.+E.g. if your <buildroot_dir> is ''~/openwrt/trunk'', the binaries are in ''~/openwrt/trunk/bin/ar71xx''.
===== Cleaning Up ===== ===== Cleaning Up =====
Line 205: Line 214:
</code> </code>
-deletes contents of ''bin'' and ''build_dir'' directories.+deletes contents of the directories ''/bin'' and ''/build_dir''.
Line 213: Line 222:
</code> </code>
-deletes contents of ''/bin'' and ''/build_dir'' directories and additionally ''/staging_dir'' and ''/toolchain'' (=the cross-compile tools). 'Dirclean' is your basic "Full clean" operation. +deletes contents of the directories ''/bin'' and ''/build_dir'' and additionally ''/staging_dir'' and ''/toolchain'' (=the cross-compile tools) and ''/logs''. 'Dirclean' is your basic "Full clean" operation.
Line 224: Line 233:
-**CAUTION**: In addition to all else, this will **erase your build configuration (.config)**, your toolchain and all other sources. Use with care!+**CAUTION**: In addition to all else, this will **erase your build configuration (''<buildroot_dir>/.config'')**, your toolchain and all other sources. Use with care!
There are numerous other functionalities in the OpenWrt build system, but the above should have covered some of the fundamentals. There are numerous other functionalities in the OpenWrt build system, but the above should have covered some of the fundamentals.
 +==== Clean small part ====
 +In more time, you may not want to clean so many objects, then you can use some of the commands below to do it.
 +
 +Clean linux objects.
 +<code>
 +make target/linux/clean
 +</code>
 +
 +Clean package base-files objects.
 +<code>
 +make package/base-files/clean
 +</code>
 +
 +Clean luci.
 +<code>
 +make package/luci/clean
 +</code>
===== Examples ===== ===== Examples =====
Line 235: Line 261:
===== Troubleshooting ===== ===== Troubleshooting =====
-First get more information on the problem using the make option "make V=99".+First get more information on the problem using the make option ''"make V=s"''.
==== Missing source code file, due to download problems ==== ==== Missing source code file, due to download problems ====
- First check if the URL path in the make file contains a trailing slash, then try with it removed (helped several times). +First check if the URL path in the make file contains a trailing slash, then try with it removed (helped several times). 
- Otherwise try to download the source code manually and put it into "dl" directory+Otherwise try to download the source code manually and put it into "dl" directory.
==== Compilation errors ==== ==== Compilation errors ====
- Try to update the main source and all the feeds (Warning! May result in other problems). +Try to update the main source and all the feeds (Warning! May result in other problems). 
- Check for a related bug in ([[https://dev.openwrt.org/query|TRAC]]), use the filters to find it. +Check for a related bug in ([[https://dev.openwrt.org/query|TRAC]]), use the filters to find it. 
- Otherwise report the problem there, by mentioning the package, the target data (CPU, image, etc.) and the code revisions (main & package). +Otherwise report the problem there, by mentioning the package, the target data (CPU, image, etc.) and the code revisions (main & package). 
- Compiling with make -j ... sometimes gives random errors. Try compiling without -j first before reporting the problem.+Compiling with make -j ... sometimes gives random errors. Try compiling without -j first before reporting the problem.
====  Bad environment variables ==== ====  Bad environment variables ====
-    * ''GREP_OPTIONS'' should not have ''--initial-tab'' or other options affecting its output +  * ''GREP_OPTIONS'' should not have ''--initial-tab'' or other options affecting its output 
-     * **''SED'' should not be set.  If it is, run `unset SED` before compiling.** (See [[https://dev.openwrt.org/ticket/10612|Ticket 10612]].)+ * **''SED'' should not be set.  If it is, run `unset SED` before compiling.** (See [[https://dev.openwrt.org/ticket/10612|Ticket 10612]].) 
 +  * others?
==== I can't find my <package> in menuconfig ==== ==== I can't find my <package> in menuconfig ====
  - Have you run this command? [[doc:howto:build#updating.feeds|See this.]] <code>./scripts/feeds install <package></code>   - Have you run this command? [[doc:howto:build#updating.feeds|See this.]] <code>./scripts/feeds install <package></code>
-  - Maybe you are not looking for it in the right submenu. See ''Makefile'' of the package to find out. <code>cat package/feeds/packages/<package>/Makefile</code> +  - Maybe you are not looking for it in the right submenu. See the ''Makefile'' of the package to find out. <code>cat feeds/<feedname>/<package>/Makefile</code> You are looking for this: \\ ''define Package/<package>/Default
- +
-You are looking for this: +
-|''define Package/<package>/Default+
  SUBMENU:=**Firewall**   SUBMENU:=**Firewall**
  SECTION:=net   SECTION:=net
-  CATEGORY:=**Network** +  CATEGORY:=**Network**'' 
-''| +  - Menuconfig appears to cache package lists and (especially) profiles. Try deleting the ''<buildroot_dir>/tmp'' directory and then running ''make menuconfig'' again. <code> 
- +cd ~/openwrt/trunk 
-==== Error: No rule to make target... ==== +rm -rf tmp 
-Make sure the path starts with ''package'' directory and that the path actually exist. The structure of ''feeds'' and ''package/feeds'' directory is different. [[doc:howto:build#building.single.packages|See this.]] +make menuconfig</code> Also try refreshing your package indexes: <code>./scripts/feeds update -i</code> The ''-i'' is important if you're not using the latest revisions of any packages, as this flag prevents updates from the feed sources.
- * Wrong: ''make feeds/packages/**utils**/screen/compile V=99'' +
-  * Correct: ''make **package**/feeds/packages/screen/compile V=99''+
==== WARNING: skipping <package> -- package not selected ==== ==== WARNING: skipping <package> -- package not selected ====
-Run ''make menuconfig'' and enable compilation for your package. It should be labeled with ''<*>'' or ''<M>'' to work correctly. [[doc:howto:build#image.configuration|See this.]]+Run ''make menuconfig'' and enable compilation for your package. It should be labeled with ''<*>'' or ''<M>'' to work correctly. Read [[doc:howto:build#image.configuration]] further up in this article.

Back to top

doc/howto/build.1348243329.txt.bz2 · Last modified: 2012/09/21 18:02 by hnyman