Appendix A. Driving the command line

Gradle’s command-line interface (CLI) is a user’s primary tool of choice for discovering available options, inspecting the project, and controlling execution behavior by providing configuration information. It consists of three parts: discovery or help tasks, build setup tasks, and configuration input. The gradle command has the following usage:

gradle [option...] [tasks...]

A.1. Discovery tasks

Many discovery tasks provide information about the build. If you’re new to a project, they’re a good place to start discovering the configuration. They’re implemented as Gradle tasks. Every Gradle build provides the discovery tasks shown in table A.1 from the get-go.

Table A.1. Discovery tasks available to all Gradle projects

Name

Description

Where To Go for More Information

dependencies Emits a list of your project’s dependencies, including transitive dependencies. For an in-depth discussion of declaring and consuming dependencies in your project, jump to chapter 5. Section 5.4.2
dependencyInsight Explains how and why a dependency is selected in the dependency graph. The task requires you to provide the mandatory parameters --dependency to inspect a particular dependency. To inspect a dependency assigned to a configuration other than compile, use the parameter --configuration. Example: gradle dependencyInsight --dependency apache-commons. Section 5.7.2
help Displays a help message on the basic usage of the Gradle command line; for example, listing all existing tasks and running a specific task. If you run the gradle command without specifying a task, the help task is executed. Gradle online manual
projects Displays all subprojects in a multiproject build. A single-project build has no subprojects. Section 6.2
properties Emits a list of all available properties in your project. Some of these properties are provided by Gradle’s Project object, the build’s internal representation. Other properties are user-defined properties originating from a property file, property command-line option, or directly declared in your build script. Section 4.1.3
tasks Displays all runnable tasks of your project, including their descriptions. Plugins applied to your project may provide additional tasks. To print additional information about the available tasks, this task can be run with the option --all. Section 2.6.1

A.2. Build setup tasks

At a minimum, every Gradle project requires a build.gradle file to define your build logic. This file can be created manually or conveniently generated by tasks of the build setup plugin. Table A.2 shows the build setup tasks for initializing a new Gradle build.

Table A.2. Build setup tasks for initializing a new Gradle build

Name

Description

Where To Go for More Information

setupBuild Initializes a Gradle project by creating build.gradle, settings.gradle, and the wrapper files. If a pom.xml is found, Gradle tries to derive a Gradle project from the Maven metadata (see task maven2Gradle). Gradle online manual
generateBuildFile Creates a build.gradle file with the standard setup for building a Java project. This task is only available if no pom.xml file can be found in the project directory. Section 3.2.1
generateSettingsFile Creates a settings.gradle file, usually used for configuring a multiproject build. This task is only available if no pom.xml file can be found in the project directory. Gradle online manual
maven2Gradle Translates a Maven project into a Gradle project (usually as part of a build migration) by inspecting the POM file in the project directory. After running this task, build.gradle and settings.gradle files are created. This task is only available if a pom.xml can be found. Section 9.2.2
wrapper Generates the Gradle wrapper files in the project directory with the same version as the Gradle runtime. Section 3.4.1

A.3. Configuration input

Build configuration information can be provided through the CLI. Options that don’t require a value can be combined; for example, -is for running the build on the INFO log level and printing out the stack trace if an error occurs.

A.3.1. Common options

Table A.3 describes common command-line options that don’t belong to a particular functional grouping. These options may come in handy in your day-to-day use of Gradle, so feel free to explore them.

Table A.3. Commonly used command-line options

Name

Description

Where To Go for More Information

