Differences between revisions 480 and 481
Revision 480 as of 2017-06-26 13:21:44
Size: 13217
Editor: ?TobiasHansen
Comment: Update explanation of pruner output.
Revision 481 as of 2017-08-07 19:50:14
Size: 13229
Editor: Infinity0
Comment: tweak key location so it works for other packages as well
Deletions are marked like this. Additions are marked like this.
Line 90: Line 90:
    --extra-repository-key=debian/deb-sci-sage.asc \     --extra-repository-key=../sagemath/debian/deb-sci-sage.asc \

Some people within DebianScience have again packaged Sage for Debian. This is one of the most complex packages in Debian and will need continual maintenance - we are always looking for new contributors! If you want to help out, read below to learn how to build the package from source, then pick one of the open tasks and get going. You can contact us via the mailing list or in #debian-science on irc.oftc.net.

Build from source

Our packages in the Debian official archives should be buildable using the normal Debian build processes. This is for users that wish to build from source, as well as build bots.

For maintainers, our development workflow is to build from our git repository. Important elements are the build dependencies of Sage, patches for Sage and a script called "pruner" that uses autoconf to determine if the necessary packages are installed.

git clone --recursive https://anonscm.debian.org/git/debian-science/packages/sagemath.git && cd sagemath

Recursive git clone to also get sage which is included as a git submodule.

To work with this repository, you must start with Debian unstable (sid) with experimental sources enabled. It is nice - optional, but highly recommended - to do this in an schroot, which you can set up using the instructions in sbuild, after which you'll probably need to apply the following workarounds: 1. 2. Next, see debian/README.source section "Local system patches", for any workarounds you might have to apply. Then:

debian/rules build-dep-maint

Install packages that are required before installing the build dependencies.

debian/rules install-apt-sources

Add our unstable-sage repo for patched dependencies. This is optional; if you prefer you can build them yourself from the instructions in the table below.

To build the package, run:

debian/rules build-dep

Install build dependencies; you may need to run apt-get -f install afterwards. If this fails, install aptitude then try it again.

debian/rules reset

Apply patches and force-reset the upstream sage submodule.

debian/rules prune

Run the pruner script. Check that the output matches the one below.

debian/rules build

Build sage and run the test suite.

fakeroot debian/rules binary

Build the Debian packages.

The output of the pruner tells you in the end which dependencies were not found on the machine ("XXX will not come from Debian"). Since all dependencies should come from Debian, such a line normally indicates that something went wrong. The pruner should only output XXX system packages will be used. Otherwise, if you are sure that you want to try this, you could go on nevertheless. Sage will then try to download and build the missing dependencies in the build step, before Sage itself is built.

See debian/README.source for further details, such as how to debug the failing doctests. At present, we have a threshold of 40 failing doctests (out of ~300K total), below which we call it a "successful build". On amd64 we have ~12 failures, and on i386 we have (??? not tested recently). It would be good to lower these numbers: upstream aim for 0 failing tests and Gentoo typically has between 10-30. 3

Once you are happy with the full build process, you can try a test release build:

debian/rules release-deb-sci-sage

Build an UNRELEASED version using sbuild, with our custom APT repo.

Open tasks

The status pages (master, develop) give an overview about package versions in Sage and Debian. Current high-priority tasks are:

  1. Deal with RC bugs in sagemath and its dependencies. (See the link "Dashboard" at the bottom of the status pages.)
  2. Package 8.0, its new dependencies (maybe thebe), update existing dependencies (at least pari, maybe jupyter-core, jupyter-notebook) and upload them to experimental.
  3. After sage 8.0 is in unstable, update ntl (needs a transition).
  4. Get high-priority patched packages into official Debian, see below.

See debian/TODO for more tasks and more details.

Custom APT repo

We've set up a mini-dinstall APT repo here to upload our patched dependency packages to. Sometimes, these patches are invasive and unlikely to be added to Debian officially, but this repo allows us to verify that they work with Sage, to unblock progress in other areas - then later we can figure out how to refine the patches so that they are acceptable for Debian.

Package

Bug / Link

Priority for getting into official Debian

Reason for being in the repository

New/updated packages:

cypari2

864792

high

New package, in NEW queue.

Patched packages:

cython

865453

high

We applied the required pull requests 1654 and 466.

sympy

840621

low

