概要

以下の記事の続きです。以下の記事では、ソースコードの内容をクラス単位で整理しました。クラス単位では全体像が見えづらいため、図とリストを使って全体を要約します。

nosix.hatenablog.com

確認環境

Kotlin 1.1.4
kotlin-frontend-plugin 0.0.21

github.com

解説

タスクの依存関係

タスクの dependsOn による依存関係を整理すると以下の図のようになる。

データフロー

各タスクと一部のクラスでの処理と入出力の関係を図にすると以下のようになる。前者は npm 関連のタスク、後者は webpack 関連のタスク。

requiredDependencies には以下の 3 つの依存関係が含まれている。

webpack (version: *, scope: DevelopmentScope)
webpack-dev-server (version: *, scope: DevelopmentScope)
source-map-loader (version: *, scope: DevelopmentScope)
- kotlinFrontend.sourceMaps が true の場合のみ

入出力の関係

全てのタスクの入力と出力の関係を以下のリストに整理する。

環境変数
- PATH
  - node コマンドのパスとして使われる
プロパティ
- org.kotlin.frontend.node.dir
  - node コマンドのパスとして使われる
project
- name
  - “$buildDir/package.json” の name に使われる
- version
  - “$buildDir/package.json” の version に使われる
sourceSets
- main.output.resourcesDir
  - 設定している場合には、"$buildDir/package.json" と同じファイルが resourcesDir に作成される
dependencies
- compile Kotlin/JS library
  - “$buildDir/node_modules_imported” に展開される
- compile project
  - “$buildDir/webpack.config.js” の resolve に使われる
compileKotlin2Js
- kotlinOptions.outputFile
  - sourceSets.main.output に追加される
  - “$buildDir/package.json” の name, main に使われる
  - “$buildDir/webpack.config.js” の context, entry value, resolve に使われる
  - “$buildDir/WebPackHelper.js” の bundlePath, moduleName に使われる
  - “$buildDir/webpack-dev-server-run.js” の bundlePath, moduleName に使われる
kotlinFrontend
- sourceMaps: Boolean = false
  - “$buildDir/WebPackHelper.js” の sourceMap に使われる
  - “$buildDir/webpack-dev-server-run.js” の sourceMap に使われる
- downloadNodeJsVersion: String = “”
  - 空でなければ nodejs-download タスクを行う
  - nodejs-download.version に設定される
- nodeJsMirror: String = “”
  - nodejs-download.mirror に設定される
- define(name: String, value: Any?)
  - “$buildDir/webpack.config.js” の defined (plugin) に使われる
  - “$buildDir/.run-webpack-dev-server.txt” の exts に記録される
npm
- dependencies: MutableList
  - dependency(name: String, version: String = “*”) で設定する
  - “$buildDir/package.json” の dependencies に使われる
- developmentDependencies: MutableList
  - devDependency(name: String, version: String = “*”) で設定する
  - “$buildDir/package.json” の devDependencies に使われる
- versionReplacements: MutableList
  - replaceVersion(name: String, version: String) で設定する
webpackBundle
- bundleName: String = project.name
  - “$buildDir/webpack.config.js” の entry key に使われる
- sourceMapEnabled: Boolean = kotlinFrontend.sourceMaps
  - “$buildDir/WebPackHelper.js” の sourceMap に使われる
  - “$buildDir/webpack-dev-server-run.js” の sourceMap に使われる
- contentPath: File? = null
  - “$buildDir/WebPackHelper.js” の contentPath に使われる
  - “$buildDir/webpack-dev-server-run.js” の contentPath に使われる
- publicPath: String = “/”
  - “$buildDir/webpack.config.js” の publicPath に使われる
  - “$buildDir/WebPackHelper.js” の publicPath に使われる
  - “$buildDir/webpack-dev-server-run.js” の publicPath に使われる
- port: Int = 8088
  - “$buildDir/WebPackHelper.js” の port に使われる
  - “$buildDir/webpack-dev-server-run.js” の port に使われる
  - “$buildDir/.run-webpack-dev-server.txt” の port に記録される
- proxyUrl: String = “”
  - “$buildDir/WebPackHelper.js” の proxyUrl に使われる
  - “$buildDir/webpack-dev-server-run.js” の proxyUrl に使われる
- stats: String = “errors-only”
  - “$buildDir/WebPackHelper.js” の stats に使われる
  - “$buildDir/webpack-dev-server-run.js” の stats に使われる
- webpackConfigFile: Any? = null
  - 設定されている場合、webpack-config タスクを行わない
  - 設定されている場合のみ、webpack-helper タスクを行う
  - “$buildDir/WebPackHelper.js” の webPackConfig に使われる
  - “$buildDir/webpack-dev-server-run.js” の webPackConfig に使われる
“$projectDir/package.json.d” 配下の JSON ファイル
- “$buildDir/package.json” にマージされる
“$projectDir/webpack.config.d” 配下の JavaScript ファイル
- “$buildDir/webpack.config.js” の拡張スクリプトとして使われる

まとめ

kotlin-frontend-plugin を使うにあたって重要なファイルは、以下の 4 つであると思われる。

node コマンド
package.json
webpack.config.js
webpack-dev-server-run.js

kotlin-frontend-plugin では、 package.json の設定により環境を整え、 webpack.config.js の設定により JavaScript のバンドルを作成し、 webpack-dev-server-run.js の設定により webpack-dev-server を起動する。これらを使う上で、node コマンドは必須である。

これら 4 つのファイルに関わる主要な入力は以下のようになっている。

node コマンド
- プロパティ org.kotlin.frontend.node.dir でパスを設定
  - 最優先されるパス
  - 別途 node.js をインストールして使用する場合に使うとよい
- ~/.gradle/nodejs
  - Gradle でインストールさせる場合のパス
  - kotlinFrontend.downloadNodeJsVersion を指定することで有効になる
- 環境変数 PATH でパスを設定
package.json
- project の name, version
- dependencies で compile 指定した Kotlin/JS library が node_modules として展開される
- compileKotlin2Js.kotlinOptions.outputFile が name, main に使用される
- npm の dependencies, developmentDependencies で依存モジュールを指定する
- “$projectDir/package.json.d” 配下の JSON ファイルで設定を拡張する
webpack.config.js
- dependencies で compile 指定した Project が resolve に含まれる
- compileKotlin2Js.kotlinOptions.outputFile が複数の設定に使用される
- kotlinFrontend の define(name: String, value: Any?) メソッドで plugin の設定を追加する
- webpackBundle の bundleName, publicPath, webpackConfigFile
  - webpackConfigFile を指定すれば、指定したファイルが使用される
  - webpackConfigFile を指定しなければ、生成したファイルが使用される
- “$projectDir/webpack.config.d” 配下の JavaScript ファイルで設定を拡張する
webpack-dev-server-run.js
- compileKotlin2Js.kotlinOptions.outputFile が bundlePath, moduleName に使用される
- kotlinFrontend の sourceMaps が source-map-loader を追加する
- webpackBundle の各設定
- スクリプトのなかでは HotModuleReplacement の設定を追加する

また、実行されるコマンドは以下のとおりであり、設定が上手くいかに場合には以下のコマンドを試すとよい。

// npm-install
npm install

// webpack-bundle
node $buildDir/node_modules/webpack/bin/webpack.js --config $buildDir/webpack.config.js

// webpack-run
node $buildDir/webpack-dev-server-run.js

// webpack-stop (実際には curl は使用せず URL にアクセスしている)
curl http://localhost:$port/webpack/dev/server/shutdown

このあたりの関係を押さえておくと設定に迷うことが少なくなるのではないかと思う。