Documentation for packagers
Packagers make software available to others through Zero Install. To do this, you will need to be able to upload files to a publicly-accessible web server (eg, apache). The web server doesn't need to do anything special (there's no dynamic content, CGI scripts or anything like that); it just needs to serve the files you upload.
I share my webserver with others, and can't put files in the root!
If you can't make a file appear as http://somehost.org/NAME, you can put a '#' after your site name. Then, users access /uri/0install/somehost.org#mydir, and the files are fetched as http://somehost.org/mydir/NAME. If you host a project on sourceforge, you don't need to do this, because each project has its own hostname.
Getting started
Packaging for Zero Install is usually quite easy. The best way to start is by reading the case studies in order:
- Case Study #1 shows how to make a simple Python application available via Zero Install, and how to make updates available. Read this first.
- Case Study #2 shows how to make the scons build system available.
Once you've read the case studies, read the tips below.
Overview
If you'd like to make software available via Zero Install then you should use the 0build program to build the index file. The easiest way to do this is to 'cd' into the directory you want to make available and run '0build' to build the index files in the server directory from there:
$ alias 0build=/uri/0install/zero-install.sourceforge.net/bin/0build $ cd ~/www $ ls -l MyProg/ total 4 -rwxr-xr-x 1 tal00r tal00r 18 2003-05-23 15:21 foo $ ./MyProg/foo 42 $ 0build /var/www myhost.com Building index files for server 'myhost.com' in '/var/www'. Creating new directory for archives '/var/www/.0inst-archives' Creating new archive for /MyProg $ /uri/0install/myhost.com/MyProg/foo 42
And that's it!
Suggested directory layout
Typically, you'll want to provide multiple versions of your software, and for multiple platforms. The suggested way to handle this is to create a subdirectory for each platform, and then a sub-sub-directory for each version, so the program will be run as:
$ /uri/0install/.../MyProg/Linux-ix86/1.0.2/MyProg
If your program is platform independent then you can skip the platform part, of course. If your program is platform dependant, but programs referring to it are not, then you should use the special '@PLATFORM@' target:
$ cd ~/www/MyProg $ ln -s '@PLATFORM@' platform
Other programs can then access it as:
$ /uri/0install/.../MyProg/platform/1.0.2/MyProg
When accessed via Zero Install, the symlink's target will be the name of the user's platform (i.e., it will appear as 'platform -> Linux-ix86' on Linux ix86 type systems).
The versions should go inside the platform directories (rather than the other way around) so that 'platform/latest-2.2' can be a different version for each platform (eg, if the ARM port is a few versions behind the x86 one). Note that some of the ROX applications use a different scheme (that predates Zero Install), putting the platforms inside the versions and using 'uname' to run them. Don't let that confuse you.
You should also use symlinks to indicate interesting versions (such as the current stable release). Thus, a python script might start with:
#!/uri/0install/python.org/platform/2.2-or-later print "Hello, I need Python 2.2 or later"
The '2.2-or-later' symlink points to the latest version of python which is compatible with version 2.2. Other examples: 'latest-2.2 -> 2.2.3', 'latest-stable', etc.
Avoiding glibc version troubles (and other binary incompatibilities)
Glibc tries to prevent programs compiled using one version of the library from running on other versions, even when the interface is compatible. To create portable binaries, it is therefore necessary to use a little program at autopackage.org (autopackage/apbuild CVS module) which can be used as a wrapper for gcc.
There are a number of other traps to watch out for here. When packaging C programs for distribution (whether using Zero Install or not), please read this:
- Chapter 6. Binary portability (in the autopackage packagers' manual)
Depending on other things in Zero Install
Your application can use other libraries from Zero Install, or it can use old-style pathnames (eg, '#!usr/bin/env python'). In that case, the user must install Python manually, as if they weren't using Zero Install. This is useful for packages that aren't provided through this system.
There's a handy '0run' command, which gets installed to /bin. This takes a program and a date and runs the program, first forcing a refresh if it's missing or too old. So a python script might instead start with:
#!/bin/0run python.org/python2.2 2003-07-05 print "Hello from python!"
(0run lets you leave out the leading /uri/0install)
If the software you're packaging has not been designed for Zero Install then it may require a 'make install' step. In that case, use --prefix to give the final location (full URI) and mount a tmpfs partition (or similar) there to catch the installed files:
$ ./configure --prefix=/uri/0install/www.gtk.org/glib/Linux-ix86/2.2.1 $ make # mount -t tmpfs tmpfs /uri/0install/www.gtk.org/ $ make install
Then use 0build to archive the tmpfs partition onto the web server.
Shared libraries
It's quite easy to make normal libraries available through Zero Install (see the glib example). For a very simple example, take a look in /uri/0install/zero-install.sourceforge.net/libs/libhello-1.0. There's an 'example' subdirectory with a test program. Copy that directory somewhere and run make inside it. The program compiles using the header files for `libhello' from Zero Install. You'll get a binary called 'demo' which, when run, dynamically links against the binary in Zero Install too.
Cool URIs
Remember that the full pathname of your application or library is part of the public API of the software. Changing your directory layout is equivalent to changing the API. See Cool URIs don't change for more thoughts on stable URIs.
Including debugging symbols
With traditional packages, you must decide whether or not to include debugging symbols in binaries. Including the symbols makes the binary many times larger (slower to download), but makes debugging with gdb much easier. With Zero Install, you can separate the debugging symbols into a separate file, which will be downloaded automatically if the user uses gdb on the program, but not otherwise.
