Image Generator (Image Builder)

→ go back to obtain.firmware

If you do not want to download a prebuilt image or go through the entire compilation process, the alternative is to use Image Generator (formerly called Image Builder). This is a pre-compiled OpenWrt build environment suitable for creating custom images without the need for compiling.

Reasons for using Image Generator are:

  • Embedding packages directly into the SquashFS to reduce space requirements on the target
  • Preconfigure images by embedding packages and configuration files directly into SquashFS, and save manpower when flashing many devices
  • Building minimal images. for example without the web interface
  • Learning

Image Generator is the program that creates the OpenWrt firmware image file. In the process of compiling OpenWrt, Image Generator is coercively created (compiled), because it is needed to eventually create the image file. It is located in /openwrt/trunk/xxx and you can use it, to create more image-files from the packages you obtained during compilation.

But you can also simply download an archive which contains Image Generator and a whole load of packages from OpenWrt.


Download OpenWrt Attitude Adjustment 12.09

http://downloads.openwrt.org/attitude_adjustment/12.09/

  • Click on your architecture, for example ar71xx
  • Download the ImageBuilder archive.
  • Extract the archive and change into the ImageBuilder directory

Example: Attitude Adjustment for ar71xx architecture

cd ~
mkdir openwrt && cd openwrt
wget http://downloads.openwrt.org/attitude_adjustment/12.09/ar71xx/generic/OpenWrt-ImageBuilder-ar71xx_generic-for-linux-i486.tar.bz2
tar -xvjf OpenWrt-ImageBuilder-ar71xx_generic-for-linux-i486.tar.bz2
cd OpenWrt-ImageBuilder-ar71xx_generic-for-linux-i486

Download OpenWrt Barrier Breaker (Bleeding Edge Snapshots) EXPERIMENTAL

WARNING The link below is for bleeding edge snapshots of OpenWrt. Development snapshots include experimental changes to OpenWrt that are considered unstable. The current stable release is OpenWrt Attitude Adjustment 12.09.

http://downloads.openwrt.org/snapshots/trunk/

  • Click on your architecture, for example ar71xx
  • Download the ImageBuilder archive.
  • Extract the archive and change into the ImageBuilder directory

Example: Barrier Breaker for ar71xx architecture

cd ~
mkdir openwrt && cd openwrt
wget http://downloads.openwrt.org/snapshots/trunk/ar71xx/OpenWrt-ImageBuilder-ar71xx_generic-for-linux-x86_64.tar.bz2
tar -xvjf OpenWrt-ImageBuilder-ar71xx_generic-for-linux-x86_64.tar.bz2
cd OpenWrt-ImageBuilder-ar71xx_generic-for-linux-x86_64

Usage

The make image command will create a minimal image with just essential packages included, the behavior can be controlled with three variables passed as arguments:

  • PROFILE - specifies the target image to build
  • PACKAGES - a list of packages to embed into the image
  • FILES - directory with custom files to include

Syntax:

$ make image PROFILE=XXX PACKAGES="pkg1 pkg2 pkg3 -pkg4 -pkg5 -pkg6" FILES=files/

See the sections below for an explanation. After the make command is finished, the generated images are stored in the bin/architecture directory.

The example below shows the contents of bin/ directory after successfully generating an OpenWrt Barrier Breaker image for WNDR3700. The architecture for WNDR3700 is ar71xx, so the exact location of the image is bin/ar71xx
user@linux:~/openwrt/OpenWrt-ImageBuilder-ar71xx_generic-for-linux-x86_64$ ls -aR bin
bin:
.  ..  ar71xx

bin/ar71xx:
.                                         openwrt-ar71xx-generic-vmlinux-lzma.elf
..                                        openwrt-ar71xx-generic-wndr3700-squashfs-factory.img
md5sums                                   openwrt-ar71xx-generic-wndr3700-squashfs-factory-NA.img
openwrt-ar71xx-generic-rootfs.tar.gz      openwrt-ar71xx-generic-wndr3700-squashfs-sysupgrade.bin
openwrt-ar71xx-generic-root.squashfs      openwrt-ar71xx-generic-wndr3700v2-squashfs-factory.img
openwrt-ar71xx-generic-root.squashfs-64k  openwrt-ar71xx-generic-wndr3700v2-squashfs-sysupgrade.bin
openwrt-ar71xx-generic-uImage-gzip.bin    openwrt-ar71xx-generic-wndr3800-squashfs-factory.img
openwrt-ar71xx-generic-uImage-lzma.bin    openwrt-ar71xx-generic-wndr3800-squashfs-sysupgrade.bin
openwrt-ar71xx-generic-vmlinux.bin        openwrt-ar71xx-generic-wndrmac-squashfs-factory.img
openwrt-ar71xx-generic-vmlinux.elf        openwrt-ar71xx-generic-wndrmac-squashfs-sysupgrade.bin
openwrt-ar71xx-generic-vmlinux.gz         openwrt-ar71xx-generic-wndrmacv2-squashfs-factory.img
openwrt-ar71xx-generic-vmlinux.lzma       openwrt-ar71xx-generic-wndrmacv2-squashfs-sysupgrade.bin

PROFILE Variable

Syntax:

$ make image PROFILE=NAMEOFPROFILE

Pre-defined Profiles

Run make info to obtain a list of defined profiles. Example output from make info is listed below.

brcm47xx Profiles
ar71xx Profiles

ar71xx Image Generator Profiles

