Nokia N810 and 770 Internet Tablets
Running Scratchbox

This writeup has been updated for the Scratchbox version to be used with Maemo-2.0 Mistral. It is very similar to the old one but a few items are a little different.

First let's define some terms.

Maemo

To summarize the official statement, Maemo is a suite of development tools and a pre-standardized user interface for producing software to run on the Nokia 770 and other handheld devices with decent displays.

(No Name)

In Linux terminology, a distro (distribution) is a coherent collection of software packages including a Linux kernel, and particularly including a package manager and a means to obtain updated packages from the distro's home. I haven't been able to detect an official name for the distro that's on the Nokia 770. However, it is similar to Debian, including in Maemo 2.0 the complete Debian package manager. As officially defined, Maemo is not a distro, but in fact Maemo.org is acting as the host site, and everybody is sure to say, Maemo is the distro used on the Nokia 770.

Hildon

Hildon is referred to as an Application Framework. It is a set of standards for how applications should appear to the user, and a suite of infrastructure to make this look-and-feel happen, specifically a window manager, a status bar, a task switcher, a background (home) screen, a control panel, and libraries to support all of this. In particular, the Hildon User Interface is implemented as a modified GTK+ (Gnome Tool Kit) library, binary compatible with standard GTK+. Hildon is the same kind of object as Gnome or KDE.

Scratchbox

Scratchbox is a cross-compilation tookit. Here is their home site. While it is particularly used by Maemo, and while the home site appears to be hosted or sponsored by Nokia, Scratchbox is not Nokia-specific and works with Familiar and Compaq IPaq. The host system is an Intel (i386) Linux box. Scratchbox includes compilers and libraries, and an ARM emulator. You use it to compile software and build packages that can run on the Nokia 770 and that can become part of the Maemo distro.

Some quick links:

• Maemo 2.0 Tutorial, including installing Scratchbox
• Scratchbox's own installation howto
• Where the Debian packages are
• Where the tarballs are
• Recommended /etc/apt/sources.list line: deb http://scratchbox.org/debian ./
• How to download the rootstraps

The Maemo site has an extensive tutorial for Maemo, Hildon and Scratchbox, which has been updated for Maemo-2.0. Some people have complained that it's too extensive. In truth, if you're going to port GTK or KDE apps for Maemo you need to know all that stuff, but there are some areas where it's not 100% clear, and so I've summarized a few items here about the basic installation and build process.

The tutorial mentions Debian or Ubuntu as host distros. I'm running it on SuSE 10.1 and have no problems. SuSE uses RPM as its package manager, and I wanted to install Scratchbox as a proper package. The apt package was useless; it's for using the Debian apt-get syntax but to really install from a mirror of the SuSE RPMs. I tried alien --to-rpm to convert the Debian packages to RPM. However, there were unmet dependencies (probably package names different from SuSE) and the pre/post install scripts were converted incorrectly so the "run_me_first.sh" script didn't get installed, nor was any proper setup done. Useless. I reverted to installing from tarballs.

Scratchbox is a pig. The tutorial says to allow 2 GB for it. My installed size with only the ARM target and very little package clutter, is 2.8 GB. Make sure you pick a spot for it where there's enough space. You may create a symbolic link /scratchbox that points to a directory in a larger filesystem.

The tutorial's installation section lists a number of source files to be downloaded. Both Maemo-1.1 and Maemo-2.0 have an installation script at the linked URL (change 2.0 to 1.1 to get the old one). This script, under the name installer.html, is a Bourne shell script with a mime-encoded executable program. It will download all the files and set everything up for you. I downloaded and un-tarred all the files by hand; if you use the installer, keep track of which steps it's doing for you, and don't do them again. The following list shows the needed files in dependency order.

• scratchbox-libs-0.9.8.8.tar.gz (13 Mbytes)
• scratchbox-toolchain-cs2005q3.2-glibc-i386-0.9.8.5-6.tar.gz (48 Mbytes)
• scratchbox-core-0.9.8.8.tar.gz (73 Mbytes)
• scratchbox-devkit-debian-0.9.8.8.tar.gz (2 Mbytes)
• scratchbox-toolchain-cs2005q3.2-glibc-arm-0.9.8.5-6.tar.gz (47 Mbytes)
• Maemo_Dev_Platform_v2.0_armel-rootstrap.tgz (145 Mbytes)
• Maemo_Dev_Platform_v2.0_i386-rootstrap.tgz (149 Mbytes)

