summaryrefslogtreecommitdiff
path: root/lib
diff options
context:
space:
mode:
authorTodd Gamblin <tgamblin@llnl.gov>2023-10-30 18:54:31 -0700
committerGitHub <noreply@github.com>2023-10-30 18:54:31 -0700
commit702a2250faec5d72734004404450453dff877908 (patch)
tree9d7db44ba317150c0d9f280d9e84966f64422cc2 /lib
parent3a0f9ce22602c3027bb6e0cf088abf4204604bd9 (diff)
downloadspack-702a2250faec5d72734004404450453dff877908.tar.gz
spack-702a2250faec5d72734004404450453dff877908.tar.bz2
spack-702a2250faec5d72734004404450453dff877908.tar.xz
spack-702a2250faec5d72734004404450453dff877908.zip
docs: update `license()` docs with examples and links (#40598)
- [x] Add links to information people are going to want to know when adding license information to their packages (namely OSI licenses and SPDX identifiers). - [x] Update the packaging docs for `license()` with Spack as an example for `when=`. After all, it's a dual-licensed package that changed once in the past. - [x] Add link to https://spdx.org/licenses/ in the `spack create` boilerplate as well.
Diffstat (limited to 'lib')
-rw-r--r--lib/spack/docs/packaging_guide.rst55
-rw-r--r--lib/spack/spack/cmd/create.py1
2 files changed, 45 insertions, 11 deletions
diff --git a/lib/spack/docs/packaging_guide.rst b/lib/spack/docs/packaging_guide.rst
index d488ae0c7f..fad913cb0f 100644
--- a/lib/spack/docs/packaging_guide.rst
+++ b/lib/spack/docs/packaging_guide.rst
@@ -3765,7 +3765,7 @@ Similarly, ``spack install example +feature build_system=autotools`` will pick
the ``AutotoolsBuilder`` and invoke ``./configure --with-my-feature``.
Dependencies are always specified in the package class. When some dependencies
-depend on the choice of the build system, it is possible to use when conditions as
+depend on the choice of the build system, it is possible to use when conditions as
usual:
.. code-block:: python
@@ -3783,7 +3783,7 @@ usual:
depends_on("cmake@3.18:", when="@2.0:", type="build")
depends_on("cmake@3:", type="build")
- # Specify extra build dependencies used only in the configure script
+ # Specify extra build dependencies used only in the configure script
with when("build_system=autotools"):
depends_on("perl", type="build")
depends_on("pkgconfig", type="build")
@@ -6831,25 +6831,58 @@ the adapter role is to "emulate" a method resolution order like the one represen
Specifying License Information
------------------------------
-A significant portion of software that Spack packages is open source. Most open
-source software is released under one or more common open source licenses.
-Specifying the specific license that a package is released under in a project's
-`package.py` is good practice. To specify a license, find the SPDX identifier for
-a project and then add it using the license directive:
+Most of the software in Spack is open source, and most open source software is released
+under one or more `common open source licenses <https://opensource.org/licenses/>`_.
+Specifying the license that a package is released under in a project's
+`package.py` is good practice. To specify a license, find the `SPDX identifier
+<https://spdx.org/licenses/>`_ for a project and then add it using the license
+directive:
.. code-block:: python
license("<SPDX Identifier HERE>")
+For example, the SPDX ID for the Apache Software License, version 2.0 is ``Apache-2.0``,
+so you'd write:
+
+.. code-block:: python
+
+ license("Apache-2.0")
+
+Or, for a dual-licensed package like Spack, you would use an `SPDX Expression
+<https://spdx.github.io/spdx-spec/v2-draft/SPDX-license-expressions/>`_ with both of its
+licenses:
+
+.. code-block:: python
+
+ license("Apache-2.0 OR MIT")
+
Note that specifying a license without a when clause makes it apply to all
versions and variants of the package, which might not actually be the case.
For example, a project might have switched licenses at some point or have
certain build configurations that include files that are licensed differently.
-To account for this, you can specify when licenses should be applied. For
-example, to specify that a specific license identifier should only apply
-to versionup to and including 1.5, you could write the following directive:
+Spack itself used to be under the ``LGPL-2.1`` license, until it was relicensed
+in version ``0.12`` in 2018.
+
+You can specify when a ``license()`` directive applies using with a ``when=``
+clause, just like other directives. For example, to specify that a specific
+license identifier should only apply to versions up to ``0.11``, but another
+license should apply for later versions, you could write:
.. code-block:: python
- license("...", when="@:1.5")
+ license("LGPL-2.1", when="@:0.11")
+ license("Apache-2.0 OR MIT", when="@0.12:")
+
+Note that unlike for most other directives, the ``when=`` constraints in the
+``license()`` directive can't intersect. Spack needs to be able to resolve
+exactly one license identifier expression for any given version. To specify
+*multiple* licenses, use SPDX expressions and operators as above. The operators
+you probably care most about are:
+
+* ``OR``: user chooses one license to adhere to; and
+* ``AND``: user has to adhere to all the licenses.
+You may also care about `license exceptions
+<https://spdx.org/licenses/exceptions-index.html>`_ that use the ``WITH`` operator,
+e.g. ``Apache-2.0 WITH LLVM-exception``.
diff --git a/lib/spack/spack/cmd/create.py b/lib/spack/spack/cmd/create.py
index 32c6ed13e1..946e9bc8b9 100644
--- a/lib/spack/spack/cmd/create.py
+++ b/lib/spack/spack/cmd/create.py
@@ -64,6 +64,7 @@ class {class_name}({base_class_name}):
# maintainers("github_user1", "github_user2")
# FIXME: Add the SPDX identifier of the project's license below.
+ # See https://spdx.org/licenses/ for a list.
license("UNKNOWN")
{versions}