After you find the appropriate profile pass it to the make image command:

EXAMPLE: Attitude Adjustment 12.09 for WNDR3700 (Atheros ar71xx architecture).

This will build OpenWrt for WNDR3700 with a bare-minumum feature set due to PACKAGES variable not being defined. For information on how to include or exclude packages, see PACKAGES Variable
$ make image PROFILE=WNDR3700

Then you would look for the image in the OpenWrt-ImageBuilder-ar71xx_generic-for-linux-i486/bin/ directory.

Adding/Modifying Profiles

Note that at least for the ar71xx architecture the image generation is tied to the profile names. If you add a new profile without also adding an appropriate macro to the image Makefile, no suitable firmware file will get generated when using the custom profile.
Make sure to remove the /tmp directory to get modified package selection from profiles to work.

The location of the profiles for the pre-compiled package for brcm47xx-for-Linux-i686 was target/linux/brcm47xx/profiles/

Remarkably, all that needs to be done to add a new profile, is to add a new file to the profiles directory.

Here is what the profiles/100-Broadcom-b43.mk profile file looks like:

define Profile/Broadcom-b43
  NAME:=Broadcom BCM43xx WiFi (default)
  PACKAGES:=kmod-b43 kmod-b43legacy
endef

define Profile/Broadcom-b43/Description
	Package set compatible with hardware using Broadcom BCM43xx cards
endef
$(eval $(call Profile,Broadcom-b43))

PACKAGES Variable

The PACKAGES variable specifies a list of packages to include and/or exclude when building an image with Image Generator.

Syntax:

NOTE: If the package name is prefixed with - then the corresponding package will be excluded from being built during make image.

The example below will include pkg1, pkg2, pkg3, and exclude pkg4, pkg5, pkg6.

$ make image PROFILE=XXX PACKAGES="pkg1 pkg2 pkg3 -pkg4 -pkg5 -pkg6"
Backfire 10.03.1-rc5 or later: Image Generator now uses opkg on the host to determine packages to install and to resolve their dependencies (which is especially useful if you use External Repositories), so the following warning does not apply!
Backfire 10.03 to 10.03.1-rc4: Using PACKAGES= will not install any of the default packages in your PROFILE. Be sure you include libuci. Without it uci won't work. Your router will boot but none of the interfaces will be configured effectively bricking your router (setting boot_wait first will let you recover via tftp).

Tip: The list of currently installed packages on your router running OpenWrt can be obtained with the command below:

echo $(opkg list_installed | awk '{ print $1 }')

Tip: The list of packages present in the current release of OpenWrt, Attitude Adjustment 12.09, can be obtained with this Linux command:

NOTE: Example is for ar71xx. Change the architecture and name of the config file as necessary.

echo $(wget -qO - http://downloads.openwrt.org/attitude_adjustment/12.09/ar71xx/generic/config.ar71xx_generic | sed -ne 's/^CONFIG_PACKAGE_\([a-z0-9-]*\)=y/\1/ip')

Tip: If you want to remove some of the default packages (for e.g. you do not need pppoe related packages), consult with the DEFAULT_PACKAGES and DEFAULT_PACKAGES.router section in the include/target.mk file.

Tip: External packages compatible with a given build (if you cannot use images from http://downloads.openwrt.org/ because you have compiled from trunk and trunk has changed since you compiled your image) can be found in packages directory.

FILES Variable

The FILES variable allows custom configuration files to be included in images built with Image Generator. This is especially useful if you need to change the network configuration from default before flashing.

Syntax:

$ make image PROFILE=XXX PACKAGES="XXX" FILES=files/

The following example shows:

  1. Creating the directory for the configuration files
  2. Using scp to transfer uci configuration files from an OpenWrt router to the files/etc/config directory
  3. Generating an image for WL500GP with custom packages and uci configuration files
mkdir -p files/etc/config
scp root@192.168.1.1:/etc/config/network files/etc/config/
scp root@192.168.1.1:/etc/config/wireless files/etc/config/
scp root@192.168.1.1:/etc/config/firewall files/etc/config/
make image PROFILE=WL500GP PACKAGES="nano openvpn -ppp -ppp-mod-pppoe" FILES=files/

Note: The files/ folder must be in the same folder where you issue the make command.

Cleanup

To clean up temporary build files and generated images, use the make clean command.

External Repositories

Trunk revisions since r22978 support external repositories in Image Generator. This option will be part of the final 10.03.1 release. To add external package repositories, edit the repositories.conf file in the toplevel directory. Sources are specified in opkg native config format.

For earlier versions of Image Generator, external packages can be downloaded into the packages/ directory. Image Generator will pick them up during index creation.

Building the Image Generator

It is possible to build the Image Generator from the sources from scratch:

:~/openwrt/trunk> svn up
:~/openwrt/trunk> rm .config
:~/openwrt/trunk> make menuconfig

In the graphical configuration, select Global Build Settings → Select all packages by default, exit and save. Then build the image, including IGNORE_ERRORS=1 as there might be unmaintained packages that fail to compile.

:~/openwrt/trunk> make IGNORE_ERRORS=1

Note: Don't call make defconfig or leave an old .config file in the path as Select all packages by default will only set the package selection to [m] for packages that are not already configured otherwise!(make defconfig will set most packages to [n], i.e. do not build.)

Back to top

doc/howto/obtain.firmware.generate.txt · Last modified: 2014/05/13 19:26 by tmomas