embulk mkbundle または embulk bundle の使い方

embulk mkbundle および embulk run -b を使うと、embulk のプラグインを Gemfile/Gemfile.lock でバージョン管理できるようになる。その使い方。

[更新履歴]

2019/02/09

• embulk >= 0.9.0 で gem 'embulk' が必要になったので注記

2015/11/06

• mkbundle コマンドが生えたので記事を修正。v0.7.8 以降で有効
• https://github.com/embulk/embulk/pull/334
• https://github.com/embulk/embulk/pull/335

基本の使い方

１. embulk mkbundle すると、Gemfile やプラグインの雛形(gem にせずに読み込みたいプラグイン)が作られる

$ embulk mkbundle bundle_dir
  Creating bundle_dir/Gemfile
  Creating bundle_dir/.ruby-version
  Creating bundle_dir/.bundle/config
  Creating bundle_dir/embulk/input/example.rb
  Creating bundle_dir/embulk/output/example.rb
  Creating bundle_dir/embulk/filter/example.rb

Gemfile.lock を扱いたいだけであれば、手動でディレクトリ作って、Gemfile を置いてもよい。

２. Gemfile を更新した場合には、ディレクトリに移って、embulk bundle する。

$ cd bundle_dir
$ embulk bundle

３. Gemfile を参照してプラグインを読み込ませて、embulk を実行するには run の -b オプションを使用する。

$ embulk example example3
$ embulk run -b bundle_dir example3/example.yml

--path vendor/bundle

https://github.com/embulk/embulk/pull/335 で --path vendor/bundle にも対応されました。

１. embulk mkbundle で --path 指定する

$ embulk mkbundle bundle_dir --path ../shared/bundle # bundle_dir からの相対パス
  Creating bundle_dir/Gemfile
  Creating bundle_dir/.ruby-version
  Creating bundle_dir/.bundle/config
  Creating bundle_dir/embulk/input/example.rb
  Creating bundle_dir/embulk/output/example.rb
  Creating bundle_dir/embulk/filter/example.rb

.bundle/config をみると、BUNDLE_PATH が設定されているのがわかる

$ cat bundle_dir/.bundle/config
---
BUNDLE_PATH: "../shared/bundle"
BUNDLE_DISABLE_SHARED_GEMS: '1'

２. embulk bundle で --path 指定しても良い

$ cd bundle_dir
$ embulk bundle --path ../shared/bundle

３. 実行

-b オプションを指定して実行

$ embulk example example3
$ embulk run -b bundle_dir example3/example.yml

ヘルプ

embulk bundle -h では bundler のヘルプが出てしまうが、embulk mkbundle -h でそれっぽいヘルプが出る。

$ embulk mkbundle -h
Usage: mkbundle <directory> [--path PATH]
  Options:
        --path PATH                  Relative path from <directory> for the location to install gems to (e.g. --path shared/bundle).

  "mkbundle" creates a new a plugin bundle directory. You can install
  plugins (gems) to the directory instead of ~/.embulk.

  See generated <directory>/Gemfile to install plugins to the directory.
  Use -b, --bundle BUNDLE_DIR option to use it:

    $ embulk mkbundle ./dir                # create bundle directory
    $ (cd dir && vi Gemfile && embulk bundle)   # update plugin list
    $ embulk guess -b ./dir ...            # guess using bundled plugins
    $ embulk run   -b ./dir ...            # run using bundled plugins

注記

embulk bundle exec は動かない

embulk bundle exec などは動きそうにみえてしまうが動かないので run -b を使う（内部で BUNDLE_GEMFILE 環境変数がクリアされてしまう）

gem 'embulk' が必要 >= 0.9.0

embulk < 0.9.0 では以下のような Gemfile で動いていたが

Gemfile

source 'https://rubygems.org/'

gem 'embulk-filtr-column'

embulk >= 0.9.0 では

Gemfile

source 'https://rubygems.org/'

gem 'embulk'
gem 'embulk-filtr-column'

のように gem 'embulk' も含めないと embulk run -b した時に

Caused by: org.jruby.exceptions.RaiseException: (LoadError) no such file to load -- embulk/logger
        at org.jruby.RubyKernel.require(org/jruby/RubyKernel.java:955)
        at RUBY.<main>(<script>:1)

のようなエラーが出るようになった。embulk mkbundle したテンプレートにはちゃんと含まれているが、手で Gemfile を作る人は要注意。

FYI: ちなみにこの gem 'embulk' が指している embulk gem は rubygems.org においているものではなくて、embulk.jar (実行ファイル) に同梱されている embulk gem である。