github.com/joey-fossa/fossa-cli@v0.7.34-0.20190708193710-569f1e8679f0/docs/integrations/golang.md (about) 1 # Go 2 3 ## Support 4 5 Go support in FOSSA CLI depends on the following tools existing in your environment: 6 7 - Go (defaults to `go`, configure with `$GO_BINARY`) 8 - At least one of: 9 1. Dep (defaults to `dep`, configure with `$DEP_BINARY`) 10 2. Gomodules, the presence of `go.mod`. 11 3. Glide (defaults to `glide`, configure with `$GLIDE_BINARY`) 12 4. Godep (defaults to `godep`, configure with `$GODEP_BINARY`) 13 5. Govendor (defaults to `govendor`, configure with `$GOVENDOR_BINARY`) 14 6. Vndr (defaults to `vndr`, configure with `$VNDR_BINARY`) 15 7. Gdm (defaults to `gdm`, configure with `$GDM_BINARY`) 16 17 ## Configuration 18 19 ### Automatic 20 21 Run `fossa init` which detects all executable go packages in the directory and creates a configuration file. If you are trying to analyze a go library that does not contain any executables run `fossa init --include-all`. Refer to [Discovery](#Discovery) for more information on the auto-configuration logic. 22 23 ### Manual 24 25 Add a module with `type: go`, `target` set to the name of the executable package, and `path` set to the location of the executable package. 26 27 See [Options](#Options) for an in depth look at all of the available options for a Go module. 28 29 ```yaml 30 analyze: 31 modules: 32 - name: github.com/fossas/fossa-cli/cmd/fossa 33 type: go 34 target: github.com/fossas/fossa-cli/cmd/fossa 35 path: cmd/fossa 36 options: 37 allow-unresolved: true 38 ``` 39 40 ## Options 41 42 | Option | Type | Name | Common Use Case | 43 | ------------------------------ | :------: | ----------------------------------------------------------------------- | -------------------------------------------- | 44 | `tags` | []string | [Tags](#tags-string) | Project utilizes go build tags. | 45 | `all-tags` | bool | [All Tags](#all-tags-bool) | Make sure all OS and Arch tags are caught. | 46 | `strategy` | string | [Strategy](#strategy-string) | Specify a go package manager. | 47 | `lockfile` | string | [Lockfile Path](#lockfilepath-string) | Specify a custom lockfile. | 48 | `manifest` | string | [Manifest Path](#manifestpath-string) | Specify a custom manifest file. | 49 | `allow-unresolved` | bool | [Allow Unresolved](#allow-unresolved-bool) | Dependency revision is not in lockfile. | 50 | `allow-unresolved-prefix` | string | [Allow Unresolved Prefix](#allow-unresolved-prefix-string) | Allow a specific unresolved package. | 51 | `allow-nested-vendor` | bool | [Allow Nested Vendor](#allow-nested-vendor-bool) | Project's parent holds the desired lockfile. | 52 | `allow-deep-vendor` | bool | [Allow Deep Vendor](#allow-deep-vendor-bool) | Project is deep in a vendor directory. | 53 | `allow-external-vendor` | bool | [Allow External Vendor](#allow-external-vendor-bool) | Read lockfiles of other projects. | 54 | `allow-external-vendor-prefix` | string | [Allow External Vendor Prefix](#allow-external-vendor-prefix-string) | Read lockfiles that match the prefix. | 55 <!--- In code but currently unused 56 | `skip-tracing` | bool | [Skip Import Tracing](#Skip-Tracing:-<bool>) | Skip dependency tracing. | 57 | `skip-project` | bool | [Skip Project](#Skip-Project:-<bool>) | Skip project detection. | 58 ---> 59 60 61 #### `tags: <[]string>` 62 63 Allows you to specify different build tags and combinations for analysis. 64 Example: 65 ```yaml 66 tags: 67 - windows 68 - test 69 - !windows 70 - custom-test-build linux 71 ``` 72 73 #### `all-tags: <bool>` 74 75 Analyzes your project using a list of predefined build tags and merges the results. This analyzes your project with each tag but does not try any combinations. If you have a build that uses a combination build tag use the [Tags](#Tags:-<[]string>) option. 76 77 Predefined build tags: 78 79 - ``` "windows", "linux", "freebsd", "android", "darwin", "dragonfly", "nacl", "netbsd", "openbsd", "plan9", "solaris" "386", "amd64", "amd64p32", "arm", "armbe", "arm64", "arm64be", "ppc64", "ppc64le", "mips", "mipsle", "mips64", "mips64le", "mips64p32", "mips64p32le", "ppc", "s390", "s390x", "sparc", "sparc64"``` 80 81 #### `strategy: <string>` 82 83 Manually specify the golang package manager being used. If this option is set, it is recommended [lockfile](#LockfilePath:-<string>) and [manifest](#ManifestPath:-<string>) be set as well. A list of supported strategies is as follows: 84 - ```manifest:gomodules, manifest:dep, manifest:gdm, manifest:glide, manifest:godep, manifest:govendor, manifest:vndr, gopath-vcs``` 85 86 #### `lockfile: <string>` 87 88 If your project has a custom lockfile or location specify it with this flag. 89 Custom lockfiles interfere with the cli's ability to determine which package manager is being used and it is recommended that the [strategy](#strategy) flag also be set. 90 91 Example: 92 ```yaml 93 lockfile: config/customLockfile.lock 94 ``` 95 #### `manifest: <string>` 96 97 If your project has a custom manifest or location specify it with this flag. 98 Custom lockfiles interfere with the cli's ability to determine which package manager is being used and it is recommended that the [strategy](#strategy) flag also be set. 99 100 Example: 101 ```yaml 102 manifest: config/customManifest.toml 103 ``` 104 #### `allow-unresolved: <bool>` 105 106 If analysis finds any dependencies from `go list` that do not have a revision specified in a lockfile, analysis will fail by default. If it is acceptable to skip these packages during analysis and upload an incomplete dependency graph set `allow-unresolved: true`. This problem is usually a result of the underlying project having build issues. 107 108 #### `allow-unresolved-prefix: <string>` 109 110 Specify a package that is allowed to be unresolved based on its prefix. 111 112 Example: This will permit any dependencies with the prefix `github.com/fossas` to be unresolved. 113 ```yaml 114 allow-unresolved-prefix: github.com/fossas 115 ``` 116 See [Allow Unresolved](#Allow-unresolved:-<bool>) for use cases and steps to resolve the underlying issue. 117 118 #### `allow-nested-vendor: <bool>` 119 120 Allows vendor folders to be nested and attempts to resolve using parent lockfile lookup. 121 122 #### `allow-deep-vendor: <bool>` 123 124 Allows nested vendored dependencies to be resolved using ancestor lockfiles farther than their direct parent. 125 126 #### `allow-external-vendor: <bool>` 127 128 Allows reading vendor lockfiles of other projects. 129 130 #### `allow-external-vendor-prefix: <string>` 131 132 If set, allow reading vendor lockfiles of projects whose import path's prefix matches. Multiple space-delimited prefixes can be specified. 133 134 ## Discovery 135 136 Golang discovery runs `go list ./...` and takes all executable packages (those with package `main`) by default. To include the rest if you are trying to analyze a library without a `main` package run `fossa init --include-all`. 137 138 ## Analysis 139 140 Analysis happens in 3 steps: 141 142 1. Use `go list <target>` to determine the imports of the specified package. 143 2. Determine the project's package manager if it has not been specified by searching for the following in order - `go.mod`, `Godeps/Godeps.json`, `vendor/vendor.conf`, `Gopkg.toml`, `vendor.conf`, `glide.yaml`, `Godeps`. 144 3. Match each package import to a dependency from the manifest to obtain revision information. 145 146 > note: If a revision is not found for an import, Analysis will fail. Either fix the import error or enable [Allow Unresolved](#allow-unresolved:-<bool>) 147 148 Step (3) is the most complex part of analysis. Not all import paths have revisions directly associated with them. It is possible to import a package called `github.com/author-name/project-name/package-folder/package` and depending on the tool, this import path may not have a revision associated with it. Instead, the revision is associated with the imported _project_: in this case, that would be `github.com/author-name/project-name`. 149 150 In order to resolve the project of an import path, we check whether any of its prefixes have revisions in the Go project's manifests. If so, we assume that project contains the package we're importing and use its revision. 151 152 ## Known limitations 153 154 - We do not currently support unvendored or tool-less imports. 155 <!-- 156 Some approaches for solving this: 157 - If there is no `vendor` folder, find the imported project on the filesystem by looking up its location relative to `$GOPATH`, and use `git` to find its revision. 158 - If the import is vendored, get the project name from its filesystem location and check the checksum of its contents against revision hashes of known revisions published by that project. 159 - Allow the user to manually specify revisions, using either top-level configuration file (e.g. `//.fossa.yaml`) or a package-level configuration file (e.g. `//vendor/github.com/author/project/.revision`) 160 --> 161 ## FAQ 162 163 ### Q: Why are all dependencies listed in go.mod not found in the discovered dependency graph? 164 165 The FOSSA CLI finds all dependencies being used with `go list` and then finds their revision by parsing `go.mod`. Gomodules installs all transitive dependencies for a dependency, including the packages which are unused in the first party code. This results in many transitive dependencies listed in `go.mod` never actually being utilized. 166 167 Example: You need package `foo` from source `company/repository`. `go.mod` will import all packages including `company/repository/bar` and its transitive dependencies. `company/repository/bar`'s dependencies will go unused in your project and will not be picked up by `fossa-cli` but will appear in `go.mod`. 168 169 ### Q: I am in the process of updating to a new package manager, how can I obtain a scan for the old package manager? 170 171 The FOSSA CLI finds what package manager is being used as specified by the fallback strategy listed in [Analysis](#analysis) Step 2. If the package manager you are migrating to is earlier in the list you will need to set the correct strategy, lockfile, and manifest in your configuration file. 172 173 Example: You are migrating to `gomodules` but have not fully converted, as result fossa fails whenever it tries to find dependencies. You are however using `dep` and would like to make sure that those dependencies are detected. Add the following to the module in your configuration file: 174 175 ```yaml 176 analyze: 177 modules: 178 - name: github.com/fossas/fossa-cli/cmd/fossa 179 type: go 180 target: github.com/fossas/fossa-cli/cmd/fossa 181 path: . 182 options: 183 strategy: manifest:dep 184 lockfile: Gopkg.lock 185 manifest: Gopkg.toml 186 ``` 187 188 > note: this example is actually how to do this for the FOSSA CLI repository itself.