diff options
Diffstat (limited to 'lib/spack/docs/getting_started.rst')
| -rw-r--r-- | lib/spack/docs/getting_started.rst | 161 |
1 files changed, 96 insertions, 65 deletions
diff --git a/lib/spack/docs/getting_started.rst b/lib/spack/docs/getting_started.rst index 9e59b28dac..8fd0840e35 100644 --- a/lib/spack/docs/getting_started.rst +++ b/lib/spack/docs/getting_started.rst @@ -1,3 +1,8 @@ +.. Copyright 2013-2018 Lawrence Livermore National Security, LLC and other + Spack Project Developers. See the top-level COPYRIGHT file for details. + + SPDX-License-Identifier: (Apache-2.0 OR MIT) + .. _getting_started: =============== @@ -11,7 +16,7 @@ Prerequisites Spack has the following minimum requirements, which must be installed before Spack is run: -1. Python 2 (2.6 or 2.7) or 3 (3.3 - 3.6) +1. Python 2 (2.6 or 2.7) or 3 (3.4 - 3.7) 2. A C/C++ compiler 3. The ``git`` and ``curl`` commands. 4. If using the ``gpg`` subcommand, ``gnupg2`` is required. @@ -163,7 +168,7 @@ compilers`` or ``spack compiler list``: Any of these compilers can be used to build Spack packages. More on how this is done is in :ref:`sec-specs`. -.. _spack-compiler-add: +.. _cmd-spack-compiler-add: ^^^^^^^^^^^^^^^^^^^^^^ ``spack compiler add`` @@ -171,7 +176,7 @@ how this is done is in :ref:`sec-specs`. An alias for ``spack compiler find``. -.. _spack-compiler-find: +.. _cmd-spack-compiler-find: ^^^^^^^^^^^^^^^^^^^^^^^ ``spack compiler find`` @@ -202,7 +207,14 @@ installed, but you know that new compilers have been added to your This loads the environment module for gcc-4.9.0 to add it to ``PATH``, and then it adds the compiler to Spack. -.. _spack-compiler-info: +.. note:: + + By default, spack does not fill in the ``modules:`` field in the + ``compilers.yaml`` file. If you are using a compiler from a + module, then you should add this field manually. + See the section on :ref:`compilers-requiring-modules`. + +.. _cmd-spack-compiler-info: ^^^^^^^^^^^^^^^^^^^^^^^ ``spack compiler info`` @@ -320,6 +332,7 @@ by adding the following to your ``packages.yaml`` file: all: compiler: [gcc@4.9.3] +.. _compilers-requiring-modules: ^^^^^^^^^^^^^^^^^^^^^^^^^^^ Compilers Requiring Modules @@ -484,6 +497,9 @@ simple package. For example: $ spack install zlib%gcc@5.3.0 + +.. _vendor-specific-compiler-configuration: + -------------------------------------- Vendor-Specific Compiler Configuration -------------------------------------- @@ -805,7 +821,7 @@ encountered on a Macintosh during ``spack install julia-master``: .. code-block:: console - ==> Trying to clone git repository: + ==> Cloning git repository: https://github.com/JuliaLang/julia.git on branch master Cloning into 'julia'... @@ -816,7 +832,7 @@ This problem is related to OpenSSL, and in some cases might be solved by installing a new version of ``git`` and ``openssl``: #. Run ``spack install git`` -#. Add the output of ``spack module loads git`` to your ``.bashrc``. +#. Add the output of ``spack module tcl loads git`` to your ``.bashrc``. If this doesn't work, it is also possible to disable checking of SSL certificates by using: @@ -861,7 +877,7 @@ or alternately: .. code-block:: console - $ spack module loads curl >>~/.bashrc + $ spack module tcl loads curl >>~/.bashrc or if environment modules don't work: @@ -926,75 +942,38 @@ Once ``curl`` has been installed, you can similarly install the others. Environment Modules """"""""""""""""""" -In order to use Spack's generated environment modules, you must have -installed one of *Environment Modules* or *Lmod*. On many Linux -distributions, this can be installed from the vendor's repository. For -example: ``yum install environment-modules`` (Fedora/RHEL/CentOS). If -your Linux distribution does not have Environment Modules, Spack can -build it for you! - -What follows are three steps describing how to install and use environment-modules with spack. - -#. Install ``environment-modules``. - - * ``spack bootstrap`` will build ``environment-modules`` for you (and may build - other packages that are useful to the operation of Spack) - - * Install ``environment-modules`` using ``spack install`` with - ``spack install environment-modules~X`` (The ``~X`` variant builds without Xorg - dependencies, but ``environment-modules`` works fine too.) - -#. Add ``modulecmd`` to ``PATH`` and create a ``module`` command. - - * If you are using ``bash`` or ``ksh``, Spack can currently do this for you as well. - After installing ``environment-modules`` following the step - above, source Spack's shell integration script. This will automatically - detect the lack of ``modulecmd`` and ``module``, and use the installed - ``environment-modules`` from ``spack bootstrap`` or ``spack install``. - - .. code-block:: console - - # For bash/zsh users - $ export SPACK_ROOT=/path/to/spack - $ . $SPACK_ROOT/share/spack/setup-env.sh +In order to use Spack's generated module files, you must have +installed ``environment-modules`` or ``lmod``. The simplest way +to get the latest version of either of these tools is installing +it as part of Spack's bootstrap procedure: +.. code-block:: console - * If you prefer to do it manually, you can activate with the following - script (or apply the updates to your ``.bashrc`` file manually): + $ spack bootstrap - .. code-block:: sh +.. warning:: + At the moment ``spack bootstrap`` is only able to install ``environment-modules``. + Extending its capabilities to prefer ``lmod`` where possible is in the roadmap, + and likely to happen before the next release. - TMP=`tempfile` - echo >$TMP - MODULE_HOME=`spack location --install-dir environment-modules` - MODULE_VERSION=`ls -1 $MODULE_HOME/Modules | head -1` - ${MODULE_HOME}/Modules/${MODULE_VERSION}/bin/add.modules <$TMP - cp .bashrc $TMP - echo "MODULE_VERSION=${MODULE_VERSION}" > .bashrc - cat $TMP >>.bashrc +Alternatively, on many Linux distributions, you can install a pre-built binary +from the vendor's repository. On Fedora/RHEL/CentOS, for example, this can be +done with the command: - This is added to your ``.bashrc`` (or similar) files, enabling Environment - Modules when you log in. - -#. Test that the ``module`` command is found with: +.. code-block:: console - .. code-block:: console + $ yum install environment-modules - $ module avail +Once you have the tool installed and available in your path, you can source +Spack's setup file: +.. code-block:: console -If ``tcl`` 8.0 or later is installed on your system, you can prevent -spack from rebuilding ``tcl`` as part of the ``environment-modules`` dependency -stack by adding the following to your ``~/.spack/packages.yaml`` replacing -version 8.5 with whatever version is installed on your system: + $ source share/spack/setup-env.sh - .. code-block:: yaml +This activates :ref:`shell support <shell-support>` and makes commands like +``spack load`` available for use. - packages: - tcl: - paths: - tcl@8.5: /usr - buildable: False ^^^^^^^^^^^^^^^^^ Package Utilities @@ -1096,6 +1075,37 @@ they may use packages you have signed using the ``--export <keyfile>`` flag. Secret keys may also be later exported using the ``spack gpg export <location> [<key>...]`` command. +.. note:: + + Key creation speed + The creation of a new GPG key requires generating a lot of random numbers. + Depending on the entropy produced on your system, the entire process may + take a long time (*even appearing to hang*). Virtual machines and cloud + instances are particularly likely to display this behavior. + + To speed it up you may install tools like ``rngd``, which is + usually available as a package in the host OS. On e.g. an + Ubuntu machine you need to give the following commands: + + .. code-block:: console + + $ sudo apt-get install rng-tools + $ sudo rngd -r /dev/urandom + + before generating the keys. + + Another alternative is ``haveged``, which can be installed on + RHEL/CentOS machines as follows: + + .. code-block:: console + + $ sudo yum install haveged + $ sudo chkconfig haveged on + + `This Digital Ocean tutorial + <https://www.digitalocean.com/community/tutorials/how-to-setup-additional-entropy-for-cloud-servers-using-haveged>`_ + provides a good overview of sources of randomness. + ^^^^^^^^^^^^ Listing keys ^^^^^^^^^^^^ @@ -1226,6 +1236,13 @@ cray-mpich module into the environment. You can then be able to use whatever environment variables, libraries, etc, that are brought into the environment via module load. +.. note:: + + For Cray-provided packages, it is best to use ``modules:`` instead of ``paths:`` + in ``packages.yaml``, because the Cray Programming Environment heavily relies on + modules (e.g., loading the ``cray-mpich`` module adds MPI libraries to the + compiler wrapper link line). + You can set the default compiler that Spack can use for each compiler type. If you want to use the Cray defaults, then set them under ``all:`` in packages.yaml. In the compiler field, set the compiler specs in your order of preference. @@ -1262,3 +1279,17 @@ for each compiler type for each cray modules. This ensures that for each compiler on our system we can use that external module. For more on external packages check out the section :ref:`sec-external-packages`. + +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Using Linux containers on Cray machines +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Spack uses environment variables particular to the Cray programming +environment to determine which systems are Cray platforms. These +environment variables may be propagated into containers that are not +using the Cray programming environment. + +To ensure that Spack does not autodetect the Cray programming +environment, unset the environment variable ``CRAYPE_VERSION``. This +will cause Spack to treat a linux container on a Cray system as a base +linux distro. |