.. _spkg_sage_conf:

sage_conf: Configuration module for the SageMath library (distributable version)
================================================================================

Description
-----------

This distribution package provides:

- a single Python module, ``sage_conf``, providing configuration information
  to the SageMath library at the time of its installation and at its runtime

- a console script ``sage-config``, for querying the variables of ``sage_conf``
  from the shell

- a sourcable shell script ``sage-env-config``, providing additional configuration
  information in the form of environment variables

The ``sage_conf`` distribution package is polymorphic:  It has several implementations.


sage_conf sdist on PyPI
-----------------------

This implementation of the ``sage_conf`` distribution package comes from
:trac:`29039`, which added the directory
`pkgs/sage-conf_pypi <https://github.com/sagemath/sage/tree/develop/pkgs/sage-conf_pypi/>`_.

To install, use ``pip install -v sage_conf``.  Using ``-v`` ensures that diagnostic
messages are displayed.

On installation (or building a wheel), it invokes ``sage_bootstrap`` to establish
a build tree (``SAGE_ROOT``) and installation tree (``SAGE_LOCAL``) for
the SageMath distribution.  By default, it uses a subdirectory of ``$HOME/.sage``
that is specific to the version of the distribution and the version of Python in
use.  If several virtual environments over the same version of Python install
``sage_conf``, they will share these trees.

After installation of ``sage_conf``, a wheelhouse containing wheels of
various libraries is available; type ``ls $(sage-config
SAGE_SPKG_WHEELS)`` to list them and ``pip install $(sage-config
SAGE_SPKG_WHEELS)/*.whl`` to install them.  After this, you can install the Sage
library, for example, using ``pip install sagemath-standard``.


sage_conf wheels
----------------

Prebuilt binary wheels of the ``sage_conf`` distribution package are available
at https://github.com/sagemath/sage-wheels/releases/

This implementation of ``sage_conf`` comes from :trac:`31396`,
which adds the directory ``pkgs/sage-conf_relocatable/``.

On building a wheel, it invokes ``sage_bootstrap`` to establish a
build and installation tree (``SAGE_ROOT``, ``SAGE_LOCAL``) in a
subdirectory of the directory ``/var/tmp/``, whose name is specific to
the version of the distribution and the version of Python in use.

The wheel distributes a copy of the prebuilt ``SAGE_ROOT`` and
``SAGE_LOCAL``.  Importing ``sage_conf`` (or using the installed
``sage-config`` script), makes sure that a symlink from the
``/var/tmp`` location to the actual persistent installation location
is created.  As the relocated libraries and programs contain the
hardcoded path ``SAGE_LOCAL`` in various ways (including as rpaths),
this symlink is necessary for the prebuilt libraries and programs to
work.

``/var/tmp`` is a sticky directory on all Linux distributions
following the Filesystem Hierarchy Standard, as well as on macOS and
on Cygwin.  On multi-user systems, only one user can use a given
version of the distribution; other installation schemes are recommended
for systems with multiple Sage users.


sage_conf in the SageMath distribution
--------------------------------------

The original version of the distribution package ``sage_conf`` is used
internally in the SageMath distribution.  It is provided in the directory
`pkgs/sage-conf <https://github.com/sagemath/sage/tree/develop/pkgs/sage-conf/>`_.
This version of the package is generated by the Sage distribution's ``configure``
script.


sage_conf in downstream distributions
-------------------------------------

Downstream packagers and advanced developers and users may want to provide
their own implementation of the distribution package to support the intended
deployment of the SageMath library.


License
-------

GNU General Public License (GPL) v3 or later

Upstream Contact
----------------

https://www.sagemath.org

This package is included in the source code of the Sage distribution,
in `pkgs/sage-conf* <https://github.com/sagemath/sage/tree/develop/pkgs/>`_.

Type
----

standard


Version Information
-------------------

package-version.txt::

    9.6

install-requires.txt::

    sage-conf ~= 9.5.b6


Equivalent System Packages
--------------------------


However, these system packages will not be used for building Sage
because using Python site-packages is not supported by the Sage distribution;
see :trac:`29023`