diff options
| -rw-r--r-- | lib/spack/docs/case_studies.rst | 167 | ||||
| -rw-r--r-- | lib/spack/docs/index.rst | 1 |
2 files changed, 168 insertions, 0 deletions
diff --git a/lib/spack/docs/case_studies.rst b/lib/spack/docs/case_studies.rst new file mode 100644 index 0000000000..bcd754fdcd --- /dev/null +++ b/lib/spack/docs/case_studies.rst @@ -0,0 +1,167 @@ +Using Spack for CMake-based Development +========================================== + +These are instructions on how to use Spack to aid in the development +of a CMake-based project. Spack is used to help find the dependencies +for the project, configure it at development time, and then package it +it in a way that others can install. Using Spack for CMake-based +development consists of three parts: + +1. Setting up the CMake build in your software +2. Writing the Spack Package +3. Using it from Spack. + + +Setting Up the CMake Build +--------------------------------------- + +You should follow standard CMake conventions in setting up your +software, your CMake build should NOT depend on or require Spack to +build. See here for an example: + https://github.com/citibeth/icebin + +Note that there's one exception here to the rule I mentioned above. +In ``CMakeLists.txt``, I have the following line:: + + include_directories($ENV{CMAKE_TRANSITIVE_INCLUDE_PATH}) + + +This is a hook into Spack, and it ensures that all transitive +dependencies are included in the include path. It's not needed if +everything is in one tree, but it is (sometimes) in the Spack world; +when running without Spack, it has no effect. + +Note that this "feature" is controversial, could break with future +versions of GNU ld, and probably not the best to use. The best +practice is that you make sure that anything you #include is listed as +a dependency in your CMakeLists.txt. + +To be more specific: if you #inlcude something from package A and an +installed HEADER FILE in A #includes something from package B, then +you should also list B as a dependency in your CMake build. If you +depend on A but header files exported by A do NOT #include things from +B, then you do NOT need to list B as a dependency --- even if linking +to A links in libB.so as well. + +I also recommend that you set up your CMake build to use RPATHs +correctly. Not only is this a good idea and nice, but it also ensures +that your package will build the same with or without ``spack +install``. + +Writing the Spack Package +--------------------------------------- + +Now that you have a CMake build, you want to tell Spack how to +configure it. This is done by writing a Spack package for your +software. See here for example: + https://github.com/citibeth/spack/blob/efischer/develop/var/spack/repos/builtin/packages/icebin/package.py + +You need to subclass ``CMakePackage``, as is done in this example. +This enables advanced features of Spack for helping you in configuring +your software (keep reading...). Instead of an ``install()`` method +used when subclassing ``Package``, you write ``configure_args()``. +See here for more info on how this works: + https://github.com/LLNL/spack/pull/543/files + +NOTE: if your software is not publicly available, you do not need to +set the URL or version. Or you can set up bogus URLs and +versions... whatever causes Spack to not crash. + + +Using it from Spack +-------------------------------- + +Now that you have a Spack package, you can get Spack to setup your +CMake project for you. Use the following to setup, configure and +build your project:: + + cd myproject + spack spconfig myproject@local + mkdir build; cd build + ../spconfig.py .. + make + make install + + +Everything here should look pretty familiar here from a CMake +perspective, except that ``spack spconfig`` creates the file +``spconfig.py``, which calls CMake with arguments appropriate for your +Spack configuration. Think of it as the equivalent to running a bunch +of ``spack location -i`` commands. You will run ``spconfig.py`` +instead of running CMake directly. + +If your project is publicly available (eg on GitHub), then you can +ALSO use this setup to "just install" a release version without going +through the manual configuration/build step. Just do: + +1. Put tag(s) on the version(s) in your GitHub repo you want to be release versions. + +2. Set the ``url`` in your ``package.py`` to download a tarball for + the appropriate version. (GitHub will give you a tarball for any + version in the repo, if you tickle it the right way). For example:: + + https://github.com/citibeth/icebin/tarball/v0.1.0 + + Set up versions as appropriate in your ``package.py``. (Manually + download the tarball and run ``md5sum`` to determine the + appropriate checksum for it). + +3. Now you should be able to say ``spack install myproject@version`` + and things "just work." + +NOTE... in order to use the features outlined in this post, you +currently need to use the following branch of Spack: + https://github.com/citibeth/spack/tree/efischer/develop + +There is a pull request open on this branch ( +https://github.com/LLNL/spack/pull/543 ) and we are working to get it +integrated into the main ``develop`` branch. + + +Activating your Software +------------------------------------- + +Once you've built your software, you will want to load it up. You can +use ``spack load mypackage@local`` for that in your ``.bashrc``, but +that is slow. Try stuff like the following instead: + +The following command will load the Spack-installed packages needed +for basic Python use of IceBin:: + + module load `spack module find tcl icebin netcdf cmake@3.5.1` + module load `spack module find --dependencies tcl py-basemap py-giss` + + +You can speed up shell startup by turning these into ``module load`` commands. + +1. Cut-n-paste the script ``make_spackenv``:: + + #!/bin/sh + # + # Generate commands to load the Spack environment + + SPACKENV=$HOME/spackenv.sh + + spack module find --shell tcl git icebin@local ibmisc netcdf cmake@3.5.1 >$SPACKENV + spack module find --dependencies --shell tcl py-basemap py-giss >>$SPACKENV + +2. Add the following to your ``.bashrc`` file:: + + source $HOME/spackenv.sh + # Preferentially use your checked-out Python source + export PYTHONPATH=$HOME/icebin/pylib:$PYTHONPATH + +3. Run ``sh make_spackenv`` whenever your Spack installation changes (including right now). + + +Giving Back +------------------- + +If your software is publicly available, you should submit the +``package.py`` for it as a pull request to the main Spack GitHub +project. This will ensure that anyone can install your software +(almost) painlessly with a simple ``spack install`` command. See here +for how that has turned into detailed instructions that have +successfully enabled collaborators to install complex software: + + https://github.com/citibeth/icebin/blob/develop/README.rst diff --git a/lib/spack/docs/index.rst b/lib/spack/docs/index.rst index 98ed9ff0fe..a5bbd4e23b 100644 --- a/lib/spack/docs/index.rst +++ b/lib/spack/docs/index.rst @@ -49,6 +49,7 @@ Table of Contents mirrors configuration developer_guide + case_studies command_index package_list API Docs <spack> |