3.3 Creating a New Sage spkg Package

Here's how to make your own Sage package.

Note that a Sage package is simply a .tar.bz2 file (or a tar file), but named with .spkg to discourage confusion. In particular, you can type
```
            tar jxvf my_package-version.spkg
```
to extract one and see what is inside.
To create your own package:
(a)

Make a directory, e.g., mypackage-0.1. The name of the directory should be a lower-case string with no dashes followed by a dash followed by a version number.

(b)

Put your files in that directory.

(c)

Create an executable shell script mypackage-0.1/spkg-install.

(d)
The script spkg-install is run during installation of the Sage package. In this script you may make the following assumptions:
- The PATH has sage and the Sage install's python location at the front. Thus the command
  python setup.py install
  will run the correct version of Python with everything setup correctly. Also, e.g., running gap or Singular will run the correct versions.
- The environment variable SAGE_ROOT points to the root directory of the Sage install.
- The environment variable SAGE_LOCAL points to the SAGE_ROOT/local directory of the Sage install.
- The environment variables LD_LIBRARY_PATH and DYLD_LIBRARY_PATH both have SAGE_ROOT/local/lib at the front.
(e)

The spkg-install script should copy your files to the appropriate place after doing any build that is necessary. That's it!

(f)

(Optional) Send a copy to the sage-devel Google group so it can be posted to the Sage web site, so anybody can automatically install it by typing sage -i my_package-version.spkg.

For example, the location of GAP is SAGE_ROOT/local/lib/gap-4.4.6/. Thus to install gap code you have to copy it there. You should check that the directory with the given version your package is created for exists in your spkg-install script, e.g., with the following code:

if [ ! -d $SAGE_ROOT/local/lib/gap-4.4.6 ]; then
    echo "This package requires that GAP 4.4.6 is installed."
    exit 1
fi

Caveat: Do not just copy to SAGE_ROOT/local/lib/gap*/ since that will copy your package to the lib directory of the old version of GAP if GAP is upgraded.

External Magma code goes in SAGE_ROOT/data/extcode/magma/user, so if you want to redistribute Magma code with Sage as a package that Magma-enabled users can use, that's where you'd put it. You'd also want to have relevant Python code to make the Magma code easily usable.

Example: These instructions provide directions for creating a particular Sage package.

Download guava2.4.tar.gz (the tarball for GUAVA, the GAP error-correcting codes package) from http://www.gap-system.org/Packages/guava.html.
Suppose you have a directory sage-package-guava. Within that, create a directory guava-2.4. Extract the tarball into that directory (so there will be a guava2.4 subdirectory of sage-package-guava).

Put the following script called spkg-install in sage-package-guava:

#!/bin/sh

if [ ! -d $SAGE_ROOT/local/lib/gap-4.4.6 ]; then
    echo "This package requires that GAP 4.4.6 is installed."
    exit 1
fi

cp -pr guava2.4 $SAGE_ROOT/local/lib/gap-4.4.6/pkg/

cd $SAGE_ROOT/local/lib/gap-4.4.6/pkg/guava2.4
./configure ../..
make

Make it executable with chmod +x spkg-install.

In the directory sagefiles, issue the command
```
<path>sage -pkg guava-2.4
```
where <path> means the absolute path to the sage script. This will do some checks, run tar/bz2, and create the spkg file, guava-2.4.spkg, in the directory sagefiles,

To test this, within the sagefiles directory (or whatever directory contains guava-2.4.spkg), type

<path>sage -i guava-2.4.spkg

It should install and compile the guava program in sage. To test its functionality, one could do the following:

sage: gap(`LoadPackage("guava")')          # requires optional package
true
sage: gap(`HammingCode(3,3)')              # requires optional package
a linear [13,10,3]1 Hamming (3,3) code over GF(3)

To build again if you've already installed the package, use

<path>sage -f guava-2.4.spkg

See About this document... for information on suggesting changes.