FIXME This page is not fully translated, yet. Please help completing the translation.
(remove this paragraph once the translation is finished)

编译环境 – 使用说明

:!: 请使用普通用户进行操作, 不要使用 root 帐号或sudo!
:!: 请确保在剩余空间充足的路径下进行
所有的构建命令都请在 <buildsystem root> 目录下执行, 例如在 ~/source/ 路径下执行 git clone

  1. 更新源码.
  2. 更新软件包库及安装软件包.
  3. 配置需要构建的固件映像.
  4. 开始构建. (自动化构建工具链, 交叉编译源码, 组件打包并且生成映像文件).

:!: 开发分支的代码变动频繁,请确保使用最新源码进行构建

git pull

:!: 在脚本 ./scripts/feeds 中的安装表示“使软件包在make menuconfig中可用”而不是立刻安装并编译它们.
在您进行了一段时间开发后,您本地的软件包可能已经过时了,可以通过执行 “feeds update -a” 获取最新的软件包.

  1. 更新库:
    ./scripts/feeds update -a
  2. 下载软件包并让它们在make menuconfig中可用:
    • 单个软件包:
      ./scripts/feeds install <PACKAGENAME>
    • 所有软件包:
      ./scripts/feeds install -a

* 在feeds.conf.default文件中加入一行:“src-link my_packages ~/$buildroot/my_packages”

例如: src-link my_packages /home/$username/src/openwrt/my_packages (将$username替换成您的home目录)

* 创建目录:

mkdir -p $buildroot/my_packages/$section/$category/$package_name



mkdir -p my_packages/net/network/rpcbind
相关的章节及目录在MakeFile中找到。 同理, "openwrt" 即为 $buildroot 构建根目录。

* 从github下载Makefile文件, 从sources.openwrt.org下载软件包源码并放到 $package_name 路径下。

* 执行:

./scripts/feeds update -a ; ./scripts/feeds/ install $packagename

* 你可以通过再次执行 “install” 以解决软件包依赖问题。


  1. 运行 make menuconfig 选定目标映像;
  2. 运行 make defconfig 为构建环境和设备设定默认配置;
  3. 运行 make kernel_menuconfig (可选);
  4. 运行 make menuconfig 配置软件包;
  5. 运行 make download (在最终构建前下载所有依赖, 并激活多线程编译);
  6. 运行 scripts/ >mydiffconfig (将所有修改保存到 mydiffconfig 文件);

The build system 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 build system configuration interface by writing the following command:

make menuconfig

This will update the dependencies of your existing configuration automatically, and you can now proceed to build your updated images.

You will see a list of options. This list is really the top of a tree. You can select a list item, and descend into its tree.

To search for the package or feature in the tree, you can type the “/” key, and search for a string. This will give you its locations within the tree.

For most packages and features, 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 opkg after flashing the firmware image file to the device.)
  • pressing n sets the < > 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.

