Note that parts of this are outdated. Currently we are on monotone 0.28, and a version of monotone >= 0.26 is needed. The global steps are still correct. If you are coming from a monotone <= 0.25 please remove the build dir (e.g. ~/slug) and start from scratch (after installing the latest monotone). If you have monotone 0.32 and above, you must run mtn db migrate.

The Master Makefile is for developing and building the latest and greatest HEAD! These instructions do not apply if all you want to do is build packages. Here are instructions for building Optware packages

For SlugOS development, you should read some OpenEmbedded bitbake recipe documentation.

Contents

• Standard steps
• Directory structure
• Software requirements
• Development with Windows (CoLinux)
• Development with Debian
• Development with Ubuntu 5.04
• Development with Ubuntu 5.10 "Breezy Badger" and 6.06 "Dapper Drake"
• Development with Ubuntu 7.04 "Feisty Fawn"
• Development with Gentoo
• Development with Fedora Core 4
• Development with MAC OS X (Intel)
• Development with Unslung
• Development with Openslug
• Development with Windows (VMWare Player and Ubuntu 5.10)
• If a package can't be downloaded
• Build a package (plus dependencies)

Standard steps

This is very simple if you have the required software dependencies (if unsure see below):

1. mkdir -p ~/slug
2. cd ~/slug
3. wget --cache=off http://www.nslu2-linux.org/Makefile
4. make <optional target>

NB 1: Don't even think about doing make as root. Chances are it will screw up your system libraries and executables. Best practise is to set up a new normal user and build using that.

NB 2: Downloading and building with the Master Makefile requires monotone 0.25. If you have an older version, then you will get a monotone error message like:

Note that as of right now (Jan 2006), the unslung package feed only has monotone 0.24, and building monotone on the nslu2 requires a build of boost, so you might as well give up now.

