Skip to content

Commit

Permalink
doc: update usages for v1.1 (#111)
Browse files Browse the repository at this point in the history
* doc: update README.md for v1.1 release

* chore: update CLI usages

* doc: add warnings in example command output to not surprise users
  • Loading branch information
Bobgy authored Apr 10, 2022
1 parent 427c3c9 commit e6efe14
Show file tree
Hide file tree
Showing 5 changed files with 139 additions and 47 deletions.
145 changes: 108 additions & 37 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,42 +7,95 @@ 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.

## Before you start

To use this tool, make sure:

* [You have Go v1.16 or later installed](https://golang.org/dl/).
* Change directory to your go project, **for example**:

```shell
git clone [email protected]:google/go-licenses.git
cd go-licenses
```

* Download required modules:

```shell
go mod download
```

## Installation

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

```shell
$ go get github.com/google/go-licenses
go install github.com/google/go-licenses@latest
```

If you were using `go get` to install this tool, note that
[starting in Go 1.17, go get is deprecated for installing binaries](https://go.dev/doc/go-get-install-deprecation).

## Reports

```shell
$ go-licenses csv "github.com/google/trillian/server/trillian_log_server"
google.golang.org/grpc,https://github.com/grpc/grpc-go/blob/master/LICENSE,Apache-2.0
go.opencensus.io,https://github.com/census-instrumentation/opencensus-go/blob/master/LICENSE,Apache-2.0
github.com/google/certificate-transparency-go,https://github.com/google/certificate-transparency-go/blob/master/LICENSE,Apache-2.0
github.com/jmespath/go-jmespath,https://github.com/aws/aws-sdk-go/blob/master/vendor/github.com/jmespath/go-jmespath/LICENSE,Apache-2.0
golang.org/x/text,https://go.googlesource.com/text/+/refs/heads/master/LICENSE,BSD-3-Clause
golang.org/x/sync/semaphore,https://go.googlesource.com/sync/+/refs/heads/master/LICENSE,BSD-3-Clause
github.com/prometheus/client_model/go,https://github.com/prometheus/client_model/blob/master/LICENSE,Apache-2.0
github.com/beorn7/perks/quantile,https://github.com/beorn7/perks/blob/master/LICENSE,MIT
$ go-licenses csv github.com/google/go-licenses
W0410 06:02:57.077781 31529 library.go:86] "golang.org/x/sys/unix" contains non-Go code that can't be inspected for further dependencies:
/home/gongyuan_kubeflow_org/go/pkg/mod/golang.org/x/[email protected]/unix/asm_linux_amd64.s
W0410 06:02:59.476443 31529 library.go:86] "golang.org/x/crypto/curve25519/internal/field" contains non-Go code that can't be inspected for further dependencies:
/home/gongyuan_kubeflow_org/go/pkg/mod/golang.org/x/[email protected]/curve25519/internal/field/fe_amd64.s
W0410 06:02:59.486045 31529 library.go:86] "golang.org/x/crypto/internal/poly1305" contains non-Go code that can't be inspected for further dependencies:
/home/gongyuan_kubeflow_org/go/pkg/mod/golang.org/x/[email protected]/internal/poly1305/sum_amd64.s
W0410 06:02:59.872215 31529 library.go:253] module github.com/google/go-licenses has empty version, defaults to HEAD. The license URL may be incorrect. Please verify!
W0410 06:02:59.880621 31529 library.go:253] module github.com/google/go-licenses has empty version, defaults to HEAD. The license URL may be incorrect. Please verify!
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.4.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/+/9b9b3d81: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.10: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 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).
URLs are versioned based on go modules metadata.
**Tip**: go-licenses writes CSV to stdout and info/warnings/errors logs to stderr.
To save the CSV to a file "licenses.csv" in bash, run:
## Complying with license terms
```bash
go-licenses csv github.com/google/go-licenses <licenses.csv
```
**Note**: some warnings and errors may be expected, refer to [Warnings and Errors](#warnings-and-errors) for more information.
## Save licenses, copyright notices and source code (depending on license type)
```shell
$ go-licenses save "github.com/google/trillian/server/trillian_log_server" --save_path="/tmp/trillian_log_server"
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 @@ -51,7 +104,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 All @@ -64,14 +117,44 @@ considered forbidden by the license classifer. See
for licenses considered forbidden.
## Usages
Report usage:
```shell
go-licenses csv <package> [package...]
```
Save licenses, copyright notices and source code (depending on license type):
```shell
go-licenses save <package> [package...] --save_path=<save_path>
```
Checking for forbidden licenses usage:
```shell
go-licenses check <package> [package...]
```
Typically, specify the Go package that builds your Go binary.
go-licenses expects the same package argument format as `go build`. For examples:
* A rooted import path like `github.com/google/go-licenses` or `github.com/google/go-licenses/licenses`.
* A relative path that denotes the package in that directory, like `.` or `./cmd/some-command`.
To learn more about package argument, run `go help packages`.
To learn more about go-licenses usages, run `go-licenses help`.
## 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" licenses csv google.golang.org/grpc/test/tools
$ 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
Expand Down Expand Up @@ -99,23 +182,11 @@ license terms.
### Error discovering URL
In order to determine the URL where a license file can be viewed, this tool
performs the following steps:
generally performs the following steps:
1. Locates the license file on disk.
2. Assuming that it is in a Git repository, inspects the repository's config to
find the URL of the remote "origin" repository.
3. Adds the license file path to this URL.

For this to work, the remote repository named "origin" must have a HTTPS URL.
You can check this by running the following commands, inserting the path
mentioned in the log message:

```shell
$ cd "path/mentioned/in/log/message"
$ git remote get-url origin
https://github.com/google/trillian.git
```
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.
If you want the tool to use a different remote repository, use the
`--git_remote` flag. You can pass this flag repeatedly to make the tool try a
number of different remotes.
There are cases this tool finds an invalid/incorrect URL or fails to find the URL.
Welcome [creating an issue](https://github.com/google/go-licenses/issues).
8 changes: 5 additions & 3 deletions check.go
Original file line number Diff line number Diff line change
Expand Up @@ -24,9 +24,11 @@ import (
)

var (
checkCmd = &cobra.Command{
Use: "check <package>",
Short: "Checks whether licenses for a package are not Forbidden.",
checkHelp = "Checks whether licenses for a package are not Forbidden."
checkCmd = &cobra.Command{
Use: "check <package> [package...]",
Short: checkHelp,
Long: checkHelp + packageHelp,
Args: cobra.MinimumNArgs(1),
RunE: checkMain,
}
Expand Down
8 changes: 5 additions & 3 deletions csv.go
Original file line number Diff line number Diff line change
Expand Up @@ -25,9 +25,11 @@ import (
)

var (
csvCmd = &cobra.Command{
Use: "csv <package>",
Short: "Prints all licenses that apply to a Go package and its dependencies",
csvHelp = "Prints all licenses that apply to one or more Go packages and their dependencies."
csvCmd = &cobra.Command{
Use: "csv <package> [package...]",
Short: csvHelp,
Long: csvHelp + packageHelp,
Args: cobra.MinimumNArgs(1),
RunE: csvMain,
}
Expand Down
17 changes: 16 additions & 1 deletion main.go
Original file line number Diff line number Diff line change
Expand Up @@ -26,11 +26,26 @@ import (

var (
rootCmd = &cobra.Command{
Use: "licenses",
Use: "go-licenses",
Short: "go-licenses helps you work with licenses of your go project's dependencies.",
Long: `go-licenses helps you work with licenses of your go project's dependencies.
Prerequisites:
1. Go v1.16 or later.
2. Change directory to your go project.
3. Run "go mod download".`,
}

// Flags shared between subcommands
confidenceThreshold float64
packageHelp = `
Typically, specify the Go package that builds your Go binary.
go-licenses expects the same package argument format as "go build".
For example:
* A rooted import path like "github.com/google/go-licenses" or "github.com/google/go-licenses/licenses".
* A relative path that denotes the package in that directory, like "." or "./cmd/some-command".
To learn more about Go package argument, run "go help packages".`
)

func init() {
Expand Down
8 changes: 5 additions & 3 deletions save.go
Original file line number Diff line number Diff line change
Expand Up @@ -30,9 +30,11 @@ import (
)

var (
saveCmd = &cobra.Command{
Use: "save <package>",
Short: "Saves licenses, copyright notices and source code, as required by a Go package's dependencies, to a directory.",
saveHelp = "Saves licenses, copyright notices and source code, as required by a Go package's dependencies, to a directory."
saveCmd = &cobra.Command{
Use: "save <package> [package...]",
Short: saveHelp,
Long: saveHelp + packageHelp,
Args: cobra.MinimumNArgs(1),
RunE: saveMain,
}
Expand Down

0 comments on commit e6efe14

Please sign in to comment.