Gradle公式ドキュメントを読む-Running Gradle Builds

#この記事について
Gradleをより理解するために公式ドキュメントを読んでメモ代わりとして私なりに訳していきます。
読んでいるドキュメントのバージョンは7.3.3です。
この記事で訳している章はRunning Gradle Builds>Customizing Executionとなります。
必要な章から読んでいるため、一連の記事は公式ドキュメントの章立て通りの順にはなっていません。

#Running Gradle Builds>Customizing Execution
##[Configuring the Build Environment](https://docs.gradle.org/current/userguide/build_environment.html)
###Build Environment
Gradleの設定方法には優先順位の高い順に下記があります。

+ [コマンドラインフラグ](https://docs.gradle.org/current/userguide/command_line_interface.html#command_line_interface)
+ [システムプロパティ](https://docs.gradle.org/current/userguide/build_environment.html#sec:gradle_system_properties)
+ [Gladleプロパティ](#gradle-properties)
+ [環境変数](https://docs.gradle.org/current/userguide/build_environment.html#sec:gradle_environment_variables)

###[Gradle properties](https://docs.gradle.org/current/userguide/build_environment.html#sec:gradle_configuration_properties)
プロジェクトの環境を統一するためにgradle.propertiesファイルに諸々の構成を保存できます。もしも一つ構成がの複数の箇所で構成されていた場合、下記の順で最初に発見された構成が適用されます。

+ -Pや--project-propのようなコマンドラインのオプション
+ GRADLE_USER_HOMEディレクトリにあるgradle.properties
+ プロジェクトルートにあるgradle.properties
+ Gradleのインストールディレクトリにあるgradle.properties

:::note
GRADLE_USER_HOMEはコマンドラインに渡された-Dgradle.user.homeによって変更されているかもしれません
:::

Gradleのビルド環境には下記のプロパティが使用できます。

<dl>
<dt>org.gradle.caching=(true,false)</dt>
<dd>trueに設定すると可能な場合は前回のビルド成果物を使用します。結果として、ビルドがとても高速になります。デフォルトではBuild Cacheは無効です。<br>&nbsp;</dd>
<dt>org.gradle.caching.debug=(true,false)</dt>
<dd>trueに設定すると入力されたプロパティのハッシュと各タスクのBuild Cacheキーがコンソールにロギングされます。デフォルトはfalseです。<br>&nbsp;</dd>
<dt>org.gradle.configureondemand=(true,false)</dt>
<dd>Gradleはインキュベーション中である"<a href="https://docs.gradle.org/current/userguide/multi_project_configuration_and_execution.html#sec:configuration_on_demand">configuration on demand</a>"オンデマンド構成を使用して必要なプロジェクトについてのみ構成を行うようになります。<br>&nbsp;</dd>
<dt>org.gradle.console=(auto,plain,rich,verbose)</dt>
<dd>コンソール出力の色付けや冗長性を変更します。既定値はGradleの呼び出され方に依存します。詳しくは<a href="https://docs.gradle.org/current/userguide/command_line_interface.html#sec:command_line_logging">command-line logging</a>を参照してください。<br>&nbsp;</dd>
<dt>org.gradle.daemon=(true,false)</dt>
<dd>trueに設定するとビルドにGradle Damonを使用します。デフォルトはtrueでビルドはデーモンを使用して実行されます。<br>&nbsp;</dd>
<dt>org.gradle.daemon.idletimeout=(# of idle millis)</dt>
<dd>指定したミリ秒後にGradle Damonが自己終了します。デフォルトは10800000（3時間）です。</dd>
<dt>org.gradle.debug=(true,false)</dt>
<dd>trueに設定されたとき、Gradleはリモートデバッグが有効な状態でビルドを行います。デフォルトはfalseです。<br>&nbsp;</dd>
<dt>org.gradle.java.home=(path to JDK home)</dt>
<dd>Gradleのビルドプロセスに使用するJava Homeを指定します。GradleクライアントVMの起動に使用されるJavaのバージョンには影響しません。<a href="https://docs.gradle.org/current/userguide/build_environment.html#sec:gradle_environment_variables">Environment variables</a>を参照してください。設定が未指定の場合はローカル環境（JAVA_HOMEなど）から導出されます。<br>&nbsp;</dd>
<dt>org.gradle.jvmargs=(JVM arguments)</dt>
<dd>Gradle Damonに使用されるJVM引数を指定します。これはビルドのパフォーマンスにかかわるJVMのメモリ設定などに便利です。GradleクライアントVMの設定には影響しません。デフォルトは<code>-Xmx512m "-XX:MaxMetaspaceSize=256m"</code>です。<br>&nbsp;</dd>
<dt>org.gradle.logging.level=(quiet,warn,lifecycle,info,debug)</dt>
<dd>Gradleのログレベルを指定します。<a href="https://docs.gradle.org/current/userguide/logging.html#sec:choosing_a_log_level">Choosing a log level</a>を参照してください。既定はlifcycleです。<br>&nbsp;</dd>
<dt>org.gradle.parallel=(true,false)</dt>
<dd>設定されていると<code>org.gradle.workers.max</code>に指定された最大数まで、JVMを並行稼働させます。詳しくは<a href="https://docs.gradle.org/current/userguide/performance.html#parallel_execution">Gradle build performance</a>を参照してください。デフォルトはfalseです。<br>&nbsp;</dd>
<dt>org.gradle.priority=(low,normal)</dt>
<dd>Gradle Damonとすべての起動プロセスのスケジューリング順位を指定します。<a href="https://docs.gradle.org/current/userguide/command_line_interface.html#sec:command_line_performance">performance command-line options</a>を参照してください。デフォルトはnomalです。<br>&nbsp;</dd>
<dt>org.gradle.vfs.verbose=(true,false)</dt>
<dd>ファイルシステムを監視する（<a href="https://docs.gradle.org/current/userguide/gradle_daemon.html#sec:daemon_watch_fs">watching the file system</a>）とき、詳細ログを設定します。デフォルトはfalseです。<br>&nbsp;</dd>
<dt>org.gradle.vfs.watch=(true,false)</dt>
<dd><a href="https://docs.gradle.org/current/userguide/gradle_daemon.html#sec:daemon_watch_fs">ファイルシステムの監視</a>を切り替えます。有効の場合、Gradleはビルド間でファイルシステムから収集した情報を再利用します。Gradleがこの機能をサポートしているOSでは既定で有効です。<br>&nbsp;</dd>
<dt>org.gradle.warning.mode=(all,fail,summary,none)</dt>
<dd>all,summary,noneに設定されたとき、Gradleは異なるタイプの警告表示を行います。<a href="https://docs.gradle.org/current/userguide/command_line_interface.html#sec:command_line_logging">Command-line logging options</a>を参照してください。デフォルトはsummaryです。<br>&nbsp;</dd>
<dt>org.gradle.workers.max=(max # of worker processes)</dt>
<dd>構成されている場合、指定の最大数のワーカーを使用します。<a href="https://docs.gradle.org/current/userguide/command_line_interface.html#sec:command_line_performance">performance command-line options</a>を参照してください。デフォルトはCPUのプロセッサ数です。<br>&nbsp;</dd>
</dl>

###[System properties](https://docs.gradle.org/current/userguide/build_environment.html#sec:gradle_system_properties)
`-D`コマンドラインオプションを使用してGradleの実行時にシステムプロパティを渡すことが可能です。gradleコマンドの-Dオプションはjavaコマンドの-Dオプションと同様に効果を持ちます。
gradle.propertiesファイルでも、`systemProp.`接頭辞でシステムプロパティを設定できます。

```properties:gladle.properties
systemProp.gradle.wrapperUser=myuser
systemProp.gradle.wrapperPassword=mypassword
```

下記のシステムプロパティが使用可能です。コマンドラインオプションはシステムプロパティよりも優先されることに注意してください。

<dl>
<dt>gradle.wrapperUser=(myuser)</dt>
<dd>Gradle配布物をHTTPBasic認証でサーバーからダウンロードする際のユーザー名を指定します。<a href="https://docs.gradle.org/current/userguide/gradle_wrapper.html#sec:authenticated_download">Authenticated wrapper downloads</a>を参照してください。<br>&nbsp;</dd>
<dt>gradle.wrapperPassword=(mypassword)</dt>
<dd>Gradle Wrapperを使用してGradle配布物をダウンロードする際のパスワードを指定します。<br>&nbsp;</dd>
<dt>gradle.user.home=(path to directory)</dt>
<dd>Gradleユーザーホームディレクトリを指定します。<br>&nbsp;</dd>
<dt>https.protocols</dt>
<dd>カンマ区切りでサポートされているTLSバージョンを指定します。例:<code>TLSv1.2,TLSv1.3</code><br>&nbsp;</dd>
</dl>

マルチプロジェクトのビルドではルートを除く"systemProp"プロパティは無視され、ルートプロジェクトのgradle.propertiesファイルでのみチェックされます。

###[Environment variables](https://docs.gradle.org/current/userguide/build_environment.html#sec:gradle_environment_variables)
下記の環境変数が`gradle`コマンドで使用できます。コマンドラインオプションとシステムプロパティは環境変数よりも優先されることに注意してください。

<dl>
<dt>GRADLE_OPTS</dt>
<dd>GradleクライアントVMのJVM引数を指定します。クライアントVMはコマンドラインの入出力のハンドリングにのみ使用されるため、これを変更する必要がある場面は稀です。現状のビルドはGradle Damonで行われ、この環境変数の影響を受けません。<br>&nbsp;</dd>
<dt>GRADLE_USER_HOME</dt>
<dd>Gradleユーザーホームディレクトリを指定します。指定されていない場合は`$USER_HOME/.gradle`が既定です。<br>&nbsp;</dd>
<dt>JAVA_HOME</dt>
<dd>クライアントVMで使用されるJDKのインストールフォルダを指定します。このVMはgradle.propertiesファイルで`org.gradle.java.home`によって別途指定されていない限りはデーモンにも使用されます。<br>&nbsp;</dd>
</dl>

###[Project properties](https://docs.gradle.org/current/userguide/build_environment.html#sec:project_properties)
`-P`コマンドラインオプションを通じて[プロジェクトオブジェクト](https://docs.gradle.org/current/dsl/org.gradle.api.Project.html)にプロパティディレクトリを追加することができます。

Gradleは特定の名前のシステムプロパティや環境変数を検知してプロジェクトプロパティに設定することも可能です。もし`ORG_GRADLE_PROJECT_prop=somevalue`のような名前の環境変数の場合、Gradleはプロジェクトオブジェクトに`somevalue`の値で`prop`プロパティをセットします。また、Gradleは`org.gladle.project.prop`のような異なる命名規則のシステムプロパティもサポートしています。
下記の場合、どちらもプロジェクトオブジェクトには`foo`プロパティに`bar`の値がセットされます。

<dl>
<dt>システムプロパティを通じてのプロジェクトプロパティ設定</dt>
<dd><code>org.gradle.project.foo=bar<br>&nbsp;</code></dd>
<dt>環境変数を通じてのプロジェクトプロパティ設定</dt>
<dd><code>ORG_GRADLE_PROJECT_foo=bar<br>&nbsp;</code></dd>
</dl>

:::note
ユーザーホームディレクトリのプロパティファイルはプロジェクトディレクトリのプロパティファイルよりも優先されます
:::

この機能は継続的インテグレーションサーバーの管理権限がなく、簡単に視認されてはならないプロパティを設定する必要がある場合に便利です。そのようなシナリオでは`-P`オプションを使用することができず、システムレベルの構成ファイルを変更することもできないため、正しい戦略となるのはあなたのCIビルドジョブに予想されるパターンに一致するプロパティを追加することです。これはシステムの通常ユーザーから視認されることがありません。

変数を使用したときと同様に、これらの名前を使用するだけでビルドスクリプトからプロジェクトプロパティにアクセスすることが可能です。

:::note
もしもプロジェクトプロパティが参照されても存在していない場合、ビルドは例外を投げて失敗します。
<code>Project.hasProperty(java.lang.String)</code>メソッドを使用して任意のプロジェクトプロパティにアクセスする前に、その実在性を確認する必要があります。
:::

###[Configuring JVM memory](https://docs.gradle.org/current/userguide/build_environment.html#sec:configuring_jvm_memory)
下記の方法でJVMオプションを修正できます。

`org.gradle.jvmargs`Gradleプロパティはビルドを実行するVMをコントロールできます。これの既定値は`-Xmx512m "-XX:MaxMetaspaceSize=256m"`です。

####ビルドVMのJVM設定の変更
```
org.gradle.jvmargs=-Xmx2g -XX:MaxMetaspaceSize=512m -XX:+HeapDumpOnOutOfMemoryError -Dfile.encoding=UTF-8
```

`JAVA_OPTS`環境変数はコマンドラインクライアントを制御します。これはコンソールの表示にのみ使用されます。既定値は`-Xmx64m`です。
####クライアントVMのJVM設定の変更
```
JAVA_OPTS="-Xmx64m -XX:MaxPermSize=64m -XX:+HeapDumpOnOutOfMemoryError -Dfile.encoding=UTF-8"
```
:::note
クライアントVMがビルドVMとしても動作するケースがひとつあります。Gradle Damonを無効化して、クライアントVMにビルドVMに必要な設定と同じ設定を持っている場合、クライアントVMはビルドを直接実行します。これ以外の場合はクライアントVMは現在のビルドの異なる設定を尊重するために新しいVMをフォークします。
:::

`test`タスクのような特定のタスクも、追加のJVMをフォークします。これはそれらのタスク自身で構成できます。デフォルトではそれらはすべて`-Xmx512m`を使用します。

####`JavaCompile`タスクにコンパイルオプションを設定する例
```gradle:build.gradle
plugins {
    id 'java'
}

tasks.withType(JavaCompile) {
    options.compilerArgs += ['-Xdoclint:none', '-Xlint:none', '-nowarn']
}
```
その他の例は`Test`APIのドキュメントや[test execution in the Java plugin reference](https://docs.gradle.org/current/userguide/java_testing.html#sec:test_execution)を参照してください。

[Build scans](https://scans.gradle.com/?_ga=2.191319138.938462560.1641379703-1655089686.1630052259)（有料版機能）は`--scan`オプションを使用するとビルド実行時のJVMの情報を表示します。

###[Configuring a task using project properties](https://docs.gradle.org/current/userguide/build_environment.html#sec:configuring_task_using_project_properties)
指定されたプロジェクトプロパティに基づいて、呼び出し時にタスクの振る舞いを変更することが可能です。
リリースビルドがCIによってのみトリガーされるようにしたいと仮定します。これの簡単な方法は`isCI`プロジェクトプロパティを通じてハンドリングすることです。

####CI以外からのリリースを防ぐ例
```gradle:build.gradle
tasks.register('performRelease') {
    doLast {
        if (project.hasProperty("isCI")) {
            println("Performing release actions")
        } else {
            throw new InvalidUserDataException("Cannot perform release outside of CI")
        }
    }
}
```
`gradle performRelease -PisCI=true --quiet`
コマンドラインからアクションを実行

###[Accessing the web through a HTTP proxy](https://docs.gradle.org/current/userguide/build_environment.html#sec:accessing_the_web_via_a_proxy)
標準JVMシステムプロパティを通じて、HTTPまたはHTTPSのプロキシ（例えば依存関係をダウンロードするなど）が構成されます。これらのプロパティはビルドスクリプト内で直接、指定できます。例えば、HTTPプロキシホストは`System.setProperty('http.proxyHost', 'www.somehost.org')`を使用して可能です。あるいは、`gradle.properties`で指定されたプロパティでも可能です。

####`gradle.properties`を使用してHTTPプロキシを構成する
```properties:gradle.properties
systemProp.http.proxyHost=www.somehost.org
systemProp.http.proxyPort=8080
systemProp.http.proxyUser=userid
systemProp.http.proxyPassword=password
systemProp.http.nonProxyHosts=*.nonproxyrepos.com|localhost
```
HTTPSの設定が別途あります。
####`gradle.properties`を使用してHTTPSプロキシを構成する
```properties:gradle.properties
systemProp.https.proxyHost=www.somehost.org
systemProp.https.proxyPort=8080
systemProp.https.proxyUser=userid
systemProp.https.proxyPassword=password
systemProp.http.nonProxyHosts=*.nonproxyrepos.com|localhost
```
異なるネットワークに接続するには異なるプロパティを設定する必要があるでしょう。その助けになる参照が2つがあります。

+ [ProxySetup.java in the Ant codebase](https://git-wip-us.apache.org/repos/asf?p=ant.git;a=blob;f=src/main/org/apache/tools/ant/util/ProxySetup.java;hb=HEAD)
+ [JDK 7 Networking Properties](http://download.oracle.com/javase/7/docs/technotes/guides/net/properties.html)

###NTLM認証
プロキシにNTLM認証が必要な場合、認証ドメインとユーザー名とパスワードが必要になるでしょう。NTMLプロキシの認証にドメインを提供する方法は2つあります。

+ `domaim/username`のような値を`http.proxyUser`システムプロパティに設定する
+ `http.auth.ntlm.domain`システムプロパティを通じて認証ドメインを提供する