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:

$b u i l d - s y s t e m . r e q u i r e s$ : Python packages needed for building SageMath,
$p r o j e c t . d e p e n d e n c i e s$ : Python packages required at runtime,
$p r o j e c t . o p t i o n a l - d e p e n d e n c i e s$ : optional dependencies for additional
functionality,
$e x t e r n a l . b u i l d - r e q u i r e s$ and $e x t e r n a l . h o s t - r e q u i r e s$ : system dependencies
needed for building,
$e x t e r n a l . d e p e n d e n c i e s$ : system libraries required at runtime.

The $e x t e r n a l$ 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 ¶

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<https://pypi.org/project/sagemath/>`_ or from the
`GitHub releases <https://github.com/sagemath/sage/releases>`_.

Prepare the Build Environment: Ensure a clean and consistent build environment with access to all required system libraries and Python packages.

Build:

Create a wheel using the $b u i l d$ 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 <https://github.com/mesonbuild/meson-python/issues/671>`_.

Install:

The resulting wheel can be installed using
```
python -m installer --destdir="<pkgdir>" dist/sagemath-*.whl
```
where $< p k g d i r >$ is the directory where you want to install the package (usually a temporary directory for packaging).
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 $s a g e m a t h$ , or $p y t h o n - s a g e m a t h$ if your distribution has a convention for Python packages.

Example Downstream Packages ¶

Arch Linux

Packaging SageMath Downstream¶

Dependencies¶

Build Procedure¶

Example Downstream Packages¶

Dependencies ¶

Build Procedure ¶

Example Downstream Packages ¶