How to patch a Sage package
What is an spkg?
The abbreviation “spkg” stands for “Sage package”. The directory SAGE_ROOT/spkg/standard contains spkg’s. In a source install, these are all Sage spkg files (actually .tar or .tar.bz2 files), which are the source code that defines Sage. In a binary install some of these may be small placeholder files to save space.
Sage packages are distributed as .spkg files, which are .tar.bz2 files (or tar files) but have the extension .spkg to discourage confusion. Although Sage packages are packed using tar and/or bzip2, please note that .spkg files contain control information (installation scripts and metadata) that are necessary for building and installing them. For source distributions, when you compile Sage the file SAGE_ROOT/makefile takes care of the unpacking, compilation, and installation of Sage packages for you. For more information on the structure of .spkg files, please refer to the Sage Developer’s Guide in your local installation of Sage at
If you cannot locate that file in your local installation of Sage, you might want to consider (re)building the standard Sage documentation using this command:
SAGE_ROOT/sage -docbuild all html
How do I patch an spkg?
Make sure you are familiar with the structure and conventions relating to spkg’s; see the section Producing New Sage Packages for details. Patching an spkg involves patching the installation script of the spkg and/or patching the upstream source code contained in the spkg. Say you want to patch the GAP package gap-4.4.10.p17. Note that “p17” denotes the patch level of the spkg. The installation script of that spkg is
In general, a script with the name spkg-install is an installation script for an spkg. To patch the installation script, use a text editor to edit that script. Then in the log file SPKG.txt, provide a high-level description of your changes. Once you are satisfied with your changes in the installation script and the log file SPKG.txt, use Mercurial to check in your changes and make sure to provide a meaningful commit message.
The directory src/ contains the source code provided by the upstream project. For example, the source code of GAP 4.4.10 is contained under
To patch the upstream source code, you should first copy the relevant file under src/ over to the directory patches/. Then edit that copied file rather than the relevant file under src/. Once you are satisfied with your changes to the copied file under patches/, generate a unified diff between the original file under src/ and the corresponding copied (and edited) file under patches/. Save the unified diff to a file with the same name, but use the file extension “.patch”, and place the diff file under patches/. Note that both of the directories patches/ and src/ should not be under revision control. The Mercurial configuration file .hgignore should contain the following two lines
Make sure that the installation script spkg-install contains code to copy over the patched file under patches/ to the relevant place under src/. For example, the file
is a patched version of the file
The installation script gap-4.4.10.p17/spkg-install contains the following conditional to test under which conditions to copy over the patched file to the relevant place under src/:
# If we're on an Itanium Linux box, we overwite configure.out # with a slightly modified version. The modified version has # all -O2's replaced by -O0. See # http://www.gap-system.org/Faq/Hardware-OS/hardware-os8.html # On the San Diego Super computer `uname -p` is unknown, but # uname -a includes ia64 in the output. So this is a better # detection method. Note that GAP was "fixed" to work fine on # Itanium without this -O0 hack, but with GCC-4.4.0, GAP # mysterious stopped working again. So we revert to using -O0. if [ `uname` = "Linux" ]; then uname -a |grep ia64 if [ $? = 0 -o `uname -p` = "ia64" ]; then cp patches/configure.out-ia64 src/cnf/configure.out echo "The file configure.out was patched for SAGE!" > src/cnf/configure.out.README fi fi
Now provide a high-level explanation of your changes in SPKG.txt. Once you are satisfied with your changes, use Mercurial to check in your changes with a meaningful commit message. Next, increment the patch level of the spkg by one, e.g. rename gap-4.4.10.p17 to gap-4.4.10.p18. If you want your patched spkg to be reviewed and available in the next release of Sage, you need to compress it using tar and bz2. Under Linux and OS X, you can compress your patched spkg as follows:
tar -jcf gap-4.4.10.p18.spkg gap-4.4.10.p18
As part of your request for your patched spkg to be reviewed, you need to provide a URL to your spkg on the relevant trac ticket and/or on an email to the relevant mailing list. Usually, you should not upload your spkg to the relevant trac ticket.