=pod
=encoding utf8
=head1 名前
Enbld::Tutorial - Enbldのチュートリアル
=head1 説明
このチュートリアルは、EnbldのDSLの文法を解説します。
=head1 DSLの文法
Enbldではソフトウェアのインストール条件を専用のDSLで定義します。ここでは、そのDSLの文法を解説します。
=head2 コンディションスクリプトの例
#!/usr/bin/perl
use strict;
use warnings;
use lib "$ENV{HOME}/.enbld/extlib/lib/perl5/";
use Enbld;
enbld 'mydevenv' => build {
target 'git' => define {
version 'latest';
};
};
=head2 基本的な構造
=over
=item * shebangにsystem perlを指定する
#!/usr/bin/perl
Enbldは必ずsystem perlから起動される必要があります。そのため、必ずshebangにはsystem perlへのパスを指定して下さい。
=item * 必ずuse strictと、use warningsを指定する
use strict;
use warnings;
モダンperlなスクリプトでは、必須です。
=item * libプラグラマでEnbldモジュールへのパスを指定する
use lib "$ENV{HOME}/.enbld/extlib/lib/perl5/";
Enbldモジュール(C<Enbld.pm>など)は、C<$HOME/.enbld/extlib/lib/perl5/>にインストールされるので、そのモジュールをロードできる様にlibプラグマでパスを指定します。
=item * Enbldモジュールをロードする
use Enbld;
Enbldモジュールは、DSLのメソッドをエクスポートします。
=back
=head2 ソフトウェアのインストールに使用する関数
以下にEnbldのDSLで使える関数を解説します。これらの関数は全てC<use Enbld>の時点でエクスポートされています。
EnbldのDSLはperlベースなので、ここに書かれていない事は全てperlの文法に従います。
=head3 enbld
enbld 'mydevenv' => build {
...
};
enbldは、ソフトウェアのインストールを行う関数です。
一つ目の引数は、環境の名前を指定します。文字列であれば何でもかまいません。
二つ目の引数は、build関数が返すコードリファレンスです。enbldは、ソフトウェアのビルド条件が書かれたコードリファレンスを実行することで、ソフトウェアをビルドします。
=head3 build
buildは、enbld関数が使うコードリファレンスを返すだけの関数です。
DSLとしての可読性を上げるための関数です :)
=head3 target
target 'git' => define {
....
};
targetは、ソフトウェアごとのインストール条件を定義する関数です。
一つ目の引数は、ソフトウェアの名前を指定します。ソフトウェアの名前は、C<enblder available>で表示される名前と一致させる必要があります。
二つ目の引数は、define関数が返すコードリファレンスです。targetは、ビルド条件が書かれたコードリファレンスを実行することで、ビルド条件を定義します。
=head3 define
defineは、target関数が使うコードリファレンスを返すだけの関数です。
DSLとしての可読性を上げるための存在です :)
=head3 version
target 'perl' => define {
version '5.18.1';
};
versionは、インストールしたいバージョン番号を指定する関数です。引数にバージョン番号を指定します。
インストールできるバージョンの一覧は、C<enblder available [ソフトウェア名]>で確認することができます。
なお、存在しないバージョン番号を指定すると、エラーになります。
target 'git' => define {
version 'latest';
};
また、バージョンに'latest'と指定すると、Enbldは自動的に最新バージョンを特定し、インストールします。自分で最新バージョンを探す必要は有りません。
target 'perl' => define {
version 'development';
};
加えて、一部のソフトウェアでは、開発中のバージョンを指定することができます。
例えば、perlでは、バージョンナンバーが偶数は、開発中を示しますが、'development'と指定することで、最新の開発バージョンをインストールすることができます。
詳しくは各Definitionモジュールのドキュメントを参照して下さい。
=head3 make_test
target 'git' => define {
version 'latest';
make_test 1;
};
make_testは、ビルド時にテストを実行するための関数です。
引数にperlで真となる値を指定すると(つまり、udnefと、0と空文字列以外)、ソフトウェアのビルド時にテストを実行します。
テストが失敗すると、ビルドも失敗します。
通常、この機能はオフになっています。
=head3 module_file
target 'perl' => define {
version 'latest';
module_file 'cpanfile';
};
module_fileは、プログラミング言語が用意するモジュールインストール機能を使ってモジュールをインストールしたい時に使う関数です。
例えば、perlでは、cpanmを呼び出し、cpanfileで指定されたモジュールをインストールします。
引数は各言語用のモジュール定義ファイルのパスを指定します(Perlならcpanfile)
詳しくは各Definitionモジュールのドキュメントを参照して下さい。
=head3 arguments
target 'perl' => define
version 'latest';
arguments '-Dusethreads';
};
argumentsは、各ソフトウェアの'configure'スクリプトへの引数を追加する関数です。
引数で指定した文字列がそのまま引き渡されます。
=head3 annotation
target 'perl' => define
version 'latest';
arguments '-Dusethreads';
annotation 'with thread support';
};
annotationは、注釈を追加する関数です。
単なるスクリプトのコメントと異なり、C<enblder freeze>でも再現されます。
=head2 設定ファイルを作成するための関数
conf '.vimrc' => load {
from 'https://raw.github.com/magnolia-k/vimrc/master/.vimrc';
};
Enbldは各ソフトウェアをビルドするだけでなく、各ソフトウェアの設定ファイル(DOTFILES)を作成するための機能も持ちます。
上記の例では、vim用の設定ファイル(.vimrc)をGitHubからダウンロードして、ホームディレクトリに配置します。
また、Enbldでは、インストールできるソフトウェアと、設定ファイルのファイル名の相関まではチェックしないので、どんな設定ファイルでも配置することができます。
=head3 conf
conf '.vimrc' => load {
...
};
confは、設定ファイルを作成するための関数です。
一つ目の引数は、設定ファイルのファイル名を指定します。
ディレクトリ名を付けて指定した時は、以下の様に解釈されます。
=over
=item * 相対パス
相対パスを指定すると、C<$HOME>からの相対パスとして設定ファイルを作成します。
例えば、C<.module-starter/config>と指定すると、設定ファイル「config」は、C<$HOME/.module-starter/config>に作成されます。
=item * 絶対パス
絶対パスを指定すると、そのパスに設定ファイルを作成します。
例えば、C</path/to/.module-starter/config>と指定すると、設定ファイル「config」は、C</path/to/.module-starter/config>に作成されます。
ただし、パーミッションには注意して下さい。
=back
なお、conf関数は、build関数の引数に指定されたコードリファレンスの中であれば、どこに記述してもかまいません。
enbld 'mydevenv' => build {
target 'vim' => define {
version 'latest';
conf '.vimrc' => load {
from 'https://raw.github.com/magnolia-k/vimrc/master/.vimrc';
}; # -> これもOK
};
conf '.bashrc' => set {
content 'export PATH=$HOME/.enbld/bin:PATH';
}; # -> これもOK
};
二つ目の引数は、設定ファイルをどこから取得するのか、指定する関数です。
=head3 load
conf '.vimrc' => load {
from 'https://raw.github.com/magnolia-k/vimrc/master/.vimrc';
};
設定ファイルをfrom関数の引数で指定したURLからダウンロードします。
引数はコードリファレンスです。
既に同じ内容のファイルが存在する場合は何もしません。ファイルが存在しても内容が異なる場合は、既存のファイルのファイル名を変更して、指定された通りにファイルを作成します。
=head3 set
conf '.bashrc' => set {
content 'export PATH=$HOME/.enbld/bin:PATH';
};
設定ファイルをcontent関数の引数で指定した内容で作成します。
引数はコードリファレンスです。
既に同じ内容のファイルが存在する場合は何もしません。ファイルが存在しても内容が異なる場合は、既存のファイルのファイル名を変更して、指定された通りにファイルを作成します。
=head3 copy
conf '.vimrc' => copy {
from '/path/to/.vimrc';
};
設定ファイルをfrom関数の引数で指定したファイルからコピーして作成します。
引数はコードリファレンスです。
既に同じ内容のファイルが存在する場合は何もしません。ファイルが存在しても内容が異なる場合は、既存のファイルのファイル名を変更して、指定された通りにファイルを配置します。
=head3 from
from関数は、設定ファイルの取得元を指定する関数です。
引数には、URLか、フルパスを指定します。
=head3 content
conf '.vimrc' => set {
content 'syntax on';
};
content関数は、設定ファイルの内容を指定する関数です。
conf '.wgetrc' => load {
from 'http://xxx.xxx.xxx/.wgetrc';
content 'proxy_user = user';
content 'proxy_passwd = PassWord';
}
ダウンロードしたファイルにcontent関数を使って、追記することもできます。
=head3 to
conf 'filerc' => set {
to "$ENV{HOME}/fileconfig";
content 'setting string';
};
to関数は、設定ファイルの配置先を指定する関数です。
conf関数の引数にファイル名だけを指定した時でも、to関数にディレクトリを指定することで、配置場所を自由に制御できます。
=head2 コンディションスクリプトのオプション指定
コンディションスクリプトは、いくつかのオプションを取ることができます。ここでは、そのオプションを解説します。
=head3 test
$ ./conditions.pl --test
$ ./conditions.pl -t
'test'オプションは、インストール時にテストを実行します。
=head3 force
$ ./conditions.pl --force
$ ./conditions.pl -f
'force'オプションは、インストール済のソフトウェアも含めて全て強制的にインストールします。
=head3 deploy
$ ./conditions.pl --deploy /path/to/install/
$ ./conditions.pl -d /path/to/install/
'deploy'オプションは、コンディションスクリプトで定義したスクリプトのインストール先を指定します。
デプロイパスは、相対パスか、絶対パスを指定できます。
ただし、'deploy'でインストールしたソフトウェアの新バージョンのリリースチェックはできません。
=head1 その他のトピック
=head2 '.enbld'ディレクトリの構成
'.enbld'ディレクトリは下記の様な構成になっています。
$HOME/.enbld --+
|
+-- bin/ 実行コマンド (シンボリックリンク)
|
+-- lib/ ライブラリ (シンボリックリンク)
|
+-- include/ インクルードファイル (シンボリックリンク)
|
+-- man/ マニュアルファイル (シンボリックリンク)
|
+-- share/ 共有ファイル (シンボリックリンク)
|
+-- extlib/ Enbldのモジュールファイル (例: lib/Enbld.pm)
|
+-- dists/ ダウンロードしたアーカイブファイル
|
+-- etc/ その他の色々なファイル
|
+-- build/ ソフトウェアのビルドディレクトリ
|
+-- depository/ インストールされたソフトウェアの構成ファイル
| |
| +-- Software A
| | |
| | +-- version 1
| | |
| | +-- version 2
| | |
| |
| +-- Software B
| | |
| | +-- version 1
| | |
|
+--conf/ Enbldの設定ファイル
|
+--log/ Enbldのログファイル
EnbldはソフトウェアをC<$HOME/.enbld/depository/[ソフトウェア名]/[バージョン]/>へインストールし、C<$HOME/.enbld/bin>や、C<$HOME/.enbld/lib>などのディレクトリへシンボリックリンクを作ります。
これにより、簡単に新しいバージョンへ切り替えることができるようになっています。
=head1 更なる情報
L<Enbld>
L<enblder>
=head1 ウェブサイト
L<https://github.com/magnolia-k/Enbld>
L<http://code-stylistics.net/enbld>
=head1 問題のレポート
L<https://github.com/magnolia-k/Enbld/issues>
=head1 コピーライト
copyright 2013- Magnolia C<< <magnolia.k@me.com> >>.
=head1 LICENSE
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.
=cut