Command-line options

The gradle command is used to execute a build. This command accepts several command-line options. We know the --quiet (or -q) option to reduce the output of a build. If we use the --help (or -h or -?) option, we see the complete list of options, as follows:

$ gradle --help
USAGE: gradle [option...] [task...]
-?, -h, --help          Shows this help message.
-a, --no-rebuild        Do not rebuild project dependencies.
-b, --build-file        Specifies the build file.
-c, --settings-file     Specifies the settings file.
--configure-on-demand   Only relevant projects are configured in this build run. This means faster build for large multi-project builds. [incubating]
--console               Specifies which type of console output to generate. Values are 'plain', 'auto' (default) or 'rich'.
--continue              Continues task execution after a task failure.
-D, --system-prop       Set system property of the JVM (e.g. -Dmyprop=myvalue).
-d, --debug             Log in debug mode (includes normal stacktrace).
--daemon                Uses the Gradle daemon to run the build. Starts the daemon if not running.
--foreground            Starts the Gradle daemon in the foreground. [incubating]
-g, --gradle-user-home  Specifies the gradle user home directory.
--gui                   Launches the Gradle GUI.
-I, --init-script       Specifies an initialization script.
-i, --info              Set log level to info.
-m, --dry-run           Runs the builds with all task actions disabled.
--max-workers           Configure the number of concurrent workers Gradle is allowed to use. [incubating]
--no-color              Do not use color in the console output. [deprecated - use --console=plain instead]
--no-daemon             Do not use the Gradle daemon to run the build.
--offline               The build should operate without accessing network resources.
-P, --project-prop      Set project property for the build script (e.g. -Pmyprop=myvalue).
-p, --project-dir       Specifies the start directory for Gradle. Defaults to current directory.
--parallel              Build projects in parallel. Gradle will attempt to determine the optimal number of executor threads to use. [incubating]
--parallel-threads      Build projects in parallel, using the specified number of executor threads. [deprecated - Please use --parallel, optionally in conjunction with --max-workers.] [incubating]
--profile               Profiles build execution time and generates a report in the <build_dir>/reports/profile directory.
--project-cache-dir     Specifies the project-specific cache directory. Defaults to .gradle in the root project directory.
-q, --quiet             Log errors only.
--recompile-scripts     Force build script recompiling.
--refresh-dependencies  Refresh the state of dependencies.
--rerun-tasks           Ignore previously cached task results.
-S, --full-stacktrace   Print out the full (very verbose) stacktrace for all exceptions.
-s, --stacktrace        Print out the stacktrace for all exceptions.
--stop                  Stops the Gradle daemon if it is running.
-t, --continuous        Enables continuous build. Gradle does not exit and will re-execute tasks when task file inputs change. [incubating]
-u, --no-search-upward  Don't search in parent folders for a settings.gradle file.
-v, --version           Print version info.
-x, --exclude-task      Specify a task to be excluded from execution.

Logging options

Let's look at some of the options in more detail. The --quiet (or -q), --debug (or -d), --info (or -i), --stacktrace (or-s), and --full-stacktrace (or-S) options control how much output we see when we execute tasks. To get the most detailed output, we use the --debug (or -d) option. This option provides a lot of output with information about the steps and classes used to run the build. The output is very verbose, therefore, we will not use it much.

To get a better insight on the steps that are executed for our task, we can use the --info (or -i) option. The output is not as verbose as with --debug, but it can provide a better understanding of the build steps:

$ gradle --info helloworld
Starting Build
Settings evaluated using settings file '/master/settings.gradle'.
Projects loaded. Root project using build file '/Users/mrhaki/Projects/gradle-effective-implementation-guide-2/gradle-impl-guide-2/src/docs/asciidoc/Chapter1/Code_Files/hello-world/build.gradle'.
Included projects: [root project 'hello-world']
Evaluating root project 'hello-world' using build file '/Users/mrhaki/Projects/gradle-effective-implementation-guide-2/gradle-impl-guide-2/src/docs/asciidoc/Chapter1/Code_Files/hello-world/build.gradle'.
All projects evaluated.
Selected primary task 'helloWorld' from project :
Tasks to be executed: [task ':helloWorld']
:helloWorld (Thread[main,5,main]) started.
:helloWorld
Executing task ':helloWorld' (up-to-date check took 0.001 secs) due to:
  Task has not declared any outputs.
Hello world.
:helloWorld (Thread[main,5,main]) completed. Took 0.021 secs.
BUILD SUCCESSFUL
Total time: 1.325 secs
This build could be faster, please consider using the Gradle Daemon: https://docs.gradle.org/2.12/userguide/gradle_daemon.html