We applied this patch to fix a doctest.

Uploading patched packages

To upload, you must be a member of the debian-science group on alioth. Then, you should add this to your ~/.dput.cf:

[deb-sci-sage]
method = scp
fqdn = alioth.debian.org
incoming = /home/groups/debian-science/htdocs/apt/mini-dinstall/incoming/
post_upload_command = ssh alioth.debian.org /home/groups/debian-science/mini-dinstall

mini-dinstall is pretty forgiving and you can upload either higher or lower versions of what's in there currently. However, you must set the distribution in debian/changelog to sid-sage or unstable-sage, otherwise your package will get rejected. Alternatively, do the build without changing debian/changelog, then afterwards edit the .changes file to say Distribution: sid-sage, then debsign it and upload.

Please include the .orig tarball in your upload, which helps our status pages report more accurately. To do this, you can give --changes-option=-sa to dpkg-buildpackage, or if you forget to do this then you can run changestool $XXX.changes includeallsources after the build, then debsign it and upload.

If you want to upload a different version of a package with the same version number as what's already in there, firstly please try to avoid this since it might confuse people. If you do it by accident, mini-dinstall won't reject your upload and you will mess up the database. In this case, run /home/groups/debian-science/mini-dinstall -b --no-db on alioth.debian.org to fix things.

To remove a package

  • ssh to alioth.debian.org

  • Delete the packages from /home/groups/debian-science/htdocs/apt/sid-sage

  • Run /home/groups/debian-science/mini-dinstall -b --no-db

To sbuild using our repo

You can sbuild to make sure you didn't miss any build-dependencies (and for its other benefits). First, set up an sbuild schroot by following the instructions on that page. Then, for each build you want to do, run:

$ sbuild \
    --chroot-setup-commands='apt-get install -y apt-transport-https' \
    --extra-repository='deb https://debian-science.alioth.debian.org/apt sid-sage/' \
    --extra-repository-key=../sagemath/debian/deb-sci-sage.asc \
    --build-dep-resolver=aspcud \
    -s .

Replace -s . with $pkg.dsc if you already built the latter.

If you also need packages from Debian experimental, add --extra-repository='deb http://httpredir.debian.org/debian experimental main' to the above command line.

Updating Sage in Debian

Every version of Sage is tested upstream with a specific version of each dependency (see our status pages). It is not always possible to provide the same versions of all dependencies in Debian. It is however advisable to follow the versions as closely as possible, especially for specialized math packages, which tend to have less stable interfaces than general purpose libraries.

This means that each update of the package sagemath comes together with a bunch of updates of other packages. As some of these updates could break the previous sagemath version in unstable, many of these updates should first be uploaded to Debian experimental. The new version of Sage will then be uploaded to experimental as well.

Once the new Sage version has been tested in experimental and is considered ready for unstable, the batch of package updates for this version is migrated from Debian experimental to unstable. This should be coordinated and not take too long, to avoid having a broken sagemath package in unstable for a long time.

Testing migration

In order to have a working sagemath package in Debian testing at all times, the whole batch of package updates for a new Sage version needs to migrate to testing together. To this end, the dependencies should declare

Breaks: sagemath (<< x.y~)

(where x.y is the new Sage version) for at least one binary package on which the binary package sagemath depends. An exception to this are libraries with a soname jump (if sagemath depends only on the library package). In this case, the new version of the library may migrate to testing before sagemath, because the old library package will be kept around until it is not used anymore.

Links

Sage out of Debian:

Historical information:

  1. If your build fails with "Permission denied", try adding the following line to /etc/schroot/sbuild/fstab: tmpfs  /dev/shm  tmpfs  rw,nosuid,nodev  0  0 - more details here (1)

  2. If your build fails with "out of pty devices", log into the chroot using sudo sbuild-shell source:${chroot_name} then run rm /dev/ptmx && mknod -m 666 /dev/ptmx c 5 2 - more details in 817236. (2)

  3. It's perhaps "not worth it" for us to lower it to 0, since the final 20 or so are not "hard" errors but are uninteresting differences like different but equivalent symbolic mathematical expressions or slightly different random number algorithms; these are generally caused by different versions of dependencies in Debian. "Fixing" them would simply involve patching Debian's Sage to expect different values. This is good for documentation purposes but you may also decide that your time is better spent doing other, more important, tasks. (3)