github.com/glimps-jbo/go-licenses@v0.0.0-20230908151000-e06d3c113277/README.md (about) 1 # Licenses tool 2 3 > This is not an officially supported Google product. 4 5 `go-licenses` analyzes the dependency tree of a Go package/binary. It can output a 6 report on the libraries used and under what license they can be used. It can 7 also collect all of the license documents, copyright notices and source code 8 into a directory in order to comply with license terms on redistribution. 9 10 ## Before you start 11 12 To use this tool, make sure: 13 14 * [You have Go v1.16 or later installed](https://golang.org/dl/). 15 * Change directory to your go project, **for example**: 16 17 ```shell 18 git clone git@github.com:google/go-licenses.git 19 cd go-licenses 20 ``` 21 22 * Download required modules: 23 24 ```shell 25 go mod download 26 ``` 27 28 ## Installation 29 30 Use the following command to download and install this tool: 31 32 ```shell 33 go install github.com/google/go-licenses@latest 34 ``` 35 36 If you were using `go get` to install this tool, note that 37 [starting in Go 1.17, go get is deprecated for installing binaries](https://go.dev/doc/go-get-install-deprecation). 38 39 ## Reports 40 41 ```shell 42 $ go-licenses report github.com/google/go-licenses 43 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: 44 /home/username/go/pkg/mod/golang.org/x/sys@v0.0.0-20220111092808-5a964db01320/unix/asm_linux_amd64.s 45 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: 46 /home/username/go/pkg/mod/golang.org/x/crypto@v0.0.0-20220112180741-5e0467b6c7ce/curve25519/internal/field/fe_amd64.s 47 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: 48 /home/username/go/pkg/mod/golang.org/x/crypto@v0.0.0-20220112180741-5e0467b6c7ce/internal/poly1305/sum_amd64.s 49 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! 50 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! 51 github.com/emirpasic/gods,https://github.com/emirpasic/gods/blob/v1.12.0/LICENSE,BSD-2-Clause 52 github.com/golang/glog,https://github.com/golang/glog/blob/23def4e6c14b/LICENSE,Apache-2.0 53 github.com/golang/groupcache/lru,https://github.com/golang/groupcache/blob/41bb18bfe9da/LICENSE,Apache-2.0 54 github.com/google/go-licenses,https://github.com/google/go-licenses/blob/HEAD/LICENSE,Apache-2.0 55 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 56 github.com/google/licenseclassifier,https://github.com/google/licenseclassifier/blob/3043a050f148/LICENSE,Apache-2.0 57 github.com/google/licenseclassifier/stringclassifier,https://github.com/google/licenseclassifier/blob/3043a050f148/stringclassifier/LICENSE,Apache-2.0 58 github.com/jbenet/go-context/io,https://github.com/jbenet/go-context/blob/d14ea06fba99/LICENSE,MIT 59 github.com/kevinburke/ssh_config,https://github.com/kevinburke/ssh_config/blob/01f96b0aa0cd/LICENSE,MIT 60 github.com/mitchellh/go-homedir,https://github.com/mitchellh/go-homedir/blob/v1.1.0/LICENSE,MIT 61 github.com/otiai10/copy,https://github.com/otiai10/copy/blob/v1.6.0/LICENSE,MIT 62 github.com/sergi/go-diff/diffmatchpatch,https://github.com/sergi/go-diff/blob/v1.2.0/LICENSE,MIT 63 github.com/spf13/cobra,https://github.com/spf13/cobra/blob/v1.4.0/LICENSE.txt,Apache-2.0 64 github.com/spf13/pflag,https://github.com/spf13/pflag/blob/v1.0.5/LICENSE,BSD-3-Clause 65 github.com/src-d/gcfg,https://github.com/src-d/gcfg/blob/v1.4.0/LICENSE,BSD-3-Clause 66 github.com/xanzy/ssh-agent,https://github.com/xanzy/ssh-agent/blob/v0.2.1/LICENSE,Apache-2.0 67 go.opencensus.io,https://github.com/census-instrumentation/opencensus-go/blob/v0.23.0/LICENSE,Apache-2.0 68 golang.org/x/crypto,https://cs.opensource.google/go/x/crypto/+/5e0467b6:LICENSE,BSD-3-Clause 69 golang.org/x/mod/semver,https://cs.opensource.google/go/x/mod/+/9b9b3d81:LICENSE,BSD-3-Clause 70 golang.org/x/net,https://cs.opensource.google/go/x/net/+/69e39bad:LICENSE,BSD-3-Clause 71 golang.org/x/sys,https://cs.opensource.google/go/x/sys/+/5a964db0:LICENSE,BSD-3-Clause 72 golang.org/x/tools,https://cs.opensource.google/go/x/tools/+/v0.1.10:LICENSE,BSD-3-Clause 73 golang.org/x/xerrors,https://cs.opensource.google/go/x/xerrors/+/5ec99f83:LICENSE,BSD-3-Clause 74 gopkg.in/src-d/go-billy.v4,https://github.com/src-d/go-billy/blob/v4.3.2/LICENSE,Apache-2.0 75 gopkg.in/src-d/go-git.v4,https://github.com/src-d/go-git/blob/v4.13.1/LICENSE,Apache-2.0 76 gopkg.in/warnings.v0,https://github.com/go-warnings/warnings/blob/v0.1.2/LICENSE,BSD-2-Clause 77 ``` 78 79 This command prints out a comma-separated report (CSV) listing the libraries 80 used by a binary/package, the URL where their licenses can be viewed and the 81 type of license. A library is considered to be one or more Go packages that 82 share a license file. 83 84 URLs are versioned based on go modules metadata. 85 86 **Tip**: go-licenses writes the report to stdout and info/warnings/errors logs 87 to stderr. To save the CSV to a file `licenses.csv` in bash, run: 88 89 ```bash 90 go-licenses report github.com/google/go-licenses > licenses.csv 91 ``` 92 93 Or, to also save error logs to an `errors` file, run: 94 95 ```bash 96 go-licenses report github.com/google/go-licenses > licenses.csv 2> errors 97 ``` 98 99 **Note**: some warnings and errors may be expected, refer to [Warnings and Errors](#warnings-and-errors) for more information. 100 101 ## Reports with Custom Templates 102 103 ```shell 104 go-licenses report github.com/google/go-licenses --template testdata/modules/hello01/licenses.tpl 105 W0822 16:56:50.696198 10200 library.go:94] "golang.org/x/sys/unix" contains non-Go code that can't be inspected for further dependencies: 106 /Users/willnorris/go/pkg/mod/golang.org/x/sys@v0.0.0-20220722155257-8c9f86f7a55f/unix/asm_bsd_arm64.s 107 /Users/willnorris/go/pkg/mod/golang.org/x/sys@v0.0.0-20220722155257-8c9f86f7a55f/unix/zsyscall_darwin_arm64.1_13.s 108 /Users/willnorris/go/pkg/mod/golang.org/x/sys@v0.0.0-20220722155257-8c9f86f7a55f/unix/zsyscall_darwin_arm64.s 109 W0822 16:56:51.466449 10200 library.go:94] "golang.org/x/crypto/chacha20" contains non-Go code that can't be inspected for further dependencies: 110 /Users/willnorris/go/pkg/mod/golang.org/x/crypto@v0.0.0-20220112180741-5e0467b6c7ce/chacha20/chacha_arm64.s 111 W0822 16:56:51.475139 10200 library.go:94] "golang.org/x/crypto/curve25519/internal/field" contains non-Go code that can't be inspected for further dependencies: 112 /Users/willnorris/go/pkg/mod/golang.org/x/crypto@v0.0.0-20220112180741-5e0467b6c7ce/curve25519/internal/field/fe_arm64.s 113 W0822 16:56:51.602250 10200 library.go:269] module github.com/google/go-licenses has empty version, defaults to HEAD. The license URL may be incorrect. Please verify! 114 W0822 16:56:51.605074 10200 library.go:269] module github.com/google/go-licenses has empty version, defaults to HEAD. The license URL may be incorrect. Please verify! 115 116 - github.com/emirpasic/gods ([BSD-2-Clause](https://github.com/emirpasic/gods/blob/v1.12.0/LICENSE)) 117 - github.com/golang/glog ([Apache-2.0](https://github.com/golang/glog/blob/23def4e6c14b/LICENSE)) 118 - github.com/golang/groupcache/lru ([Apache-2.0](https://github.com/golang/groupcache/blob/41bb18bfe9da/LICENSE)) 119 - github.com/google/go-licenses ([Apache-2.0](https://github.com/google/go-licenses/blob/HEAD/LICENSE)) 120 - github.com/google/go-licenses/internal/third_party/pkgsite ([BSD-3-Clause](https://github.com/google/go-licenses/blob/HEAD/internal/third_party/pkgsite/LICENSE)) 121 - github.com/google/licenseclassifier ([Apache-2.0](https://github.com/google/licenseclassifier/blob/3043a050f148/LICENSE)) 122 - github.com/google/licenseclassifier/licenses ([Unlicense](https://github.com/google/licenseclassifier/blob/3043a050f148/licenses/Unlicense.txt)) 123 - github.com/google/licenseclassifier/stringclassifier ([Apache-2.0](https://github.com/google/licenseclassifier/blob/3043a050f148/stringclassifier/LICENSE)) 124 - github.com/jbenet/go-context/io ([MIT](https://github.com/jbenet/go-context/blob/d14ea06fba99/LICENSE)) 125 - github.com/kevinburke/ssh_config ([MIT](https://github.com/kevinburke/ssh_config/blob/01f96b0aa0cd/LICENSE)) 126 - github.com/mitchellh/go-homedir ([MIT](https://github.com/mitchellh/go-homedir/blob/v1.1.0/LICENSE)) 127 - github.com/otiai10/copy ([MIT](https://github.com/otiai10/copy/blob/v1.6.0/LICENSE)) 128 - github.com/sergi/go-diff/diffmatchpatch ([MIT](https://github.com/sergi/go-diff/blob/v1.2.0/LICENSE)) 129 - github.com/spf13/cobra ([Apache-2.0](https://github.com/spf13/cobra/blob/v1.5.0/LICENSE.txt)) 130 - github.com/spf13/pflag ([BSD-3-Clause](https://github.com/spf13/pflag/blob/v1.0.5/LICENSE)) 131 - github.com/src-d/gcfg ([BSD-3-Clause](https://github.com/src-d/gcfg/blob/v1.4.0/LICENSE)) 132 - github.com/xanzy/ssh-agent ([Apache-2.0](https://github.com/xanzy/ssh-agent/blob/v0.2.1/LICENSE)) 133 - go.opencensus.io ([Apache-2.0](https://github.com/census-instrumentation/opencensus-go/blob/v0.23.0/LICENSE)) 134 - golang.org/x/crypto ([BSD-3-Clause](https://cs.opensource.google/go/x/crypto/+/5e0467b6:LICENSE)) 135 - golang.org/x/mod/semver ([BSD-3-Clause](https://cs.opensource.google/go/x/mod/+/86c51ed2:LICENSE)) 136 - golang.org/x/net ([BSD-3-Clause](https://cs.opensource.google/go/x/net/+/a158d28d:LICENSE)) 137 - golang.org/x/sys ([BSD-3-Clause](https://cs.opensource.google/go/x/sys/+/8c9f86f7:LICENSE)) 138 - golang.org/x/tools ([BSD-3-Clause](https://cs.opensource.google/go/x/tools/+/v0.1.12:LICENSE)) 139 - gopkg.in/src-d/go-billy.v4 ([Apache-2.0](https://github.com/src-d/go-billy/blob/v4.3.2/LICENSE)) 140 - gopkg.in/src-d/go-git.v4 ([Apache-2.0](https://github.com/src-d/go-git/blob/v4.13.1/LICENSE)) 141 - gopkg.in/warnings.v0 ([BSD-2-Clause](https://github.com/go-warnings/warnings/blob/v0.1.2/LICENSE)) 142 ``` 143 144 This command executes a specified Go template file to generate a report of 145 licenses. The template file is passed a slice of structs containing license 146 data: 147 148 ```go 149 []struct { 150 Name string 151 Version string 152 LicenseURL string 153 LicenseName string 154 LicensePath string 155 } 156 ``` 157 158 Each struct also has a `LicenseText` method which will return the text of the license stored at `LicensePath` if present, 159 or an empty string if not. 160 161 Example template rendering licenses as markdown: 162 163 ```` 164 {{ range . }} 165 ## {{ .Name }} 166 167 * Name: {{ .Name }} 168 * Version: {{ .Version }} 169 * License: [{{ .LicenseName }}]({{ .LicenseURL }}) 170 171 ``` 172 {{ .LicenseText }} 173 ``` 174 {{ end }} 175 ```` 176 177 ## Save licenses, copyright notices and source code (depending on license type) 178 179 ```shell 180 go-licenses save "github.com/google/go-licenses" --save_path="/tmp/go-licenses-cli" 181 ``` 182 183 This command analyzes a binary/package's dependencies and determines what needs 184 to be redistributed alongside that binary/package in order to comply with the 185 license terms. This typically includes the license itself and a copyright 186 notice, but may also include the dependency's source code. All of the required 187 artifacts will be saved in the directory indicated by `--save_path`. 188 189 ## Checking for forbidden licenses 190 191 ```shell 192 $ go-licenses check github.com/logrusorgru/aurora 193 Forbidden license type WTFPL for library github.com/logrusorgru/auroraexit status 1 194 ``` 195 196 This command analyzes a package's dependencies and determines if any are 197 considered forbidden by the license classifer. See 198 [github.com/google/licenseclassifier](https://github.com/google/licenseclassifier/blob/842c0d70d7027215932deb13801890992c9ba364/license_type.go#L323) 199 for licenses considered forbidden. 200 201 ## Usages 202 203 ### Global 204 Typically, specify the Go package that builds your Go binary. 205 go-licenses expects the same package argument format as `go build`. For examples: 206 207 * A rooted import path like `github.com/google/go-licenses` or `github.com/google/go-licenses/licenses`. 208 * A relative path that denotes the package in that directory, like `.` or `./cmd/some-command`. 209 210 To learn more about package argument, run `go help packages`. 211 212 To learn more about go-licenses usages, run `go-licenses help`. 213 214 ### Report 215 216 Report usage (default csv output): 217 218 ```shell 219 go-licenses report <package> [package...] 220 ``` 221 222 Report usage (using custom template file): 223 224 ```shell 225 go-licenses report <package> [package...] --template=<template_file> 226 ``` 227 228 ### Save 229 230 Save licenses, copyright notices and source code (depending on license type): 231 232 ```shell 233 go-licenses save <package> [package...] --save_path=<save_path> 234 ``` 235 236 ### Check 237 238 Checking for forbidden and unknown licenses usage: 239 240 ```shell 241 go-licenses check <package> [package...] 242 ``` 243 244 **Tip**: Usually you'll want to 245 246 * append `/...` to the end of an import path prefix (e.g., your repo path) to include all packages matching that pattern 247 * add `--include_tests` to also check packages only imported by testing code (e.g., testing libraries/frameworks) 248 249 ```shell 250 go-licenses check --include_tests github.com/google/go-licenses/... 251 ``` 252 253 Checking for disallowed license types: 254 255 ```shell 256 go-licenses check <package> [package...] --disallowed_types=<comma separated license types> 257 ``` 258 259 Supported license types: 260 261 * See `forbidden` list: [github.com/google/licenseclassifier](https://github.com/google/licenseclassifier/blob/e6a9bb99b5a6f71d5a34336b8245e305f5430f99/license_type.go#L341) 262 * See `notice` list: [github.com/google/licenseclassifier](https://github.com/google/licenseclassifier/blob/e6a9bb99b5a6f71d5a34336b8245e305f5430f99/license_type.go#L249) 263 * See `permissive` list: [github.com/google/licenseclassifier](https://github.com/google/licenseclassifier/blob/e6a9bb99b5a6f71d5a34336b8245e305f5430f99/license_type.go#L321) 264 * See `reciprocal` list: [github.com/google/licenseclassifier](https://github.com/google/licenseclassifier/blob/e6a9bb99b5a6f71d5a34336b8245e305f5430f99/license_type.go#L225) 265 * See `restricted` list: [github.com/google/licenseclassifier](https://github.com/google/licenseclassifier/blob/e6a9bb99b5a6f71d5a34336b8245e305f5430f99/license_type.go#L185) 266 * See `unencumbered` list: [github.com/google/licenseclassifier](https://github.com/google/licenseclassifier/blob/e6a9bb99b5a6f71d5a34336b8245e305f5430f99/license_type.go#L324) 267 * `unknown` 268 269 Allow only specific license names: 270 271 ```shell 272 go-licenses check <package> [package...] --allowed_licenses=<comma separated license names> 273 ``` 274 275 * See supported license names: [github.com/google/licenseclassifier](https://github.com/google/licenseclassifier/blob/e6a9bb99b5a6f71d5a34336b8245e305f5430f99/license_type.go#L28) 276 277 ### Build tags 278 279 To read dependencies from packages with 280 [build tags](https://golang.org/pkg/go/build/#hdr-Build_Constraints). Use the 281 `$GOFLAGS` environment variable. 282 283 ```shell 284 $ GOFLAGS="-tags=tools" go-licenses report google.golang.org/grpc/test/tools 285 github.com/BurntSushi/toml,https://github.com/BurntSushi/toml/blob/master/COPYING,MIT 286 google.golang.org/grpc/test/tools,Unknown,Apache-2.0 287 honnef.co/go/tools/lint,Unknown,BSD-3-Clause 288 golang.org/x/lint,Unknown,BSD-3-Clause 289 golang.org/x/tools,Unknown,BSD-3-Clause 290 honnef.co/go/tools,Unknown,MIT 291 honnef.co/go/tools/ssa,Unknown,BSD-3-Clause 292 github.com/client9/misspell,https://github.com/client9/misspell/blob/master/LICENSE,MIT 293 github.com/golang/protobuf/proto,https://github.com/golang/protobuf/blob/master/proto/LICENSE,BSD-3-Clause 294 ``` 295 296 ### Ignoring packages 297 298 Use the `--ignore` global flag to specify package path prefixes to be ignored. 299 For example, to ignore your organization's internal packages under `github.com/example-corporation`: 300 301 ```shell 302 $ go-licenses check \ 303 github.com/example-corporation/example-product \ 304 --ignore github.com/example-corporation 305 ``` 306 307 Note that dependencies from the ignored packages are still resolved and checked. 308 This flag makes effect to `check`, `report` and `save` commands. 309 310 ### Include testing packages 311 312 Use the `--include_tests` global flag to include packages only imported by testing code (e.g., testing libraries/frameworks). 313 Example command: 314 315 ```shell 316 go-licenses check --include_tests "github.com/google/go-licenses/..." 317 ``` 318 319 This flag makes effect to `check`, `report` and `save` commands. 320 321 ## Warnings and errors 322 323 The tool will log warnings and errors in some scenarios. This section provides 324 guidance on addressing them. 325 326 ### Dependency contains non-Go code 327 328 A warning will be logged when a dependency contains non-Go code. This is because 329 it is not possible to check the non-Go code for further dependencies, which may 330 conceal additional license requirements. You should investigate this code to 331 determine whether it has dependencies and take action to comply with their 332 license terms. 333 334 ### Error discovering URL 335 336 In order to determine the URL where a license file can be viewed, this tool 337 generally performs the following steps: 338 339 1. Locates the license file on disk. 340 2. Parses go module metadata and finds the remote repo and version. 341 3. Adds the license file path to this URL. 342 343 There are cases this tool finds an invalid/incorrect URL or fails to find the URL. 344 Welcome [creating an issue](https://github.com/google/go-licenses/issues).