Packaging SageMath Downstream

This document is intended for downstream maintainers (e.g., Linux distribution package maintainers) who wish to create redistributable builds of Sage.

Dependencies

SageMath relies on a broad set of Python and system libraries. These must be provided by the downstream distribution. The definitive list of dependencies is found in pyproject.toml.

These include:

  • build-system.requires: Python packages needed for building SageMath,

  • project.dependencies: Python packages required at runtime,

  • project.optional-dependencies: optional dependencies for additional

    functionality,

  • external.build-requires and external.host-requires: system dependencies

    needed for building,

  • external.dependencies: system libraries required at runtime.

The external section follows PEP 725 and specifies dependencies in the form of ̀PURLs. At the moment, there is no standard interface to translate these PURLs into system package names. However, the names should be quite self-explanatory. You may also consult the section Packages and Features for a list of Sage’s dependencies and their corresponding system package names in various distributions.

Build Procedure

  1. Obtain the Source:

    Clone the SageMath repository:

    $ git clone https://github.com/sagemath/sage.git

    Alternatively, download the sdist tarball from the SageMath PyPI project or from the GitHub releases.

  2. Prepare the Build Environment:

    Ensure a clean and consistent build environment with access to all required system libraries and Python packages.

  3. Build:

    Create a wheel using the build module:

    $ python -m build --wheel --no-isolation

    If you are sure that all dependencies are available, you may also add the --skip-dependency-check option. Moreover, if you care about reproducible builds, it is recommended to use -Cbuild-dir=build to specify a build directory, see this Meson-Python issue.

  4. Install:

    The resulting wheel can be installed using

    $ python -m installer --destdir="<pkgdir>" dist/sagemath-*.whl

    where <pkgdir> is the directory where you want to install the package (usually a temporary directory for packaging).

  1. Test the Build:

    Run the Sage tests to ensure functionality:

    $ python -m sage.doctest --all

    However, some tests are known to fail, see Issue #39872.

If you maintain a downstream package and encounter build issues or patches that may benefit others, please consider contributing back by reporting issues or opening pull requests on the SageMath GitHub repository.

Other considerations: - Package naming: Use sagemath, or python-sagemath if your distribution has a convention for Python packages.

Example Downstream Packages