NSLU2-Linux
view · edit · print · history

This whole page is mostly obsolete. See the Development HomePage instead.

Overview

This document represents a step-by-step description of how to build the Unslung or OpenSlug firmware using OE. Thanks to Kergoth for writing the first version of this page.

The phases of the build

The entire build is done in several steps (all of which are explained in detail below):

  1. download BitBake from the BitBake SubVersion repository
  2. download the openembedded/ source from the nslu2-linux repository
  3. edit one or more configuration files to reflect that you're building for an nslu2
  4. $ bitbake unslung-image, whose eventual output will be a flashable image for your device

The required hardware

You should have at least 512MB RAM to complete this process with reasonable amount of swapping.

As of 2005-01-18 the /home/slung directory needs at least 3.3GB. The temp build directory "/home/slug/build/tmp" for "bitbake unslung-image" needs 2.5GB and can be changed by editing /home/slug/build/conf/local.conf and adding TMPDIR=/new/path/to/tmp/dir. The tmp dir should not be a symlink as this will break autconf.

The temp build directory for OpenSlug requires approximately 2GB (2005-01-25).

The required software

There is already a wiki page that describes what (non-OE) software should already exist on your Linux system -- see our Required Software page.

First, regarding the actual _required_ software, a couple of observations:

  • A FC2? system has only version 2.5.4 of the patch utility, but this seems to be adequate. I don't know of any compelling reason to have to upgrade to version 2.5.9 as the Required Software page suggests; if anyone knows, feel free to add it here, but version 2.5.4 appears to work just fine.
  • There is apparently no way to avoid building the documentation packages so, yes, you do need the various DocBook? and SGML tools. This is an unfortunate situation that is out of our hands (talk to the BitBake maintainers if you feel strongly about it).

Regarding what are actually _optional_ packages:

  • The Psyco JIT Compiler may be optional, but it's *strongly* recommended -- it will speed things up noticeably.
  • The ccache compiler cache program is also optional, but if you're going to use it, note that it will only speed things up after your first build. It won't make any difference when you're starting from scratch. And if you plan on using it, apparently, you have to use it right from the beginning -- adding it later will cause problems with libtool. Bottom line -- use it right from the start, or don't use it at all.

If you want a tutorial on ccache, I suggest this(approve sites), but you don't really need to know how it works to take advantage of it.

Where to next?

You now have the option of following the StepByStepSetup, which will tell you what to do, without explaining much of the reasoning, or you can continue with the following steps, which give extra information, but require you to fill in some blanks.

Set up a workspace

 mkdir /home/slug

 cd /home/slug

Getting the BitBake software

Your first job is to download the BitBake software. Install SubVersion, and then run:

 svn co svn://svn.berlios.de/bitbake/trunk/bitbake

This will create a bitbake/ directory in the current directory. Remain in this current directory (not the bitbake subdirectory) for the following steps (all the other directories go alongside the bitbake/ directory).

Installing BitBake Software

After downloading BitBake you will need to install the BitBake software. To install, cd into the BitBake directory you just created and type ./setup.py install --prefix=/usr/local --install-data=/usr/local/share

