0install: Developers

0compile: Developers

This page explains how to publish source code using Zero Install. Publishing source this way means that:

Users can compile it easily using 0compile.
Build dependencies, such as header files and build tools, can be downloaded automatically.
0release can automatically compile binaries for your software during the release process.

Making source available
Customising the binary implementation
Adding run-time dependencies
Tips
Examples
Further reading

Making source available

To make source code available for others to use you need to add source implementations to the program's feed file. This is almost exactly the same as adding binaries, except that you give src as the machine (CPU) type:

Adding a source implementation

You can also edit the XML directly, which gives more control. A minimal source implementation might look like this:

<implementation arch="*-src" id="." version="0.1-pre">
  <command name='compile' path='Makefile'>
    <runner interface='http://repo.roscidus.com/devel/make'>
      <arg>-f</arg>
    </runner>
  </command>
</implementation>

The job of the compile command is to call the actual build system. It is executed inside the build directory ($BUILDDIR). It must compile the source in $SRCDIR, putting the final result (ready for distribution) in $DISTDIR. The path to the generated feed for the new binary is $BINARYFEED, if you need it during the build.

Instead of giving a <runner>, you can instead give a shell command, like this:

  <implementation arch="*-src" id="." version="0.1-pre"
    xmlns:compile="http://zero-install.sourceforge.net/2006/namespaces/0compile"
    compile:command="make -f ${SRCDIR}/Makefile"/>

However, the first form (with <command name='compile'>) is preferred. If the command starts to get complicated, you should move it to a script (either inside the main source archive or in a separate dependency) and just set this attribute to the command to run the script.

There are also some extra attributes you can add to the implementation element:

compile:binary-main: This optional attribute gives the value of the main attribute on the binary feed that is created. If it is not given, then the binary created cannot be executed (e.g., it is a library).
compile:dup-src: Some programs insist on creating files in their source directory, which is typically a read-only directory when using Zero Install. In this case, set compile:dup-src='true' and 0compile will copy everything in $SRCDIR into 'build' before building.

Customising the binary implementation

Starting from 0compile 0.23, you can specify a template <implementation> for the binary. You can use this, for example, to add <command> elements to it. Here's a more complex example for a Java program:

  <implementation arch="*-src" id="." version="0.1-pre" compile:min-version='0.24'>
  <command name="compile" path="src/Makefile">
      <runner interface='http://repo.roscidus.com/devel/make'>
        <arg>-f</arg>
      </runner>

      <compile:implementation arch='*-*'>
        <environment name='CLASSPATH' insert='.'/>
        <requires interface="http://repo.roscidus.com/utils/graphviz"/>
        <command name='run'>
          <runner interface='http://repo.roscidus.com/java/openjdk-6-jre'/>
          <arg>com.example.MainClass</arg>
        </command>
      </compile:implementation>
    </command>
    <requires interface="http://repo.roscidus.com/java/iris" compile:include-binary='true'/>
    <requires interface="http://repo.roscidus.com/java/openjdk-6-jdk">
      <environment name='PATH' insert='bin'/>
    </requires>
  </implementation>

The interesting bits here are:

arch="*-src": tells us that the root <implementation> describes some source code.
compile:min-version: requires 0compile >= 0.24 to use the template feature.
<command name='compile'>: this replaces the old compile:command attribute described above.
<compile:implementation>: this is the template for the implementation that will be created by the compile.
arch='*-*': indicates that the generated binary is platform independent (Java bytecode).
<command name='run'>: says how to run the resulting binary (by using the Java runtime).

Adding run-time dependencies

By default, the feed created for the new binary doesn't have any dependencies. There are three ways to add them:

You can annotate any <requires> element in your source feed with the 'include-binary' attribute. This causes the dependency to appear in the generated binary's feed, in addition to being made available at compile-time. e.g.
```
    <requires compile:include-binary='true' interface="http://my/library">
      <environment insert="lib" name="MY_LIBRARY_DIR" mode="replace"/>
    </requires>
```
You can use the template feature described above.
You can edit the feed XML file directly during the build (it's in the $DISTDIR/0install directory).

Tips

Using a separate source feed

You can keep the source implementations in a separate file (MyProg-src.xml) and add a feed from the main feed, e.g.:

  <feed src='http://mysite/interfaces/MyProg-src.xml' arch='*-src'/>

The arch attribute lets the injector know that it doesn't need to fetch this file unless it's looking for source code.

Making library headers available (-dev packages)

See Make-headers for information about publishing library source and -dev packages.

Python distutils

You should use the --build-base option to make distutils build to 0compile's build directory, not under the source code (which is read-only). Unfortunately, this option isn't available with the install command, so you have to do the build in two steps. A typical command is:

cd "$SRCDIR" &&
python setup.py build --build-base="$BUILDDIR/build" &&
cd "$BUILDDIR" &&
python "$SRCDIR"/setup.py install --home="$DISTDIR" --skip-build

Examples

Anders F Björklund has created a set of example source feeds. There are also some template projects which can be used as a starting point for publishing your own software.

Zero Install