-?, -h, --help Prints out all available command-line options, including a descriptive message. Gradle online manual
-a, --no-rebuild Avoids rebuilding all subprojects participating in a multiproject build other than the project that the command issues for (also called a partial build). By using partial builds, you can avoid the cost of checking the subproject model and bring down your build execution time. Section 6.3.3
-b, --build-file The default naming convention for a Gradle build script is build.gradle. Use this option to execute a build script with a different name (for example, gradle –b test.gradle build). Section 8.3
-c, --settings-file The default naming convention for a Gradle settings file is settings.gradle. Use this option to execute a build with a nonstandard settings filename (for example, gradle –c mySettings.gradle build). Gradle online manual
--continue Gradle will continue execution when a task fails to execute. This option is particularly useful in a multiproject build with many subprojects. It’ll discover all possible issues with a build, and allows you to fix them at once without having to fix problems one by one. Gradle online manual
--configure-on-demand This option aims for optimizing the configuration time required to initialize a multiproject build. The configuration on-demand mode attempts to configure only projects that are relevant for requested tasks. This option can be activated for all Gradle builds by setting the property org.gradle.configure-ondemand in a gradle.properties file. Gradle online manual
-g, --gradle-user-home Gradle’s default home directory is located in the directory .gradle under the user’s home directory. Use this option if you want to point to a different directory. Gradle online manual
--gui Launches a Swing-based user interface as an alternative to executing Gradle tasks from the command line. Gradle online manual
-I, --init-script Specifies an initialization script used for the build. This script is executed before any of your project tasks are executed. Gradle online manual
-p, --project-dir By default, a build is executed based on the current directory. With this option, you can specify a different directory to execute the build. Gradle online manual
--parallel Builds participating subprojects of a multi-project build in parallel. Gradle automatically determines the optimal number of executor threads. This option can be activated for all Gradle builds by setting the property org.gradle.parallel in a gradle.properties file. Gradle online manual
--parallel-threads When building a multiproject build in parallel, this option can be used to override the number of executor threads (for example, --parallel-threads=5). Gradle online manual
-m, --dry-run Prints the order of tasks without executing their actions. This option comes in handy if you want to quickly determine the task execution order of your build. Gradle online manual
--profile Apart from the total build time output on each build run, you can break down the execution time even more. The profile option generates a detailed HTML report under build/reports/profile listing task execution times and time spent during configuration phases. Gradle online manual
--rerun-tasks Reruns all tasks in the determined task execution graph. This option ignores any UP-TO-DATE status of previous task executions. Gradle online manual
-u, --no-search-upwards Tells Gradle to not search for a settings file in parent directories. This option is useful if you want to avoid the performance hit of searching all parent directories in a deeply nested project structure. Section 6.2.4
-v, --version Prints the version of the Gradle runtime that executes the command. Section 2.4
-x, --exclude-task Specifies a task that’s excluded from task execution. A practical example for this option is if you want to execute a full build of a Java project without running the unit tests (for example, gradle –x test build). Section 2.6.2

A.3.2. Property options

Properties provide a way to configure your build from the command line. Besides the standard Java system properties, Gradle defines project properties. Table A.4 describes their specific use cases.

Table A.4. Providing properties to Gradle JVM process or the Gradle project

Name

Description

Where To Go for More Information

-D, --system-prop Gradle runs as a JVM process. As with all Java processes, you can provide a system property like this: –Dmyprop=myvalue. Section 4.1.3
-P, --project-prop Project properties are variables available in your build script. You can use this option to pass a property to the build script directly from the command line (for example, -Pmyprop=myvalue). Section 4.1.3

A.3.3. Logging options

Gradle allows access to all log messages produced by your build. Depending on your use case, you can provide logging options to filter the relevant messages important to you, as shown in table A.5.

Table A.5. Controlling the runtime logging level

Name

Description

Where To Go for More Information

-i, --info A Gradle build does not output a lot of information in the default settings. Use this option to get more informative messages by changing Gradle’s logger to the INFO log level. This is helpful if you want to get more information on what’s happening under the hood. Section 7.3.1
-d, --debug Running Gradle on the DEBUG log level will give you a vast amount of low-level logging messages, including stack traces. Use this option if you want to troubleshoot a build problem. Gradle online manual
-q, --quiet Reduces the log messages of a build run to error messages only. Section 2.6.1
-s, --stacktrace If you run into errors in your build, you’ll want to know where they stem from. The option –s prints out an abbreviated stack trace if an exception is thrown, making it perfect for debugging broken builds. Gradle online manual
-S, --full-stacktrace Prints out the full stack trace for all exceptions. Gradle online manual

A.3.4. Caching options

Gradle uses caching on various levels to improve the performance of the build. With the options presented in table A.6, you can change the default caching behavior.

Table A.6. Managing Gradle’s caching functionality

Name

Description

Where To Go for More Information

--offline Often your build only declares dependencies on libraries available in repositories outside of your network. If these dependencies weren’t stored in your local cache, running a build without a network connection to these repositories would result in a failed build. Use this option to run your build in offline mode and only check the local dependency cache for dependencies. Section 5.6.2
--project-cache-dir The default dependency cache directory sits under .gradle in the user home directory. This option can be used to point to a different directory. Gradle online manual
--recompile-scripts Gradle compiles every script by default and stores them in a local cache to improve the performance of the build. To flush the cache of compiled scripts, execute the build with this option. Gradle online manual
--refresh-dependencies Manually refreshes the dependencies in your cache. This flag forces a check for changed artifact versions with the configured repositories. Section 5.7.4

A.3.5. Daemon options

The daemon runs Gradle as a background process. Once started, the gradle command will reuse the forked daemon process for subsequent builds, avoiding the startup costs altogether. Table A.7 gives an overview of the available options for controlling the daemon process.

Table A.7. Managing the daemon

Name

Description

Where To Go for More Information

--daemon Executes the build with the Gradle daemon for better performance. If a daemon process exists, it’s reused. If it doesn’t exist, a new daemon process is started. The daemon can be activated for all Gradle builds by setting the property org.gradle.daemon in a gradle.properties file. Section 2.6.4
--foreground Starts the Gradle daemon in the foreground of your console for debugging and monitoring purposes. Section 2.6.4
--no-daemon Executes the build without using an existing Gradle daemon process. Section 2.6.4
--stop Stops an existing Gradle daemon process. Section 2.6.4
..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset
3.94.150.98