第11章 Gradleのコマンドラインを使う

You can execute multiple tasks in a single build by listing each of the tasks on the command-line. For example, the command gradle compile test will execute the compile and test tasks. Gradle will execute the tasks in the order that they are listed on the command-line, and will also execute the dependencies for each task. Each task is executed once only, regardless of how it came to be included in the build: whether it was specified on the command-line, or as a dependency of another task, or both. Let's look at an example.

一回のビルドで、複数のタスクを実行することができます。ビルドを実行するときに、タスクを並べて指定してください。たとえば、gradle compile testというコマンドを実行すれば、compileタスクとtestタスクが実行されます。Gradleはタスクを列挙された順に実行するほか、それらが依存しているタスクも実行します。また、タスクが実行されるのはそれぞれ一度だけです。コマンドラインで明示的に指定されたタスクも、それらに依存して実行されるタスクも、またその両方に含まれるタスクも同様です。次の例を見てください。

Below four tasks are defined. Both dist and test depend on the compile task. Running gradle dist test for this build script results in the compile task being executed only once.

この例では、四つのタスクが定義されており、distとtestはどちらもcompileタスクに依存しています。このビルドスクリプトを呼び出してgradle dist testと実行しても、実行された二つのタスクから依存されているcompileタスクは一度だけしか実行されません。

図11.1 Task間の依存関係Task dependencies

task compile << {
    println 'compiling source'
}

task compileTest(dependsOn: compile) << {
    println 'compiling unit tests'
}

task test(dependsOn: [compile, compileTest]) << {
    println 'running unit tests'
}

task dist(dependsOn: [compile, test]) << {
    println 'building the distribution'
}

> gradle dist test
:compile
compiling source
:compileTest
compiling unit tests
:test
running unit tests
:dist
building the distribution

BUILD SUCCESSFUL

Total time: 1 secs

Each task is executed only once only, so gradle test test is exactly the same as gradle test.

タスクが一度だけ実行されるということは、gradle test testと打ち込んでもgradle testと打ち込んでも、実行される処理は全く同じだということです。

You can exclude a task from being executed using the -x command-line option and providing the name of the task to exclude. Let's try this with the sample build file above.

-xオプションでタスクの名前を指定することで、そのタスクを除外してビルドを実行することができます。先ほどのサンプルで試してみましょう。

> gradle dist -x test
:compile
compiling source
:dist
building the distribution

BUILD SUCCESSFUL

Total time: 1 secs

You can see from the output of this example, that the test task is not executed, even though it is a dependency of the dist task. You will also notice that the test task's dependencies, such as compileTest are not executed either. Those dependencies of test that are required by another task, such as compile, are still executed.

distタスクはtestに依存しているのですが、この例ではtestタスクは実行されていないことが分かります。また、testタスクが依存しているタスク、たとえばcompileTestタスクもやはり実行されていません。しかし、testタスクが依存しているタスクのうち、test以外からも依存されているタスク、つまりcompileタスクは実行されているのです。

By default, Gradle will abort execution and fail the build as soon as any task fails. This allows the build to complete sooner, but hides other failures that would have occurred. In order to discover as many failures as possible in a single build execution, you can use the --continue option.

デフォルトでは、タスクが失敗するとすぐにGradleは実行を中止してビルドを失敗させます。これはビルドの完了は早くなりますが、発生するかもしれない他のエラーを隠してしまうかもしれません。 一回のビルド実行でできるだけ多くのエラーを発見するには、--continueオプションを使用します。

When executed with --continue, Gradle will execute every task to be executed where all of the dependencies for that task completed without failure, instead of stopping as soon as the first failure is encountered. Each of the encountered failures will be reported at the end of the build.

--continueオプションをつけてビルドすると、エラー発生時に即ビルドが停止されるのではなく、失敗せずに完了したタスクに依存するタスクは全て実行されるようになります。 また、ビルド中に発生したエラーはビルド終了時に全てレポートされます。

If a task fails, any subsequent tasks that were depending on it will not be executed, as it is not safe to do so. For example, tests will not run if there is a compilation failure in the code under test; because the test task will depend on the compilation task (either directly or indirectly).

タスクが失敗した場合、依存関係上の後続タスクは安全に実行できないため行われません。 例えば、テストの際、コードのコンパイルでエラーが発生するとテストは実施されません。テストタスクはコンパイルタスクに直接的、間接的に依存しているからです。

When you specify tasks on the command-line, you don't have to provide the full name of the task. You only need to provide enough of the task name to uniquely identify the task. For example, in the sample build above, you can execute task dist by running gradle d:

タスク名をコマンドラインで指定するとき、タスク名をすべて入力する必要はありません。タスク名を一つに決定できるだけの文字を入力すればよいのです。先ほどの例で言えば、gradle dと入力すればdistを実行できます。

> gradle di
:compile
compiling source
:compileTest
compiling unit tests
:test
running unit tests
:dist
building the distribution

BUILD SUCCESSFUL

Total time: 1 secs

