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 で動いていたが

```ruby:Gemfile
source 'https://rubygems.org/'

gem 'embulk-filtr-column'
```

embulk >= 0.9.0 では

```ruby: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 を作る人は要注意。

https://github.com/embulk/embulk/blob/v0.9.0/embulk-core/src/main/resources/org/embulk/jruby/bundler/template/Gemfile#L6

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