From a7103d5f4d6ce064b5026a238090e74d1e00a3a3 Mon Sep 17 00:00:00 2001 From: Yuan Gong Date: Sun, 27 Feb 2022 03:06:38 +0000 Subject: [PATCH] doc: update README.md for v1.1 release --- README.md | 128 ++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 91 insertions(+), 37 deletions(-) diff --git a/README.md b/README.md index 318c4d3c..4c620c43 100644 --- a/README.md +++ b/README.md @@ -7,28 +7,65 @@ 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 git@github.com: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 +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 @@ -36,13 +73,12 @@ 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. -## Complying with license terms +## 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 +87,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,6 +100,36 @@ considered forbidden by the license classifer. See for licenses considered forbidden. +## Usages + +Report usage: + +```shell +go-licenses csv +``` + +Save licenses, copyright notices and source code (depending on license type): + +```shell +go-licenses save --save_path= +``` + +Checking for forbidden licenses usage: + +```shell +go-licenses check +``` + +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 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 @@ -71,7 +137,7 @@ To read dependencies from packages with `$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 +165,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: - -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. +generally performs the following steps: -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).