summaryrefslogtreecommitdiff
path: root/lib/spack/docs/basic_usage.rst
diff options
context:
space:
mode:
authorHarmen Stoppels <harmenstoppels@gmail.com>2022-11-11 09:50:07 +0100
committerGitHub <noreply@github.com>2022-11-11 00:50:07 -0800
commit0f54a63dfd33905d55de1148b2ef02cccb56b48c (patch)
tree1903b0ba9d76dfd8339d6ac4db799237bfc977f9 /lib/spack/docs/basic_usage.rst
parentf11778bb02ae7394cdc9ac24357073d76077a403 (diff)
downloadspack-0f54a63dfd33905d55de1148b2ef02cccb56b48c.tar.gz
spack-0f54a63dfd33905d55de1148b2ef02cccb56b48c.tar.bz2
spack-0f54a63dfd33905d55de1148b2ef02cccb56b48c.tar.xz
spack-0f54a63dfd33905d55de1148b2ef02cccb56b48c.zip
remove activate/deactivate support in favor of environments (#29317)
Environments and environment views have taken over the role of `spack activate/deactivate`, and we should deprecate these commands for several reasons: - Global activation is a really poor idea: - Install prefixes should be immutable; since they can have multiple, unrelated dependents; see below - Added complexity elsewhere: verification of installations, tarballs for build caches, creation of environment views of packages with unrelated extensions "globally activated"... by removing the feature, it gets easier for people to contribute, and we'd end up with fewer bugs due to edge cases. - Environment accomplish the same thing for non-global "activation" i.e. `spack view`, but better. Also we write in the docs: ``` However, Spack global activations have two potential drawbacks: #. Activated packages that involve compiled C extensions may still need their dependencies to be loaded manually. For example, ``spack load openblas`` might be required to make ``py-numpy`` work. #. Global activations "break" a core feature of Spack, which is that multiple versions of a package can co-exist side-by-side. For example, suppose you wish to run a Python package in two different environments but the same basic Python --- one with ``py-numpy@1.7`` and one with ``py-numpy@1.8``. Spack extensions will not support this potential debugging use case. ``` Now that environments are established and views can take over the role of activation non-destructively, we can remove global activation/deactivation.
Diffstat (limited to 'lib/spack/docs/basic_usage.rst')
-rw-r--r--lib/spack/docs/basic_usage.rst139
1 files changed, 12 insertions, 127 deletions
diff --git a/lib/spack/docs/basic_usage.rst b/lib/spack/docs/basic_usage.rst
index 73895449b0..b26429b248 100644
--- a/lib/spack/docs/basic_usage.rst
+++ b/lib/spack/docs/basic_usage.rst
@@ -1114,21 +1114,21 @@ set of arbitrary versions, such as ``@1.0,1.5,1.7`` (``1.0``, ``1.5``,
or ``1.7``). When you supply such a specifier to ``spack install``,
it constrains the set of versions that Spack will install.
-For packages with a ``git`` attribute, ``git`` references
-may be specified instead of a numerical version i.e. branches, tags
-and commits. Spack will stage and build based off the ``git``
+For packages with a ``git`` attribute, ``git`` references
+may be specified instead of a numerical version i.e. branches, tags
+and commits. Spack will stage and build based off the ``git``
reference provided. Acceptable syntaxes for this are:
.. code-block:: sh
-
+
# branches and tags
foo@git.develop # use the develop branch
foo@git.0.19 # use the 0.19 tag
-
+
# commit hashes
foo@abcdef1234abcdef1234abcdef1234abcdef1234 # 40 character hashes are automatically treated as git commits
foo@git.abcdef1234abcdef1234abcdef1234abcdef1234
-
+
Spack versions from git reference either have an associated version supplied by the user,
or infer a relationship to known versions from the structure of the git repository. If an
associated version is supplied by the user, Spack treats the git version as equivalent to that
@@ -1745,13 +1745,13 @@ directly when you run ``python``:
Using Extensions
^^^^^^^^^^^^^^^^
-There are four ways to get ``numpy`` working in Python. The first is
+There are multiple ways to get ``numpy`` working in Python. The first is
to use :ref:`shell-support`. You can simply ``load`` the extension,
-and it will be added to the ``PYTHONPATH`` in your current shell:
+and it will be added to the ``PYTHONPATH`` in your current shell, and
+Python itself will be available in the ``PATH``:
.. code-block:: console
- $ spack load python
$ spack load py-numpy
Now ``import numpy`` will succeed for as long as you keep your current
@@ -1777,128 +1777,13 @@ load, you can use the ``spack module tcl|lmod loads`` command to get
the name of the module from the Spack spec.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Activating Extensions in a View
+Extensions in an Environment
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Another way to use extensions is to create a view, which merges the
python installation along with the extensions into a single prefix.
-See :ref:`configuring_environment_views` for a more in-depth description
-of views.
-
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Activating Extensions Globally
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-As an alternative to creating a merged prefix with Python and its extensions,
-and prior to support for views, Spack has provided a means to install the
-extension into the Spack installation prefix for the extendee. This has
-typically been useful since extendable packages typically search their own
-installation path for addons by default.
-
-Global activations are performed with the ``spack activate`` command:
-
-.. _cmd-spack-activate:
-
-^^^^^^^^^^^^^^^^^^
-``spack activate``
-^^^^^^^^^^^^^^^^^^
-
-.. code-block:: console
-
- $ spack activate py-numpy
- ==> Activated extension py-setuptools@11.3.1%gcc@4.4.7 arch=linux-debian7-x86_64-3c74eb69 for python@2.7.8%gcc@4.4.7.
- ==> Activated extension py-nose@1.3.4%gcc@4.4.7 arch=linux-debian7-x86_64-5f70f816 for python@2.7.8%gcc@4.4.7.
- ==> Activated extension py-numpy@1.9.1%gcc@4.4.7 arch=linux-debian7-x86_64-66733244 for python@2.7.8%gcc@4.4.7.
-
-Several things have happened here. The user requested that
-``py-numpy`` be activated in the ``python`` installation it was built
-with. Spack knows that ``py-numpy`` depends on ``py-nose`` and
-``py-setuptools``, so it activated those packages first. Finally,
-once all dependencies were activated in the ``python`` installation,
-``py-numpy`` was activated as well.
-
-If we run ``spack extensions`` again, we now see the three new
-packages listed as activated:
-
-.. code-block:: console
-
- $ spack extensions python
- ==> python@2.7.8%gcc@4.4.7 arch=linux-debian7-x86_64-703c7a96
- ==> 36 extensions:
- geos py-ipython py-pexpect py-pyside py-sip
- py-basemap py-libxml2 py-pil py-pytz py-six
- py-biopython py-mako py-pmw py-rpy2 py-sympy
- py-cython py-matplotlib py-pychecker py-scientificpython py-virtualenv
- py-dateutil py-mpi4py py-pygments py-scikit-learn
- py-epydoc py-mx py-pylint py-scipy
- py-gnuplot py-nose py-pyparsing py-setuptools
- py-h5py py-numpy py-pyqt py-shiboken
-
- ==> 12 installed:
- -- linux-debian7-x86_64 / gcc@4.4.7 --------------------------------
- py-dateutil@2.4.0 py-nose@1.3.4 py-pyside@1.2.2
- py-dateutil@2.4.0 py-numpy@1.9.1 py-pytz@2014.10
- py-ipython@2.3.1 py-pygments@2.0.1 py-setuptools@11.3.1
- py-matplotlib@1.4.2 py-pyparsing@2.0.3 py-six@1.9.0
-
- ==> 3 currently activated:
- -- linux-debian7-x86_64 / gcc@4.4.7 --------------------------------
- py-nose@1.3.4 py-numpy@1.9.1 py-setuptools@11.3.1
-
-Now, when a user runs python, ``numpy`` will be available for import
-*without* the user having to explicitly load it. ``python@2.7.8`` now
-acts like a system Python installation with ``numpy`` installed inside
-of it.
-
-Spack accomplishes this by symbolically linking the *entire* prefix of
-the ``py-numpy`` package into the prefix of the ``python`` package. To the
-python interpreter, it looks like ``numpy`` is installed in the
-``site-packages`` directory.
-
-The only limitation of global activation is that you can only have a *single*
-version of an extension activated at a time. This is because multiple
-versions of the same extension would conflict if symbolically linked
-into the same prefix. Users who want a different version of a package
-can still get it by using environment modules or views, but they will have to
-explicitly load their preferred version.
-
-^^^^^^^^^^^^^^^^^^^^^^^^^^
-``spack activate --force``
-^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-If, for some reason, you want to activate a package *without* its
-dependencies, you can use ``spack activate --force``:
-
-.. code-block:: console
-
- $ spack activate --force py-numpy
- ==> Activated extension py-numpy@1.9.1%gcc@4.4.7 arch=linux-debian7-x86_64-66733244 for python@2.7.8%gcc@4.4.7.
-
-.. _cmd-spack-deactivate:
-
-^^^^^^^^^^^^^^^^^^^^
-``spack deactivate``
-^^^^^^^^^^^^^^^^^^^^
-
-We've seen how activating an extension can be used to set up a default
-version of a Python module. Obviously, you may want to change that at
-some point. ``spack deactivate`` is the command for this. There are
-several variants:
-
-* ``spack deactivate <extension>`` will deactivate a single
- extension. If another activated extension depends on this one,
- Spack will warn you and exit with an error.
-* ``spack deactivate --force <extension>`` deactivates an extension
- regardless of packages that depend on it.
-* ``spack deactivate --all <extension>`` deactivates an extension and
- all of its dependencies. Use ``--force`` to disregard dependents.
-* ``spack deactivate --all <extendee>`` deactivates *all* activated
- extensions of a package. For example, to deactivate *all* python
- extensions, use:
-
- .. code-block:: console
-
- $ spack deactivate --all python
+See :ref:`environments` for a more in-depth description
+of environment views.
-----------------------
Filesystem requirements