From 53d129236645b9f967514466b9d2748d97a564a0 Mon Sep 17 00:00:00 2001 From: Jubilee <46493976+workingjubilee@users.noreply.github.com> Date: Tue, 6 Feb 2024 23:40:58 -0800 Subject: [PATCH] Explain some caveats in license detection (#597) --- docs/src/checks/licenses/README.md | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/docs/src/checks/licenses/README.md b/docs/src/checks/licenses/README.md index 382c794e2..1ceba58a9 100644 --- a/docs/src/checks/licenses/README.md +++ b/docs/src/checks/licenses/README.md @@ -8,18 +8,25 @@ cargo deny check licenses ## SPDX -cargo-deny uses [SPDX license expressions][SPDX] as the source of truth for the license requirements of a crate. Note however, that cargo-deny does **not** (currently)exhaustively search the entirety of the source code of every crate to find every possible license that could be attributed to the crate, as there are a ton of edge cases to that approach. +cargo-deny uses [SPDX license expressions][SPDX] to interpret the license requirements of a crate. In the event that it cannot obtain an SPDX license expression directly from metadata, it tries to +derive such within the confidence threshold you specify. Note that cargo-deny currently does **not** exhaustively search the entirety of the source code of every crate to find every possible license that could be attributed to the crate. There are many edge cases to that approach, and human ingenuity, or even human error, can always outwit a statically-compiled program. -cargo-deny rather assumes that each crate correctly defines its license requirements, but it provides a mechanism for manually specifying the license requirements for crates in the, from our experience, rare circumstance that they cannot be gathered automatically. +cargo-deny makes a good-faith assumption each crate correctly defines its license requirements. In the (in our experience, rare) circumstance such data cannot be gathered automatically, it provides a mechanism for manually specifying the license requirements for crates. ### Expression Source Precedence -The source of the SPDX expression used to evaluate the crate by is obtained in the following order. +The source of the SPDX expression used to evaluate the crate's licensing requirement is obtained in the following order: 1. If the crate in question has a [Clarification](cfg.md#the-clarify-field-optional) applied to it, and the source file(s) in the crate's source still match, the expression from the clarification will be used. 1. The [`license`][cargo-md] field from the crate's Cargo.toml manifest will be used if it exists. 1. The [`license-file`][cargo-md] field, as well as **all** other `LICENSE(-*)?` files will be parsed to determine the SPDX license identifier, and then all of those identifiers will be joined with the `AND` operator, meaning that you must accept **all** of the licenses detected. +*Importantly*, this precedence, combined with the trust that licensing data is handled correctly, means the following edge cases are **not** handled. This is not an exhaustive list, but are rather a sample of the kinds of things a program is not able to completely prevent, even if more checks are added: + +1. **Absences**: If the package contains inadequate licensing data, in e.g. the event of a crate not reflecting the license of code it is linked with. +1. **Mismatches:** If the Cargo.toml documents a given SPDX expression that does not match the actual license files in the package, this is not checked. +1. **Inventiveness**: It is possible to place licensing data somewhere that is not in these locations, or have names that start with things other than `LICENSE`. There is no guarantee such placements inside a package would lose their legal force, even if there is other licensing data that cargo-deny may detect first and assume is comprehensive. + ### Evaluation Precedence Currently, the precedence for determining whether a particular license is accepted or rejected is as follows: