github.com/joey-fossa/fossa-cli@v0.7.34-0.20190708193710-569f1e8679f0/docs/integrations/gradle.md (about)

     1  # Gradle
     2  
     3  ## Installation
     4  
     5  Gradle support in FOSSA CLI depends on the following tools existing in your environment:
     6  
     7  - Gradle (defaults to the first successful command to run from the following list: `$FOSSA_GRADLE_CMD`, `gradlew`, `gradlew.bat`, `gradle`)
     8  
     9  ## Configuration
    10  
    11  ### Automatic
    12  
    13  `fossa init` will attempt a "best-effort" strategy to look through all available Gradle tasks/configurations and elect the most likely ones used for a production build.
    14  
    15   1. Look for a root Gradle build (`build.gradle`).
    16   2. Run `gradle tasks --all` to find all available sub-modules that support a `:dependencies` command.
    17   3. If no valid tasks are found, list the root project, `:`, as a Build Target.
    18   4. Filter out any suspicious-looking tasks (i.e. labeled `test` or `testCompile`).
    19   5. Write tasks to configuration (`fossa.yml`).
    20  
    21  If a gradle wrapper was provided in the same directory (`./gradlew`, `./gradlew.bat`), `fossa` will use that over the local `gradle` binary.
    22  
    23  ### Manual
    24  
    25  `fossa init` will automatically generate this configuration for you, but if you'd like to manually configure, add a `gradle` module to your `fossa.yml`:
    26  
    27  ```yaml
    28  analyze:
    29    modules:
    30      - name: project-name
    31        path: path-to-build.gradle
    32        target: subproject
    33        type: gradle
    34  ```
    35  
    36  ## Options
    37  
    38    | Option               |  Type  | Name                                           | Common Use Case                                                            |
    39    | -------------------- | :----: | ---------------------------------------------- | -------------------------------------------------------------------------- |
    40    | `cmd`                | string | [Cmd](#cmd-string)                             | Specify the gradle command to use.                                         |
    41    | `task`               | string | [Task](#task-string)                           | Specify the gradle task to run.                                            |
    42    | `timeout`            | string | [Timeout](#timeout-string)                     | Specify the length of time a `gradle` command is allowed to run.           |
    43    | `retries`            |  int   | [Retries](#retries-int)                        | Specify the number of times to retry a `gradle` command when it fails.     |
    44    | `online`             |  bool  | [Online](#online-bool)                         | Remove `--offline` from the `gradle <project>:dependencies` command.       |
    45    | `all-submodules`     |  bool  | [All Submodules](#all-submodules-bool)         | Running `fossa analyze gradle:.` and you want to analyze all sub-projects. |
    46    | `configuration`      | string | [Configuration](#configuration-string)         | Comma separated list of configurations to analyze.                         |
    47    | `all-configurations` |  bool  | [All Configurations](#all-configurations-bool) | Analyze all configurations for the gradle project.                         |
    48  
    49  
    50  
    51  #### `cmd: <string>` 
    52  
    53  Specify the command for fossa to use when it runs gradle commands. By default, the cli will select the first command of `cmd` option, `$FOSSA_GRADLE_COMMAND`, `./gradlew`, and `gradle` to execute `<cmd> -v` successfully.
    54  
    55  #### `task: <string>`
    56  
    57  Specify the exact arguments to be run by the gradle command before analyzing output for dependencies. By default this is `<project>:dependencies --quiet --offline` but this can be changed to anything using this option.
    58  
    59  #### `timeout: <string>`
    60  
    61  Specify the amount of time in that a gradle command is allowed to run before timing out. When fossa shells out to run `gradle` or `gradlew` the command can hang and consume extra resources. This option allows a user to kill the command and continue analyzing a project.
    62  > A duration string is a sequence of numbers, each with a unit suffix, such as "500ms", "1.5m", or "2h45m". Valid time units are "ms", "s", "m", "h".
    63  
    64  #### `retries: <int>`
    65  
    66  Specify the amount of times to retry running the gradle command after it fails to complete. This command works best in conjunction with the `timeout` option in order to allow a command to be killed and retried.
    67  
    68  #### `online: <bool>`
    69  
    70  When set to true, this option will remove the `--offline` flag from the command `gradle <project>:dependencies --quiet --offline` used to find the dependencies of the specified project.
    71  
    72  #### `all-submodules: <bool>`
    73  
    74  This options tells Fossa to scan for all sub projects of the specified module. The primary use case of this option is when running fossa using only arguments such as `fossa analyze gradle:.`. This ensures that all sub-projects of the root project are also scanned. If `fossa init` has been run, this command is largely unnecessary as all of the sub-projects will already be listed as build targets within the configuration file.
    75  
    76  #### `configuration: <string>`
    77  
    78  This option takes a comma delimited list of configurations to include in the dependency scan. Fossa includes a few configurations by default but allows the user to specify any specific configurations they are interested in.
    79  
    80  The default list of configurations is: `compile, api, implementation, compileDependenciesMetadata, apiDependenciesMetadata, implementationDependenciesMetadata`
    81  
    82  Example:
    83  ```yaml
    84      configuration: implementation,implementationTest,customConfiguration
    85  ```
    86  
    87  #### `all-configurations: <bool>`
    88  
    89  When set to true, fossa will ignore the default list of configurations and include the dependencies from every configuration found. This is useful when analyzing development, test, and debug dependencies is desired. 
    90  
    91  ## Analysis
    92  
    93  Analysis for gradle projects happens in 3 steps:
    94  
    95  1. `<cmd> <project>:dependencies` is run.
    96  2. Output is separated by configuration and dependency graphs are created.
    97  3. Desired configurations are selected and their merged dependency graph is finalized.
    98  
    99  The most complicated part of this process is separating dependency information by configuration and returning the desired information. Projects can have an overwhelming amount of configurations, many of which are undesirable for license scanning purposes such as test and development configurations. Fossa selects a default list of dependencies to avoid this noise, listed in the [configuration](#configuration:-<string>) option above. If you desire to scan [all configurations](#all-configurations:-<bool>) or a [known set](#configuration:-<string>), both of these options are available.
   100  
   101  ## FAQ
   102  
   103  ### Q: Why does fossa fail immediately?
   104  One reason `fossa` can fail immediately is if gradle is not properly setup. Fossa requires your build environment to be satisfied and Gradle tasks to reliably succeed before `fossa` can run.
   105  
   106  Most issues are often fixed by simply verifying that your Gradle build succeeds.
   107  
   108  ### Q: Why are my dependencies incorrect?
   109  If you're having trouble getting correct dependency data, try verifying the following:
   110  
   111  1. Your configuration and task name is valid (i.e. `app:compile` vs `customTask:customConfiguration`) in `fossa.yml`
   112  2. You get the desired output from your configured dependencies task `gradle {subtask}:dependencies --configuration={configuration}` (i.e. `gradle app:dependencies --configuration=compile`)
   113  
   114  If running the gradle command in your terminal does not succeed that means your gradle build is not properly configured.
   115  
   116  If it does succeed but produces unexpected or empty output, it means you have likely selected the wrong task or configuration for `fossa` to analyze.  Running without the `--configuration` will give you the full output and help you find the right configuration to select.