From 629c405e8504513330bb6e9e830556b6b54e270d Mon Sep 17 00:00:00 2001 From: Ross Date: Mon, 31 Aug 2026 16:32:11 -0400 Subject: [PATCH] Add documentation on install exact rsp env --- stack/conda.rst | 31 +++++++++++++++++++++++++++++++ stack/lsstsw.rst | 3 +++ 2 files changed, 34 insertions(+) diff --git a/stack/conda.rst b/stack/conda.rst index 957f94fc..e2835ad6 100644 --- a/stack/conda.rst +++ b/stack/conda.rst @@ -186,3 +186,34 @@ New builds of ``rubin-env`` (without updating its version) can always be used to The conda environments used by Jenkins to build nightly, weekly, and official release tarballs are preserved as ``conda list --explicit`` outputs in ``eups.lsst.cloud``. These can be used in place of the ``rubin-env`` metapackage to exactly reproduce a build for consistency in production or for debugging. Both ``newinstall`` and ``lsstsw`` allow specification of an eups tag to retrieve the exact environment used when that tag was published. + +.. _conda-exact-rsp-environments: + +"Exact" RSP environments +------------------------ + +Alongside each tag's ``rubin-env`` environment file, a ``{tag}_rsp.env`` file records the exact ``rubin-env-rsp`` environment (see :ref:`conda-rsp-notebooks`) for the same tag. +Install it when you need to reproduce behavior reported from an RSP notebook, where one of the packages that ``rubin-env-rsp`` adds on top of ``rubin-env`` may be involved. +For anything else, prefer the plain ``rubin-env`` environment. + +Pass ``-R`` to either installer to select the RSP environment: + +.. code-block:: bash + + # lsstinstall: install the exact RSP environment for a published tag + lsstinstall -P -R -X w_2026_22 + + # lsstsw: deploy prints the name of the environment it creates + ./bin/deploy -R -x w_2026_22 + source bin/envconfig -n lsst-scipipe-w_2026_22-rsp + +The conda environment name gains an ``-rsp`` suffix so that RSP and non-RSP installations of the same version cannot be mistaken for each other or falsely reused. +``lsstinstall`` appends it after the ``-exact`` suffix, so ``-X w_2026_22 -R`` creates ``lsst-scipipe-{version}-exact-rsp`` while ``-R`` on its own creates ``lsst-scipipe-{version}-rsp``. + +The default behavior of both tools is unchanged. +Without ``-R`` you get a plain ``rubin-env`` environment, which remains the right choice for ordinary development work and is what the distributed tarball binaries are meant to be used, but also work with ``-rsp``. + +Only tags published after RSP environment files were introduced have a ``{tag}_rsp.env``; requesting ``-R`` for an older tag fails with a message saying so. +``-R`` is also rejected for the pre-``rubin-env`` hash-referenced environments, which have no RSP counterpart. + +Without ``-X`` (for ``lsstinstall``) or ``-x`` (for ``deploy``), ``-R`` solves ``rubin-env-rsp={version}`` fresh from conda-forge rather than installing a pinned package list. diff --git a/stack/lsstsw.rst b/stack/lsstsw.rst index 4015a4dd..d8ea1d74 100644 --- a/stack/lsstsw.rst +++ b/stack/lsstsw.rst @@ -58,6 +58,9 @@ example:: enough to turn into a no-op when it detects it has successfully run already. +By default :command:`deploy` creates a plain ``rubin-env`` conda environment. +Pass ``-R`` to create the ``rubin-env-rsp`` superset that the Rubin Science Platform runs instead, optionally combined with ``-x `` to reproduce the exact RSP environment published for that tag; see :ref:`conda-exact-rsp-environments`. + .. _lsst_build repository: https://github.com/lsst/lsst_build.git .. _lsstsw repository: https://github.com/lsst/lsstsw.git .. _Miniconda: http://conda.pydata.org/miniconda.html