`bin/webpack`を読んだ

webpackerを理解するため、rails g webpacker:installで追加されるbin/webpackや設定の中身を読むことにした。

bin/webpack

newenv  = { "NODE_PATH" => NODE_MODULES_PATH.shellescape }
cmdline = ["yarn", "run", "webpack", "--", "--config", WEBPACK_CONFIG] + ARGV

Dir.chdir(APP_PATH) do
  exec newenv, *cmdline
end
  • bin/webpackでは実際にはyarn run webpack -- --config WEBPACK_CONFIGを実行している。
  • WEBPACK_CONFIGconfig/webpack/#{NODE_ENV}.jsとなっているため、config/webpack/development.jsなどとなる。

config/webpack/development.js

const sharedConfig = require('./shared.js')

module.exports = merge(sharedConfig, {
  // ...
})
  • config/webpack/shared.jsというファイルが環境ごとの設定ファイルでmergeされているようだ。

config/webpack/shared.js

const { env, settings, output, loaderDir } = require('./configuration.js')
  • settingsconfig/webpacker.ymlをロードしたオブジェクトを参照している。
    • settings.extensions: [.coffee, .erb, .js, .jsx, .ts, .vue, ...]
    • settings.source_path: app/javascript
    • settings.source_entry_path: packs
  • outputpathpublicPathというプロパティをもったオブジェクトを参照している。
    • path: public/packs
    • publicPath: ‘/packs’
      • ASSET_HOSTという環境変数を指定することでホストを変更できそう。
  • loadersDirconfig/webpack/loaders/を参照している。
const extensionGlob = `**/*{${settings.extensions.join(',')}}*`
const entryPath = join(settings.source_path, settings.source_entry_path)
const packPaths = sync(join(entryPath, extensionGlob))

module.exports = {
  entry: packPaths.reduce(
    // ...
  )
}
  • entryはwebpackによってbundleされる対象のファイルを設定する。
  • synchttps://github.com/isaacs/node-globからexportされている。同期的にglobサーチをしている。
  • ここでは、app/javascript/packs/**/*{.coffee,.erb,.js,.jsx}*のようなglobでファイルを検索し、マッチしたファイルのリストがpackPathsに代入されている。
  • つまり、app/javascript/packs/以下のsettings.extensionsで指定された拡張子をもつファイルがwebpackによってbundleされるということになる。
module.exports = {
  entry: packPaths.reduce(
    (map, entry) => {
      const localMap = map
      const namespace = relative(join(entryPath), dirname(entry))
      localMap[join(namespace, basename(entry, extname(entry)))] = resolve(entry)
      return localMap
    }, {}
  )
}
  • entryにオブジェクトが指定された場合、プロパティごとにbundleされるファイルが分割される。output.filename[name]と指定された箇所にプロパティ名が入る。
const { env, settings, output, loaderDir } = require('./configuration.js')

module.exports = {
  output: {
    filename: '[name].js',
    path: output.path,
    publicPath: output.publicPath
  }
}
  • outputはbundleされたファイルの出力先を設定する。
  • output.filenameでbundleされたファイル名を設定する。entryがオブジェクトで指定されているため、[name]にはオブジェクトの各プロパティ名が代入される。
  • output.pathは出力先のパスを設定する。上記の通りpublic/packsが設定されている。
  • output.publicPathは本番ビルド時のCSSやHTML内のURLを設定する。これは本番のみCDNを使う場合に便利。上述の通りこれは/packsが設定されているが、ASSET_HOSTという環境変数でこれを変更することができるようになっている。