When you open menuconfig you will need to set the build settings in this order (also shown in this order in menuconfig's interface):

  1. Target system (general category of similar devices)
  2. Subtarget (subcategory of Target system, grouping similar devices)
  3. Target profile (each specific device)
  4. Package selection
  5. Build system settings
  6. Kernel modules

Select your device's Target system first, then select the right Subtarget, then you can find your device in the Target profile's list of supported platforms.

Beside make menuconfig another way to configure is using a configuration diff file. This file includes only the changes compared to the default configuration. A benefit is that this file can be version-controlled in your downstream project. It's also less affected by upstream updates, because it only contains the changes.

Creating diff file

This file is created using the ./scripts/ script.

./scripts/ > diffconfig # write the changes to diffconfig

Note: Since r2752 LEDE firmware make process automatically creates the configuration diff file config.seed file to the target image directory.

Using diff file

These changes can form the basis of a config file (<buildroot dir>/.config). By running make defconfig these changes will be expanded into a full config.

cp diffconfig .config   # write changes to .config
make defconfig   # expand to full config

These changes can also be added to the bottom of the config file (<buildroot dir>/.config), by running make defconfig these changes will override the existing configuration.

cat diffconfig >> .config   # append changes to bottom of .config
make defconfig   # apply changes

The build system integrates quilt for easy patch management:

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

E.g. if your <buildroot dir> is ~/source and you want some files to be copied into firmware image's /etc/config directory, the correct place to put them is ~/source/files/etc/config .

make defconfig

will produce a default configuration of the target device and build system, including a check of dependencies and prerequisites for the build environment.

Defconfig will also remove outdated items from .config. E.g. references to non-existing packages or config options.

It also checks the dependencies and will add possibly missing necessary dependencies. This can be used to “expand” a short .config recipe (like diffconfig output, possible even pruned further) to a full .config that the make process accepts.

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:

make kernel_menuconfig CONFIG_TARGET=subtarget

CONFIG_TARGET allows you to select which config you want to edit. possible options: target, subtarget, env.

The changes can be reviewed with

git diff target/linux/

and reverted with

git checkout target/linux/

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 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 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.

Before running final make it is best to issue make download command first, this step will pre-fetch all source code for all dependencies, this enables you compile with more cpu cores (for example, make -j10, for 4 core, 8 thread cpu works great).

If you try compiling OpenWrt on multiple cores and don't download all source files for all dependency packages it is very likely that your build will fail.

make download

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


make download will pre-download all source code for all dependencies, this will enable multi core compilation to succeed, without it is is very likely to fail. make -jX will speed up compilation by using up to X cores or hardware threads to speed up compilation, make -j9 fully uses 8 cores or hardware threads.

Example of pre-downloading and building the image(s) on a 4 core CPU:

make -j5 download world

Building in the background

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 (4 core, 8 thread CPU):

make download
ionice -c 3 nice -n19 make -j9

Building single Packages

When developing or packaging software, it is convenient to be able to build only the package in question (e.g. with package cups):

make package/cups/compile V=s

For a rebuild:

make package/cups/{clean,compile,install} V=s

It doesn't matter what feed the package is located in, this same syntax works for any installed package.

Spotting build errors

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 '[^_-"a-z]error[^_-.a-z]' 

The above saves a full verbose copy of the build output (with stdout piped to stderr) in ~/source/build.log and shows errors on the screen (along with a few spurious instances of 'error').

Another example:

ionice -c 3 nice -n 20 make -j 2 V=s CONFIG_DEBUG_SECTION_MISMATCH=y 2>&1 | tee build.log

The above saves a full verbose copy of the build output (with stdout piped to stderr) in build.log 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. i.e.: 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

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'

Skipping failed packages

If you are building everything (not just the packages to make a flashable image), you will probably want to keep building all packages even if some have compile errors and won't be built.

IGNORE_ERRORS=1 make <make options>

After a successful build, the freshly built image(s) can be found below the newly created <buildroot_dir>/bin directory. The compiled files are additionally classified by the target platform and subtarget, so e.g. a generic firmware built for an ar71xx device will be located in <buildroot_dir>/bin/targets/ar71xx/generic directory (and the package files are below <buildroot_dir>/bin/packages/mips_24kc).

E.g. if your <buildroot_dir> is ~/source, the binaries are in ~/source/bin/targets/ar71xx/generic and ~/source/bin/packages/mips_24kc.

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

make clean

deletes contents of the directories /bin and /build_dir.

make clean does not remove the toolchain, and it also avoids cleaning architectures/targets other than the one you have selected in your .config

It is a good practice to do make clean before a build to ensure that no outdated artefacts have been left from the previous builds. That may not be necessary always, but as a general rule it helps to ensure quality builds.

make dirclean

deletes contents of the directories /bin and /build_dir and additionally /staging_dir and /toolchain (=the cross-compile tools), /tmp (e.g data about packages) and /logs. 'Dirclean' is your basic “Full clean” operation.

make distclean

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). Use only if you need a “factory reset” of the build system!

There are numerous other functionalities in the 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.

make target/linux/clean

Clean package base-files objects.

make package/base-files/clean

Clean luci.

make package/luci/clean
  • Beware of unusual environment variables such as
    • SED should not be set. If it is, run `unset SED` before compiling. (See Ticket 10612.)
  • First get more information on the problem using the make option “make V=sc” or enable logging.

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 the bugtracker (depends from the feed the package comes from). Otherwise report the problem there, by mentioning the package, the target data (CPU, image, etc.) and the code revisions (main & package).

Run make menuconfig and enable compilation for your package. It should be labeled with <*> or <M> to work correctly.

When you execute make to build a flashable image for your device, both a sysupgrade and a factory image should be generated for every board that is linked to the device profile that you have selected via make config or make menuconfig.

If running make does not yield images for one (or even all) of the boards linked to the device profile that you have selected, than you probably have selected/enabled too many options or packages, and the image was too big to be flashed onto your device.

This website uses cookies. By using the website, you agree with storing cookies on your computer. Also you acknowledge that you have read and understand our Privacy Policy. If you do not agree leave the website.More information about cookies
  • Last modified: 2019/12/05 11:13
  • by