Building OpenWrt

Pre-built images of the current OpenWrt release are always available, and easily found and downloaded from the OpenWrt website. These pre-built images are based on a default configuration, and only targeted at supported platforms/devices. There are several good reasons for why it is practical to build one's own images: Custom configurations Experimental platforms Participation in testing and development Or, simply keeping up-to-date

The best of it all is that, in reality, it is quite simple to build an OpenWrt image.

Prerequisites
1. To install all requirements for buildroot, please follow buildroot.exigence for your OS. 2. Read the Technical Reference for Buildroot NOTE: All examples on this page use '#' to indicate a shell prompt. This is not an indication that everything should be run as root. Except for apt-get, most of the commands should be run with normal user privileges. Before you get started with the actual building a few practical details have to be in place; as with any other process of building the correct tools and materials have to be ready and at hand. 1. A system for building the OpenWrt image 2. Ensure that the needed dependencies are installed 3. Copy of the OpenWrt source-code First of all, you need to have access to a system which supports the building of OpenWrt. It is recommended to use a Linux system, either as a standalone installation or as a separate system running in a virtual environment (Vmware or Qemu). It is potentially possible to build OpenWrt images directly on a *BSD or Mac OSX systems, but success is not guaranteed. The following description assumes the use of a current Debian system which uses apt-get for package management. An alternative choice would be one of the (Debian-based) Ubuntu variants (Kubuntu, Xubuntu etc.). In this step, the components upon which the OpenWRT build system depends will be installed. This includes compilers, unzip applications, specific libraries, etc. Simply type in the following command (which normally requires root or sudo privileges) in your shell of choice: 32 bit (x86) installs:

# apt-get install build-essential asciidoc binutils bzip2 gawk gettext \ git-core libncurses5-dev libz-dev patch unzip zlib1g-dev bison autoconf libextutils-autoins

64 bit (x86_64) installs will need multilib packages also:

# apt-get install build-essential asciidoc binutils bzip2 gawk gettext \ git-core libncurses5-dev libz-dev patch unzip zlib1g-dev ia32-libs \

lib32gcc1 libc6-dev-i386 bison autoconf

Consult this Table of Correspondence in order to find your prerequisites on platforms other than Debian/Ubuntu. Some of these dependencies might already be installed on the system, in which case apt-get will respond and ask what to do (ignore, re-install etc.).

Install Subversion
To download source code, you must have Subversion installed. Subversion, or SVN, is the current version control system used by the OpenWrt project, and it is quite similar to CVS in terms of interface and use. Again, this dependency is easily installed:
# apt-get install subversion

When Subversion is installed, the simplest way to confirm that everything works as assumed is to fetch a clean copy of the OpenWrt source. First you create a new directory in which to store the source-code, then move to this new directory and download ('check out' in svn parlance) the source by issuing the required Subversion command.

(Re-) Building Process

The process of creating the correct image for your specific device consists of a few simple steps: 1. 2. 3. 4. 5. Downloading/updating sources via Subversion Updating (and installing) package feeds Creating a default configuration to check pre-requisites (if necessary) Using Menuconfig to configure the image(s) to build Building the image

Downloading Sources
Finally, download a copy of the complete OpenWrt source code to your build system. You have two choices: Downloading the latest stable release, or Downloading the bleeding edge development snapshot (called "trunk").

Using Release Sources

As of this writing, the latest stable release is OpenWrt 10.03 "backfire". There is a Backfire branch in SVN repository, which is still slowly updated with verified patches. Using it will most likely produce a stable and working OpenWrt installation, but all the newest features and patches might not be there. As an example, this will check out the source code that the backfire release is built from (plus the latest backported fixes from trunk):
# mkdir OpenWrt/ # cd OpenWrt/ # svn co svn://svn.openwrt.org/openwrt/branches/backfire

NOTE: The above svn command will create a OpenWrt/backfire/ subfolder containing the newly checked out sources. You can also download a 'tagged' version of the sources of a certain release. For instance, if you insist on using the pristine release sources of Backfire 10.03 (no backported fixes applied), you could use:
# svn co svn://svn.openwrt.org/openwrt/tags/backfire_10.03

Using Development Sources

The current development branch (trunk) contains all the most recent experimental patches. It has all the features, but some of the new stuff may also break something for some hardware configurations, so using trunk is more adventurous.
# mkdir OpenWrt/ # cd OpenWrt/ # svn co svn://svn.openwrt.org/openwrt/trunk/

Before going ahead with the actual build process when building from trunk, it is a good idea to take a look at the contents of the trunk/ directory, as it is often convenient to be able to compare the contents of the directory before and after the actual build. More information on checking out sources can be found here: https://dev.openwrt.org/wiki/GetSource.

Updating Source
Since OpenWrt changes over time, it is recommended to use the latest sources. The following assumes that you are using the release sources.
## Here, backfire is the directory name of the current release branch you're tracking # cd OpenWrt/backfire/ # svn up

'svn up' is the command to use for updating local source code with the newest changes from the SVN repository. If no target path is specified, the command will update the source from the current directory and subdirectories.

