Skip to content

Commit ad357d0

Browse files
mnonnenmachermnonnenmacher
committed
docs: Move OrtProject package manager docs to the plugin
As detailed descriptions of plugins are now supported and automatically added to the website, move the docs of the `OrtProject` package manager to the plugin itself. Signed-off-by: Martin Nonnenmacher <martin.nonnenmacher@doubleopen.io>
1 parent 8a84185 commit ad357d0

3 files changed

Lines changed: 165 additions & 163 deletions

File tree

‎plugins/package-managers/ort-project-file/src/main/kotlin/OrtProjectFile.kt‎

Lines changed: 163 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,169 @@ import org.ossreviewtoolkit.model.config.Includes
3030
import org.ossreviewtoolkit.plugins.api.OrtPlugin
3131
import org.ossreviewtoolkit.plugins.api.PluginDescriptor
3232

33+
/**
34+
* The ORT Project package manager can be used to manually define projects in situations like:
35+
*
36+
* * Package manager is not supported by ORT yet.
37+
* * Project is using a custom or in-house package manager.
38+
* * Project has no package manager at all.
39+
* * Project contains additional packages that are not detected by the main package manager.
40+
*
41+
* ### Definition file location, naming and format
42+
*
43+
* #### Location
44+
*
45+
* To use the ORT Project Package Manager, just place the definition file(s) in any directory of your project.
46+
* If you have multiple projects in a mono-repo, it's possible to place multiple definition files in the project
47+
* sub-directories.
48+
*
49+
* #### File naming
50+
*
51+
* The ORT Project definition file must be named, or end with `ortproject.yml`, `ortproject.yaml`, or `ortproject.json`.
52+
* For example, all of the following names are valid:
53+
*
54+
* * `ortproject.yml`
55+
* * `my.ortproject.yaml`
56+
* * `custom-name.ortproject.json`
57+
*
58+
* ### Definition file format
59+
*
60+
* ORT Project package manager uses an ORT Project definition file to define projects and their dependencies.
61+
* Example definition files can be found below:
62+
*
63+
* #### Example files
64+
*
65+
* ~~~yaml
66+
* projectName: "Example ORT project"
67+
* description: "Project description"
68+
* homepageUrl: "https://project.example.com"
69+
* declaredLicenses:
70+
* - "Apache-2.0"
71+
* authors:
72+
* - "John Doe"
73+
* - "Foo Bar"
74+
* dependencies:
75+
* - purl: "pkg:maven/com.example/full@1.1.0"
76+
* description: "Package with fully elaborated model."
77+
* vcs:
78+
* type: "Mercurial"
79+
* url: "https://example.com/hg/full"
80+
* revision: "master"
81+
* path: "/"
82+
* sourceArtifact:
83+
* url: "https://repo.example.com/m2/full-1.1.0-sources.jar"
84+
* hash:
85+
* value: "da39a3ee5e6b4b0d3255bfef95601890afd80709"
86+
* algorithm: "SHA-1"
87+
* declaredLicenses:
88+
* - "Apache-2.0"
89+
* - "MIT"
90+
* homepageUrl: "https://project.example.com/full"
91+
* labels:
92+
* label: "value"
93+
* label2: "value2"
94+
* authors:
95+
* - "Doe John"
96+
* - "Bar Foo"
97+
* scopes:
98+
* - "main"
99+
* - "some_scope"
100+
* linkage: "DYNAMIC"
101+
* isModified: false
102+
* isMetadataOnly: false
103+
* - purl: "pkg:maven/com.example/minimal@0.1.0"
104+
* - id: "Maven:com.example:partial:1.0.1"
105+
* ~~~
106+
*
107+
* Minimal example file:
108+
*
109+
* ~~~yaml
110+
* dependencies:
111+
* - purl: "pkg:maven/com.example/full@1.1.0"
112+
* ~~~
113+
*
114+
* #### Definition file schema
115+
*
116+
* ##### Project schema
117+
*
118+
* The ORT Project definition file uses the following schema:
119+
*
120+
* ~~~yaml
121+
* projectName: String (optional) Project name.
122+
* description: String (optional) Project brief description.
123+
* homepageUrl: String (optional) URL to the project homepage.
124+
* # (optional) List of declared licenses for the project.
125+
* declaredLicenses:
126+
* - String list (optional) List of declared licenses in SPDX format (see remarks below).
127+
* # (optional) List of authors of the project.
128+
* authors:
129+
* - String Author name.
130+
* # (optional) List of dependency packages for the project.
131+
* dependencies:
132+
* - Dependency element schema (see below)
133+
* ~~~
134+
*
135+
* ##### Dependency element schema
136+
*
137+
* Single dependency package schema:
138+
*
139+
* ~~~yaml
140+
*
141+
* purl: String (mandatory at least one of the id or purl) Package URL in purl format (see remarks below).
142+
* id: String (mandatory at least one of the purl or id) Package identifier in the "ORT" format (see remarks below).
143+
* description: String (optional) Package brief description.
144+
* # (optional) Definition of the package's version control system location.
145+
* vcs:
146+
* type: String (mandatory) VCS type, e.g., "Git", "Subversion", "Mercurial".
147+
* url: String (mandatory) VCS repository URL.
148+
* revision: String (mandatory) VCS revision (branch).
149+
* path: String (optional) VCS path within the repository. Default is empty string.
150+
* # (optional) The remote artifact where the source package can be downloaded.
151+
* sourceArtifact:
152+
* url: String (mandatory) URL to the source artifact.
153+
* # (optional) Hash of the source artifact.
154+
* hash:
155+
* value: String (mandatory) hash value.
156+
* algorithm: String (mandatory) hash algorithm. Check remarks below for supported algorithms.
157+
* # (optional) List of declared licenses for the dependency.
158+
* declaredLicenses:
159+
* - String Declared license in SPDX format (see remarks below).
160+
* homepageUrl: String (optional) URL to the package homepage.
161+
* labels: (optional) User defined labels associated with this package. The labels are not interpreted by the core of
162+
* ORT itself, but can be used in parts of ORT such as plugins, in evaluator rules, or in reporter templates. Labels
163+
* are key-value pairs where both the key and value are strings.
164+
* # (optional) List of authors of the dependency.
165+
* authors:
166+
* - String Author name.
167+
* # (optional) List of scopes the package belongs to.
168+
* scopes:
169+
* - String Package's scope.
170+
* linkage: String (optional) linkage type, if set must be either "STATIC" or "DYNAMIC". If not set defaults to
171+
* "DYNAMIC".
172+
* isModified: Boolean (optional) Flag indicating whether the source code of the package has been modified compared to
173+
* the original source code, e.g., in case of a fork of an upstream Open Source project. Default is false.
174+
* isMetadataOnly: Boolean (optional) Flag indicating whether the package is just metadata, like e.g. Maven BOM
175+
* artifacts which only define constraints for dependency versions. Default is false.
176+
* ~~~
177+
*
178+
* #### Remarks
179+
*
180+
* * Each dependency package must at least define either a `purl` or an `id`.
181+
* * The `purl` field must contain a valid package identifier in
182+
* [PURL format](https://github.com/package-url/purl-spec).
183+
* Only purls starting with `pkg:` are supported.
184+
* Also, `qualifier` and `subpath` components are not supported.
185+
* * The `id` field must contain a valid ORT package identifier in the format:
186+
* `<package-manager>/<namespace>/<name>/<version>`.
187+
* * The following hash algorithms are supported in the `sourceArtifact.hash.algorithm` field:
188+
* * `MD5`
189+
* * `SHA-1`
190+
* * `SHA-256`
191+
* * `SHA-384`
192+
* * `SHA-512`
193+
* * `SHA-1-GIT`
194+
* * All license names must be in [SPDX format](https://spdx.org/licenses/).
195+
*/
33196
@OrtPlugin(
34197
displayName = "ORT Project File",
35198
summary = "A package manager that uses an ORT-specific file format as package list source.",

‎website/docs/guides/ort-project-package-manager.md‎

Lines changed: 0 additions & 161 deletions
This file was deleted.

‎website/docs/tools/analyzer.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -72,8 +72,8 @@ the generic fallbacks can be used:
7272

7373
### ORT Project package manager
7474

75-
The [ORT Project package manager](../guides/ort-project-package-manager.md) can be used to manually define projects and
76-
their dependencies in an ORT Project definition file.
75+
The [ORT Project package manager](../plugins/package-managers/ORT%20Project%20File.md) can be used to manually define
76+
projects and their dependencies in an ORT Project definition file.
7777

7878
### SPDX
7979

0 commit comments

Comments
 (0)