You can also abbreviate each word in a camel case task name. For example, you can execute task compileTest by running gradle compTest or even gradle cT

キャメルケースで分割されたそれぞれの単語を省略することもできます。たとえば、compileTestというタスクだと、gradle compTestと入力したり、gradle cTと入力したりすることで実行できます。

> gradle cT
:compile
compiling source
:compileTest
compiling unit tests

BUILD SUCCESSFUL

Total time: 1 secs

You can also use these abbreviations with the -x command-line option.

-xオプションで除外タスクを指定するときにも、同じようにタスク名を省略できます。

When you run the gradle command, it looks for a build file in the current directory. You can use the -b option to select another build file. If you use -b option then settings.gradle file is not used. Example:

gradleコマンドは、デフォルトではカレントディレクトリにあるビルドスクリプトを探して実行しますが、-bオプションを使えば別のビルドスクリプトを指定することもできます。次の例を見てください。 なお、-bを使うと、settings.gradleファイルは使用されなくなります。

task hello << {
    println "using build file '$buildFile.name' in '$buildFile.parentFile.name'."
}

> gradle -q -b subdir/myproject.gradle hello
using build file 'myproject.gradle' in 'subdir'.

Alternatively, you can use the -p option to specify the project directory to use. For multi-project builds you should use -p option instead of -b option.

別の方法として、-pオプションを指定して、使用するプロジェクトディレクトリを変更することもできます。 マルチプロジェクトの場合は、-bオプションでなく-pオプションを使用するべきです。

> gradle -q -p subdir hello
using build file 'build.gradle' in 'subdir'.

Gradle provides several built-in tasks which show particular details of your build. This can be useful for understanding the structure and dependencies of your build, and for debugging problems.

ビルドに関する様々な情報を表示するために、組み込みのタスクがいくつか用意されています。自分の作ったビルドが今どんな構造になっているのか調べたり、何か問題が起こったときにデバッグしたりするのに役立つはずです。

In addition to the built-in tasks shown below, you can also use the project report plugin to add tasks to your project which will generate these reports.

この組み込みタスクに加えて、プロジェクトレポートプラグインというプラグインを使うこともできます。このプラグインは、これらの情報をレポートに保存するタスクをプロジェクトに追加してくれます。

> gradle -q projects
------------------------------------------------------------
Root project
------------------------------------------------------------

Root project 'projectReports'
+--- Project ':api' - The shared API for the application
\--- Project ':webapp' - The Web application implementation

To see a list of the tasks of a project, run gradle <project-path>:tasks
For example, try running gradle :api:tasks

description = 'The shared API for the application'

> gradle -q tasks
------------------------------------------------------------
All tasks runnable from root project
------------------------------------------------------------

Default tasks: dists

Build tasks
-----------
clean - Deletes the build directory (build)
dists - Builds the distribution
libs - Builds the JAR

Build Setup tasks
-----------------
init - Initializes a new Gradle build. [incubating]
wrapper - Generates Gradle wrapper files. [incubating]

Help tasks
----------
components - Displays the components produced by root project 'projectReports'.
dependencies - Displays all dependencies declared in root project 'projectReports'.
dependencyInsight - Displays the insight into a specific dependency in root project 'projectReports'.
help - Displays a help message.
projects - Displays the sub-projects of root project 'projectReports'.
properties - Displays the properties of root project 'projectReports'.
tasks - Displays the tasks runnable from root project 'projectReports' (some of the displayed tasks may belong to subprojects).

To see all tasks and more detail, run with --all.

dists {
    description = 'Builds the distribution'
    group = 'build'
}

> gradle -q tasks --all
------------------------------------------------------------
All tasks runnable from root project
------------------------------------------------------------

Default tasks: dists

Build tasks
-----------
clean - Deletes the build directory (build)
api:clean - Deletes the build directory (build)
webapp:clean - Deletes the build directory (build)
dists - Builds the distribution [api:libs, webapp:libs]
    docs - Builds the documentation
api:libs - Builds the JAR
    api:compile - Compiles the source files
webapp:libs - Builds the JAR [api:libs]
    webapp:compile - Compiles the source files

Build Setup tasks
-----------------
init - Initializes a new Gradle build. [incubating]
wrapper - Generates Gradle wrapper files. [incubating]

Help tasks
----------
components - Displays the components produced by root project 'projectReports'.
api:components - Displays the components produced by project ':api'.
webapp:components - Displays the components produced by project ':webapp'.
dependencies - Displays all dependencies declared in root project 'projectReports'.
api:dependencies - Displays all dependencies declared in project ':api'.
webapp:dependencies - Displays all dependencies declared in project ':webapp'.
dependencyInsight - Displays the insight into a specific dependency in root project 'projectReports'.
api:dependencyInsight - Displays the insight into a specific dependency in project ':api'.
webapp:dependencyInsight - Displays the insight into a specific dependency in project ':webapp'.
help - Displays a help message.
api:help - Displays a help message.
webapp:help - Displays a help message.
projects - Displays the sub-projects of root project 'projectReports'.
api:projects - Displays the sub-projects of project ':api'.
webapp:projects - Displays the sub-projects of project ':webapp'.
properties - Displays the properties of root project 'projectReports'.
api:properties - Displays the properties of project ':api'.
webapp:properties - Displays the properties of project ':webapp'.
tasks - Displays the tasks runnable from root project 'projectReports' (some of the displayed tasks may belong to subprojects).
api:tasks - Displays the tasks runnable from project ':api'.
webapp:tasks - Displays the tasks runnable from project ':webapp'.