If our build throws exceptions, we can see the stack trace information with the --stacktrace (or -s) and --full-stacktrace (or -S) options. The latter option will output the most information and is the most verbose. The --stacktrace and --full-stacktrace options can be combined with the other logging options.

Changing the build file and directory

We created our build file with the build.gradle name. This is the default name for a build file. Gradle will look for a file with this name in the current directory to execute the build. However, we can change this with the --build-file (or -b) and --project-dir (or -p) command-line options.

Let's run the gradle command from the parent directory of our current directory:

$ cd ..
$ gradle --project-dir hello-world -q helloWorld
Hello world.

We can also rename our build.gradle to, for example, hello.build and still execute our build:

$ mv build.gradle hello.build
$ gradle --build-file hello.build -q helloWorld
Hello world.

Running tasks without execution

With the --dry-run (or -m) option, we can run all tasks without really executing them. When we use the dry-run option, we can see the tasks that are executed, so we get an insight on the tasks that are involved in a certain build scenario. We don't even have to worry whether the tasks are actually executed. Gradle builds up a Directed Acyclic Graph (DAG) with all tasks before any task is executed. The DAG is build so that the tasks will be executed in order of dependencies, and a task is only executed once:

$ gradle --dry-run helloWorld
:helloWorld SKIPPED
BUILD SUCCESSFUL
Total time: 1.307 secs
This build could be faster, please consider using the Gradle Daemon: https://docs.gradle.org/2.12/userguide/gradle_daemon.html

Gradle daemon

We already discussed that Gradle executes in a JVM, and each time we invoke the gradle command, a new JVM is started, the Gradle classes and libraries are loaded, and the build is executed. We can reduce the build execution time if we don't have to load JVM and Gradle classes and libraries each time we execute a build. The --daemon command-line option starts a new Java process that will have all Gradle classes and libraries already loaded and then execute the build. Next time when we run Gradle with the --daemon option, only the build is executed as the JVM with the required Gradle classes and libraries is already running.

The first time we execute Gradle with the --daemon option, the execution speed will not have improved as the Java background process was not started yet. However, the next time, we can see a major improvement:

$ gradle --daemon helloWorld
Starting a new Gradle Daemon for this build (subsequent builds will be faster).
:helloWorld
Hello world.
BUILD SUCCESSFUL
Total time: 2.136 secs
$ gradle helloWorld
:helloWorld
Hello world.
BUILD SUCCESSFUL
Total time: 0.594 secs

Even though the daemon process is started, we can still run Gradle tasks without using the daemon. We use the --no-daemon command-line option to run a Gradle build, and then the daemon is not used:

$ gradle --no-daemon helloWorld
:helloWorld
Hello world.
BUILD SUCCESSFUL
Total time: 1.325 secs

To stop the daemon process, we use the --stop command-line option:

$ gradle --stop
Stopping daemon(s).
Gradle daemon stopped.

This will stop the Java background process completely.

To always use the --daemon command-line option, but we don't want to type it every time we run the gradle command, we can create an alias if our operating system supports aliases. For example, on a Unix-based system, we can create an alias and then use the alias to run the Gradle build:

$ alias gradled='gradle --daemon'
$ gradled helloWorld
:helloWorld
Hello world.
BUILD SUCCESSFUL
Total time: 0.572 secs

Instead of using the --daemon command-line option, we can use the org.gradle.daemon Java system property to enable the daemon. We can add this property to the GRADLE_OPTS environment variable so that it is always used when we run a Gradle build:

$ export GRADLE_OPTS="-Dorg.gradle.daemon=true"
$ gradle helloWorld
:helloWorld
Hello world.
BUILD SUCCESSFUL
Total time: 0.575 secs

Finally, we can add a gradle.properties file to the root of our project directory. In the file, we can define a org.gradle.daemon property and assign the  true value to enable the Gradle daemon for all builds that are executed from this directory.

Let's create a gradle.properties file with the following contents:

org.gradle.daemon=true 

We can run our example task, helloWorld, and the build will use the Gradle daemon:

$ gradle helloWorld
:helloWorld
Hello world.
BUILD SUCCESSFUL
Total time: 0.58 secs

Profiling

Gradle also provides the --profile command-line option. This option records the time that certain tasks take to complete. The data is saved in an HTML file in the build/reports/profile directory. We can open this file in a web browser and check the time taken for several phases in the build process. The following image shows the HTML contents of the profile report:

HTML page with profiling information

Offline usage

If we don't have access to a network at some location, we might get errors from our Gradle build, when a task needs to download something from the Internet, for example. We can use the --offline command-line option to instruct Gradle to not access any network during the build. This way we can still execute the build if all necessary files are already available offline and we don't get an error.