-
Notifications
You must be signed in to change notification settings - Fork 125
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
doc: update usages for v1.1 #111
Merged
Merged
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -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 | ||
|
@@ -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 | ||
|
@@ -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 | ||
|
@@ -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). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Note, required features for
go install
are usable starting from go 1.16, so we can simply tell people to use go install now.