module.exports = {
  module: {
    rules: sync(join(loadersDir, '*.js')).map(loader => require(loader))
  }
}
  • rulesはwebpackのモジュールを設定する。
  • config/webpack/loaders/*.jsにマッチするファイルを検索している。
  • マッチしたファイルをrequireしている。各ファイルは以下のようになっている。これによって、config/webpack/loaders/*.js内の設定を展開している。
module.exports = {
  test: /\.(jpg|jpeg|png|gif|svg|eot|ttf|woff|woff2)$/i,
  use: [{
    loader: 'file-loader',
    options: {
      publicPath,
      name: env.NODE_ENV === 'production' ? '[name]-[hash].[ext]' : '[name].[ext]'
    }
  }]
}
const webpack = require('webpack')
const ExtractTextPlugin = require('extract-text-webpack-plugin')
const ManifestPlugin = require('webpack-manifest-plugin')

module.exports = {
  plugins: [
    new webpack.EnvironmentPlugin(JSON.parse(JSON.stringify(env))),
    new ExtractTextPlugin(env.NODE_ENV === 'production' ? '[name]-[hash].css' : '[name].css'),
    new ManifestPlugin({
      publicPath: output.publicPath,
      writeToFileEmit: true
    })
  ]
}
= stylesheet_pack_tag "application" # load /packs/application-xxxxxxxx.css
{
  "application.css": "/packs/application-xxxxxxxx.css"
}
module.exports = {
  resolve: {
    extensions: settings.extensions,
    modules: [
      resolve(settings.source_path),
      'node_modules'
    ]
  }
}
  • resolveはモジュール解決方法を設定する。webpackはデフォルトではいい感じに設定されている。
  • resolve.extensionsはファイル名からモジュールを解決する際に自動的に付与する拡張子を設定する。
  • resolve.modulesはモジュールを解決する際に検索されるディレクトリを設定する。

github.com/rails/webpacker/lib/webpacker/helper.rb

#stylesheet_pack_tagマニフェストファイルからどのようにアセットを参照するかを確認する。

def stylesheet_pack_tag(*names, **options)
  unless Webpacker.dev_server.running? && Webpacker.dev_server.hot_module_replacing?
    stylesheet_link_tag(*sources_from_pack_manifest(names, type: :stylesheet), **options)
  end
end

def sources_from_pack_manifest(names, type:)
  names.map { |name| Webpacker.manifest.lookup(pack_name_with_extension(name, type: type)) }
end

def pack_name_with_extension(name, type:)
  "#{name}#{compute_asset_extname(name, type: type)}"
end
  • #sources_from_pack_manifestマニフェストからアセットのファイル名を解決しているようだ。
  • ActionView::Helpers::AssetUrlHelper#compute_asset_extnameはファイル名とtypeから適切な拡張子を返す。
  • Webpacker.manifestWebpacker::Manifestインスタンスを返す。

github.com/rails/webpacker/lib/webpacker/manifest.rb

def lookup(name)
  compile if compiling?
  find name
end

def find(name)
  data[name.to_s] || handle_missing_entry(name)
end

def data
  if env.development?
    refresh
  else
    @data ||= load
  end
end

def refresh
  @data = load
end

def load
  if config.public_manifest_path.exist?
    JSON.parse config.public_manifest_path.read
  else
    {}
  end
end
  • #lookupマニフェストファイルの中身にアクセスしている。
  • マニフェストファイルの中身はJSON.parseした結果をメモリに保持している。開発環境ではアクセス毎にJSON.parseし直している。

vim も zsh も捨てた

プロジェクト移行期に入って暇な時間ができたので、開発環境をリフレッシュすることにした。vimzsh の設定が少しずつ壊れてきていたのだった。

.vimrc や .zshrc を眺めてみると、かつて意識が高かった頃に施した設定が何のためのものだったのか忘れてしまっていた。別人が書いたスパゲティコードのようだった。

また vimzsh の設定を検索して理解するべきなんだろうか。ここで覚えた知識はまたすぐに忘れてしまうんじゃないだろうか。設定が洗練されるほどに、それを更新する機会もまた少なくなってくる。設定が必要になるきっかけは忘れた頃にやってくるもんだ。

やり方を根本的に見直す時期なのかもしれない。新しいツールもいまなら選択できる。

まず、vim から atom に移行した。git のコミットメッセージやちょっとしたファイルの修正ではまだ vim を使うものの、細かい設定が必要になる作業では vim を使うのをやめた。デフォルトでインストールされているプラグインのおかげで、開発環境に合ったプラグインをインストールだけで充分に使えるものになった。

プラガブルな作りになっているから、プラグインのインストール・アンインストールだけで設定が完結してしまう。もしプラグインが壊れたら、替わりをインストールすればいい。解決すべき問題は局所化されているから、なんとか自作することも可能だろう。

次に、zsh から fish に移行した。fish は設定しなくてもコマンドの補完などの設定がデフォルトでいい感じになっていて、ほとんど設定がいらなかった。しかも、設定ファイルも何種類もあるのではなくて、1つのファイルだけでいいようだ。

fish 自体にはプラガブルな機構がないので、fisherman というツールを併用している。fisherman によってプラグインのインストール・アンインストール、依存関係の管理が可能になった。

自分でいくつかプラグインをつくった。

結局、設定ファイルがプラグインという形に変わっただけではとも思ったが、一度壊れたプラグインはおそらくもう修正することはないだろう。アンインストールして、新たに必要なプラグインを見繕うことになる。ダメになったら捨てればいい、みたいな気軽さがある。


追記(2017-04-20)

思っていた以上に反響があって驚いた。修正点と反響へのコメントを載せます。

  • 「意識が高かった頃に施した」という表現を撤回しました。意識が高いとか低いとか不毛な話を避けたかったので。
  • vimzsh だけじゃなく tmux も捨てました。サーバー内で作業するなら必要かもしれないけど、普段の開発では主にウィンドウ分割の用途としてのみ使っており、iTerm 2 の機能だけで十分ではということに気づきました。
  • デフォルトのままが良いという話について。僕は普段は iOS アプリの開発が主な仕事なので、シェルスクリプトに触れる機会はあんまりありません。サーバーにログインして何か作業するような仕事がメインであれば、bash をデフォルト設定で使ったり、ちゃんとシェルスクリプトを理解することは必要だと思います。あくまでここに書いたのは僕の場合なので、そこを考慮してくれると誤解がないかなと思います。
  • Git で設定ファイル群、俗にいう dotfiles を管理すれば良いという話について。僕もかなり昔から dotfilesGitHub で公開しており、かつてはちゃんとメンテナンスしていました。やらなくなった理由としては、細かいチューニングの度にコミットするのがめんどくさくなったということがありますね。あとは、直接設定ファイルを修正することが減ってきているというのもあります。atom の設定画面でポチポチ設定を修正すると、それをコミットするのを忘れてしまうのです。こうして大きい差分が生まれてしまい、メンテナンスをする意欲が失われていきました。

Homebrew で自分のためのツールを公開するのが楽しい

  • Homebrew で自分のためだけの細々としたツール類を公開するのが楽しい。
  • naoty/homebrew-misc という tap を作って、そこにツールのための Formula を置いている。
  • brew tap naoty/misc を実行すると、インストール可能になる。
  • 自分で作ったソフトウェアを日々自分で使っていると、ジワジワと幸福感が広がってくる。
  • rubygems など、特定の言語、特定のバージョン、特定のライブラリに依存したソフトウェアはずっと使っていくことができなくなるかもしれない。使えなくなった頃には、もうそのソフトウェアを書き直す意欲やモチベーションは失われているかもしれない。
  • できれば、コンパイル済みの実行ファイルのみを配布できるようにしたい。Go を好んで使ってるのはそういう理由だ。
  • Go 以外の言語を使う場合は 2 パターンある。
    1. その言語でなければ実現できない機能。macOS の機能を使ったソフトウェアは Swift で書くだろう。naoty/flock もこの理由で Swift で書かれている。
    2. ソフトウェアの利用者が特定の言語の利用者に偏ってる場合、メンテナンスしやすさを考えて利用者の言語でソフトウェアを書くことになりそう。CocoaPods や Fastlane が Ruby で書かれていることは、この理由で個人的に好きではない。
  • 自分のためのツールを Homebrew で配布するのは、仕事用の PC でもプライベート用の PC でも使えるようにしたかったり、PC を新調しても使えるようにしたいからだ。ポータビリティを高めて、ずっと長く使えるようにしたい。
  • 自分は iOS アプリのプログラマーなので、Linux に移ることはしばらくないと思う。なので、Homebrew を使ってる。
  • まだ Homebrew に移せていないツールがたくさんあるので、隙を見て移していきたい。

Swiftのオブジェクトグラフを生成する flock を作った

Swift で定義されたオブジェクト間の依存関係を可視化する flock というツールを作った。これによって、 Swift で書かれたコードベース全体を把握しやすくなったり、リファクタリング時に影響範囲を把握しやすくなる。

Usage

Homebrew からインストールできる。

$ brew tap naoty/misc
$ brew install flock

flock は指定したディレクトリ(何も指定しなければカレントディレクトリ)以下の Swift のソースコードを解析して dot 形式のソースコードを出力する。これを Graphviz 等を用いて画像に出力して使う。

$ flock <directory>

試しに Alamofireflock を試してみた。

f:id:naoty_k:20170313230437p:plain

横長になってしまうので、一部を切り取った。

f:id:naoty_k:20170313231019p:plain

コードの依存関係がハッキリと把握できるようになった。

How it works

Objective-C では nst/objc_dep というツールがあった。これはシンプルな Python によるスクリプトでありながら、コードベースを把握する上で強力なツールだった。しかし、 Swift は Objective-C よりも文法がはるかに複雑なため、正規表現で依存関係を抽出するのは困難だ。

幸いにも、 Apple は SourceKit という IDE のためのフレームワークOSS として公開している。これを使うことで、正規表現によるパースなしに Swift のソースコードの AST を抽出することができる。 SourceKit を使った有名なツールに realm/SwiftLint がある。

flock では、間接的に SourceKit を使っている。間接的に、というのは SourceKit を Swift から扱いやすくする jpsim/SourceKitten を使っているからだ。 flock は SourceKitten が提供する情報をもとに dot ファイルのソースコードを生成している。

課題

現状では、 [String], String?, Set<String> といった Compound Type を扱えていないため、依存関係の一部分しかグラフにできていない。 SourceKitten がこうした型を扱えていないため、 SourceKit を直接扱うか、こちら側でなんとかパースするかすることになりそう。

Homebrew にコントリビュートした

あらすじ

前回、 naoty/todo というツールを Homebrew で配布しようとしたときにとある問題にハマった。 todo という名前を持つファイルが README.mdLICENSE のようなメタファイルとして判断されエラーが起きてしまうという問題だった。

Homebrew に Pull request を送った

前回は、メタファイルではない適当な名前の空ファイルを置いてこの問題を回避していたが、なんというか負けな気がしてきたので、 Homebrew に Pull request を送った。前回、コードを読んで何が原因なのかは把握していたので、修正すべきポイントもおおよそ見当がついていた。

当初は実行ファイルであればメタファイルではないという方針で Pull request を送ってみたが、パーミッションが正しく付与されていないものも稀にあるらしかった。そこで、コミッターのアドバイスを基にメタファイルは keg のルートディレクトリにしか存在しないだろうという前提で修正し、無事に merge された。

この修正によって、 todo, changelog, license といったメタファイルっぽい実行ファイルを配布したいときに Empty installation エラーによって失敗することはなくなった。また一つ、世界が便利になった。

Homebrewで自作Formulaを作るときの落とし穴

naoty/todo という CLI ツールを Homebrew で配布しようとしたときにハマったことを書く。

naoty/todo は Go で書かれており、コンパイル済みのバイナリを GitHub Releases にアップロードしてそこから配信したいと思っていた。ドキュメント等を調べると以下のように formula を書くことでインストールが完了するものと思っていた。

class Todo < Formula
  desc "A todo management tool just for myself"
  homepage "https://github.com/naoty/todo"
  url "https://github.com/naoty/todo/releases/download/0.2.0/todo.tar.gz"
  sha256 "be20e4069c0ae49998dfc00a010ca8f5d49d26193bd0c3e8611a4bf53cac469d"

  def install
    bin.install "todo"
  end
end

しかし、実際には Empty installation というエラーが発生してインストールができない現象に遭遇した。ドキュメントを調べてみるも、なぜこれが失敗するのか突き止めることはできなかった。そこで、エラーメッセージを頼りに Homebrew のソースコードを読むことにした。

まず、 Homebrew のソースコード/usr/local/Homebrew/Library/Homebrew にある。そこで ag で Empty installation というエラーメッセージを検索してみると、以下のようなコードを見つけることができた。

if !formula.prefix.directory? || Keg.new(formula.prefix).empty_installation?
  raise "Empty installation"
end

ここからは pry を使ってブレークポイントを貼りながら進めようと思った。 Homebrew はシステムの Ruby を使っているようなので、 システムの rubygems で pry をインストールし調査を続けた。

binding.pry で調べたところ、 empty_installation?true を返しているようだった。このメソッドの中身は以下のようになっていた。

def empty_installation?
  Pathname.glob("#{path}/**/*") do |file|
    next if file.directory?
    basename = file.basename.to_s
    next if Metafiles.copy?(basename)
    next if %w[.DS_Store INSTALL_RECEIPT.json].include?(basename)
    return false
  end

  true
