SPKG Howto

SPKG directory structure

• .hgignore: this must contain "src" since we are not tracking its content.

• src directory: vanilla upstream, but there are a few exceptions: For example if the spkg shipped with Sage in effect is upstream and development on that code base is happening in close coordination with Sage. One example here is eclib by John Cremona. Note that the root of the spkg and the upstream code in src should be in separate hg repos.

• SPKG.txt: describes the spkg in wiki format, each new revision needs an updated changelog entry or the spkg will get an automatic "needs work" at review time
• spkg-install: the install script - see below for an example and some style tips
• spkg-check: runs the test suite - this is somewhat optional since not all spkgs have test suites. If possible do create such a script since it helps isolate bugs in upstream packages
• patches: for patches against upstream. Each file foo.extension needs to have a diff against the original file, i.e. foo.extension.patch for easy rebases against new upstream. Updated files should be copied into the right place in src at the start of spkg-install. Please document all patches in SPKG.txt, i.e. what they do, if they are platform specific, if they should be pushed upstream

A couple more remarks:

• Every file in the spkg with the exception of the src directory and its content needs to be under version control, i.e. everything must be checked into an hg repo. All outstanding changes must also be checked in before creating the spkg itself and submitting it for review.
• Make sure that the spkg you submit is built on top of the latest spkg in the current Sage release including alpha and rc releases.
• For review purposes it might be beneficial to attach a patch of the repo changes to the ticket so the changes can be easily reviewed
• Do not attach spkgs to tickets, post a link to the spkg hosted via some web space

Important Resources

• A list of spkgs

• A template for SPKG.txt

Important things to consider

There are usually a number of things to do for all spkgs:

• ensure that "make install" is non-parallel, i.e. do a "export MAKE=make"

• SAGE_LOCAL check (#633) (the spkg-install script below does this)

• add spkg-check (#299)

• add proper SPKG.txt to all packages

• /usr/bin/env bash (#1638)

• add md5sums for spkgs (#329)

• set LDFLAGS on OSX (#3349)

A Sample spkg-install

if [ "$SAGE_LOCAL" = "" ]; then
   echo "SAGE_LOCAL undefined ... exiting";
   echo "Maybe run 'sage -sh'?"
   exit 1
fi

cd src

./configure --prefix="$SAGE_LOCAL"
if [ $? -ne 0 ]; then
   echo "Error configuring PACKAGE_NAME."
   exit 1
fi

make
if [ $? -ne 0 ]; then
   echo "Error building PACKAGE_NAME."
   exit 1
fi

make install
if [ $? -ne 0 ]; then
   echo "Error installing PACKAGE_NAME."
   exit 1
fi