xref: /aosp_15_r20/external/spdx-tools/README.md (revision ba677afa8f67bb56cbc794f4d0e378e0da058e16)
1*ba677afaSXin Li[![Build Status](https://github.com/spdx/tools-golang/workflows/build/badge.svg)](https://github.com/spdx/tools-golang/actions)
2*ba677afaSXin Li[![Coverage Status](https://coveralls.io/repos/github/spdx/tools-golang/badge.svg)](https://coveralls.io/github/spdx/tools-golang)
3*ba677afaSXin Li[![GitHub release](https://img.shields.io/github/release/spdx/tools-golang.svg)](https://github.com/spdx/tools-golang/releases/latest)
4*ba677afaSXin Li[![Go Reference](https://pkg.go.dev/badge/github.com/spdx/tools-golang.svg)](https://pkg.go.dev/github.com/spdx/tools-golang)
5*ba677afaSXin Li[![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/5710/badge)](https://bestpractices.coreinfrastructure.org/projects/5710)
6*ba677afaSXin Li
7*ba677afaSXin Li# SPDX tools-golang
8*ba677afaSXin Li
9*ba677afaSXin Litools-golang is a collection of Go packages intended to make it easier for
10*ba677afaSXin LiGo programs to work with [SPDX®](https://spdx.dev/) files.
11*ba677afaSXin Li
12*ba677afaSXin Li## Recent news
13*ba677afaSXin Li
14*ba677afaSXin Li2022-01-11: **v0.4.0**: added support for SPDX v2.3 and YAML, as well as other
15*ba677afaSXin Liimprovements and bugfixes. See [RELEASE-NOTES.md](./RELEASE-NOTES.md) for full
16*ba677afaSXin Lidetails.
17*ba677afaSXin Li
18*ba677afaSXin Li## What it does
19*ba677afaSXin Li
20*ba677afaSXin Litools-golang currently works with files conformant to versions 2.1 and 2.2
21*ba677afaSXin Liof the SPDX specification, available at: https://spdx.dev/specifications
22*ba677afaSXin Li
23*ba677afaSXin Litools-golang provides the following packages:
24*ba677afaSXin Li
25*ba677afaSXin Li* *spdx* - in-memory data model for the sections of an SPDX document
26*ba677afaSXin Li* *tvloader* - tag-value document loader
27*ba677afaSXin Li* *tvsaver* - tag-value document saver
28*ba677afaSXin Li* *rdfloader* - RDF document loader
29*ba677afaSXin Li* *json* - JSON document parser and writer
30*ba677afaSXin Li* *yaml* - YAML document parser and writer
31*ba677afaSXin Li* *builder* - builds "empty" SPDX document (with hashes) for directory contents
32*ba677afaSXin Li* *idsearcher* - searches for [SPDX short-form IDs](https://spdx.org/ids/) and builds SPDX document
33*ba677afaSXin Li* *licensediff* - compares concluded licenses between files in two packages
34*ba677afaSXin Li* *reporter* - generates basic license count report from SPDX document
35*ba677afaSXin Li* *spdxlib* - various utility functions for manipulating SPDX documents in memory
36*ba677afaSXin Li* *utils* - various utility functions that support the other tools-golang packages
37*ba677afaSXin Li
38*ba677afaSXin LiExamples for how to use these packages can be found in the `examples/`
39*ba677afaSXin Lidirectory.
40*ba677afaSXin Li
41*ba677afaSXin Li## What it doesn't do
42*ba677afaSXin Li
43*ba677afaSXin Litools-golang doesn't currently do any of the following:
44*ba677afaSXin Li
45*ba677afaSXin Li* work with files under any version of the SPDX spec prior to v2.1
46*ba677afaSXin Li* convert between different versions of SPDX documents (e.g., from 2.1 to 2.2)
47*ba677afaSXin Li* enable applications to interact with SPDX files without needing to care
48*ba677afaSXin Li  (too much) about the particular SPDX file version
49*ba677afaSXin Li
50*ba677afaSXin LiWe are working towards adding functionality for all of these. Code contributions
51*ba677afaSXin Liare welcome!
52*ba677afaSXin Li
53*ba677afaSXin Li## Documentation
54*ba677afaSXin Li
55*ba677afaSXin LiSPDX tools-golang documentation is available on the pkg.go.dev website at https://pkg.go.dev/github.com/spdx/tools-golang.
56*ba677afaSXin Li
57*ba677afaSXin Li## Contributors
58*ba677afaSXin Li
59*ba677afaSXin LiThank you to all of the contributors to spdx/tools-golang. A full list can be
60*ba677afaSXin Lifound in the GitHub repo and in [the release notes](RELEASE-NOTES.md).
61*ba677afaSXin Li
62*ba677afaSXin LiIn particular, thank you to the following for major contributions:
63*ba677afaSXin Li
64*ba677afaSXin LiJSON parsing and saving support was added by @specter25 as part of his Google
65*ba677afaSXin LiSummer of Code 2021 project.
66*ba677afaSXin Li
67*ba677afaSXin LiRDF parsing support was added by @RishabhBhatnagar as part of his Google Summer
68*ba677afaSXin Liof Code 2020 project.
69*ba677afaSXin Li
70*ba677afaSXin Li## Licenses
71*ba677afaSXin Li
72*ba677afaSXin LiAs indicated in `LICENSE-code`, tools-golang **source code files** are
73*ba677afaSXin Liprovided and may be used, at your option, under *either*:
74*ba677afaSXin Li* Apache License, version 2.0 (**Apache-2.0**), **OR**
75*ba677afaSXin Li* GNU General Public License, version 2.0 or later (**GPL-2.0-or-later**).
76*ba677afaSXin Li
77*ba677afaSXin LiAs indicated in `LICENSE-docs`, tools-golang **documentation files** are
78*ba677afaSXin Liprovided and may be used under the Creative Commons Attribution
79*ba677afaSXin Li4.0 International license (**CC-BY-4.0**).
80*ba677afaSXin Li
81*ba677afaSXin LiThis `README.md` file is documentation:
82*ba677afaSXin Li
83*ba677afaSXin Li`SPDX-License-Identifier: CC-BY-4.0`
84*ba677afaSXin Li
85*ba677afaSXin Li## Security
86*ba677afaSXin Li
87*ba677afaSXin LiFor security policy and reporting security issues, please refer to [SECURITY.md](SECURITY.md)
88