go-mkopensource

go-mkopensource

go-mkopensource is a program for generating reports of the libraries used by a piece of Go code, in order to be in compliance with the attribution requirements of various opensource licenses.

Building

You may clone the repo and run the following commands (or any of the other usual ways of building)

cd cmd/go-mkopensource
go build .

Running

TL;DR: run one of

go-mkopensource --gotar=/path/to/go1.17.2.src.tar.gz --package=mod --output-format=txt --output-type=markdown >DEPENDENCIES.md
go-mkopensource --gotar=/path/to/go1.17.2.src.tar.gz --package=mod --output-format=tar --output-name=mything >mything.OPENSOURCE.tar.gz
#               \________________  ________________/ \_____  ____/ \_________________________________  _______________________________/
#                                \/                        \/                                        \/
#                         Getting set up           Target to describe                          Output format

Let's now look at those flags piece-by-piece.

Getting set up

There is one piece of knowledge that go-mkopensource cannot detect: Which version of the Go standard library it should be referencing. Before running go-mkopensource, you will need to download the source tarball for the relevent version of Go. For example for Go 1.17.2, you need to download https://dl.google.com/go/go1.17.2.src.tar.gz . When you run go-mkopensource, you will need to tell it the download location by passing it the --gotar flag to point it at the download path. For example, --gotar=$HOME/Downloads/go1.17.2.tar.gz.

Target to describe

The --package= flag tells go-mkopensource which Go packages it should produce a report for. You can either

• pass it a string that you would pass to go list like ./... or ./cmd/mything, or
• pass the special value mod to describe the entire Go module of the current directory.

When passing a go list string, the behavior matches go list: What gets returned may depend on GOOS and GOARCH. You may set those environment variables to affect what gets returned. This means that by default the report would not include dependencies that are only needed on a platform other than the current one.

On the other hand, --package=mod considers all operating systems and architectures, including dependencies in the report even if they are only needed on a single platform.

Output format

There are two modes of operation:

1. --output-format=txt which produces a short-ish textual report of all of the dependencies, their versions, and their licenses.
2. --output-format=tar which produces a gzipped-tarball containing both the DEPENDENCIES.md file that --output-format=txt generates (plus a footer reading "The appropriate license notices and source code are in correspondingly named directories."), and a directory for each dependency, containing any necessary license notices and source code.

Many licenses require the author to be credited, the full license text to be included, a notice to be included, or even (in the case of the MPL) a subset of the source code to be included. This is what --output-format=tar is for; the --output-format=txt output alone is usually not sufficient to be in compliance with the licenses.

In both modes, it writes the output to stdout; it is up to you to redirect this output to a file.

--output-format=tar

In the Windows world, it is normal for a .zip file to include files directly inside of it in the root. However, in the Unix world, it is considered rude to have files directly inside of a .tar file; they should all be inside of a directory in the tarball, the name of that directory reflecting the expected name of the .tar file.

This is what the --output-name= flag is for, it tells go-mkopensource what to use for the name of the directory inside of the tarball (since it does not know the name of the file that you are directing the output to).

Output type

Parameter --output-type controls for output format.
When parameter is not provided in the command line or value is incorrect, --output-type is set to markdown.

This parameter only applies when --ouput-format is txt

--output-type=markdown

Program outputs dependency information in Markdown format

--output-type=json

Program outputs dependency information in json format

Application type

Parameter --application-type controls the types of licenses that are allowed. Logic is documented in Notion

--application-type=internal

Use this option with applications that run on customer infrastructure. This is the default.

--application-type=external

Use this option with applications that run on Ambassador Labs infrastructure.