You need to keep in mind what phase each instruction goes with, because different levels and frequencies are commingled in the tutorial.

1. Installation, only needs to be done once (as root). Run the installation script, or download and un-tar the Scratchbox tarballs yourself. (Download the i386 and ARM rootstrap packages but don't un-tar yet -- move them into /scratchbox/packages where a later step can find them.) Configure Scratchbox (following the tutorial's summary). This includes creating your home directory within /scratchbox. The homedir is /scratchbox/users/$USER/home/$USER, and /scratchbox/users/$USER is the root that you chroot into.

2. Startup, makes a bind mount to bring the tools into the chroot area. This needs to be done (as root) once per reboot of the host system. If you can't compile anything, you may have forgotten this step. If you're seriously into development on Scratchbox you may want to create a boot-time startup script for this. The command is /scratchbox/sbin/sbox_ctl start

3. Login as yourself (ordinary user), which (basically) does chroot to your home area. You'll probably want to do this in a separate xterm since you'll need to do things on the host also. The command is /scratchbox/login (no need to give your loginID).

   1. Once after installation you need to create your rootstrap target(s) and stuff it with the rootstrap package (large). SDK_PC is for debugging software without dealing with ARM emulation; SDK_ARM is for building (and/or testing) the software on the simulated actual ARM processor. To create the target: sbox-config -ct SDK_ARM (or SDK_PC). You need to answer these questions. For the compiler question you give a number from a list; you want the cs2005q3.2-glibc-$ARCH package, not the host compiler, and I've shown the corresponding numbers in the list shown to me, but follow your list, not blindly entering these numbers.

      Question	SDK_ARM	SDK_PC
      Compiler	0	2 (don't use host)
      CPU Transparency	qemu-arm	none
      Devkit	debian	debian

   2. You need to pick one or the other target (ARM or i386). Once you do this, the selection persists until changed. The commands would be

      • sbox-config -st SDK_ARM
      • sbox-config -st SDK_PC

   3. Once after installation you have some configuration to do for each target. Select it first with one of the commands above.

      1. Configure compiler: sbox-config -cc
      2. Configure root directory: sbox-config -cf
      3. Edit /etc/passwd (it's writable by you) to include your full name in the 5th field. dh_make needs this.
      4. Stuff the target with the rootstrap distro (target libraries and programs): sbox-config -er /scratchbox/packages/Maemo_Dev_Platform_RS_v2.0_arm.tgz (or i386, or whatever version is currently current).

4. Now, download your source code (for this demo I'm doing NTP) and copy it to your scratchbox homedir: cp /tmp/ntp-4.2.0.tar.gz /scratchbox/users/jimc/home/jimc/ Do all your normal procedures to build the package -- see the tutorial for lots of good info about porting. You're running on a simulated ARM processor, emulated by qemu-arm. If you do uname -m it will say arm rather than i686. Here's a sample procedure:

   • Unpack the software into a directory whose name has the form basename-version, e.g. ntp-4.2.0. Most packages include this dirname in the tar file. Since sntp was obtained as a subset of ntp, I'll have to rename its directory appropriately, i.e. sntp-1.6, this being the version declared in the README file.
   • dh_make -n -s -e jimc@math.ucla.edu
     Credit to OS Junkie for pointing out this step which non-Debian people wouldn't know about. There's also a useful Debian documentation article. I'm sure there is a lot you can do for building Debian packages that I've never encountered. In the command line, -n means the program is Debian native so don't generate .orig, which sounds important. -s means there is only one binary file in this package (-m for multiple). -e gives the e-mail address of the maintainer, which I assume means the maintainer of the package file, not of the software itself.
   • Modify the resulting files in the ./debian directory.
     • Probably you should list the original software's provenance in the README file. You can toss README.Debian.
     • Don't touch the changelog unless you know what you're doing (I don't). Same for compat.
     • conffiles -- Although NTP has a configuration file, SNTP doesn't, so this file could be tossed. It would have had a list of absolute path names of configuration files which should get special treatment in installation.
     • control --You need to edit the descriptions appropriately: the short one on the Description line, and following that, a long one where each line starts with whitespace (1 blank is OK). For Maemo-1.1 the instructions were to make the package depend on maemo; for Maemo-2.0 identify the library and other packages that yours actually depends on (basenames, without version) and list them here. If you're given a documentation stanza and you don't have or aren't going to include a documentation package, remove the stanza.
     • copyright -- It's best to copy the real copyright file from your package to replace the boilerplate that they give you.
     • cron.d -- An extended crontab file to be dropped into /etc/cron.d. SNTP is typically run from cron, but the servers have to be listed on the command line, so I'm not going to provide a default cron entry. Toss this file.
     • dirs -- I assume that this is a root-relative list of directories which the installer needs to create if missing. var/lib/sntp needed to be added.
     • docs -- A list of documentation files, relative to the source directory. I left this alone.
     • init.d -- NTP is supposed to run as a daemon, and its startup file needs to be provided. But we don't want that for SNTP. Toss this file.
     • ntp-doc.{docs,files} -- Seem to be no-ops. I left them alone.
     • rules -- This is a Makefile, with targets that dpkg-buildpackage is expecting. You particularly need to edit the configure command. For SNTP I used these options:
       • --host=$(XXX) --build=$(XXX) (leave as-is, comes out as arm)
       • --prefix=/usr -- Use your judgment on this. If the default for a particular package turns out to be /usr/local, you'll probably want to change it to /usr. Some packages will want --prefix=/ . Keep a close eye on where it thinks it's going to install your package, and if it comes out wrong, fix the prefix and do it over. Maemo-1.1 needed a prefix of /var/lib/install or /var/lib/install/usr for all packages.
       • --mandir --infodir (leave alone, won't be used I think)
       • LOCKNAME=/var/run/sntp.pid
       • SAVENAME=/var/lib/sntp/sntp.state
       • ADJTIME_MISSING=1
       • If there are optional features that are useless on the ITB you should turn them off to save installation and runtime memory. SNTP does not have any optional features.
       You also need to make sure there is a distclean: target in the package's own Makefile, or else do the equivalent manually before building.
     • All other files with names ending in .ex may be deleted, unless your package needs the relevant features, in which case rename the file to lose the .ex, and edit as needed.
   • To build the package: cd to the package directory, then dpkg-buildpackage -rfakeroot
     The result (sntp_1.6_arm.deb) is deposited in the containing directory, together with Debian administrative files which would be useful if submitting the package to a real Debian package archive. fakeroot is Scratchbox's special version of su which doesn't really su.

5. Here are some problems I encountered when working on NTP, as a guide to what might happen when you Maemo-ize other packages.

   • The rules file wanted to make distclean first, but one of the directory makefiles lacked a distclean target. (sntp)
   • It never ran ./configure. But when I did essentially the same thing for SNTP, ./configure was run properly.
   • The rules file did make install, but another of the directory makefiles lacked an install target. (util) It's installing into a subdirectory of debian, from which it will create the compressed tar or cpio component of the .deb file.

So how did SNTP come out? The program runs and displays the time offset, but run as root and given the -r or -a switches it doesn't actually change the time. So this project was not a stunning success, and I'm not going to debug the code. I suspect that my build procedure was not to blame; I'll bet there's something wacko with time management on ARM that SNTP (and I) don't know about.

On the other hand, ntpdate will change the system time; however, it requires /usr/lib/libelf.so (and its referent) which is present in Scratchbox but is not installed by default on the ITB, so I copied the libelf from scratchbox (this is really cowboy programming) and it lets ntpdate execute. (That was on Maemo-1.1; libelf.so.0 is present on Maemo-2.0.) I never finished making the full NTP into a package [on Maemo-1.1]; I just copied over that one executable. On Maemo-2.0 I did succeed in making the packages; ntpdate sets the time, but the NTP daemon just exits with no useful diagnostics even with debug turned on.

I've gotten so tired of using more, and rather than just copying less off scratchbox, I decided to make up a proper package for less. So how did this one go? I whipped together the control files, copyright notice, etc, and built the package, in less than 20 minutes. Again there was no distclean target (error was ignored). It did configure the package. [On Maemo-1.1] it produced the .deb file, but when doing dh_clean -k -i (possibly to build the nonexistent architecture-independent portion), dh_clean complained I have no package to build, which was no lie, and the procedure finished with an error, not having deposited the various Debian admin files (which I'm not going to use anyway). It works on the ITB! So now I have a decent pager. The build process was clean on Maemo-2.0.

Where is the Source?

Start at the Maemo.Org Cross Referencer, which is for navigating and displaying the Hildon and (some?) Osso sources.

This release notes document is for the original (1.0) Maemo release. It has a list of included packages, and it suggests that you use apt-get to get the binary and source packages (into Scratchbox). Version numbers are of course out of date, but likely you can make something happen on v1.1 also.