(If you get an error: "./setup.py: No such file or directory", then you might have to install python and then use the command # python setup.py install --prefix=/usr/local --install-data=/usr/local/share) - willpost

Important: once you have installed the bitbake software the installed version takes precedence over the version in the svn tree. If you subsequently follow the StepByStepSetup instructions these do not install the software, but python will find the old installed versions. Either reinstall or remove or rename the installed bb directory.

Now type bitbake at the command line and see if there are any errors. If you get an error about not being able to load the bb module you need to modify your PYTHONPATH variable. To do this type export PYTHONPATH=/usr/local/lib/python2.3/site-packages/:$PYTHONPATH.

You will also need to set up the BBPATH variable. It needs to contain /path/to/build:/path/to/openembedded. (The path to your build directory should come first.) BBPATH and other necessary variables that were set by oe.env can now be set with the script bitbake/contrib/bbdev.sh.

Getting the OE packages and metadata

Your next job is to download the OE-related openembedded/ directory. You get them from the BitKeeper repo. (no you don't. the project no longer uses bitkeeper.) The process for doing this is documented at http://openembedded.org/cgi-bin/moin.cgi/BitKeeper, but you must get them from the following nslu2-linux repository instead of the ones stated on that page:

 bk://nslu2-linux.bkbits.net/openembedded

NOTE: Your host name must be fully qualified (host.domainname) for this process to complete.

All you're after is the downloading and creation of one sibling directory:

  • openembedded/ (about 100M)

NOTE: If you are upgrading from a pre-bitbake situation. It is better to redo this step.

    cd ${OEROOT}    
    rm -rf packages/
    bk clone bk://nslu2-linux.bkbits.net/openembedded

The directory structure

Once you've downloaded the bitbake/ and openembedded/ directories, you need to create a few more directories and files to complete the picture before you can start your build. Here's a fairly generic directory structure you can use for the build, along with some representative variable names that, in some cases, match their usage in some of the configuration files:

   /home/slug/                (OEROOT, wherever you downloaded the previous stuff)
          bitbake/            (OESYS)
          openembedded/       (PKGDIR)

In addition to the above, you'll have to create (or they'll be created for you) the following, also directly under your OEROOT directory:

          build/              (OEBUILD)
             conf/
                local.conf
             tmp/             (TMPDIR)
          sources/

Of the above, you only need to create the build/conf/local.conf file; the other two directories will be created automatically when you do a build so you can ignore them for the time being.

  • NOTE* that you can create the tmp/ and sources/ directories elsewhere if you want, just by setting the appropriate variables in your configuration file, as explained in the next section.

Setting up your build/conf/local.conf file

Grabbing a template for this file from your openembedded/ directory and make it writable:

 $ cp ${PKGDIR}/conf/local.conf.sample ${OEBUILD}/conf/local.conf
 $ chmod u+w ${OEBUILD}/conf/local.conf

customize your copy of that file to reflect your build environment and final image, something along the lines of:

  OEROOT = /home/slug
DL_DIR = ${OEROOT}/sources
BBFILES = ${OEROOT}/openembedded/packages/*/*.bb
MACHINE = nslu2
DISTRO = unslung

In the case you are targeting an OpenSlug build, alternatively set

  DISTRO = openslug

Finally, remove or comment out the last line -- the one containing "=REMOVE_THIS_LINE=".

Creating and running the bb.env environment script

Simply copy and paste the sample commands below into a file called bb.env and then the command source bb.env will get you going. (Note that this file will need to be modified to match the paths on your system, the OEROOT is probably the only one that needs changed if you've put your workspace in a different place)

Once you do that, your working environment has been set up and you're in the build/ directory, ready to go.

Note that all subsequent =bitbake= commands have to be run from within the build/ directory.

Sample bb.env file:

export OEROOT=/home/slug
#the directory into which you downloaded everything

export PKGDIR=${OEROOT}/openembedded
#the directory that contains all of the packages

export BUILDDIR=${OEROOT}/build
#directory where all builds are done

export PYTHONPATH=/usr/local/lib/python2.3/site-packages/:$PYTHONPATH
#Setup python to find the bb module

export BBPATH=${BUILDDIR}:${PKGDIR}

cd ${BUILDDIR}

Pre-fetching the sources

When you eventually start a build, part of the build process is to download a pile of sources, by default into the directory ${OEROOT}/sources. If you want to get that out of the way first, or if you want to pre-fetch those sources in preparation for disconnecting from the net and still being able to do a build later, you can run:

 $ bitbake -cfetch unslung-image

This will load up your sources/ directory without actually starting the build process. Of course, this step is entirely optional. (On my system, that directory consumes about 230M of space, so you definitely want to have a fast net connection.)

Building the image(s) and getting the results

All of the build intermediate results are placed in the directory ${OEROOT}/build/tmp, so make sure you have sufficient room for this. To build a minimal flashable image, run:

 $ bitbake unslung-image

or

 $ bitbake openslug-image

The results will show up in .../build/tmp/deploy/images/.

Use the usual upgrade method to load the openslug-nslu2-timestamp.flashdisk.img file, see HowTo.InstallUnslungFirmware.

Redoing the build from scratch

If you want to redo a build, or the build failed and you made some fixes, all you need to do is remove the entire .../build/tmp/ directory, and rerun the oemake unslung-image command. Before you do that, however, if you want to keep up to date, you might want to make sure you have the latest versions of everything in your openembedded/ directory by running:

 $ (cd openembedded ; bk pull ; bk -r co -q)

Under some circumstances changes in bitbake itself may result in the system not building after a pull. You will then have to update the bitbake source code from svn. One example of the effects of this is at the end of StepByStepSetup. In general this is worth double checking if the build starts giving mysterious python tracebacks after a pull.

Speeding up the bitbake

It's possible to restrict the bitbake of the OpenEmbedded packages to only Unslung and OpenSlug packages. This reduces the numeber of packages from 2000 to around 330.

The instructions are on the the following page:

http://www.nslu2-linux.org/wiki/OpenEmbedded/NSLU2PackageSymlinks

By using NSLU2PackageSymlinks a Duron 2GHz with 768MB did a bitbake unslung image in 75 minutes.

Problems & Solutions

2005-01-19: There might be a problem doing a "bitbake unslung-image" without the NSLU2PackageSymlinks. Please try using the instructions on http://www.nslu2-linux.org/wiki/OpenEmbedded/NSLU2PackageSymlinks.

Page last modified on August 21, 2005, at 11:26 AM