Theolizer  Version.1.2.0
serializer for C++ / Do you want to update your classes easily ?
Theolizerのビルド手順

1.Theolizerライブラリのビルド方法

1-1.使用するツールとリンクするライブラリ

1-1-1.v1.1.3以降

アイテム条件検証済のアイテム
C++コンパイラC++11規格対応Visual Studio C++ 2017 Community Version 15.2
MinGW 7.1.0 32bit posix dwarf
MinGW 7.1.0 64bit posix seh
gcc 5.4.0(Ubuntu 5.4.0-6ubuntu1~16.04.2)
CMake3.8.0以上CMake 3.8.0 64bit
boost1.64.0以降boost 1.64.0

TheolzierのドキュメントはDoxygenとGraphvizを用いて生成します。現在は下記バージョンを用いています。

DoxygenGraphviz
1.8.122.38

1-1-2.v1.1.2以前

アイテム条件検証済のアイテム
C++コンパイラC++11規格対応Visual Studio C++ 2015 Community update 3
MinGW 5.4.0 32bit posix dwarf
MinGW 5.4.0 64bit posix seh
gcc 5.4.0(Ubuntu 5.4.0-6ubuntu1~16.04.2)
CMake3.5.0以上CMake 3.5.0 32bit
boost1.59.0以上boost 1.59.0

1-2.ビルド概要

TheolizerライブラリはBoostを使用しています。ヘッダオンリーではないsystem, filesystemをリンクします。そこで、Boostを公式からダウンロードしてこれらのライブラリをビルドする必要があります。

Theolizerのビルド・システムでは、便利のためにcmakeスクリプトを用意しています。そのcmakeスクリプトにて以下の処理を行います。

  1. 指定バージョンのBoostソース・コード一式をBoost公式からダウンロード
  2. Theolizerが必要とするBoostライブラリをビルド(数分で完了)
  3. Theolizerライブラリをビルド
  4. Theolizerライブラリの自動テスト実施
  5. (Theolizerドライドのビルド準備とビルドと自動テスト実施：次節で解説します。)
  6. Theolizer一式のインストール
  7. インストール出来ていることの自動テスト

1-3.ビルド用スクリプトの設定とビルド

