giter8テンプレートの作り方

giter8の復活

その昔、Scala世界にはgiter8というツールがありました。GitHub上のテンプレートプロジェクトをベースにプロジェクトを作成できるというなかなか便利なものでしたが、初期の頃はWindowsでの利用に問題があったり、Typesafe Activatorという用途がモロ被りするツールが登場したりするなどしたため、ここ数年はあまり積極的に利用されていませんでした。

時は流れて2016年、Scalaの標準的なビルドツールsbtの最新版である0.13.13でgiter8テンプレートのサポートが追加されました。sbtさえインストールしておけば、

$ sbt new scalatra/scatara-sbt.g8

のようにnewサブコマンドでgiter8テンプレートを使用してプロジェクトを作成できるようになったのです。これまでactivatorを使用してプロジェクトを作成することになっていたPlay Frameworkも今ではsbt newを使用するようになっています。

なお、現在はgiter8はオリジナルの開発者であるn8han氏からfoundweekendsというorganizationに引き継がれ開発が継続されています。オープンソースって本当に素晴らしいですね!

github.com

giter8テンプレートの作り方

ドキュメントを読めばだいたい分かると思いますので、ここでは要点だけ。

まずはgiter8テンプレートのためのテンプレートが用意されているので以下のようにしてプロジェクトを作成します。なお、giter8テンプレートのリポジトリ名は末尾が.g8になっている必要があるので注意しましょう。

$ sbt new foundweekends/giter8.g8

src/main/g8ディレクトリ以下にプロジェクトのテンプレートを配置していきます。重要なのがdefault.propertiesというファイルです。デフォルトでは以下のような内容になっています。

name=My Something Project
description=Say something about this template.

ここに定義したプロパティは各ファイルに以下のようにして埋め込むことができます。default.propertiesでデフォルト値を定義しますが、プロジェクトの作成時にユーザからの入力を受け付けることができ、入力された値で上書きされます。

organization := "$organization$"
name := "$name$"
version := "$version$"
scalaVersion := "$scala_version$"

いくつか特殊なプロパティがあります。これらはファイルに変数として埋め込むだけでなく、以下のように特殊な用途にも利用されます。

  • name: 作成されるプロジェクトのディレクトリ名としても使われます。
  • package: $package$という名前のディレクトリがあるとパッケージのディレクトリ構造に展開されます。

なお、テンプレートをsrc/main/g8ディレクトリに配置する方法とは別にルートディレクトリに直接配置するrootレイアウトという方法もあるのですが、まだ実験的な機能のようです。scalatra-scalajs.g8は試しにこのrootレイアウトで作ってみました。

テンプレートのエスケープとか

テンプレートプロジェクトを作成していると、ファイル中に含まれる$をエスケープしたいとか、ファイルごとテンプレートの対象外にしたいという場合があるかもしれません。$をエスケープというかそのまま出力するには以下のようにするのが簡単です。

$var -> $"$"$var

ファイルごとテンプレートの対象外にするにはdefault.propertiesにverbatimというプロパティを追加します。半角スペース区切りで対象外にするファイルのパターンを指定することができます。

verbatim=*.html *.js

他にもテンプレートに変数を埋め込む際に便利なフォーマッタなども用意されていますので細かい話についてはgiter8のドキュメントを見るのがよいです。

テンプレートのテスト

sbt newでは以下のようにローカルファイルのテンプレートを指定してプロジェクトを作成することができるのでこれでテンプレートが実際に動作するかをテストすることができます。

$ sbt new file:///path/to/dir/my-template.g8

また、Giter8Pluginの機能を使用して、プロジェクトの作成及びscriptted testを使ったテストができるようなので、可能であれば自動テストを作っておくとよさそうです。

まとめ

sbtで使えるようになったのでgiter8テンプレートを活用していきましょう。