diff options
Diffstat (limited to 'lib')
| -rw-r--r-- | lib/spack/docs/packaging_guide.rst | 102 |
1 files changed, 99 insertions, 3 deletions
diff --git a/lib/spack/docs/packaging_guide.rst b/lib/spack/docs/packaging_guide.rst index c815c97dd7..8b1576ae88 100644 --- a/lib/spack/docs/packaging_guide.rst +++ b/lib/spack/docs/packaging_guide.rst @@ -809,12 +809,108 @@ after it's downloaded. ~~~~~~~~~~~~~~~~~~~~~ You can specif patches in your package file with the ``patch()`` -function. ``patch`` looks like this:: +function. ``patch`` looks like this: -.. literalinclude:: ../spack/packages/mvapich2/__init__.py - :end-before: def install +.. code-block:: python + + class Mvapich2(Package): + ... + patch('http://www.example.com/ad_lustre_rwcontig_open_source.patch', + when='@1.9:') + +The first argument can be either a URL or a filename. It specifies a +patch file that should be applied to your source. If it is a URL, as +above, then the patch will be fetched from the URL and then applied to +your source code. If the patch you supply is a filename, then the +patch needs to live within the spack source tree. + +``patch`` can take two options keyword arguments. They are: + +``when`` + If supplied, this is a spec that tells spack when to apply + the patch. If the installed package spec matches this spec, the + patch will be applied. In our example above, the patch is applied + when mvapich is at version ``1.9`` or higher. + +``level`` + This tells spack how to run the ``patch`` command. By default, + the level is 1 and spack runs ``patch -p1``. If level is 2, + spack will run ``patch -p2``, and so on. + +A lot of people are confused by level, so here's a primer. If you +look in your patch file, you'll see something like this: + +.. code-block:: diff + + --- a/src/mpi/romio/adio/ad_lustre/ad_lustre_rwcontig.c 2013-12-10 12:05:44.806417000 -0800 + +++ b/src/mpi/romio/adio/ad_lustre/ad_lustre_rwcontig.c 2013-12-10 11:53:03.295622000 -0800 + @@ -8,7 +8,7 @@ + * Copyright (C) 2008 Sun Microsystems, Lustre group + */ + + -#define _XOPEN_SOURCE 600 + +//#define _XOPEN_SOURCE 600 + #include <stdlib.h> + #include <malloc.h> + #include "ad_lustre.h" + +The first two lines show paths with synthetic ``a/`` and ``b/`` +prefixes. These are placeholders for the two ``mvapich2`` source +directories that ``diff`` compared when it created the patch file. +It's actually the default behavior for most programs that produce +patch files. + +``-p1`` strings off the first level of prefix in both paths, allowing +the patch to be applied from the root of an expanded mvapich2 archive. +If you set level to ``2``, it would strip off ``src``, and so on. + +It's generally easier to just structure your patch file so that it +applies cleanly with ``-p1``, but if you're using a URL to a patch you +didn't create yourself, ``level`` can be handy. +Patch files +~~~~~~~~~~~~~~~~~~~~~ + +If you don't want to use URLs, where in the spack source tree should +you put patch files? + +We told you before that the ``mvapich2`` package needs to live in a +python file like this:: + + $SPACK_ROOT/lib/spack/spack/ + packages/ + mvapich2.py + +This isn't actually the whole truth. Packages in spack are actually +just python modules, and another way to structure your python module +is to use a directory containing ``__init__.py``. So, you can make +some room for your patch file like this:: + + $ cd $SPACK_ROOT/lib/spack/spack/packages + $ mkdir mvapich2 + $ mv mvapich2.py mvapich2/__init__.py + +You can now put the patch file alongside ``__init__``.py inside the +``mvapich2`` directory. Your package directory now looks like this:: + + $SPACK_ROOT/lib/spack/spack/ + packages/ + mvapich2/ + __init__.py + ad_lustre_rwcontig_open_source.patch + +And ``__init__.py`` should look something like this: + +.. code-block:: python + + class Mvapich2(Package): + ... + patch('ad_lustre_rwcontig_open_source.patch', when='@1.9:') + +The path to the local patch file should be relative to the package's +directory in Spack, i.e. relative to +``$SPACK_ROOT/lib/spack/spack/packages/<pkg_name>``. .. _install-method: |