Downloading Feeds
Feeds are additional package trees included in your OpenWrt environment. The most important feeds are 'packages' - many additional basic router features, 'LuCI' - the default www GUI for OpenWrt, and 'Xwrt' - alternative GUI. In a typical case, you will need at least 'packages' and 'LuCI'. Before downloading feeds (additional predefined package build recipes for OpenWrt) you can check which feeds sources you want to include. Just edit the file 'feeds.conf.default' in the base directory of your build environment. Then start the download with

# ./scripts/feeds update -a

After this the downloaded packages need to be installed. The installation step means they will be available during the 'make menuconfig' step later. Without this 'installation' step the packages will not be selectable in 'make menuconfig'.
# ./scripts/feeds install -a

The feeds configuration file makes it easy to add new or experimental packages sources to the build system. Just edit the file and run the update command. Note: Please note that this step replaces the old method of creating symlinks, which can be still found on-line in many old forum and user-group entries.

Updating Feeds
Just like the basic source code, you need to regularly update the feeds sources. That is done with the same commands:
# ./scripts/feeds update -a # ./scripts/feeds install -a

Note: If you know that you do not want to add possible new packages for menuconfig, you may skip the install step, when updating already existing feeds.

Making configuration
You may not have to make configration always after updating sources and feeds, but making it ensures that all packages from source and feeds are correctly included in your build configuration.

Defconfig
Next step is to produce a general purpose configuration of the build system including a check of dependencies and prerequisites for the build environment etc.
# make defconfig

Should the defconfig command report an error about a missing dependency, then the problem is easily solved with installing the missing package and then run the command again.

Menuconfig
Menuconfig is a text-based tool which handles the selection of target, packages to include in the build, kernel options etc.
# make menuconfig

This will update the dependencies of your existing configuration automatically and you can now proceed to build your updated images. The intention with the development of 'menuconfig' has been 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: 1. 2. 3. 4. 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. If you want to use LuCI, you'll need to go to the LuCI menu, then Collections, then choose luci. This will include full and mini admin and the standard theme. (you can explore here and customize later) If you don't need PPP, you can remove it by deselecting it under the Network menu. Using Menuconfig: Make sure you mark these packages as a '*' instead of just an 'M'. If you mark with a '*', the package will be built into the firmware you create. If you mark it with just an 'M', the package will be built but not installed. 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 and save. Source Mirrors The 'Build system settings' include some efficient options for changing package locations which makes it easy to handle a local package set: 1. Local mirror for source packages 2. 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. 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.

Building Images
Everything is now ready for building the image(s), which is done with a single command:

# make

Building on multicore systems The build process can be speeded up by using more than 1 concurrent job process. The most common suggestion is to use <your number of CPUs + 1> e.g. to use 3 concurrently building job processes (dualcore CPU), do:
# make -j 3

Building in the background If you intend to use your system while building, you can have the build process only use idle I/O and CPU capacity like this (dualcore CPU):
# ionice -c 3 nice -n 20 make -j 2

Building single Packages When developing or packaging software for OpenWrt, it is convenient to be able to build only the package in question (e.g. with package cups):
# make package/cups/compile V=99

For a package in the feeds it looks like this:

# make package/feeds/packages/ndyndns/compile V=99

Spotting build errors If for some reason the build fails, the easiest way to spot the error is to do:
# make V=99 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 build.log and only shows errors on the screen. Another example:
# 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)'

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.

Build scripts
Many people use shell script for building OpenWrt versions. You can find somes examples in the forum here: https://forum.openwrt.org/viewtopic.php?id=28267

Locating Images
After a successful build, the freshly built image(s) can be found in the newly created bin/ directory.
# cd bin/ # ls */

Cleaning Up
You might need to clean your build environment every now and then. The following make targets are useful for that job:

Clean
Cleaning the trunk/ directory after the build process is simple and only requires 'make clean'. It deletes contents of 'bin' and 'build_dir' directories.
## See CAUTION below # make clean

CAUTION: Make sure to move your compiled OpenWrt images to another location before issuing this command since it erases the contents of the "bin" directory (where the compiled OpenWrt images live).

Dirclean
If you want to clean in addition to the build directories also the cross-compile tools (in toolchain directory), use the 'dirclean' make, which does the same as 'clean' and also deletes 'staging_dir' and 'toolchain' contents. 'Dirclean' is your basic "Full clean" operation.
## See CAUTION below # make dirclean

CAUTION: Make sure to move your compiled OpenWrt images to another location before issuing this command.

Distclean
If complete cleaning of the build environment is required, then all it takes is 'make distclean'. It practically nukes everything you have compiled or configured and also deletes all downloaded feeds contents and package sources. Making distclean means quite a lot downloading afterwards, so it should not be used lightly. 'Dirclean' is enough for most cases.
## See CAUTION below # make distclean

CAUTION: In addition to all else, this will erase your build configuration (.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.

Installing OpenWrt
In comparison to the actual building of the desired image(s), the installation of the OpenWrt image can sometimes be a little, or more, of a challenge. It can be as simple as using the tools supplied by the manufacturer of the hardware (web interface or recovery tools), over manually uploading a new firmware via tftp and rebooting, to doing extensive hardware modifications with the intent of enabling JTAG access. Though, generally installation is made possible via the bootloader (Redboot, Uboot etc.) or simple copying onto a CompactFlash-card all depending on the specific device.