end

さらにここでイテレーションされている file を調べると formula でインストールした todoREADME 等のファイルが含まれていた。ここで何が原因か調べてみると、どうやら以下のように todo が README や LICENSE といったメタファイルのひとつとして扱われていて、ここで true が返っているようだった。

BASENAMES = Set.new %w[
  about authors changelog changes copying copyright history license licence
  news notes notice readme todo
].freeze

ということは、メタファイルではないものがひとつでも存在すれば true が返るということなので、以下のような formula を定義して適当なファイルを置くことで、この問題を回避することができた。

def install
  bin.install "todo"

  # Avoid "Empty installation" error which will be caused when the only
  # "todo" file is installed.
  bin.install "empty"
end

この問題は licensechangelog といった名前のパッケージを配布する場合でも起こる。ソースコードを読まないと原因が分からないので、同じ問題に直面した人は不運という感じがする。

CHANGELOG.mdを書き始めた

チビチビ開発しているライブラリの1.0.0をリリースしたのを機にCHANGELOGというものを書き始めた。その際にCHANGELOGについて調べていた。

そもそもCHANGELOGは何のために必要なのか考えてみた。CHANGELOGは各バージョンの変更点をざっくり把握するためにあると思う。例えば、Railsの変更点を見たいと思ったとき、まず最初にCHANGELOGを見ると思う。いきなりPull requestやコミットログは見ないだろう。それらは各変更の実装や議論といった詳細を見るのに使われると思う。CHANGELOGは変更の詳細ではなく大まかな変更点の一覧を把握するために使われるんじゃないだろうか。