cmakeスクリプトはTholizerソースのbuild_toolsフォルダにおいてます。Windowsでビルドする場合はwindows.cmakeを、linuxでビルドする場合linux.cmakeを用いて下さい。
設定内容は以下の通りです。(相対指定する時は、各cmakeスクリプトがあるフォルダが起点となります。）

設定先設定内容
THEOLIZER_SOURCETheolizerのソースがあるルート・フォルダ
THEOLIZER_BINARYビルド時の中間ファイル群を置くフォルダ
THEOLIZER_PREFIXTheolizerのインストール先ルート・フォルダ
BOOST_VERSION使用するBoostのバージョン番号
REQUIRE_CMAKE_VERSION必須CMakeバージョン
CC32MingWまたはgccの32ビット版のbinフォルダのパス(既にパスが通っているなら指定不要)
CC64MingWまたはgccの64ビット版のbinフォルダのパス(既にパスが通っているなら指定不要)
build_by_msvc()Visual Studio 2015でビルドする時にビルドする組み合わせを指定する
build_by_gcc()MinGWもしくはgccでビルドする時にビルドする組み合わせを指定する

build_by_msvc()とbuild_by_gcc()について補足

  • BUILD_DRIVERにTRUEを指定するとドライバをビルドします
    この時はLLVMの指定が必要です。
  • BUILD_DOCUMENTにTRUEを指定するとドキュメントをビルドします
    この時はDoxygenとGraphvizのインストールが必要になります。

下記のバッチ(Windowsの場合)、もしくは、スクリプト(linuxの場合)を起動することでTheolizerのビルド・自動テスト・インストールを行います。１組み合わせ当たり十数分でビルド完了します。

linuxのスクリプト
Windowsのバッチ		処理内容ログ・ファイル名
zy0_full_all.sh
zz0_full_all.bat 		ビルド・フォルダを削除し作成
CMakeによるプロジェクト生成
ライブラリのビルドとテスト
(ドライバのビルドとテスト)
ドキュメントのビルド
ライブラリとドキュメントのインストール
インストール後のビルド・テスト		z3_full_test-full_all.log
zy1_config_all.sh
zz1_config_all.bat 		ビルド・フォルダがなければ作成
CMakeによるプロジェクト生成		z0_config.log
zy2_middle_all.sh
zz2_middle_all.bat 		ビルド・フォルダがなければ作成
CMakeによるプロジェクト生成
ライブラリのビルドとテスト
(ドライバのビルドとテスト)
ドキュメントのビルド
Theolizerのインストール		z3_full_test-middle_all.log
zy3_last_all.sh
zz3_last_all.bat 		ビルド・フォルダがなければ作成
CMakeによるプロジェクト生成
インストール確認のためのビルド・テスト		z3_full_test-last_all.log

ビルド・フォルダに下記のバッチ(Windowsの場合)、もしくは、スクリプト(linuxの場合)が生成されます。必要に応じてお使い下さい。 また、Visual Studioの場合はソリューション・ファイル(Theolizer.sln)も生成されています。これをダブル・クリックすればVisual Studioが起動します。

linuxのスクリプト
Windowsのバッチ		処理内容ログ・ファイル名
zy0_config.sh
zz0_config.bat 		CMakeによるプロジェクト生成z0_config.log
zy1_short_test.sh
zz1_short_test.bat 		ライブラリのビルドとテストz1_short_test.log
zy2_long_test.sh
zz1_short_test.bat 		ドライバのビルドとテストz2_long_test.log
zy3_full_test.sh
zz3_full_test.bat 		ライブラリのビルドとテスト
ドライバのビルドとテスト
ドキュメントのビルド
Theolizerのインストール
インストール確認のためのビルド・テスト		z3_full_test-.log
zy4_ja.sh
zz4_ja.bat 		ドキュメントのビルドz4_ja.log


従来Windows版のログ・ファイルはShift-JISで出力していましたが、今回よりUTF-8へ変更しています。 詳しくはGitHub Issue #37を参照下さい。

1-4.Boostの処理について補足

BoostのダウンロードとビルドはTHEOLIZER_BINARY/${BOOST_VERSION}配下の次のフォルダで処理します。

フォルダ名説明
.Boostのソースをダウンロードする
sourceダウンロードしたソースを解凍する
${COMPLIER}x${BIT_NUM}Boostのビルド・フォルダ
install3232ビット版のインストール先
install6464ビット版のインストール先
install32-fPIC32ビットfPICオプション付き版のインストール先(linuxのみ)
install64-fPIC64ビットfPICオプション付き版のインストール先(linuxのみ)

なお、Boostを既にビルド／インストールしている場合は下記のオプションを指定することで、それを使用可能です。その場合、systemとfilesystemをビルドしてください。また、linuxの場合はfPICオプション付きのビルドも必要になります。

設定先設定内容
BOOST_INSTALLEDx32インストール済Boostのフォルダを指定する(32Bit)
BOOST_INSTALLEDx64インストール済Boostのフォルダを指定する(64Bit)
BOOST_INSTALLEDx32fPICインストール済Boostのフォルダを指定する(32Bit;fPICオプション付き)
BOOST_INSTALLEDx64fPICインストール済Boostのフォルダを指定する(64Bit;fPICオプション付き)


2.Theolizerドライバのビルド方法

2-1.使用するツールとリンクするライブラリ

「1-1.使用するツールとリンクするライブラリ」に加えて下記が必要です。

アイテム条件検証済のアイテム
LLVM4.0.0LLVM 4.0.0
C++コンパイラC++11規格対応Visual Studio C++ 2015 Community update 3

LLVM 4.0.0はVisual C++ 2017ではビルドできません。代わりにVisual C++ 2015でビルドします。2015と2017はバイナリ互換性がありますので、バージョン相違による問題は発生しない筈です。

注）LLVM 3.8.0, 3.8.1, 3.9.0でもビルドできるよう対応していますが、Theolizer最新版でのテストは行っていません。

2-2.ビルド概要

TheolizerドライバはllvmのlibToolingを用いていますので、ビルドされたlibToolingライブラリが必要になります。

  • Windowsについて
    Theolizer用にプリビルドしたlibToolingをbuild_libToolingで提供しています。Theolizerで用いるlibToolingライブラリだけを抽出しています。Theolizerドライバをビルドする時はこれをビルド用cmakeスクリプトにより自動的にダウンロードして使用します。
  • Linuxについて
    ubuntu等linux用にはllvm公式にてAPTパッケージが提供されています。これらをインストールしてお使い下さい。

ubuntu 16.04へllvmをインストールする手順は次の通りです。
システム設定→ソフトウェアとアップデート→「他のソフトウェア」タブを開いて→「追加」ボタンを押し、次の内容を入力し、「ソースを追加」ボタンを押下して、APTリポジトリをubuntuへ登録して下さい。 deb http://apt.llvm.org/xenial/ llvm-toolchain-xenial-4.0 main

その後、下記コマンドで/usr/lib/llvm-4.0/へインストールされます。

$ sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys 15CF4D18AF4F7421
$ sudo apt-get update
$ sudo apt-get install libclang-4.0-dev
$ sudo apt-get install llvm-4.0-dev

2-3.ビルド用スクリプトの設定とビルド

camkeスクリプトはTheolizerライブラリのビルドに用いたもの(1-3.ビルド用スクリプトの設定とビルド)を用います。

設定先設定内容
LLVM_VERSION使用するlvmのバージョン番号
LLVMllvmのダウンロード先パス(ダウンロードする時のみ指定)
LLVM_ROOTインストール済llvmのパス(ダウンロードしない時のみ指定)
LLVM_DOWNLOADllvmのダウンロード元URL
LLVM_MSVCbuild_libToolingからダウンロードするllvmをビルドしたmsvcのバージョン
LLVM_CCbuild_libToolingからダウンロードするllvmをビルドしたMinGWのバージョン


3.Theolizer自身のバージョン番号について

3-1.バージョン番号の付け方

バージョン番号を下記のように付けて管理します。

<Major>.<Minor>.<Detail>
<Major>.<Minor>.<Detail>-Prerelease

項目更新するタイミング
Major仕様や実装を大幅に追加／変更する時
Minor仕様変更する時
Detailバグ・フィックス、自動テスト等の周辺機能、ドキュメントを修正した時
-Prerease暫定的な正規リリース前のバージョンに付加する
正規リリース後のPrereaseはバージョン番号を上げて行う

3-2.コミットの管理

コミットの度にバージョン番号を上げるわけではないため、GitHubには同じバージョン番号のものが複数登録されることになります。
それを判別できるようにするため、TheolizerドライバとTheolizerライブラリのそれぞれがversion.hを持ち、これにソース・コードのMD5ハッシュ値（kTheolizerSourcesHash）を記録しています。
この値はそれぞれをビルドする際に自動的に更新されます。（linuxタイプの改行コードへ変換後、計算していますので、改行コードの異なるOSで処理しても同じ値になります。）

項目生成元ファイル群
Theolzierドライバライブラリとドライバのソース、および、CMakeLists.txt
TheolzierライブラリライブラリのソースとCMakeLists.txt

Theolizerバイナリから下記方法でkTheolizerSourcesHashを得ることができます。

項目方法
TheolzierドライバTheolizerDriver –theolizer-versionにて表示されるSourcesHash
Theolzierライブラリtheolizer::getVersionString()にて得ることができるSourcesHash


gitのコミット・ハッシュ値を用いて管理する方法も検討したのですが、Theolizerバイナリ生成後にコミットする手順にしたかったため、このような仕組みにしています。


3-3.gitのフックについて

２つフックしています。

3-3-1.commit-msgフック

これにより、上述のSourcesHash値を下記のフォーマットでコミット・メッセージへ自動追加しています。
以上の仕組みによりSourcesHash値がGitHubに登録されている時にはソース・コードを特定できます。

----------------- MD5 Hash Values -----------------
TheolizerDriver : ce745e6dc35b70e87674e1daac64b739
TheolizerLibrary : 3de4f1e42c55188f88ececb53e88fc49
Library's Header : 97197bb96f6980c19c222542c8d89d54

なお、コミット・メッセージを修正するような場合（最後のコミットをやり直すなど）は、これらをコミット・メッセージから手動で削除して下さい。

3-3-2.pre-commitフック

コミット操作した時、pre-commitフックにより、ソースのハッシュ値を計算し、ビルド時のソース・ハッシュ値と比較して、不一致ならコミットできないようにしています。
これにより、コミット・メッセージに登録されるハッシュ値が操作ミスで不適切になることはない筈です。

3-3-3.gitフックのインストールはコンフィグ時に自動インストール

CMakeの機能を使ってコンフィグ時に.git/hooksへインストールしています。


4.ドキュメントについて補足

ドキュメントの生成にDoxygenとGraphvizを用いています。 現在使っているバージョンは以下の通りです。

項目バージョン(Windows)バージョン(Ubuntu)
Doxygen1.8.121.8.11
Graphviz2.38.02.38.0

Theolizerのドキュメントは、主にsource/reference_and_test/jaフォルダにおいています。
また、ライブラリのソース・コードはsource/libraryですが、ユーザが直接使うことを想定しているもののみドキュメントを付けています。

名前空間 internal 内のクラス等 全ての要素、および、THEOLIZER_INTERNAL もしくは THEOLIZER_GENERATEDで始まるマクロは全てTheolizer内部用です。
Theolizerのアップデート時、上位互換性を考慮しませんので使用しないようお願いします。