diff options
Diffstat (limited to 'lib/spack/docs')
| -rw-r--r-- | lib/spack/docs/basic_usage.rst | 139 | ||||
| -rw-r--r-- | lib/spack/docs/contribution_guide.rst | 29 | ||||
| -rw-r--r-- | lib/spack/docs/environments.rst | 4 | ||||
| -rw-r--r-- | lib/spack/docs/packaging_guide.rst | 61 |
4 files changed, 16 insertions, 217 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 diff --git a/lib/spack/docs/contribution_guide.rst b/lib/spack/docs/contribution_guide.rst index 837a850ff9..455a420ff2 100644 --- a/lib/spack/docs/contribution_guide.rst +++ b/lib/spack/docs/contribution_guide.rst @@ -253,27 +253,6 @@ to update them. multiple runs of ``spack style`` just to re-compute line numbers and makes it much easier to fix errors directly off of the CI output. -.. warning:: - - Flake8 and ``pep8-naming`` require a number of dependencies in order - to run. If you installed ``py-flake8`` and ``py-pep8-naming``, the - easiest way to ensure the right packages are on your ``PYTHONPATH`` is - to run:: - - spack activate py-flake8 - spack activate pep8-naming - - so that all of the dependencies are symlinked to a central - location. If you see an error message like: - - .. code-block:: console - - Traceback (most recent call last): - File: "/usr/bin/flake8", line 5, in <module> - from pkg_resources import load_entry_point - ImportError: No module named pkg_resources - - that means Flake8 couldn't find setuptools in your ``PYTHONPATH``. ^^^^^^^^^^^^^^^^^^^ Documentation Tests @@ -309,13 +288,9 @@ All of these can be installed with Spack, e.g. .. code-block:: console - $ spack activate py-sphinx - $ spack activate py-sphinx-rtd-theme - $ spack activate py-sphinxcontrib-programoutput + $ spack load py-sphinx py-sphinx-rtd-theme py-sphinxcontrib-programoutput - so that all of the dependencies are symlinked into that Python's - tree. Alternatively, you could arrange for their library - directories to be added to PYTHONPATH. If you see an error message + so that all of the dependencies are added to PYTHONPATH. If you see an error message like: .. code-block:: console diff --git a/lib/spack/docs/environments.rst b/lib/spack/docs/environments.rst index 9f75f789ae..2fd51baafb 100644 --- a/lib/spack/docs/environments.rst +++ b/lib/spack/docs/environments.rst @@ -233,8 +233,8 @@ packages will be listed as roots of the Environment. All of the Spack commands that act on the list of installed specs are Environment-sensitive in this way, including ``install``, -``uninstall``, ``activate``, ``deactivate``, ``find``, ``extensions``, -and more. In the :ref:`environment-configuration` section we will discuss +``uninstall``, ``find``, ``extensions``, and more. In the +:ref:`environment-configuration` section we will discuss Environment-sensitive commands further. ^^^^^^^^^^^^^^^^^^^^^ diff --git a/lib/spack/docs/packaging_guide.rst b/lib/spack/docs/packaging_guide.rst index 2ceb4ce051..fb1d5edcab 100644 --- a/lib/spack/docs/packaging_guide.rst +++ b/lib/spack/docs/packaging_guide.rst @@ -2722,67 +2722,6 @@ extensions; as a consequence python extension packages (those inheriting from ``PythonPackage``) likewise override ``add_files_to_view`` in order to rewrite shebang lines which point to the Python interpreter. -^^^^^^^^^^^^^^^^^^^^^^^^^ -Activation & deactivation -^^^^^^^^^^^^^^^^^^^^^^^^^ - -Adding an extension to a view is referred to as an activation. If the view is -maintained in the Spack installation prefix of the extendee this is called a -global activation. Activations may involve updating some centralized state -that is maintained by the extendee package, so there can be additional work -for adding extensions compared with non-extension packages. - -Spack's ``Package`` class has default ``activate`` and ``deactivate`` -implementations that handle symbolically linking extensions' prefixes -into a specified view. Extendable packages can override these methods -to add custom activate/deactivate logic of their own. For example, -the ``activate`` and ``deactivate`` methods in the Python class handle -symbolic linking of extensions, but they also handle details surrounding -Python's ``.pth`` files, and other aspects of Python packaging. - -Spack's extensions mechanism is designed to be extensible, so that -other packages (like Ruby, R, Perl, etc.) can provide their own -custom extension management logic, as they may not handle modules the -same way that Python does. - -Let's look at Python's activate function: - -.. literalinclude:: _spack_root/var/spack/repos/builtin/packages/python/package.py - :pyobject: Python.activate - :linenos: - -This function is called on the *extendee* (Python). It first calls -``activate`` in the superclass, which handles symlinking the -extension package's prefix into the specified view. It then does -some special handling of the ``easy-install.pth`` file, part of -Python's setuptools. - -Deactivate behaves similarly to activate, but it unlinks files: - -.. literalinclude:: _spack_root/var/spack/repos/builtin/packages/python/package.py - :pyobject: Python.deactivate - :linenos: - -Both of these methods call some custom functions in the Python -package. See the source for Spack's Python package for details. - -^^^^^^^^^^^^^^^^^^^^ -Activation arguments -^^^^^^^^^^^^^^^^^^^^ - -You may have noticed that the ``activate`` function defined above -takes keyword arguments. These are the keyword arguments from -``extends()``, and they are passed to both activate and deactivate. - -This capability allows an extension to customize its own activation by -passing arguments to the extendee. Extendees can likewise implement -custom ``activate()`` and ``deactivate()`` functions to suit their -needs. - -The only keyword argument supported by default is the ``ignore`` -argument, which can take a regex, list of regexes, or a predicate to -determine which files *not* to symlink during activation. - .. _virtual-dependencies: -------------------- |