4. Package internals

Let’s open the box of a package. If you enter the hello-1.1.0.package directory, you will notice the following:

• an xml file called manifest.xml, mandatory
• a Executables directory, optional
• a Resources directory, optional

The central essence of a package lays in its particular name, and its particular structure.

The manifest.xml is the description of the package contents and meta information about executables, resources and so on. It explicitly exposes the internals of the package.

if you edit the manifest file, you will see the current manifest file version 1.0. It has a Meta section, and a Contents section. We will explore the Contents section, as it contains the most important things. Contents hosts two types of xml elements: ExecutableGroup and ResourceGroup. They are similar: one defines Executable entry points, and the other (surprise surprise) Resource entry points.

        <ExecutableGroup entryPoint="hello" description="Prints hello in the specified language">
            <Executable>
                <Platform>Linux-i686</Platform>
                <Interpreter>bash</Interpreter>
                <Path type="standard">hello</Path>
            </Executable>
            <Executable>
                <Platform>Darwin-Power Macintosh</Platform>
                <Interpreter>bash</Interpreter>
                <Path type="standard">hello</Path>
            </Executable>
            <Executable>
                <Platform>noarch</Platform>
                <Interpreter>bash</Interpreter>
                <Path type="standard">hello</Path>
            </Executable>
        </ExecutableGroup>

Why Group? an executable (and a resource as well) can be bound to a specific platform. A C++ program can be compiled on Linux, and this executable will not run on MacOSX. Wouldn’t it be nice to have both the Linux executable and the OSX executable in the same package, and have cnrun decide which one to run depending on the platform the package is in? This is what an ExecutableGroup is for.

This feature is particularly interesting if you have a NFS mounted Package repository, with different architectures accessing this NFS. When the entry point is executed, the proper executable will be used. As a fallback mechanism, Chestnut will always try to execute the “noarch” architecture if it does not find a match.

This can also be used for handling the following case: suppose you have two versions of a program: a scripted version (slower, but portable), and a compiled version (faster, but platform dependent). You can package both in the same executable group, with the scripted version associated to the “noarch” platform, and the compiled version associated to the proper native platform. The program will always run (assuming you have the interpreter!) but it will be faster if the native platform for the compiled version is used.

The same mechanism exists for Resources. Sometimes, data can be platform dependent (like in case of endianness issues, or with data files optimized for a specific platform). Defining a Resource group is similar to the definition of an Executable group.

4.1 The package paths

In the previous snippet from the manifest, we saw the following xml chunk:

<Path type="standard">hello</Path>

The path defines where Chestnut Package Manager should look for the executable. There are currently three possibilities for type:

1. standard: the executable is searched into the standard package subdirectory “Executables/`uname`-`uname -m`/” (eg. “Executables/Linux-i686/”). In this case, the program that will be executed is therefore “hello-1.1.0.package/Executables/Linux-i686/hello”
2. package_relative: the executable is searched under the package subdirectory, but the actual path is up to you to decide.
3. absolute: the executable is searched anywhere on the filesystem, as specified. The full, absolute path must be provided. Useful to create “virtual packages”, and let unpackaged programs be accessible through the Chestnut interface

Again, the same can be said about Resources.