diff options
| -rw-r--r-- | lib/spack/docs/basic_usage.rst | 42 | ||||
| -rw-r--r-- | lib/spack/docs/conf.py | 2 | ||||
| -rw-r--r-- | lib/spack/docs/developer_guide.rst | 2 | ||||
| -rw-r--r-- | lib/spack/docs/features.rst | 2 | ||||
| -rw-r--r-- | lib/spack/docs/getting_started.rst | 13 | ||||
| -rw-r--r-- | lib/spack/docs/mirrors.rst | 6 | ||||
| -rw-r--r-- | lib/spack/docs/packaging_guide.rst | 62 | ||||
| -rw-r--r-- | lib/spack/docs/workflows.rst | 76 |
8 files changed, 97 insertions, 108 deletions
diff --git a/lib/spack/docs/basic_usage.rst b/lib/spack/docs/basic_usage.rst index a5377415c7..bbedfff3fc 100644 --- a/lib/spack/docs/basic_usage.rst +++ b/lib/spack/docs/basic_usage.rst @@ -1,7 +1,7 @@ .. _basic-usage: =========== -Basic usage +Basic Usage =========== The ``spack`` command has many *subcommands*. You'll only need a @@ -14,7 +14,7 @@ Spack to maintain this colorization. E.g.: $ spack find | less -R -It is recommend that the following be put in your ``.bashrc`` file: +It is recommended that the following be put in your ``.bashrc`` file: .. code-block:: sh @@ -28,7 +28,7 @@ To install software with Spack, you need to know what software is available. You can see a list of available package names at the :ref:`package-list` webpage, or using the ``spack list`` command. -.. _spack-list: +.. _cmd-spack-list: ^^^^^^^^^^^^^^ ``spack list`` @@ -57,13 +57,13 @@ All packages whose names start with a capital M: All packages whose names or descriptions contain Documentation: -.. command-output:: spack list -d Documentation +.. command-output:: spack list --search-description Documentation All packages whose names contain documentation case insensitive: -.. command-output:: spack list -d documentation +.. command-output:: spack list --search-description documentation -.. _spack-info: +.. _cmd-spack-info: ^^^^^^^^^^^^^^ ``spack info`` @@ -82,7 +82,7 @@ viruses. :ref:`Dependencies <sec-specs>` and :ref:`virtual dependencies <sec-virtual-dependencies>` are described in more detail later. -.. _spack-versions: +.. _cmd-spack-versions: ^^^^^^^^^^^^^^^^^^ ``spack versions`` @@ -107,7 +107,7 @@ able to find remote versions. Installing and uninstalling --------------------------- -.. _spack-install: +.. _cmd-spack-install: ^^^^^^^^^^^^^^^^^ ``spack install`` @@ -180,14 +180,14 @@ configuration a **spec**. In the commands above, ``mpileaks`` and ``mpileaks@3.0.4`` are both valid *specs*. We'll talk more about how you can use them to customize an installation in :ref:`sec-specs`. -.. _spack-uninstall: +.. _cmd-spack-uninstall: ^^^^^^^^^^^^^^^^^^^ ``spack uninstall`` ^^^^^^^^^^^^^^^^^^^ To uninstall a package, type ``spack uninstall <package>``. This will ask -the user for confirmation, and in case will completely remove the directory +the user for confirmation before completely removing the directory in which the package was installed. .. code-block:: console @@ -285,7 +285,7 @@ Seeing installed packages We know that ``spack list`` shows you the names of available packages, but how do you figure out which are already installed? -.. _spack-find: +.. _cmd-spack-find: ^^^^^^^^^^^^^^ ``spack find`` @@ -798,7 +798,7 @@ it refers. Otherwise, it will prompt for a more qualified hash. Note that this will not work to reinstall a depencency uninstalled by ``spack uninstall --force``. -.. _spack-providers: +.. _cmd-spack-providers: ^^^^^^^^^^^^^^^^^^^ ``spack providers`` @@ -1373,7 +1373,7 @@ an *extension*. Suppose you have Python installed like so: -- linux-debian7-x86_64 / gcc@4.4.7 -------------------------------- python@2.7.8 -.. _spack-extensions: +.. _cmd-spack-extensions: ^^^^^^^^^^^^^^^^^^^^ ``spack extensions`` @@ -1467,7 +1467,7 @@ for this case. Instead of requiring users to load particular environment modules, you can *activate* the package within the Python installation: -.. _spack-activate: +.. _cmd-spack-activate: ^^^^^^^^^^^^^^^^^^ ``spack activate`` @@ -1532,19 +1532,19 @@ into the same prefix. Users who want a different version of a package can still get it by using environment modules, but they will have to explicitly load their preferred version. -^^^^^^^^^^^^^^^^^^^^^ -``spack activate -f`` -^^^^^^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^^^^^^^^^^^ +``spack activate --force`` +^^^^^^^^^^^^^^^^^^^^^^^^^^ If, for some reason, you want to activate a package *without* its -dependencies, you can use ``spack activate -f``: +dependencies, you can use ``spack activate --force``: .. code-block:: console - $ spack activate -f py-numpy + $ 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. -.. _spack-deactivate: +.. _cmd-spack-deactivate: ^^^^^^^^^^^^^^^^^^^^ ``spack deactivate`` @@ -1622,7 +1622,7 @@ A nicer error message is TBD in future versions of Spack. Getting Help ------------ -.. _spack-help: +.. _cmd-spack-help: ^^^^^^^^^^^^^^ ``spack help`` diff --git a/lib/spack/docs/conf.py b/lib/spack/docs/conf.py index 57469964ee..08c57b8525 100644 --- a/lib/spack/docs/conf.py +++ b/lib/spack/docs/conf.py @@ -79,7 +79,7 @@ command_names = [] for filename in glob('*rst'): with open(filename) as f: for line in f: - match = re.match(r'.. _(spack-[^:]*)', line) + match = re.match('.. _(cmd-spack-.*):', line) if match: command_names.append(match.group(1).strip()) diff --git a/lib/spack/docs/developer_guide.rst b/lib/spack/docs/developer_guide.rst index 27f03df57a..0942fdd9c3 100644 --- a/lib/spack/docs/developer_guide.rst +++ b/lib/spack/docs/developer_guide.rst @@ -331,7 +331,7 @@ Profiling Spack has some limited built-in support for profiling, and can report statistics using standard Python timing tools. To use this feature, -supply ``-p`` to Spack on the command line, before any subcommands. +supply ``--profile`` to Spack on the command line, before any subcommands. .. _spack-p: diff --git a/lib/spack/docs/features.rst b/lib/spack/docs/features.rst index 57629997aa..2df1d182d6 100644 --- a/lib/spack/docs/features.rst +++ b/lib/spack/docs/features.rst @@ -1,5 +1,5 @@ ================ -Feature overview +Feature Overview ================ This is a high-level overview of features that make Spack different diff --git a/lib/spack/docs/getting_started.rst b/lib/spack/docs/getting_started.rst index 3130d1e25c..7510693b18 100644 --- a/lib/spack/docs/getting_started.rst +++ b/lib/spack/docs/getting_started.rst @@ -135,7 +135,7 @@ compiler versions. Spack searches for compilers on your machine automatically the first time it is run. It does this by inspecting your ``PATH``. -.. _spack-compilers: +.. _cmd-spack-compilers: ^^^^^^^^^^^^^^^^^^^ ``spack compilers`` @@ -559,7 +559,7 @@ flags to the ``icc`` command: .. code-block:: console - $ spack location -i gcc + $ spack location --install-dir gcc /home2/rpfische/spack2/opt/spack/linux-centos7-x86_64/gcc-4.9.3-iy4rw... #. Set up ``compilers.yaml``, for example: @@ -761,14 +761,13 @@ by installing a new version of ``git`` and ``openssl``: #. Add the output of ``spack module loads git`` to your ``.bahsrc``. If this doesn't work, it is also possible to disable checking of SSL -certificates by using either of: +certificates by using: .. code-block:: console - $ spack -k install $ spack --insecure install -Using ``-k/--insecure`` makes Spack disable SSL checking when fetching +Using ``--insecure`` makes Spack disable SSL checking when fetching from websites and from git. .. warning:: @@ -810,7 +809,7 @@ or if environment modules don't work: .. code-block:: console - $ export PATH=`spack location -i curl`/bin:$PATH + $ export PATH=`spack location --install-dir curl`/bin:$PATH External commands are used by Spack in two places: within core Spack, @@ -899,7 +898,7 @@ with Spack: TMP=`tempfile` echo >$TMP - MODULE_HOME=`spack location -i environment-modules` + 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 diff --git a/lib/spack/docs/mirrors.rst b/lib/spack/docs/mirrors.rst index c4d275a8fc..87ce3d96a2 100644 --- a/lib/spack/docs/mirrors.rst +++ b/lib/spack/docs/mirrors.rst @@ -52,7 +52,7 @@ contains tarballs for each package, named after each package. not standardize on a particular compression algorithm, because this would potentially require expanding and re-compressing each archive. -.. _spack-mirror: +.. _cmd-spack-mirror: ---------------- ``spack mirror`` @@ -148,7 +148,7 @@ can supply a file with specs in it, one per line: boost@1.44: boost@1.39.0 ... - $ spack mirror create -f specs.txt + $ spack mirror create --file specs.txt ... This is useful if there is a specific suite of software managed by @@ -237,7 +237,7 @@ as other Spack mirrors (so it can be copied anywhere and referenced with a URL like other mirrors). The mirror is maintained locally (within the Spack installation directory) at :file:`var/spack/cache/`. It is always enabled (and is always searched first when attempting to retrieve files for an installation) -but can be cleared with :ref:`purge <spack-purge>`; the cache directory can also +but can be cleared with :ref:`purge <cmd-spack-purge>`; the cache directory can also be deleted manually without issue. Caching includes retrieved tarball archives and source control repositories, but diff --git a/lib/spack/docs/packaging_guide.rst b/lib/spack/docs/packaging_guide.rst index 6efb0078f6..15c3e0ca7f 100644 --- a/lib/spack/docs/packaging_guide.rst +++ b/lib/spack/docs/packaging_guide.rst @@ -33,7 +33,7 @@ easy. Creating & editing packages --------------------------- -.. _spack-create: +.. _cmd-spack-create: ^^^^^^^^^^^^^^^^ ``spack create`` @@ -81,7 +81,7 @@ Spack will automatically download the number of tarballs you specify You do not *have* to download all of the versions up front. You can always choose to download just one tarball initially, and run -:ref:`spack checksum <spack-checksum>` later if you need more. +:ref:`cmd-spack-checksum` later if you need more. .. note:: @@ -93,14 +93,14 @@ always choose to download just one tarball initially, and run $ spack create --name cmake http://www.cmake.org/files/v2.8/cmake-2.8.12.1.tar.gz If it fails entirely, you can get minimal boilerplate by using - :ref:`spack-edit-f`, or you can manually create a directory and + :ref:`spack edit --force <spack-edit-f>`, or you can manually create a directory and ``package.py`` file for the package in ``var/spack/repos/builtin/packages``. .. note:: Spack can fetch packages from source code repositories, but, ``spack create`` will *not* currently create a boilerplate package - from a repository URL. You will need to use :ref:`spack-edit-f` + from a repository URL. You will need to use :ref:`spack edit --force <spack-edit-f>` and manually edit the ``version()`` directives to fetch from a repo. See :ref:`vcs-fetch` for details. @@ -198,7 +198,7 @@ The rest of the tasks you need to do are as follows: Before going into details, we'll cover a few more basics. -.. _spack-edit: +.. _cmd-spack-edit: ^^^^^^^^^^^^^^ ``spack edit`` @@ -238,7 +238,7 @@ package: .. code-block:: console - $ spack edit -f foo + $ spack edit --force foo Unlike ``spack create``, which infers names and versions, and which actually downloads the tarball and checksums it for you, ``spack edit @@ -271,8 +271,8 @@ Naming & directory structure ---------------------------- This section describes how packages need to be named, and where they -live in Spack's directory structure. In general, :ref:`spack-create` and -:ref:`spack-edit` handle creating package files for you, so you can skip +live in Spack's directory structure. In general, :ref:`cmd-spack-create` and +:ref:`cmd-spack-edit` handle creating package files for you, so you can skip most of the details here. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -371,7 +371,7 @@ some examples: ================= ================= In general, you won't have to remember this naming convention because -:ref:`spack-create` and :ref:`spack-edit` handle the details for you. +:ref:`cmd-spack-create` and :ref:`cmd-spack-edit` handle the details for you. ----------------- Trusted Downloads @@ -590,7 +590,7 @@ Doing this for lots of files, or whenever a new package version is released, is tedious. See ``spack checksum`` below for an automated version of this process. -.. _spack-checksum: +.. _cmd-spack-checksum: ^^^^^^^^^^^^^^^^^^ ``spack checksum`` @@ -1120,7 +1120,7 @@ function gives you some benefits. First, spack ensures that the ``patch()`` function is run once per code checkout. That means that if you run install, hit ctrl-C, and run install again, the code in the patch function is only run once. Also, you can tell Spack to run only -the patching part of the build using the :ref:`spack-patch` command. +the patching part of the build using the :ref:`cmd-spack-patch` command. --------------- Handling RPATHs @@ -1134,7 +1134,7 @@ dynamic loader where to find its dependencies at runtime. You may be familiar with `LD_LIBRARY_PATH <http://tldp.org/HOWTO/Program-Library-HOWTO/shared-libraries.html>`_ on Linux or `DYLD_LIBRARY_PATH -<https://developer.apple.com/library/mac/documentation/Darwin/Reference/ManPages/man1/dyld.1.html>` +<https://developer.apple.com/library/mac/documentation/Darwin/Reference/ManPages/man1/dyld.1.html>`_ on Mac OS X. RPATH is similar to these paths, in that it tells the loader where to find libraries. Unlike them, it is embedded in the binary and not set in each user's environment. @@ -1191,7 +1191,7 @@ information about the package, and to determine where to download its source code. Spack uses the tarball URL to extrapolate where to find other tarballs -of the same package (e.g. in `spack checksum <spack-checksum_>`_, but +of the same package (e.g. in :ref:`cmd-spack-checksum`, but this does not always work. This section covers ways you can tell Spack to find tarballs elsewhere. @@ -1202,7 +1202,7 @@ Spack to find tarballs elsewhere. ^^^^^^^^^^^^ When spack tries to find available versions of packages (e.g. with -`spack checksum <spack-checksum_>`_), it spiders the parent directory +:ref:`cmd-spack-checksum`), it spiders the parent directory of the tarball in the ``url`` attribute. For example, for libelf, the url is: @@ -1859,7 +1859,7 @@ explicitly. Concretization policies are discussed in more detail in :ref:`configuration`. Sites using Spack can customize them to match the preferences of their own users. -.. _spack-spec: +.. _cmd-spack-spec: ^^^^^^^^^^^^^^ ``spack spec`` @@ -2092,7 +2092,7 @@ discover its dependencies. If you want to see the environment that a package will build with, or if you want to run commands in that environment to test them out, you -can use the :ref:`spack env <spack-env>` command, documented +can use the :ref:`cmd-spack-env` command, documented below. .. _compiler-wrappers: @@ -2871,7 +2871,7 @@ A typical package workflow might look like this: Below are some commands that will allow you some finer-grained control over the install process. -.. _spack-fetch: +.. _cmd-spack-fetch: ^^^^^^^^^^^^^^^ ``spack fetch`` @@ -2886,7 +2886,7 @@ directory will be located under ``$SPACK_HOME/var/spack``. When run after the archive has already been downloaded, ``spack fetch`` is idempotent and will not download the archive again. -.. _spack-stage: +.. _cmd-spack-stage: ^^^^^^^^^^^^^^^ ``spack stage`` @@ -2897,7 +2897,7 @@ the downloaded archive in its temporary directory, where it will be built by ``spack install``. Similar to ``fetch``, if the archive has already been expanded, ``stage`` is idempotent. -.. _spack-patch: +.. _cmd-spack-patch: ^^^^^^^^^^^^^^^ ``spack patch`` @@ -2911,7 +2911,7 @@ this step if they have been. If Spack discovers that patches didn't apply cleanly on some previous run, then it will restage the entire package before patching. -.. _spack-restage: +.. _cmd-spack-restage: ^^^^^^^^^^^^^^^^^ ``spack restage`` @@ -2927,7 +2927,7 @@ Does this in one of two ways: #. If the source was checked out from a repository, this deletes the build directory and checks it out again. -.. _spack-clean: +.. _cmd-spack-clean: ^^^^^^^^^^^^^^^ ``spack clean`` @@ -2938,7 +2938,7 @@ expanded/checked out source code *and* any downloaded archive. If ``fetch``, ``stage``, or ``install`` are run again after this, Spack's build process will start from scratch. -.. _spack-purge: +.. _cmd-spack-purge: ^^^^^^^^^^^^^^^ ``spack purge`` @@ -2996,7 +2996,7 @@ to get rid of the install prefix before you build again: Graphing dependencies --------------------- -.. _spack-graph: +.. _cmd-spack-graph: ^^^^^^^^^^^^^^^ ``spack graph`` @@ -3056,7 +3056,7 @@ For ``csh`` and ``tcsh`` run: ``spack cd`` will then be available. -.. _spack-cd: +.. _cmd-spack-cd: ^^^^^^^^^^^^ ``spack cd`` @@ -3081,14 +3081,14 @@ build it: directory containing the expanded ``libelf`` source code. There are a number of other places you can cd to in the spack directory hierarchy: -.. command-output:: spack cd -h +.. command-output:: spack cd --help Some of these change directory into package-specific locations (stage directory, install directory, package directory) and others change to -core spack locations. For example, ``spack cd -m`` will take you to +core spack locations. For example, ``spack cd --module-dir`` will take you to the main python source directory of your spack install. -.. _spack-env: +.. _cmd-spack-env: ^^^^^^^^^^^^^ ``spack env`` @@ -3117,7 +3117,7 @@ provide them after the spec argument to ``spack env``: This will cd to the build directory and then run ``configure`` in the package's build environment. -.. _spack-location: +.. _cmd-spack-location: ^^^^^^^^^^^^^^^^^^ ``spack location`` @@ -3129,13 +3129,13 @@ cd'ing to it. In bash, this: .. code-block:: console - $ cd $(spack location -b <spec>) + $ cd $(spack location --build-dir <spec>) is the same as: .. code-block:: console - $ spack cd -b <spec> + $ spack cd --build-dir <spec> ``spack location`` is intended for use in scripts or makefiles that need to know where packages are installed. e.g., in a makefile you @@ -3143,7 +3143,7 @@ might write: .. code-block:: makefile - DWARF_PREFIX = $(spack location -i libdwarf) + DWARF_PREFIX = $(spack location --install-dir libdwarf) CXXFLAGS += -I$DWARF_PREFIX/include CXXFLAGS += -L$DWARF_PREFIX/lib diff --git a/lib/spack/docs/workflows.rst b/lib/spack/docs/workflows.rst index b879fed124..314f57c8b5 100644 --- a/lib/spack/docs/workflows.rst +++ b/lib/spack/docs/workflows.rst @@ -79,7 +79,7 @@ The following set is not consistent: curl@7.50.1%gcc@5.3.0 arch=linux-SuSE11-x86_64 ^openssl@system%gcc@5.3.0 arch=linux-SuSE11-x86_64 ^zlib@1.2.8%gcc@5.3.0 arch=linux-SuSE11-x86_64 - zlib@1.2.7%gcc@5.3.0 arch=linux-SuSE11-x86_64 + zlib@1.2.7%gcc@5.3.0 arch=linux-SuSE11-x86_64 The compatibility of a set of installed packages determines what may be done with it. It is always possible to ``spack load`` any set of @@ -153,7 +153,7 @@ preferred versions and variants to use for packages. For example: This approach will work as long as you are building packages for just -one application. +one application. ^^^^^^^^^^^^^^^^^^^^^ Multiple Applications @@ -183,7 +183,6 @@ of usage: .. code-block:: sh #!/bin/sh - # compilers=( %gcc @@ -218,10 +217,6 @@ of usage: done done - - - - ------------------------------ Running Binaries from Packages ------------------------------ @@ -237,11 +232,11 @@ Find and Run The simplest way to run a Spack binary is to find it and run it! In many cases, nothing more is needed because Spack builds binaries with RPATHs. Spack installation directories may be found with ``spack -location -i`` commands. For example: +location --install-dir`` commands. For example: .. code-block:: console - $ spack location -i cmake + $ spack location --install-dir cmake /home/me/spack2/opt/spack/linux-SuSE11-x86_64/gcc-5.3.0/cmake-3.6.0-7cxrynb6esss6jognj23ak55fgxkwtx7 This gives the root of the Spack package; relevant binaries may be @@ -249,7 +244,7 @@ found within it. For example: .. code-block:: console - $ CMAKE=`spack location -i cmake`/bin/cmake + $ CMAKE=`spack location --install-dir cmake`/bin/cmake Standard UNIX tools can find binaries as well. For example: @@ -650,9 +645,9 @@ environments: Administrators might find things easier to maintain without the added "heavyweight" state of a view. -============================== +------------------------------ Developing Software with Spack -============================== +------------------------------ For any project, one needs to assemble an environment of that application's dependencies. You might consider @@ -700,10 +695,9 @@ can be seamlessly integrated into the Spack ecosystem. We will show how this process works by example, assuming the software you are creating is called ``mylib``. - ---------------------- +^^^^^^^^^^^^^^^^^^^^^ Write the CMake Build ---------------------- +^^^^^^^^^^^^^^^^^^^^^ For now, the techniques in this section only work for CMake-based projects, although they could be easily extended to other build @@ -731,7 +725,7 @@ The ``CMakeLists.txt`` file should be written as normal. A few caveats: # when building, don't use the install RPATH already # (but later on when installing) - SET(CMAKE_BUILD_WITH_INSTALL_RPATH FALSE) + SET(CMAKE_BUILD_WITH_INSTALL_RPATH FALSE) # add the automatically determined parts of the RPATH # which point to directories outside the build tree to the install RPATH @@ -770,9 +764,9 @@ The ``CMakeLists.txt`` file should be written as normal. A few caveats: .. _write-the-spack-package: ------------------------ +^^^^^^^^^^^^^^^^^^^^^^^ Write the Spack Package ------------------------ +^^^^^^^^^^^^^^^^^^^^^^^ The Spack package also needs to be written, in tandem with setting up the build (for example, CMake). The most important part of this task @@ -838,9 +832,9 @@ used for development: not used in development. Don't worry if you don't have any, or if they are behind a firewall. ----------------- +^^^^^^^^^^^^^^^^ Build with Spack ----------------- +^^^^^^^^^^^^^^^^ Now that you have a Spack package, you can use Spack to find its dependencies automatically. For example: @@ -894,11 +888,9 @@ into Git or downloading tarballs. problems in our experience, as long as your project sets RPATHs as shown above. You DO use RPATHs, right? - - --------------------- +^^^^^^^^^^^^^^^^^^^^ Build Other Software --------------------- +^^^^^^^^^^^^^^^^^^^^ Now that you've built ``mylib`` with Spack, you might want to build another package that depends on it --- for example, ``myapp``. This @@ -924,9 +916,9 @@ for example: .. _release-your-software: ---------------------- +^^^^^^^^^^^^^^^^^^^^^ Release Your Software ---------------------- +^^^^^^^^^^^^^^^^^^^^^ You are now ready to release your software as a tarball with a numbered version, and a Spack package that can build it. If you're @@ -952,7 +944,7 @@ hosted on GitHub, this process will be a bit easier. ==> Found 1 versions of mylib 0.1.2 https://github.com/citibeth/mylib/tarball/v0.1.2 - How many would you like to checksum? (default is 5, q to abort) + How many would you like to checksum? (default is 5, q to abort) ==> Downloading... ==> Trying to fetch from https://github.com/citibeth/mylib/tarball/v0.1.2 ######################################################################## 100.0% @@ -969,11 +961,9 @@ hosted on GitHub, this process will be a bit easier. Spack concretization will always prefer numbered version to non-numeric versions. Users will only get it if they ask for it. - - ------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^ Distribute Your Software ------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^ Once you've released your software, other people will want to build it; and you will need to tell them how. In the past, that has meant a @@ -1012,9 +1002,9 @@ Spack is the best way to install it: systems. The :ref:`getting_started` section should cover this, but there could always be issues. -------------------- +^^^^^^^^^^^^^^^^^^^ Other Build Systems -------------------- +^^^^^^^^^^^^^^^^^^^ ``spack setup`` currently only supports CMake-based builds, in packages that subclass ``CMakePackage``. The intent is that this @@ -1028,9 +1018,9 @@ Python Distutils is another popular build system that should get directly in the user's ``PYTHONPATH``. Then, edits in source files are immediately available to run without any install process at all! ----------- +^^^^^^^^^^ Conclusion ----------- +^^^^^^^^^^ The ``spack setup`` development workflow provides better automation, flexibility and safety than workflows relying on environment modules @@ -1049,9 +1039,9 @@ or filesystem views. However, it has some drawbacks: integrate Spack explicitly in their workflow. Not all users are willing to do this. -================== +------------------ Upstream Bug Fixes -================== +------------------ It is not uncommon to discover a bug in an upstream project while trying to build with Spack. Typically, the bug is in a package that @@ -1059,9 +1049,9 @@ serves a dependency to something else. This section describes procedure to work around and ultimately resolve these bugs, while not delaying the Spack user's main goal. ------------------ +^^^^^^^^^^^^^^^^^ Buggy New Version ------------------ +^^^^^^^^^^^^^^^^^ Sometimes, the old version of a package works fine, but a new version is buggy. For example, it was once found that `Adios did not build @@ -1092,9 +1082,9 @@ procedure is: depends_on('hdf5@:1.9', when='@:1.10.0') depends_on('hdf5', when='@1.10.1:') ----------------- +^^^^^^^^^^^^^^^^ No Version Works ----------------- +^^^^^^^^^^^^^^^^ Sometimes, *no* existing versions of a dependency work for a build. This typically happens when developing a new project: only then does @@ -1183,9 +1173,9 @@ of ``py-proj/package.py`` is instructive here: bugfix, then the unofficial ``version()`` line should be removed from the Spack package. -------- +^^^^^^^ Patches -------- +^^^^^^^ Spack's source patching mechanism provides another way to fix bugs in upstream projects. This has advantages and disadvantages compared to the procedures above. |