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.