to generate an installable OpenWrt firmware image file with a size of e.g. 8MB:
|1. Do everything as non-root user
2. Issue all commands in the
- Update OpenWrt sources.
- Update and install package feeds.
- 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.
- Proceed to Installing OpenWrt
You can check the currently installed revision with
OpenWrt sources change frequently. It is recommended that you work with the latest sources.
- Update feeds:
./scripts/feeds update -a
- Make downloaded package/packages available in
- single package:
./scripts/feeds install <PACKAGENAME>
- all packages:
./scripts/feeds install -a
Please note that installing in context of
./scripts/feeds script means "making package available in
make menuconfig" rather than really installing or compiling package.
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:
This will update the dependencies of your existing configuration automatically, and you can now proceed to build your updated images.
You have three options:
n which are represented as follows:
This package will be compiled and included in the firmware image file.
< >excluded label
The source code will not be processed.
When you save your configuration, the file
<buildroot dir>/.config will be created according to your configuration.
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:
- Target system
- Package selection
- Build system settings
- Kernel modules
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.
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.
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:
The changes can be reviewed with
svn diff target/linux/
and reverted with
svn revert -R target/linux/
The 'Build system settings' include some efficient options for changing package locations which makes it easy to handle a local package set:
- Local mirror for source packages
- Download folder
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.
|Warning! Be carefull! OpenWrt failsafe relies on 100%-working base files on the SquashFS-partition (i.e. the
In case you want to include some custom configuration files, the correct place to put them is:
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:
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.
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.
Everything is now ready for building the image(s), which is done with one single command:
This simple command will trigger a cascade of activity. As already stated, it will
- compile the toolchain
- then crosscompile the sources with this toolchain
- create opkg-packages
- generate a firmware image file ready to be flashed.
Build may FAIL
The build process can be accelerated by running multiple concurrent job processes using the
make -j 3
- Use the standard formula
<your number of CPU cores + 1>
- If this produces random build errors try compiling again without the
If you intend to use your system while building, you can have the build process use only idle I/O and CPU capacity like this (dualcore CPU):
ionice -c 3 nice -n19 make -j 2
When developing or packaging software for OpenWrt, it is convenient to be able to build only the package in question (e.g. with package
make package/cups/compile V=s
For the package
mc (midnight commander), which is contained the feed packages it looks like this:
make package/feeds/packages/mc/compile V=s
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=s.
If for some reason the build fails, the easiest way to spot the error is to do:
make V=s 2>&1 | tee build.log | grep -i error
The above saves a full verbose copy of the build output (with stdout piped to stderr) in
/openwrt/trunk/build.log and only shows errors on the screen.
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)'
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 -C package/kernel/mac80211 compile", then you can go to <buildroot>/logs/package/kernel/mac80211 and view the compile.txt found there.
Depending on your CPU, the process will take a while, or while longer. If you want an acoustic notification, you could use
echo -e '\a':
make V=s ; echo -e '\a'
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
E.g. if your <buildroot_dir> is
~/openwrt/trunk, the binaries are in
You might need to clean your build environment every now and then. The following
make-targets are useful for that job:
deletes contents of the directories
deletes contents of the directories
/build_dir and additionally
/toolchain (=the cross-compile tools) and
/logs. 'Dirclean' is your basic "Full clean" operation.
nukes everything you have compiled or configured and also deletes all downloaded feeds contents and package sources.
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.
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.
Clean package base-files objects.
First get more information on the problem using the make option
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.
Try to update the main source and all the feeds (Warning! May result in other problems). Check for a related bug in (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). Compiling with make -j … sometimes gives random errors. Try compiling without -j first before reporting the problem.
GREP_OPTIONSshould not have
–initial-tabor other options affecting its output
SEDshould not be set. If it is, run `unset SED` before compiling. (See Ticket 10612.)
- Have you run this command? See this.
./scripts/feeds install <package>
- Maybe you are not looking for it in the right submenu. See the
Makefileof the package to find out.
You are looking for this:
define Package/<package>/Default SUBMENU:=Firewall SECTION:=net CATEGORY:=Network
- Menuconfig appears to cache package lists and (especially) profiles. Try deleting the
<buildroot_dir>/tmpdirectory and then running
cd ~/openwrt/trunk rm -rf tmp make menuconfig
Also try refreshing your package indexes:
./scripts/feeds update -i
-iis important if you're not using the latest revisions of any packages, as this flag prevents updates from the feed sources.
Make sure the path starts with
package directory and that the path actually exist. The structure of
package/feeds directory is different. See this.
make feeds/packages/utils/screen/compile V=s
make package/feeds/packages/screen/compile V=s
make menuconfig and enable compilation for your package. It should be labeled with
<M> to work correctly. Read image.configuration further up in this article.
doc/howto/build.txt · Last modified: 2014/03/05 22:21 by guraltsev