Skip to content

Commit

Permalink
doc: add v2 README
Browse files Browse the repository at this point in the history
  • Loading branch information
@Bobgy
Bobgy committed Mar 1, 2022
1 parent 6666d3a commit 657c2ef
Show file tree
Hide file tree
Showing 2 changed files with 180 additions and 3 deletions.
169 changes: 169 additions & 0 deletions README-v2.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,169 @@
# Licenses tool

> This is not an officially supported Google product.
`go-licenses` analyzes the dependency tree of a Go package/binary. It can output a
report on the libraries used and under what license they can be used. It can
also collect all of the license documents, copyright notices and source code
into a directory in order to comply with license terms on redistribution.

## Installation

To download and install this tool, make sure
[you have Go v1.16 or later installed](https://golang.org/dl/), then run the
following command:

```shell
go get github.com/google/go-licenses@master
```

For Go v1.17 or later, [go get is deprecated for installing binaries](https://go.dev/doc/go-get-install-deprecation).
Use the following command instead to download and install this tool:

```shell
go install github.com/google/go-licenses@master
```

Change directory to your go project, for example:

```shell
git clone git@github.com:google/go-licenses.git
cd go-licenses
go mod download
```

## Reports

```shell
$ go-licenses csv github.com/google/go-licenses
github.com/emirpasic/gods,https://github.com/emirpasic/gods/blob/v1.12.0/LICENSE,BSD-2-Clause
github.com/golang/glog,https://github.com/golang/glog/blob/23def4e6c14b/LICENSE,Apache-2.0
github.com/golang/groupcache/lru,https://github.com/golang/groupcache/blob/41bb18bfe9da/LICENSE,Apache-2.0
github.com/google/go-licenses,https://github.com/google/go-licenses/blob/HEAD/LICENSE,Apache-2.0
github.com/google/go-licenses/internal/third_party/pkgsite,https://github.com/google/go-licenses/blob/HEAD/internal/third_party/pkgsite/LICENSE,BSD-3-Clause
github.com/google/licenseclassifier,https://github.com/google/licenseclassifier/blob/3043a050f148/LICENSE,Apache-2.0
github.com/google/licenseclassifier/stringclassifier,https://github.com/google/licenseclassifier/blob/3043a050f148/stringclassifier/LICENSE,Apache-2.0
github.com/jbenet/go-context/io,https://github.com/jbenet/go-context/blob/d14ea06fba99/LICENSE,MIT
github.com/kevinburke/ssh_config,https://github.com/kevinburke/ssh_config/blob/01f96b0aa0cd/LICENSE,MIT
github.com/mitchellh/go-homedir,https://github.com/mitchellh/go-homedir/blob/v1.1.0/LICENSE,MIT
github.com/otiai10/copy,https://github.com/otiai10/copy/blob/v1.6.0/LICENSE,MIT
github.com/sergi/go-diff/diffmatchpatch,https://github.com/sergi/go-diff/blob/v1.2.0/LICENSE,MIT
github.com/spf13/cobra,https://github.com/spf13/cobra/blob/v1.3.0/LICENSE.txt,Apache-2.0
github.com/spf13/pflag,https://github.com/spf13/pflag/blob/v1.0.5/LICENSE,BSD-3-Clause
github.com/src-d/gcfg,https://github.com/src-d/gcfg/blob/v1.4.0/LICENSE,BSD-3-Clause
github.com/xanzy/ssh-agent,https://github.com/xanzy/ssh-agent/blob/v0.2.1/LICENSE,Apache-2.0
go.opencensus.io,https://github.com/census-instrumentation/opencensus-go/blob/v0.23.0/LICENSE,Apache-2.0
golang.org/x/crypto,https://cs.opensource.google/go/x/crypto/+/5e0467b6:LICENSE,BSD-3-Clause
golang.org/x/mod/semver,https://cs.opensource.google/go/x/mod/+/v0.5.1:LICENSE,BSD-3-Clause
golang.org/x/net,https://cs.opensource.google/go/x/net/+/69e39bad:LICENSE,BSD-3-Clause
golang.org/x/sys,https://cs.opensource.google/go/x/sys/+/5a964db0:LICENSE,BSD-3-Clause
golang.org/x/tools,https://cs.opensource.google/go/x/tools/+/v0.1.9:LICENSE,BSD-3-Clause
golang.org/x/xerrors,https://cs.opensource.google/go/x/xerrors/+/5ec99f83:LICENSE,BSD-3-Clause
gopkg.in/src-d/go-billy.v4,https://github.com/src-d/go-billy/blob/v4.3.2/LICENSE,Apache-2.0
gopkg.in/src-d/go-git.v4,https://github.com/src-d/go-git/blob/v4.13.1/LICENSE,Apache-2.0
gopkg.in/warnings.v0,https://github.com/go-warnings/warnings/blob/v0.1.2/LICENSE,BSD-2-Clause
```

This command prints out a comma-separated report (CSV) listing the libraries
used by a binary/package, the URL where their licenses can be viewed and the
type of license. A library is considered to be one or more Go packages that
share a license file.

URLs are versioned based on go modules metadata.

## Save licenses, copyright notices and source code (depending on license type)

```shell
go-licenses save "github.com/google/go-licenses" --save_path="/tmp/go-licenses-cli"
```

This command analyzes a binary/package's dependencies and determines what needs
to be redistributed alongside that binary/package in order to comply with the
license terms. This typically includes the license itself and a copyright
notice, but may also include the dependency's source code. All of the required
artifacts will be saved in the directory indicated by `--save_path`.

## Checking for forbidden licenses

```shell
$ go-licenses check github.com/logrusorgru/aurora
Forbidden license type WTFPL for library github.com/logrusorgru/auroraexit status 1
```

This command analyzes a package's dependencies and determines if any are
considered forbidden by the license classifer. See
[github.com/google/licenseclassifier](https://github.com/google/licenseclassifier/blob/842c0d70d7027215932deb13801890992c9ba364/license_type.go#L323)

for licenses considered forbidden.

## Usages

Report usage:

```shell
go-licenses csv <package>
```

Save licenses, copyright notices and source code (depending on license type):

```shell
go-licenses save <package> --save_path=<save_path>
```

Checking for forbidden licenses usage:

```shell
go-licenses check <package>
```

go-licenses expects the same package argument format as `go build`. For example,
it can be:

* A rooted import path like `github.com/google/go-licenses`.
* A relative path that denotes the package in that directory, like `.` or `./cmd/some-command`.

To learn more, run `go help packages`.

## Build tags

To read dependencies from packages with
[build tags](https://golang.org/pkg/go/build/#hdr-Build_Constraints). Use the
`$GOFLAGS` environment variable.

```shell
$ GOFLAGS="-tags=tools" go-licenses csv google.golang.org/grpc/test/tools
github.com/BurntSushi/toml,https://github.com/BurntSushi/toml/blob/master/COPYING,MIT
google.golang.org/grpc/test/tools,Unknown,Apache-2.0
honnef.co/go/tools/lint,Unknown,BSD-3-Clause
golang.org/x/lint,Unknown,BSD-3-Clause
golang.org/x/tools,Unknown,BSD-3-Clause
honnef.co/go/tools,Unknown,MIT
honnef.co/go/tools/ssa,Unknown,BSD-3-Clause
github.com/client9/misspell,https://github.com/client9/misspell/blob/master/LICENSE,MIT
github.com/golang/protobuf/proto,https://github.com/golang/protobuf/blob/master/proto/LICENSE,BSD-3-Clause
```

## Warnings and errors

The tool will log warnings and errors in some scenarios. This section provides
guidance on addressing them.

### Dependency contains non-Go code

A warning will be logged when a dependency contains non-Go code. This is because
it is not possible to check the non-Go code for further dependencies, which may
conceal additional license requirements. You should investigate this code to
determine whether it has dependencies and take action to comply with their
license terms.

### Error discovering URL

In order to determine the URL where a license file can be viewed, this tool
generally performs the following steps:

1. Locates the license file on disk.
2. Parses go module metadata and finds the remote repo and version.
3. Adds the license file path to this URL.

There are rare cases this tool finds an invalid URL or fails to find the URL.
Welcome [creating an issue](https://github.com/google/go-licenses/issues).
14 changes: 11 additions & 3 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,14 @@ report on the libraries used and under what license they can be used. It can
also collect all of the license documents, copyright notices and source code
into a directory in order to comply with license terms on redistribution.

## Licenses tool v2 under development

The documentation below corresponds to go-licenses v1. There is a new v2 version
that natively supports go modules. It's under development based on
[the proposal](https://github.com/google/go-licenses/issues/70).

You can try it early following [the go-licenses v2 README](./README-v2.md).

## Installation

To download and install this tool, make sure
Expand Down Expand Up @@ -68,10 +76,10 @@ share a license file.
URLs may not be available if the library is not checked out as a Git repository
(e.g. as is the case when Go Modules are enabled).

## Complying with license terms
## Save licenses, copyright notices and source code (depending on license type)

```shell
$ go-licenses save "github.com/google/go-licenses" --save_path="/tmp/go-licenses-cli"
go-licenses save "github.com/google/go-licenses" --save_path="/tmp/go-licenses-cli"
```

This command analyzes a binary/package's dependencies and determines what needs
Expand All @@ -80,7 +88,7 @@ license terms. This typically includes the license itself and a copyright
notice, but may also include the dependency's source code. All of the required
artifacts will be saved in the directory indicated by `--save_path`.

## Checking for forbidden licenses.
## Checking for forbidden licenses

```shell
$ go-licenses check github.com/logrusorgru/aurora
Expand Down

0 comments on commit 657c2ef

Please sign in to comment.