> gradle -q help --task libs
Detailed task information for libs

Paths
     :api:libs
     :webapp:libs

Type
     Task (org.gradle.api.Task)

Description
     Builds the JAR

> gradle -q dependencies api:dependencies webapp:dependencies
------------------------------------------------------------
Root project
------------------------------------------------------------

No configurations

------------------------------------------------------------
Project :api - The shared API for the application
------------------------------------------------------------

compile
\--- org.codehaus.groovy:groovy-all:2.3.6

testCompile
\--- junit:junit:4.11
     \--- org.hamcrest:hamcrest-core:1.3

------------------------------------------------------------
Project :webapp - The Web application implementation
------------------------------------------------------------

compile
+--- project :api
|    \--- org.codehaus.groovy:groovy-all:2.3.6
\--- commons-io:commons-io:1.2

testCompile
No dependencies

> gradle -q api:dependencies --configuration testCompile
------------------------------------------------------------
Project :api - The shared API for the application
------------------------------------------------------------

testCompile
\--- junit:junit:4.11
     \--- org.hamcrest:hamcrest-core:1.3

> gradle -q webapp:dependencyInsight --dependency groovy --configuration compile
org.codehaus.groovy:groovy-all:2.3.6
\--- project :api
     \--- compile

> gradle -q api:properties
------------------------------------------------------------
Project :api - The shared API for the application
------------------------------------------------------------

allprojects: [project ':api']
ant: org.gradle.api.internal.project.DefaultAntBuilder@12345
antBuilderFactory: org.gradle.api.internal.project.DefaultAntBuilderFactory@12345
artifacts: org.gradle.api.internal.artifacts.dsl.DefaultArtifactHandler_Decorated@12345
asDynamicObject: org.gradle.api.internal.ExtensibleDynamicObject@12345
baseClassLoaderScope: org.gradle.api.internal.initialization.DefaultClassLoaderScope@12345
buildDir: /home/user/gradle/samples/userguide/tutorial/projectReports/api/build
buildFile: /home/user/gradle/samples/userguide/tutorial/projectReports/api/build.gradle

11.6.7. ビルドのプロファイリングProfiling a build

The --profile command line option will record some useful timing information while your build is running and write a report to the build/reports/profile directory. The report will be named using the time when the build was run.

コマンドラインオプションで--profileをつけてビルドを実行すると、ビルドに要した時間のうち有用と思われるいくつかの情報を計測して、結果をbuild/reports/profileディレクトリを出力します。レポート名には、ビルドを行った時刻が付加されます。

This report lists summary times and details for both the configuration phase and task execution. The times for configuration and task execution are sorted with the most expensive operations first. The task execution results also indicate if any tasks were skipped (and the reason) or if tasks that were not skipped did no work.

このレポートでは、ビルド時間に関する概要のほか、設定フェーズとタスク実行に要した時間がタスクごとに表示されます。設定フェーズ、タスク実行に関するレポートは必要時間の降順でソートされており、さらにタスク実行については、タスクがスキップされたかどうか、作業が発生したかどうかみることができるようになっています。

Builds which utilize a buildSrc directory will generate a second profile report for buildSrc in the buildSrc/build directory.

なお、buildSrcディレクトリを使っている場合、buildSrc/buildにbuildSrcのレポートが別途出力されます。

Sometimes you are interested in which tasks are executed in which order for a given set of tasks specified on the command line, but you don't want the tasks to be executed. You can use the -m option for this. For example, if you run “gradle -m clean compile”, you'll see all the tasks that would be executed as part of the clean and compile tasks. This is complementary to the tasks task, which shows you the tasks which are available for execution.

コマンドラインにタスク名を並べて実行したときに、どのタスクがどの順番で実行されるのか知りたくなることがあります。しかしそのために実際にタスクを実行したくはありません。このような場合、-mオプションをつけて実行してください。たとえば、gradle -m clean compileと実行すれば、cleanタスクとcompileタスクの実行にあたって実際に実行されるすべてのタスクが実行順に表示されます。これは、実行可能なタスクの一覧を表示するtasksタスクの補足にもなります。

In this chapter, you have seen some of the things you can do with Gradle from the command-line. You can find out more about the gradle command in 付録D Gradle コマンドラインGradle Command Line.

この章では、コマンドラインで使えるGradleの機能をいくつか見てきました。gradleコマンドについては付録D Gradle コマンドラインGradle Command Lineにも記載してあります。