この記事について
Gradleをより理解するために公式ドキュメントを読んでメモ代わりとして私なりに訳していきます。
読んでいるドキュメントのバージョンは7.3.3です。
この記事で訳している章はRunning Gradle Builds>Customizing Executionとなります。
必要な章から読んでいるため、一連の記事は公式ドキュメントの章立て通りの順にはなっていません。
Running Gradle Builds>Customizing Execution
Configuring the Build Environment
Build Environment
Gradleの設定方法には優先順位の高い順に下記があります。
Gradle properties
プロジェクトの環境を統一するためにgradle.propertiesファイルに諸々の構成を保存できます。もしも一つ構成がの複数の箇所で構成されていた場合、下記の順で最初に発見された構成が適用されます。
- -Pや--project-propのようなコマンドラインのオプション
- GRADLE_USER_HOMEディレクトリにあるgradle.properties
- プロジェクトルートにあるgradle.properties
- Gradleのインストールディレクトリにあるgradle.properties
GRADLE_USER_HOMEはコマンドラインに渡された-Dgradle.user.homeによって変更されているかもしれません
Gradleのビルド環境には下記のプロパティが使用できます。
- org.gradle.caching=(true,false)
- trueに設定すると可能な場合は前回のビルド成果物を使用します。結果として、ビルドがとても高速になります。デフォルトではBuild Cacheは無効です。
- org.gradle.caching.debug=(true,false)
- trueに設定すると入力されたプロパティのハッシュと各タスクのBuild Cacheキーがコンソールにロギングされます。デフォルトはfalseです。
- org.gradle.configureondemand=(true,false)
- Gradleはインキュベーション中である"configuration on demand"オンデマンド構成を使用して必要なプロジェクトについてのみ構成を行うようになります。
- org.gradle.console=(auto,plain,rich,verbose)
- コンソール出力の色付けや冗長性を変更します。既定値はGradleの呼び出され方に依存します。詳しくはcommand-line loggingを参照してください。
- org.gradle.daemon=(true,false)
- trueに設定するとビルドにGradle Damonを使用します。デフォルトはtrueでビルドはデーモンを使用して実行されます。
- org.gradle.daemon.idletimeout=(# of idle millis)
- 指定したミリ秒後にGradle Damonが自己終了します。デフォルトは10800000（3時間）です。
- org.gradle.debug=(true,false)
- trueに設定されたとき、Gradleはリモートデバッグが有効な状態でビルドを行います。デフォルトはfalseです。
- org.gradle.java.home=(path to JDK home)
- Gradleのビルドプロセスに使用するJava Homeを指定します。GradleクライアントVMの起動に使用されるJavaのバージョンには影響しません。Environment variablesを参照してください。設定が未指定の場合はローカル環境（JAVA_HOMEなど）から導出されます。
- org.gradle.jvmargs=(JVM arguments)
- Gradle Damonに使用されるJVM引数を指定します。これはビルドのパフォーマンスにかかわるJVMのメモリ設定などに便利です。GradleクライアントVMの設定には影響しません。デフォルトは
-Xmx512m "-XX:MaxMetaspaceSize=256m"です。
- org.gradle.logging.level=(quiet,warn,lifecycle,info,debug)
- Gradleのログレベルを指定します。Choosing a log levelを参照してください。既定はlifcycleです。
- org.gradle.parallel=(true,false)
- 設定されていると
org.gradle.workers.maxに指定された最大数まで、JVMを並行稼働させます。詳しくはGradle build performanceを参照してください。デフォルトはfalseです。
- org.gradle.priority=(low,normal)
- Gradle Damonとすべての起動プロセスのスケジューリング順位を指定します。performance command-line optionsを参照してください。デフォルトはnomalです。
- org.gradle.vfs.verbose=(true,false)
- ファイルシステムを監視する（watching the file system）とき、詳細ログを設定します。デフォルトはfalseです。
- org.gradle.vfs.watch=(true,false)
-
ファイルシステムの監視を切り替えます。有効の場合、Gradleはビルド間でファイルシステムから収集した情報を再利用します。Gradleがこの機能をサポートしているOSでは既定で有効です。
- org.gradle.warning.mode=(all,fail,summary,none)
- all,summary,noneに設定されたとき、Gradleは異なるタイプの警告表示を行います。Command-line logging optionsを参照してください。デフォルトはsummaryです。
- org.gradle.workers.max=(max # of worker processes)
- 構成されている場合、指定の最大数のワーカーを使用します。performance command-line optionsを参照してください。デフォルトはCPUのプロセッサ数です。
System properties
-Dコマンドラインオプションを使用してGradleの実行時にシステムプロパティを渡すことが可能です。gradleコマンドの-Dオプションはjavaコマンドの-Dオプションと同様に効果を持ちます。
gradle.propertiesファイルでも、systemProp.接頭辞でシステムプロパティを設定できます。
systemProp.gradle.wrapperUser=myuser
systemProp.gradle.wrapperPassword=mypassword
下記のシステムプロパティが使用可能です。コマンドラインオプションはシステムプロパティよりも優先されることに注意してください。
- gradle.wrapperUser=(myuser)
- Gradle配布物をHTTPBasic認証でサーバーからダウンロードする際のユーザー名を指定します。Authenticated wrapper downloadsを参照してください。
- gradle.wrapperPassword=(mypassword)
- Gradle Wrapperを使用してGradle配布物をダウンロードする際のパスワードを指定します。
- gradle.user.home=(path to directory)
- Gradleユーザーホームディレクトリを指定します。
- https.protocols
- カンマ区切りでサポートされているTLSバージョンを指定します。例:
TLSv1.2,TLSv1.3
マルチプロジェクトのビルドではルートを除く"systemProp"プロパティは無視され、ルートプロジェクトのgradle.propertiesファイルでのみチェックされます。
Environment variables
下記の環境変数がgradleコマンドで使用できます。コマンドラインオプションとシステムプロパティは環境変数よりも優先されることに注意してください。
- GRADLE_OPTS
- GradleクライアントVMのJVM引数を指定します。クライアントVMはコマンドラインの入出力のハンドリングにのみ使用されるため、これを変更する必要がある場面は稀です。現状のビルドはGradle Damonで行われ、この環境変数の影響を受けません。
- GRADLE_USER_HOME
- Gradleユーザーホームディレクトリを指定します。指定されていない場合は`$USER_HOME/.gradle`が既定です。
- JAVA_HOME
- クライアントVMで使用されるJDKのインストールフォルダを指定します。このVMはgradle.propertiesファイルで`org.gradle.java.home`によって別途指定されていない限りはデーモンにも使用されます。
Project properties
-Pコマンドラインオプションを通じてプロジェクトオブジェクトにプロパティディレクトリを追加することができます。
Gradleは特定の名前のシステムプロパティや環境変数を検知してプロジェクトプロパティに設定することも可能です。もしORG_GRADLE_PROJECT_prop=somevalueのような名前の環境変数の場合、Gradleはプロジェクトオブジェクトにsomevalueの値でpropプロパティをセットします。また、Gradleはorg.gladle.project.propのような異なる命名規則のシステムプロパティもサポートしています。
下記の場合、どちらもプロジェクトオブジェクトにはfooプロパティにbarの値がセットされます。
- システムプロパティを通じてのプロジェクトプロパティ設定
org.gradle.project.foo=bar
- 環境変数を通じてのプロジェクトプロパティ設定
ORG_GRADLE_PROJECT_foo=bar
ユーザーホームディレクトリのプロパティファイルはプロジェクトディレクトリのプロパティファイルよりも優先されます
この機能は継続的インテグレーションサーバーの管理権限がなく、簡単に視認されてはならないプロパティを設定する必要がある場合に便利です。そのようなシナリオでは-Pオプションを使用することができず、システムレベルの構成ファイルを変更することもできないため、正しい戦略となるのはあなたのCIビルドジョブに予想されるパターンに一致するプロパティを追加することです。これはシステムの通常ユーザーから視認されることがありません。
変数を使用したときと同様に、これらの名前を使用するだけでビルドスクリプトからプロジェクトプロパティにアクセスすることが可能です。
もしもプロジェクトプロパティが参照されても存在していない場合、ビルドは例外を投げて失敗します。
Project.hasProperty(java.lang.String)メソッドを使用して任意のプロジェクトプロパティにアクセスする前に、その実在性を確認する必要があります。
Configuring JVM memory
下記の方法でJVMオプションを修正できます。
org.gradle.jvmargsGradleプロパティはビルドを実行する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"
クライアントVMがビルドVMとしても動作するケースがひとつあります。Gradle Damonを無効化して、クライアントVMにビルドVMに必要な設定と同じ設定を持っている場合、クライアントVMはビルドを直接実行します。これ以外の場合はクライアントVMは現在のビルドの異なる設定を尊重するために新しいVMをフォークします。
testタスクのような特定のタスクも、追加のJVMをフォークします。これはそれらのタスク自身で構成できます。デフォルトではそれらはすべて-Xmx512mを使用します。
JavaCompileタスクにコンパイルオプションを設定する例
plugins {
id 'java'
}
tasks.withType(JavaCompile) {
options.compilerArgs += ['-Xdoclint:none', '-Xlint:none', '-nowarn']
}
その他の例はTestAPIのドキュメントやtest execution in the Java plugin referenceを参照してください。
Build scans（有料版機能）は--scanオプションを使用するとビルド実行時のJVMの情報を表示します。
Configuring a task using project properties
指定されたプロジェクトプロパティに基づいて、呼び出し時にタスクの振る舞いを変更することが可能です。
リリースビルドがCIによってのみトリガーされるようにしたいと仮定します。これの簡単な方法はisCIプロジェクトプロパティを通じてハンドリングすることです。
CI以外からのリリースを防ぐ例
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
標準JVMシステムプロパティを通じて、HTTPまたはHTTPSのプロキシ（例えば依存関係をダウンロードするなど）が構成されます。これらのプロパティはビルドスクリプト内で直接、指定できます。例えば、HTTPプロキシホストはSystem.setProperty('http.proxyHost', 'www.somehost.org')を使用して可能です。あるいは、gradle.propertiesで指定されたプロパティでも可能です。
gradle.propertiesを使用してHTTPプロキシを構成する
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プロキシを構成する
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つがあります。
NTLM認証
プロキシにNTLM認証が必要な場合、認証ドメインとユーザー名とパスワードが必要になるでしょう。NTMLプロキシの認証にドメインを提供する方法は2つあります。
-
domaim/usernameのような値をhttp.proxyUserシステムプロパティに設定する -
http.auth.ntlm.domainシステムプロパティを通じて認証ドメインを提供する