WORK-IN-PROGRESS! FOLLOW WITH CAUTION!

This page provides a description, suitable for following along at home, of how we have been creating the firmware image for the AlixCab and WgtCab devices that we've been working on.

Historical Context

• The AlixCab and WgtCab are named after the CloneArmyBox and subsequent NewCloneArmyBox (or NuCab) they are meant to replace. These predecessors were based on recycled PCs that we obtained for free and, running Debian GNU/Linux, repurposed as routers/gateway devices for our network installations. The AlixCab and WgtCab are based on the Alix single-board computer (from PC Engines in Zurich Switzerland) and the Netgear WGT634U, respectively. PersonalTelco is (as of late June 2009) part way through a purchase of 30 Alix boards. We already own or have deployed a number of Netgear WGT634Us. PersonalTelco has some Soekris board (typically as MetrixKits) deployed about as well, running various firmware. It is notable that the same firmware (or slight permutations) as described here can also run on the Soekris devices.

OpenWrt

• The respective firmware images for the AlixCab and WgtCab are both based on OpenWrt.

  In order to take advantage of the newest and shiniest features and bugfixes, as well as to add our own packages to images, we build the firmware ourselves rather than relying on specific binary image releases of OpenWrt. If you have (or can get easily) a Linux box with a few development tools, you can do this yourself without much difficulty. You will also need an internet connection.

  OpenWrt is built using a Makefile system called a buildroot. The Makefile infrastructure handles all the details of downloading source code, building the cross-compiling toolchain, compiling the packages and composing an image files suitable for flashing (or otherwise writing) onto the device. The buildroot system you obtain from OpenWrt is itself not very large. Instead, it has pointers to the source packages for everything it is going to build, and construction implies retrieving them to a local archive if you haven't already.

  We are typically building the most recent (or very nearly) version from OpenWrt's subversion (svn) tree. We are currently using a git version that synchronizes with the svn tree every 10 minutes.

Bleeding Edge

• Building the current version of a developing code base can sometimes not work. Don't be afraid to report non-workingness, using the Trac ticket system or on the freenode Irc channel #openwrt-devel. Over time, bit by bit, you learn about how the buildroot works and can begin to repair problems yourself and submit patches. Don't be afraid. Try, learn, develop.

Checkout

• There are often many ways of doing things and this is no exception. We'll show how we do it. If you like another way better, and it works for you, feel free to deviate. First thing to do is to check out OpenWrt's current "trunk" buildroot verion. In a directory where you ordinarily build software (we'll use /src in the examples here) and where you have at least several gigabytes of free disk space:

  • cd /src
    git clone git://nbd.name/openwrt.git

  Then, change directories into your shiney new buildroot, what is known in OpenWrt as $(TOPDIR), or in our case, /src/openwrt:

  • cd openwrt

Configuration

• The first thing to do after checking out the buildroot is to set up any feeds you want to use. A feed is basically a URL to a tree of packages that can be built using the buildroot. The primary feed is one called "packages". You almost certainly want to enable that one. Feeds are configured in a file called $(TOPDIR)/feeds.conf. The newly checked out tree will contain a file called feeds.conf.default, so make a copy of that to modify:

  • cp feeds.conf.default feeds.conf

  The file (as of lately) arrives containing this:

  • src-svn packages svn://svn.openwrt.org/openwrt/packages
    src-svn xwrt http://x-wrt.googlecode.com/svn/trunk/package
    src-svn luci http://svn.luci.subsignal.org/luci/branches/luci-0.8/contrib/package
    #src-svn phone svn://svn.openwrt.org/openwrt/feeds/phone
    #src-svn efl svn://svn.openwrt.org/openwrt/feeds/efl
    #src-svn desktop svn://svn.openwrt.org/openwrt/feeds/desktop
    #src-svn xfce svn://svn.openwrt.org/openwrt/feeds/xfce

  We aren't using anything from the xwrt or luci feeds currently, so we can comment those out. We'll change the packages feed to use git instead of svn and also to add a local feed for NoCatAuth (at least until we merge it upstream).

Building

• In what OpenWrt calls the $(TOPDIR), in our case /src/openwrt, building

  • make BUILD_LOG=1 IGNORE_ERRORS=m V=99 -j17

If things go reasonably well, the last thing you'll see is a list of:

• Generating index for package ./<pkgname>_<platform>.ipk
  make[2]: Leaving directory `/src/openwrt'
  make[1]: Leaving directory `/src/openwrt'

You can look in /src/openwrt/bin and find the images that were built, and in /src/openwrt/bin/packages/<platform-libversion-name>/ you'll find the package files you just built.

(MORE DETAIL TO FOLLOW SHORTLY)