CHANGELOGを構成する要素はなんだろうか。まず、バージョンとそこに含まれる変更点が挙げられる。そして、変更点の詳細が載ったページへのリンクがあると便利だと思う。変更の種類によってグルーピングするとより見やすくなると思う。よく見かけるのはAdded, Changed, Fixed, Removed, Deprecatedなどといったラベルで変更点をわけている。リリース前の変更点についても書いておくと、今後の変更予定が分かって便利だと思う。

書き方としては、変更点を上から追記していくスタイルと、バージョンごとに書き換えるスタイルがあると思う。歴史の長いソフトウェアの場合、ひとつのファイルにそれらをすべて載せるのは見にくいので、後者のやり方が合うんじゃないかと思う。Railsなんかはこのスタイルだったと思う。

以上のようなことを踏まえて、このようなフォーマットに至った。

# Change Log

## Unreleased

### Added
* `changed(year:month:day:hour:minute:second:nanosecond:)`, which creates a `Date` instance by changing receiver's date components. [#77](https://github.com/naoty/Timepiece/pull/77)
* `changed(weekday:)`, which creates a `Date` instance by changing receiver's weekday. [#77](https://github.com/naoty/Timepiece/pull/77)

## 1.0.2
Released on 2016-12-20.

### Fixed
* Fix testDateInISO8601Format() availability. [#74](https://github.com/naoty/Timepiece/pull/74).
* Specify Swift version for the compilation of watchOS target. [#79](https://github.com/naoty/Timepiece/pull/79).

iOSアプリの開発でもCHANGELOGを書くようになった。CHANGELOGの読者としては、開発者自身もそうなんだけど、ベータ版を配信するテスターを主に想定している。ベータ版配信では、fastlaneからFabricを使って配信しているんだけど、その際にCHANGELOG.mdをパースしてリリースノートを自動生成するようにしている。このパーサーはrubygemとして公開している。