Android Build のドキュメントを読む
nashcft動機
Android Developers の Gradle まわりのドキュメントの刷新や新しいページの追加がアナウンスされた。そういえばこの辺のページ群は what's new 以外あまりちゃんと目を通したことがなかったのでいい機会だし読んでみる。
nashcftAndroid build overview
Overview ということで Android project の build で使われている Gradle のしくみや特徴について大まかにまとめられている。前半2つが主に構成の話、後半2つが依存に関する話。
Gradle build overview
全体の導入として Gradle build system の全体像や Android アプリ開発における役割と機能、アプリ開発者は何を書くかといった概観が書かれている。 Gradle よくわからんという人はまずこれを読むのがよい。
このページくらいは要点をまとめておいた方がよかろうと思うので以下にざっと書き出した:
- Task という単位で処理が行われている
- ファイルやディレクトリ、 Java のデータ型で定義された値を入力として受け取り、成果物としてファイルやディレクトリを出力する
- 特定の目的をこなすための task 群とそのための設定をまとめて Plugin が作られる
- Plugin を適用することで build 上でそれに定義されている task を使った処理を行うことができる
- Plugin の機能を拡張する plugin というものもある
- Build の設定は DSL によって記述する
- Build script (e.g.
build.gradle) には what (成果物の定義など) を書き、 how (処理のロジック) は書かない (how は plugin の中に書くべき)
- Build script (e.g.
- Gradle の build file は割と自由に記述ができてしうので難解になりやすく、ある程度自制的な設計が必要になる
-
While Gradle supports writing arbitrary code and task declarations in your build files, this can make it more difficult for tooling to understand your build and for you to maintain. For example, you can write tests for code inside plugins but not in build files. Instead, you should restrict build logic and task declarations to plugins (that you or someone else define) and declare how you want to use that logic in your build files.
-
- Gradle の build 実行は initialization, configuration, execution の 3 phase に分かれる
- どこの記述がどの phase で実行されるか意識できるようになると便利
- Gradle project (build の単位) は外部 repository で公開されている maven artifact や他の project を参照して、それらの artifact を使用することができる (「依存」と呼ぶ)
- Android アプリ開発の build 文脈で言及される "module" と Gradle の "project" や "subproject" は同義
- 一つの Android appliction に複数の build variant を設定して、同じ実装に対してそれぞれ異なる設定を振り分けたり、特定の環境のみ特定の実装を含ませたりといったカスタマイズを行うことができる
- Build variant は "build types" と "product flavors" によって構成される
Android build structure
Gradle を用いた Android project のディレクトリ構成の概観。
Tool and library interdependencies
ちょっと扱っている内容が散漫な印象があるけど、要点としては以下になるか:
- 外部依存 (Gradle plugins や libraries) はそれ自体がさらに何かしらの依存を持っていることがあり、 build 実行時にそれらも一緒に解決 (バージョンの決定と取り込み) される
- "Transitive dependency" (推移的依存) と呼ばれる
- 自分で明示的に宣言・管理する依存が減るので設定の手間は省けるが、依存の更新時にそれらの依存も更新されることがあるので更新の影響箇所には注意が必要になる
- (Android) Gradle project の build における主要な登場人物と役割・関係について
- 特にソースコードと直接関わらない build tool 群 (Gradle とか compiler とか) がどう関わってくるか
- 関係図は project の build file の存在が含まれていないせいで plugin の立ち位置がわかりにくいかも? 下の "Tools" の項の説明と組み合わせて理解する必要がある
- Gradle scopes の項は中途半端に version catalog と plugin のサンプルコードが混ざっててかなり謎になってしまっているが、要は依存の宣言の仕方によって依存の含め方をコントロールできるよ、ということを言いたいらしい
このページは将来的にもっと内容が整理されて分割されたりするんじゃないかな、そうあってほしい。
Gradle dependency resolution
Gradle の依存解決の仕方と依存のバージョン指定方法の種類について。重要なのは前半の同じライブラリのバージョン違いが依存の中に存在した場合にどのように解決されるかの方。こういうことが直接宣言していない依存も含めて起こるよということと、 dependencies task を使ってどのバージョンに解決されたかが確認できるよということを押さえておくと良い。
nashcftManage your build
Android project の build 設定に関するセクション。 "Configure your build" のページは Gradle project 内の各種設定ファイルの紹介になっているので詳しくない人はひとまず読んでみるのが良さそう。それ以外はほぼ build.gradle に記述するものに関する話題なので、基本的にはこれの修正で困った時に読むと良いと思われる。
Configure your build
Android project の build 設定に関する overview のページ。 Configuration にどのような要素があるか、どこのファイルで何を設定するかなどを紹介している。基本的に各トピックの詳細は別のページに譲るようになっているが、 minSdk, compileSdk, targetSdk の関係に関しては後述の "Configure the app module" ではなくこちらで解説されている (The module-level build file)。
Add annotation processors
Annotation processor の設定に関する詳細。
Java versions in Android builds
諸々の要素と参照される JDK の場所や適用される Java version の関係について。
「Gradle を実行する JDK」と「project の build に使う JDK」と「build の成果物の互換 Java バージョンの設定」は別々に指定できるよ、というのが明確に述べられたドキュメントが公式から出てほしいなーって思っていたので有難い。ただ AGP 8 リリース前後 (2023年4月頃) に公開されていたらなあと思わないこともない (Wayback Machine で遡れる限りでは現在の内容で公開されたのは 2023年8月頃、ただし7月にはこの URL が公開されているようだが内容が確認できない)。
Configure the app module
Application ID と namespace の設定について。
Manage manifest files
AndroidManifest.xml の merge の仕組みや conflict 時の解決に関わる設定、あと manifest への変数の埋め込みについて。 Manifest の merge で何か問題あった時にこれ見ながら対処するみたいな使い方で良さそう。
Apply custom build logic
依存関係まわりの操作に関する task や DSL について。必要になる機会はあまりないかも。
Configure build variants
Build types, product flavors の設定の方法と用途、その他 build variants 関連の設定 (sourceSets や signingConifgs) まわりについて。複雑な機能ではないのだけど product flavors の記述のせいで長い。
Use the Android Gradle plugin Upgrade Assistant, Use the Android SDK Upgrade Assistant
Android Studio にある AGP, Android SDK それぞれの更新アシスタントツールの紹介と使い方の解説ページ。
nashcftManage dependencies
依存まわりの設定に関するセクション。ここの記事を読む前に overview のセクションの依存に関するページを読んでおきたい。設定関連のページはそんなに複雑なトピックがないこともありあっさりしているが、依存更新については人間の活動の話だからかかなり力が入っているように見える。
Add build dfependencies
(TOML形式での) version catalog を使った依存の定義の仕方と、それを使った build file での依存の宣言の仕方と依存の宣言の種類の機能について (e.g. implementation, api, ksp, etc.) あたりがメインの話題。他にも細々とした解説があるが、依存の宣言順と manifest や resource の merge 時の優先順位の関係を少し気にしておくと良い程度か。
Add native dependencies
メニューのタイトルは "Add native dependencies" だけどページのタイトルは "Native dependencies with the Android Gradle plugin" になってる。内容もどちらかというと native library として module を公開するための build の設定のように見える。
Manage remote repositories
依存の取得先となる remote repositories の指定方法について。
Verify build dependencies
新しく追加されたページとのこと。依存しているライブラリ等が正当なものかを検証する Gradle の機能の導入手順を簡単にまとめたもの。概ね Gradle のドキュメントからの抜粋という印象だがとりあえず適用するという目的では十分という所感。
Upgrade build dependencies
こちらも新しく追加されたページ。依存を更新するにあたって考慮すべき評価指標 (どんな project をどういう体制で開発しているか? 更新対象となる依存の立ち位置は? 更新の規模は? etc.) や、行うべき影響調査 (依存や API, 挙動の変化の確認、実際に build や lint を実行して出力を確認、など) について列挙している。様々な観点・項目が記載されており読むのが大変だが、一度はきちんと目を通しておきたい内容ではある。
If you use plugins or tools that help automate dependency upgrades, be aware that they don't do any analysis for you; they upgrade to the latest library versions. Don't assume that everything will work properly after these types of automatic upgrades.
ここすき
nashcftRun your build
ここはそもそもそんなに書くことがないのかもしれない。 "Build your app from the command line" のページだけ読めば良いと思った。
Build your app from the command line
CLI で Android project を build したり色々したりするための Gradle task と、関連する CLI tools 群の紹介。
Build your app for release to users
タイトルの割に説明しているのは Android Studio の Build menu でできることの説明。あと若干内容が古い。
Build and run your app in Android Studio
内容がないよう
nashcftOptimize your build
Build 実行の高速化とアプリのサイズ縮小、パフォーマンス最適化に関する設定に関するセクション。このセクションは読んだことあったかも。
Overview (Optimize your build speed)
Build の実行時間を短くするための tips 集。内容が古い記述が所々あるように思われる。
Troubleshoot build performance
Android Stuidio の Build Analyzer を使って build performance のボトルネックを調査をする方法について。
Profile your build
Gradle build の実行内容の profiling をするツール (gradle-profiler, Gradle の --profile option) の紹介と、幾らかの profiling のレシピ。
Shrink your app
R8 による shrinking や obfuscation の解説や設定に関する話。 ProGuard file の調整をする時にお世話になる。
D8 and R8 compiler version compatibility
Kotlin, サポート下限の AGP, D8/R8 のバージョン対応表。
Enable multidex
API level 20 以下向けに application code 内で multidex の設定をするための色々のページ。 minSdk が 21 以上の世界では考慮不要なトピックなので現代で必要になる人は限られていそう。
nashcftExtend your build
Gradle project の build file の記述に関するやや突っ込んだ話のまとめセクションという風。
Write Gradle plugins
Android project のための (= Android Gradle plugin の API を使った) 自作 Gradle plugin を作るためのガイドライン的なページ。共通設定の抽出とかではなく自分で task を作ったりそれなりな処理を実装したりするくらいのレベル感が対象っぽい。
Gradle tips and recipes
Build の便利設定集みたいな感じ。主なトピックとしては build variants まわりの設定、 test や lint の設定、署名や artifact 公開に関する設定、その他、と言ったところ。幾らかは別のページと内容が重複している。あと少し内容が古い。
Integrate a custom C/C++ build system
CMake, ndk-build 以外の tool で Android native project で build したいよ〜という人のための設定ガイド的な。 Ninja という tool を経由して組み合わせるとのこと。
nashcftPublish your library
Library 開発者向けの情報がまとまってるセクション。
Overview
このセクションの他のページへのリンク。
Prepare your library for release
内容は以下の4点:
-
namespaceを設定しよう -
minSdkを決める時にの考慮ポイント - AAR metadata で
minCompileSdkが設定できる - Test fixtures を有効にしよう
Configure publication variants
Build variants とは別に publication variants というのがあって、それがどういうものかという話と、 AGP 7.1 から追加された publishing DSL を使ったその辺の設定の説明をしているページ。
Configure test fixtures for publication
Test fixtures って何だよという話は Gradle のドキュメントを読むとして、これは Gradle や AGP の機能で自動で生成してくれるわけではないから自分で module 切って命名規則に従ってどうにかせよという感じで、そのために module の名前をどうするか、という話っぽい。書かれていない前提が多くない?
Upload your library
Gradle の Maven Publish plugin を使って repository に publish しようね、という話。前半 (公開方法の話) と後半 (Maven Publish plugin の設定) で想定読者にブレがあるような気がしてやや読みにくく感じた。
nashcftMigrate your build
Build file の記述を新しいものに置き換えるための手順がまとめられたセクション。必要な時になったら目を通せば良い。
Migrate to the Kotlin DSL
Groovy DSL から Kotlin DSL への移行における構文や DSL の差分の説明と、 plugin まわりの設定を buildScript と apply plugin から plugin DSL に置き換えよう、というページ。
Migrate to version catalogs
ベタ書きの依存宣言から version catalog を使った宣言への移行手順のページ。
Migrate to Kotlin Symbol Processing
kapt から KSP の移行手順のページ。
nashcftTroubleshoot
困った時に読むページ群... だと思うのだけどコンテンツが少ないので役に立つかは微妙。
Overview
Android Build のドキュメント外で参照するべきページへのリンク。
Debug dependency resolution errors
依存解決でエラーが発生した時の調査方法と代表的っぽい2つの問題に対する対処法について書かれている。同じライブラリのバージョン違いで conflict 起こすみたいなのは strict な指定方法でもしない限り現代で遭遇することはないように思うけど... という所感。
nashcftあとで読む