Theolizer  Version.1.2.0
serializer for C++ / Do you want to update your classes easily ?
5.build_theolizer.h
[詳解]
1 //############################################################################
2 /*!
3  @brief ドキュメント・ファイル－Theolizerのビルド手順
4  @ingroup Documents
5  @file 5.build_theolizer.h
6  @author Yoshinori Tahara
7  @date 2016/11/01 Created
8 */
9 /*
10  © 2016 Theoride Technology (http://theolizer.com/) All Rights Reserved.
11  "Theolizer" is a registered trademark of Theoride Technology.
12 
13  "Theolizer" License
14  In the case where you are in possession of a valid “Theolizer” License,
15  you may use this file in accordance with the terms and conditions of
16  the use license determined by Theoride Technology.
17 
18  General Public License Version 3 ("GPLv3")
19  You may use this file in accordance with the terms and conditions of
20  GPLv3 published by Free Software Foundation.
21  Please confirm the contents of GPLv3 at https://www.gnu.org/licenses/gpl.txt .
22  A copy of GPLv3 is also saved in a LICENSE.TXT file.
23 
24  商用ライセンス
25  あなたが有効なTheolizer商用ライセンスを保持している場合、
26  セオライド テクノロジーの定める使用許諾書の条件に従って、
27  このファイルを取り扱うことができます。
28 
29  General Public License Version 3(以下GPLv3)
30  Free Software Foundationが公表するGPLv3の使用条件に従って、
31  あなたはこのファイルを取り扱うことができます。
32  GPLv3の内容を https://www.gnu.org/licenses/gpl.txt にて確認して下さい。
33  またGPLv3のコピーをLICENSE.TXTファイルにおいてます。
34 */
35 //############################################################################
36 
37 /*!
38  @page HowToBuildTheolizer Theolizerのビルド手順
39 
40 @section HowToBuildLibrary 1.Theolizerライブラリのビルド方法
41 
42 ---
43 
44 @subsection HowToBuildLibrary11 1-1.使用するツールとリンクするライブラリ
45 @subsubsection HowToBuildLibrary111 1-1-1.v1.1.3以降
46 
47 |アイテム|条件|検証済のアイテム|
48 |-----|----|-----|
49 |C++コンパイラ|C++11規格対応|[Visual Studio C++ 2017 Community Version 15.2](https://www.microsoft.com/ja-jp/dev)|
50 |||[MinGW 7.1.0 32bit posix dwarf](https://sourceforge.net/projects/mingw-w64/files/Toolchains%20targetting%20Win32/Personal%20Builds/mingw-builds/7.1.0/threads-posix/dwarf/i686-7.1.0-release-posix-dwarf-rt_v5-rev0.7z/download)|
51 |||[MinGW 7.1.0 64bit posix seh](https://sourceforge.net/projects/mingw-w64/files/Toolchains%20targetting%20Win64/Personal%20Builds/mingw-builds/7.1.0/threads-posix/seh/x86_64-7.1.0-release-posix-seh-rt_v5-rev0.7z/download)|
52 |||gcc 5.4.0(Ubuntu 5.4.0-6ubuntu1~16.04.2)|
53 |CMake|3.8.0以上|[CMake 3.8.0 64bit](https://cmake.org/)|
54 |boost|1.64.0以降|[boost 1.64.0](http://www.boost.org/)|
55 
56 TheolzierのドキュメントはDoxygenとGraphvizを用いて生成します。現在は下記バージョンを用いています。
57 
58 |Doxygen|Graphviz|
59 |-------|--------|
60 |[1.8.12](http://www.stack.nl/~dimitri/doxygen/download.html)|[2.38](http://www.graphviz.org/Download..php)
61 
62 @subsubsection HowToBuildLibrary112 1-1-2.v1.1.2以前
63 
64 |アイテム|条件|検証済のアイテム|
65 |-----|----|-----|
66 |C++コンパイラ|C++11規格対応|[Visual Studio C++ 2015 Community update 3](https://www.microsoft.com/ja-jp/dev)|
67 |||[MinGW 5.4.0 32bit posix dwarf](https://sourceforge.net/projects/mingw-w64/)|
68 |||[MinGW 5.4.0 64bit posix seh](https://sourceforge.net/projects/mingw-w64/)|
69 |||gcc 5.4.0(Ubuntu 5.4.0-6ubuntu1~16.04.2)|
70 |CMake|3.5.0以上|[CMake 3.5.0 32bit](https://cmake.org/)|
71 |boost|1.59.0以上|[boost 1.59.0](http://www.boost.org/)|
72 
73 @subsection HowToBuildLibrary12 1-2.ビルド概要
74 TheolizerライブラリはBoostを使用しています。ヘッダオンリーではないsystem, filesystemをリンクします。そこで、Boostを[公式](http://www.boost.org/)からダウンロードしてこれらのライブラリをビルドする必要があります。<br>
75 <br>
76 Theolizerのビルド・システムでは、便利のためにcmakeスクリプトを用意しています。そのcmakeスクリプトにて以下の処理を行います。<br>
77 
78 1. 指定バージョンのBoostソース・コード一式をBoost公式からダウンロード
79 2. Theolizerが必要とするBoostライブラリをビルド(数分で完了)
80 3. Theolizerライブラリをビルド
81 4. Theolizerライブラリの自動テスト実施
82 5. (Theolizerドライドのビルド準備とビルドと自動テスト実施：次節で解説します。)
83 6. Theolizer一式のインストール
84 7. インストール出来ていることの自動テスト
85 
86 @subsection HowToBuildLibrary13 1-3.ビルド用スクリプトの設定とビルド
87 cmakeスクリプトはTholizerソースのbuild_toolsフォルダにおいてます。Windowsでビルドする場合はwindows.cmakeを、linuxでビルドする場合linux.cmakeを用いて下さい。<br>
88 設定内容は以下の通りです。(相対指定する時は、各cmakeスクリプトがあるフォルダが起点となります。）
89 
90 |設定先|設定内容|
91 |------|--------|
92 |THEOLIZER_SOURCE|Theolizerのソースがあるルート・フォルダ|
93 |THEOLIZER_BINARY|ビルド時の中間ファイル群を置くフォルダ|
94 |THEOLIZER_PREFIX|Theolizerのインストール先ルート・フォルダ|
95 |BOOST_VERSION|使用するBoostのバージョン番号|
96 |REQUIRE_CMAKE_VERSION|必須CMakeバージョン|
97 |CC32|MingWまたはgccの32ビット版のbinフォルダのパス(既にパスが通っているなら指定不要)|
98 |CC64|MingWまたはgccの64ビット版のbinフォルダのパス(既にパスが通っているなら指定不要)|
99 |build_by_msvc()|Visual Studio 2015でビルドする時にビルドする組み合わせを指定する|
100 |build_by_gcc()|MinGWもしくはgccでビルドする時にビルドする組み合わせを指定する|
101 
102 <b>build_by_msvc()とbuild_by_gcc()について補足</b><br>
103 - BUILD_DRIVERにTRUEを指定するとドライバをビルドします<br>
104 この時はLLVMの指定が必要です。
105 - BUILD_DOCUMENTにTRUEを指定するとドキュメントをビルドします<br>
106 この時は[Doxygen](http://www.doxygen.jp/)と[Graphviz](http://www.graphviz.org/)のインストールが必要になります。
107 
108 下記のバッチ(Windowsの場合)、もしくは、スクリプト(linuxの場合)を起動することでTheolizerのビルド・自動テスト・インストールを行います。１組み合わせ当たり十数分でビルド完了します。
109 
110 |linuxのスクリプト<br>Windowsのバッチ|処理内容|ログ・ファイル名|
111 |------------------------------------|--------|----------------|
112 |zy0_full_all.sh<br>zz0_full_all.bat |ビルド・フォルダを削除し作成<br>CMakeによるプロジェクト生成<br>ライブラリのビルドとテスト<br>(ドライバのビルドとテスト)<br>ドキュメントのビルド<br>ライブラリとドキュメントのインストール<br>インストール後のビルド・テスト|z3_full_test-full_all.log |
113 |zy1_config_all.sh<br>zz1_config_all.bat |ビルド・フォルダがなければ作成<br><b>CMakeによるプロジェクト生成</b>|z0_config.log |
114 |zy2_middle_all.sh<br>zz2_middle_all.bat |ビルド・フォルダがなければ作成<br>CMakeによるプロジェクト生成<br><b>ライブラリのビルドとテスト</b><br><b>(ドライバのビルドとテスト)</b><br>ドキュメントのビルド<br><b>Theolizerのインストール</b>|z3_full_test-middle_all.log |
115 |zy3_last_all.sh<br>zz3_last_all.bat |ビルド・フォルダがなければ作成<br>CMakeによるプロジェクト生成<br><b>インストール確認のためのビルド・テスト</b>|z3_full_test-last_all.log |
116 
117 ビルド・フォルダに下記のバッチ(Windowsの場合)、もしくは、スクリプト(linuxの場合)が生成されます。必要に応じてお使い下さい。
118 また、Visual Studioの場合はソリューション・ファイル(Theolizer.sln)も生成されています。これをダブル・クリックすればVisual Studioが起動します。
119 
120 |linuxのスクリプト<br>Windowsのバッチ|処理内容|ログ・ファイル名|
121 |------------------------------------|--------|----------------|
122 |zy0_config.sh<br>zz0_config.bat |CMakeによるプロジェクト生成|z0_config.log |
123 |zy1_short_test.sh<br>zz1_short_test.bat |ライブラリのビルドとテスト|z1_short_test.log |
124 |zy2_long_test.sh<br>zz1_short_test.bat |ドライバのビルドとテスト|z2_long_test.log |
125 |zy3_full_test.sh<br>zz3_full_test.bat |ライブラリのビルドとテスト<br>ドライバのビルドとテスト<br>ドキュメントのビルド<br>Theolizerのインストール<br>インストール確認のためのビルド・テスト|z3_full_test-.log |
126 |zy4_ja.sh<br>zz4_ja.bat |ドキュメントのビルド|z4_ja.log |
127 <br>
128 
129 <div style="padding: 10px; margin-bottom: 10px; border: 1px solid #333333; border-radius: 10px; background-color: #d0d0d0;">
130 従来Windows版のログ・ファイルはShift-JISで出力していましたが、今回よりUTF-8へ変更しています。
131 詳しくは[GitHub Issue #37](https://github.com/yossi-tahara/Theolizer/issues/37#issuecomment-309667431)を参照下さい。
132 </div>
133 
134 @subsection HowToBuildLibrary14 1-4.Boostの処理について補足
135 BoostのダウンロードとビルドはTHEOLIZER_BINARY/${BOOST_VERSION}配下の次のフォルダで処理します。
136 
137 |フォルダ名|説明|
138 |----------|----|
139 |.|Boostのソースをダウンロードする|
140 |source|ダウンロードしたソースを解凍する|
141 |${COMPLIER}x${BIT_NUM}|Boostのビルド・フォルダ|
142 |install32|32ビット版のインストール先|
143 |install64|64ビット版のインストール先|
144 |install32-fPIC|32ビットfPICオプション付き版のインストール先(linuxのみ)|
145 |install64-fPIC|64ビットfPICオプション付き版のインストール先(linuxのみ)|
146 
147 なお、Boostを既にビルド／インストールしている場合は下記のオプションを指定することで、それを使用可能です。その場合、systemとfilesystemをビルドしてください。また、linuxの場合はfPICオプション付きのビルドも必要になります。
148 
149 |設定先|設定内容|
150 |------|--------|
151 |BOOST_INSTALLEDx32|インストール済Boostのフォルダを指定する(32Bit)|
152 |BOOST_INSTALLEDx64|インストール済Boostのフォルダを指定する(64Bit)|
153 |BOOST_INSTALLEDx32fPIC|インストール済Boostのフォルダを指定する(32Bit;fPICオプション付き)|
154 |BOOST_INSTALLEDx64fPIC|インストール済Boostのフォルダを指定する(64Bit;fPICオプション付き)|
155 
156 <br>
157 @section HowToBuildDriver 2.Theolizerドライバのビルド方法
158 
159 ---
160 
161 @subsection HowToBuildLibrary21 2-1.使用するツールとリンクするライブラリ
162 「1-1.使用するツールとリンクするライブラリ」に加えて下記が必要です。
163 
164 |アイテム|条件|検証済のアイテム|
165 |-----|----|-----|
166 |LLVM|4.0.0|[LLVM 4.0.0](http://llvm.org/)|
167 |C++コンパイラ|C++11規格対応|[Visual Studio C++ 2015 Community update 3](https://www.microsoft.com/ja-jp/dev)|
168 
169 LLVM 4.0.0はVisual C++ 2017ではビルドできません。代わりにVisual C++ 2015でビルドします。[2015と2017はバイナリ互換性があります](https://stackoverflow.com/questions/40854917/is-visual-c-2017-binary-compatible-with-vc-2015)ので、バージョン相違による問題は発生しない筈です。<br>
170 <br>
171 注）LLVM 3.8.0, 3.8.1, 3.9.0でもビルドできるよう対応していますが、Theolizer最新版でのテストは行っていません。
172 
173 @subsection HowToBuildLibrary22 2-2.ビルド概要
174 Theolizerドライバはllvmの[libTooling](http://qiita.com/Chironian/items/6021d35bf2750341d80c)を用いていますので、ビルドされたlibToolingライブラリが必要になります。
175 
176 - Windowsについて<br>
177 Theolizer用にプリビルドしたlibToolingを[build_libTooling](https://github.com/yossi-tahara/build_libTooling)で提供しています。Theolizerで用いるlibToolingライブラリだけを抽出しています。Theolizerドライバをビルドする時はこれをビルド用cmakeスクリプトにより自動的にダウンロードして使用します。
178 
179 - Linuxについて<br>
180 ubuntu等linux用にはllvm公式にて[APTパッケージ](https://apt.llvm.org/)が提供されています。これらをインストールしてお使い下さい。
181 
182 <b>ubuntu 16.04へllvmをインストールする手順は次の通りです。</b><br>
183 システム設定→ソフトウェアとアップデート→「他のソフトウェア」タブを開いて→「追加」ボタンを押し、次の内容を入力し、「ソースを追加」ボタンを押下して、APTリポジトリをubuntuへ登録して下さい。
184  deb http://apt.llvm.org/xenial/ llvm-toolchain-xenial-4.0 main
185 
186 その後、下記コマンドで/usr/lib/llvm-4.0/へインストールされます。
187 
188 @code
189 $ sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys 15CF4D18AF4F7421
190 $ sudo apt-get update
191 $ sudo apt-get install libclang-4.0-dev
192 $ sudo apt-get install llvm-4.0-dev
193 @endcode
194 
195 @subsection HowToBuildLibrary23 2-3.ビルド用スクリプトの設定とビルド
196 camkeスクリプトはTheolizerライブラリのビルドに用いたもの(@ref HowToBuildLibrary13)を用います。
197 
198 |設定先|設定内容|
199 |------|--------|
200 |LLVM_VERSION|使用するlvmのバージョン番号|
201 |LLVM|llvmのダウンロード先パス(ダウンロードする時のみ指定)|
202 |LLVM_ROOT|インストール済llvmのパス(ダウンロードしない時のみ指定)|
203 |LLVM_DOWNLOAD|llvmのダウンロード元URL|
204 |LLVM_MSVC|build_libToolingからダウンロードするllvmをビルドしたmsvcのバージョン|
205 |LLVM_CC|build_libToolingからダウンロードするllvmをビルドしたMinGWのバージョン|
206 
207 <br>
208 @section VersionNo 3.Theolizer自身のバージョン番号について
209 
210 @subsection VersionManagement 3-1.バージョン番号の付け方
211 バージョン番号を下記のように付けて管理します。
212 
213 `<Major>.<Minor>.<Detail>`<br>
214 `<Major>.<Minor>.<Detail>-Prerelease`<br>
215 
216 |項目|更新するタイミング|
217 |----|------------------|
218 |Major|仕様や実装を大幅に追加／変更する時|
219 |Minor|仕様変更する時|
220 |Detail|バグ・フィックス、自動テスト等の周辺機能、ドキュメントを修正した時|
221 |-Prerease|暫定的な正規リリース前のバージョンに付加する<br>正規リリース後のPrereaseはバージョン番号を上げて行う|
222 
223 @subsection NonVersionNo 3-2.コミットの管理
224 コミットの度にバージョン番号を上げるわけではないため、GitHubには同じバージョン番号のものが複数登録されることになります。<br>
225 それを判別できるようにするため、TheolizerドライバとTheolizerライブラリのそれぞれがversion.hを持ち、これにソース・コードのMD5ハッシュ値（kTheolizerSourcesHash）を記録しています。<br>
226 この値はそれぞれをビルドする際に自動的に更新されます。（linuxタイプの改行コードへ変換後、計算していますので、改行コードの異なるOSで処理しても同じ値になります。）
227 
228 |項目|生成元ファイル群|
229 |----|----------------|
230 |Theolzierドライバ|ライブラリとドライバのソース、および、CMakeLists.txt|
231 |Theolzierライブラリ|ライブラリのソースとCMakeLists.txt|
232 
233 Theolizerバイナリから下記方法でkTheolizerSourcesHashを得ることができます。
234 
235 |項目|方法|
236 |----|----|
237 |Theolzierドライバ|TheolizerDriver --theolizer-versionにて表示されるSourcesHash|
238 |Theolzierライブラリ|theolizer::getVersionString()にて得ることができるSourcesHash|
239 <br>
240 <div style="padding: 10px; margin-bottom: 10px; border: 1px solid #333333; border-radius: 10px; background-color: #d0d0d0;">
241 gitのコミット・ハッシュ値を用いて管理する方法も検討したのですが、Theolizerバイナリ生成後にコミットする手順にしたかったため、このような仕組みにしています。
242 </div>
243 
244 <br>
245 @subsection GitHooks 3-3.gitのフックについて
246 ２つフックしています。
247 
248 @subsubsection commit-msg 3-3-1.commit-msgフック
249 これにより、上述のSourcesHash値を下記のフォーマットでコミット・メッセージへ自動追加しています。<br>
250 以上の仕組みによりSourcesHash値がGitHubに登録されている時にはソース・コードを特定できます。
251 
252 @code
253 ----------------- MD5 Hash Values -----------------
254 TheolizerDriver : ce745e6dc35b70e87674e1daac64b739
255 TheolizerLibrary : 3de4f1e42c55188f88ececb53e88fc49
256 Library's Header : 97197bb96f6980c19c222542c8d89d54
257 @endcode
258 
259 なお、コミット・メッセージを修正するような場合（最後のコミットをやり直すなど）は、これらをコミット・メッセージから手動で削除して下さい。
260 
261 @subsubsection pre-commit 3-3-2.pre-commitフック
262 コミット操作した時、pre-commitフックにより、ソースのハッシュ値を計算し、ビルド時のソース・ハッシュ値と比較して、不一致ならコミットできないようにしています。<br>
263 これにより、コミット・メッセージに登録されるハッシュ値が操作ミスで不適切になることはない筈です。
264 
265 @subsubsection InstallHooks 3-3-3.gitフックのインストールはコンフィグ時に自動インストール
266 CMakeの機能を使ってコンフィグ時に.git/hooksへインストールしています。
267 
268 <br>
269 @section Documents 4.ドキュメントについて補足
270 
271 ---
272 
273 ドキュメントの生成に[Doxygen](http://www.stack.nl/~dimitri/doxygen/)と[Graphviz](http://www.graphviz.org/)を用いています。
274 現在使っているバージョンは以下の通りです。
275 
276 |項目|バージョン(Windows)|バージョン(Ubuntu)|
277 |----|-------------------|------------------|
278 |Doxygen|1.8.12|1.8.11|
279 |Graphviz|2.38.0|2.38.0|
280 
281 Theolizerのドキュメントは、主にsource/reference_and_test/jaフォルダにおいています。<br>
282 また、ライブラリのソース・コードはsource/libraryですが、ユーザが直接使うことを想定しているもののみドキュメントを付けています。<br>
283 
284 名前空間 <b>internal</b> 内のクラス等 全ての要素、および、<b>THEOLIZER_INTERNAL</b> もしくは <b>THEOLIZER_GENERATED</b>で始まるマクロは全てTheolizer内部用です。<br>
285 Theolizerのアップデート時、上位互換性を考慮しませんので使用しないようお願いします。
286 
287 */