Note: If you have a monotone newer than 0.28 (Debian Etch has 0.31 at the time of this writing), you will get the database schema error, however this can be remedied with mtn db migrate -d monotone/nslu2-linux.mtn && mtn -d monotone/nslu2-linux.mtn db regenerate_rosters, but beware, this takes a LONG time ! ( rough time for mine was 4hours ( vmware machine )

Note: Debian unstable at time of writing has monotone 0.35 and the command to migrate the database is now regenerate_caches NOT regenerate_rosters as above.

Note: I tried to build it with my x86_64 (SUSE Linux 9.3 x86_64), build in 64bit mode failed because the image was to big in the end, when I forced 32bit mode (with linux32 make openslug-image) it failed with an internal gcc error.

Warning:When choosing a path to contain the build enviroment make sure to choose a path that contains NO SYMLINKS, otherwise building will fail (see also OpenSlugBuildFailsDueToSymlinks). Also make sure the volume on which you are working is mounted with the exec attribute (pmount, by default mounts volumes with noexec). Also make sure your path contains no spaces in any part of the path.

There's a bucketload of valid targets. For a complete list, peruse the Makefile. It should be quite easy to figure out what target you want to build.
Example targets include slugosle-image, openslug-image, unslung-image, optware-nslu2, optware-wl500g.

Before building you may need to download the two zip files from Intel. Check carefully to see what versions your environment will need; the versions are not interchangeable, nor are they upwards compatible. See the partial list below to see which ones you'll need.

• IPL_ixp400AccessLibrary-2_1.zip (25.03.2006: Intel has changed the name of the file into BSD_ixp400AccessLibrary-2_1.zip, however, renaming the file works fine; they also released 2.1.1, but that's just a patch against 2.1 and not yet compatible with this environment, so stay with 2.1 for now)
• IPL_ixp400NpeLibrary-2_3.zip

1. Go to http://www.intel.com/design/network/products/npfamily/download_ixp400.htm
2. Agree to the license and download "2.1 Download" of Intel Hardware Access Software (this gives you BSD_ixp400AccessLibrary-2_1.zip which must be renamed to IPL_ixp400AccessLibrary-2_1)
3. Go to http://www.intel.com/design/network/products/npfamily/download_ixp400.htm
4. Agree to the license and download "2.3 Download" of NPE Microcode (this gives you IPL_ixp400NpeLibrary-2_3.zip)

If you're building Openslug 3.10 then you need the 2.3 versions of the Intel libs from http://www.intel.com/design/network/products/npfamily/ixp400_current.htm

If you're building Openslug 4.8 and newer, then you need the 2.4 versions of the Intel libs from http://www.intel.com/design/network/products/npfamily/download_ixp400.htm

''DO NOT download the 3.0 versions -- this version is not used by any current firmware, and will not build.

Place these files along with their md5s in the downloads directroy. You can download these files from http://www.intel.com/design/network/products/npfamily/ixp425swr1.htm after logging in and supplying a lot of personal information, or you can use the Alternative method suggested above.

To generate the md5sums, you can use the md5sum utility like this:
md5sum -b IPL_ixp400AccessLibrary-2_1.zip | awk '{print $1}' > IPL_ixp400AccessLibrary-2_1.zip.md5
md5sum -b IPL_ixp400NpeLibrary-2_3.zip | awk '{print $1}' > IPL_ixp400NpeLibrary-2_3.zip.md5

If you have already done a majority of the MasterMakefile build, saw the error about the missing Intel drivers and did the fix above; you don't need to restart the build! Just go to the 'openslug/tmp/stamps' directory and remove the 'ixp4xx*' files. Then all you need to do is go back to the top level and restart your 'make'. It will continue where it left off.

If you use ccache, then it's important that CCACHE_PATH is not set because then the cross-compiler cannot be found.

A quick start is to run

make setup

followed by

make openslug-image

It will download all the files necessary for building a complete cross development environment. After that it will download all packages and the kernel needed for the openslug firmware, crosscompile them and combine them into a firmware package.

Note that the Makefile will build the entire distro rather than just the flash image. To fix this, edit the makefile and change "-k distro" to "-k image". I use sed like this:
mv Makefile Makefile.ORIG
sed -e s/-distro/-image/ Makefile.ORIG > Makefile
Then you can build the kernel, ramdisk, and a complete flash image without loads of other stuff including even X11!

Also the Makefile builds the latest HEAD: if you want the stable version, make a target like debianslug-3.10-beta or openslug-3.10-beta.

If you have lots of time (out for the night?) and disk space (as of September 2005: 7GB), you can easily kick off make build-openslug, too. That will do the development environment and firmware (as above), too. After that it will then download and compile every application package that can be installed. It should work quite automagically. (If you would rather not build all the application packages, there are a lot, then you can edit the file openembedded/packages/meta/slugos-packages.bb to build only the ones you want. This file is fetched in the build process so you will have to break the build in order to edit it -- maybe running 'make update' first will fetch the file. You can build individual packages using bitbake as described below.)

Another handy target is: make update (it could require a prior make setup or make setup-unslung setup-debianslug setup-openslug setup-ucslugc) You will get a directory structure, that looks like this:

If you encounter any problems while building this, please check, if there is already a bug filed at Trac or email your bug report to the nslu2-linux mailiing list. You might also check the OpenEmbedded Eventcounter to see, if any of your problem have been fixed since your last monotone checkout.
#openslug at irc.freenode.org is where your chances to get some first aid are the best. :)

OpenEmbedded contains much more packages than SlugOS, so you can add a package to openembedded/packages/meta/slugos-packages.bb, if there is already a bitbake file for it. After that, you can rerun make build-openslug and this time your package will be included in the feed. Alternatively you can do a
$ cd openslug; source setup-env; bb -b openembedded/packages/mynewpackage/mynewpackage_0.1.bb
or
$ cd openslug; . ./setup-env; bb -b openembedded/packages/mynewpackage/mynewpackage_0.1.bb

If you get kicked out of your shell when running one of the above commands, you should run make in the openslug directory, which will set up a file in the openslug directory. This file is parsed by setup-env and contains the right configuration that prevents you from being kicked out of your shell.

If you want a slim firmware, which leaves as much space on the flash as possible, you should build the ucslugc target rather than openslug. See the UcSlugC home page

If you're making changes to the code, config files, or other items, please be aware that when you commit your changes, your work is indelibly preserved for the community. Please follow the guidelines on the CommitGuidelines page; doing so is very helpful to others who might need to understand the nature of the changes you've made. Requirements:
boost - http://www.boost.org/
monotone - http://venge.net/monotone/ (Depends on boost)
cvs - http://www.gnu.org/software/cvs/
subversion - http://subversion.tigris.org/
python, bison, bzip2, unzip, texinfo, diffstat

Recommended:
ccache - http://ccache.samba.org/
psyco - http://psyco.sourceforge.net/

Development with Windows (CoLinux)

You can build the Master Makefile on a Windows system using 'coLinux' (http://www.colinux.org). Their wiki has various quick start guides.
A working solution would be to choose the Debian root fs image, increase the filesystem image size using 'toporesize.zip' to 5Gb at a minimum.
Once coLinux is up and running and you have used 'adduser' to add a non-root build account then apt-get install <package> the following packages:
gcc-3.3, cvs, flex, bison, make, pkg-config, rsync, gettext, libglib2.0-dev, autoconf, libtool, automake1.9, sudo and while your at it, your favourite editor e.g. emacs.
There are other dependancies listed below and I found using the Debian 'dselect' install program helped when installing monotone 2.4.

ben says: If you get mtn: command not found after installing monotone, try ln -s monotone mtn.
If you get error: failure extracting schema..., your montone version may be too old.
If you get misuse: layout of database..., your monotone version may be too new.
Your best bet (worked for me) is:

• get coLinux
• get the debian fs
• log in as root and adduser nslu2
• configure networking ("bridged" is easy)
• log in as nslu2
• mkdir slug; cd slug
• wget http://www.nslu2-linux.org/Makefile
• make setup-host-debian
• "make setup-host-debian" now also installs a current version of "monotone" (at the time of this writing v0.31-6). This works, but propably requires converting the database as described beneath. There is no need to install an older version of "monotone".
• make setup

"make setup" propably terminates after some time showing the following error-messages:

mtn: misuse: layout of database /home/nslu2/slug/monotone/nslu2-linux.mtn doesn't match this version of monotone
mtn: misuse: try "mtn db migrate" to upgrade

In this case enter the following commands to migrade the database:
mtn --db monotone/nslu2-linux.mtn db migrate
mtn --db monotone/nslu2-linux.mtn db regenerate_rosters

After the database has been converted, call "make setup" again.

Development with Debian

It is recommended, but not essential, to make a new user, to build using the Master Makefile.
Install Debian Sarge (Stable) or Etch (Testing)
Ensure you are using a testing repository (edit /etc/apt/sources.list or follow paragraph 5.2 on
http://www.debian.org/doc/manuals/reference/ch-woody.en.html#s-testing-transition)
Download the makefile as above and run:
make setup-host-debian
You have to install monotone separately from: http://venge.net/monotone/

NB: Root access required

NB: If you're using Debian Etch (testing) you can use the distros monotone and need not to download/install it seperately as described above.

NB: If you're using Debian Sid (unstable) you must use the older version monotone-0.25 still in the pool of the distro. Sid apparently switched to monotone-0.26 in May-2006. Monotone-0.26 uses an incompatible database format.
Get the monotone_0.25-0.1 Deb package from your favourite Mirror and Arch (here: i386)
Installing the package with dpkg -i monotone_0.25-0.1*
Set it on hold to prevent automatic upgrading: echo "monotone hold" | dpkg --set-selections

Development with Ubuntu 5.04

It is recommended, but not essential, to make a new user, to build using the Master Makefile.
Install Ubuntu 5.04 "The Hoary Hedgehog"
Ensure that you have the universe repositories enabled (edit /etc/apt/sources.list)
Download the makefile as above and run:
make setup-host-ubuntu
You have to install monotone separately from: http://venge.net/monotone/
NB: Root access required

Development with Ubuntu 5.10 Breezy Badger and 6.06 Dapper Drake

Proceed as described with Ubuntu 5.04 Note: Ubuntu 5.10 now (at least as of March 29. 2006) has Monotone 0.25 in its repo.
NB: With Ubuntu 5.10, I had the error :
make: [MT/.configured] Erreur 1 (ignorée) ( monotone -d monotone/nslu2-linux.db pull monotone.nslu2-linux.org org.{nslu2-linux.*,openembedded.dev} ) monotone: misuse: database schemas do not match: wanted 1509fd75019aebef5ac3da3a5edf1312393b70e9, got bd86f9a90b5d552f0be1fa9aee847ea0f317778b. try migrating database make: *** [MT/.configured] Erreur 1

Monotone version 0.23 was inadequate so you need to install 0.28. This can be downloaded from http://venge.net/monotone/downloads/monotone_0.28-dapper0.1_i386.deb
Install this by sudo dpkg -i monotone_0.28-dapper0.1_i386.deb

''monotone 0.24 which is comming with Ubuntu 6.06 and 6.10 (Edgy) is out of date for the current monotone repository (01.10.2006). You should install monotone 0.28 from here: http://monotone.ca/downloads/0.28/monotone_0.28-dapper0.1_i386.deb

NB: on Dapper you must "sudo aptitude install monotone diffstat python-psyco" in addition to setup-host-ubuntu

Development with Ubuntu 7.04 Feisty Fawn

Install monotone 'apt-get install monotone'. The current Makefile determines the monotone version and downloads the appropriate database version.
Make a directory for your build and change to it ('mkdir slug' and then 'cd slug' perhaps).
Run: wget http://www.nslu2-linux.org/Makefile to download the MasterMakefile.
Run: make setup-host-ubuntu to set up the environment.
Run: make update to make sure the database is current.
Run: make slugosbe-image to build the tools and build the images.

There are many different things you can build, I have worked with Openslug in the past and it was changed to slugosbe. To build Unslung, the command would be make unslung-image. To build the packages that can be installed, the command would be make slugosle-packages for example. This will take a while...:)

Development with Gentoo

It is recommended, but not essential, to make a new user, to build using the Master Makefile.
Download the makefile as above and run:
make setup-host-gentoo
This will unmask montone-0.24 and boost-1.32.0 NB: Root access required
Note: After a 2005.1 installation, the permissions of my root drive turned out to be wrong (340?). The correct permissions are 755 - if you do not check and correct this, the perl and boost builds will fail.

Alternatively, you can emerge required packages in Gentoo with (As of 2006.1, Jan-2007):
At /etc/portage/package.keywords:
dev-embedded/bitbake ~amd64
dev-libs/boost ~amd64
dev-embedded/bitbake ~amd64
dev-python/PyQt? ~amd64
dev-python/sip ~amd64
emerge boost bitbake PyQt? sip monotone bitbake
In addition, it needs another two packages:
emerge app-misc/git dev-util/diffstat
Then:
make update
When doing so, you will get an error message saying that the monotone database needs to be converted. You need to do the following:
mtn --db monotone/nslu2-linux.mtn db migrate
mtn --db monotone/nslu2-linux.mtn db regenerate_caches
Now you are ready to build the packages.
make openslug
for the whole nine yards or
make openslug-packages
just for the openslug packages

Development with Fedora Core 4

Install the needed packages through yum. The native compiler of FC 4 is gcc 4.0.2 but with that compiler it is possible to build the needed cross compiler (tested for optware and unslung image)

Development with MAC OS X (Intel)

At time of writing: download version 0.28 of mtn: http://venge.net/monotone/downloads/mtn-0.28-osx-univ.bz2

It might be that during provessing of the file errors occuring about missing tools (like git and gawk). Use port (can be downloaded form http://www.macports.org) to install these additional tools)

Completing the Makefile failed with the following messages:

NOTE: package quilt-native-0.45-r0: task do_configure: started ERROR: Information not available for target 'i386-darwin' NOTE: exceptions.TypeError?:iterable argument required while evaluating: ${@siteinfo_get_endianess(d)} ERROR: Information not available for target 'i386-darwin'

Don't know how to proceed

Development with Unslung

See NativelyCompileUnslungPackages

1. ipkg install unslung-devel

(But will this really work to recompile the kernel?)

Development with Openslug

See SlugOSNativeCompileEnvironment

Development with Windows (VMWare Player and Ubuntu 5.10)

• Download and install VMWare Playerhttp://www.vmware.com/download/player/
• Download and unzip Ubuntu Virtual Machine: http://www.vmware.com/vmtn/vm/ubuntu.html
• Note: You'll need at least 4 GB disk space on the partition you're going to use it. My VMWare Virtual Machine takes approximately 6.1 GB, so if you're still using FAT32, it's propably a good idea to convert it to NTFS, because FAT32 can't handle files > 4 GB.
  (e.g. convert drive D to NTFS: Start -> Run -> convert d: /FS:NTFS)
• Load the Ubuntu Virtual Machine into the VMWare Player
• Open a Terminal
• Edit /etc/apt/sources.list sudo gedit /etc/apt/sources.list (password: ubuntu)
• Put a # in front of the line that starts with deb cdrom:)
• Add deb http://us.archive.ubuntu.com/ubuntu breezy universe main restricted multiverse
deb http://security.ubuntu.com/ubuntu breezy-security universe main restricted multiverse
deb http://us.archive.ubuntu.com/ubuntu breezy-updates main restricted universe multiverse
  and save the file
• The above 'sources.list' entries did not work for me. I replaced the 'sources.list' file with the alternative on at <<http://www.psychocats.net/ubuntu/sources>>
• Run sudo apt-get update
• Run sudo apt-get upgrade
• Run sudo apt-get install autoconf automake automake1.9 bison \
ccache cvs docbook flex gcc g++ gawk gcj gettext libc6-dev libglib2.0-dev \
libtool m4 make patch pkg-config python python-dev python2.4 \
python2.4-dev sed texinfo unzip subversion bzip2 python2.4-psyco \
fakeroot dpkg-dev cdbs debhelper libboost-date-time-dev libboost-filesystem-dev \
libboost-regex-dev libboost-test-dev libboost-dev libz-dev \
diffstat texi2html
• Download the monotone source from http://www.venge.net/monotone wget http://www.venge.net/monotone/downloads/monotone-0.25.tar.gz
• Untar/gzip it tar xzvf monotone-0.25.tar.gz
• cd monotone-0.25
• dpkg-buildpackage -rfakeroot -uc -b # takes about 10-20 minutes
• cd ..
• sudo dpkg -i monotone_0.25-0.1_i386.deb
• Continue as described on the top of this page

If a package can't be downloaded

If a package can not be found (for example, at the moment the homepage of xinetd, http://www.xinetd.org is down so the build tools can't download xinetd-2.3.13.tar.gz from there) but you have a copy of the package file (for example, xinetd-2.3.13.tar.gz can be downloaded from ftp://gd.tuwien.ac.at/infosys/servers/xinetd/xinetd-2.3.13.tar.gz):

1. Download the package file to ~/slug/openslug/downloads/PACKAGENAME.tar.gz
2. Run:

 md5sum ~/slug/openslug/downloads/PACKAGENAME.tar.gz | \ 
 sed s/\ .*$// > ~/slug/openslug/downloads/PACKAGENAME.tar.gz.md5

3. Try running:

 make build-openslug

Build a package (plus dependencies)

To build a package for openslug or unslung, simply execute the following commands (in a bash shell) from the MasterMakefile directory (after checking out the repository):

% cd [openslug|unslung]
% source ./setup-env
% bb <package-name>

or if you are working on your own bitbake file

% bb -b my_file_0.00.bb

This will build the package represented by "<package-name>", if the package exists as a part of the distribution. If the package you want to build is not a part of the given distribution, you can try adding it by editing openembedded/packages/meta/slugos-packages.bb.

If you want to rebuild after making changes then use the bitbake command bb -c clean <package-name>.

The openembedded file format for .bb files is not well documented, I found useful this set of lecture notes http://www.vanille.de/tools/FOSDEM2005.pdf.

Build notes

I have just attempted the build from the source and encountered two issues.

1. Sleepycat does not have the db-4.3.27.tar.gz for download.

   I searched the net and found a copy. Dumped into download dir.
   Then created a checksum with md5sum.

2. There is an issue with your cvs download of irssi from your cvs.

   Edit the file openembedded/packages/irssi/irssi_cvs.bb 
   Add a line near the top
    CVSDATE = "20050930"
   Force the date and the build continues.