Theolizer  Version.1.2.0
serializer for C++ / Do you want to update your classes easily ?
1.mainpage.h
[詳解]
1 //############################################################################
2 /*!
3  @brief ドキュメント・ファイル－概要
4  @ingroup Documents
5  @file 1.mainpage.h
6  @author Yoshinori Tahara
7  @date 2015/08/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  @mainpage --目次--
39 
40  @subpage Abstract <br>
41  @par
42  @ref What <br>
43  @ref Platforms <br>
44  @ref Features <br>
45  @ref Mechanism <br>
46  @par ""
47 
48  @subpage Specification <br>
49  @par
50  @ref Basic <br>
51  @ref Tracking <br>
52  @ref Modifying <br>
53  @par ""
54 
55  @subpage Prepare <br>
56  @par
57  @ref Install <br>
58  @ref Uninstall <br>
59  @par ""
60 
61  @subpage HowToMakeProject <br>
62  @par
63  @ref Selecting <br>
64  @ref CMake <br>
65  @ref Example <br>
66  @ref NonCMake <br>
67  @ref FileStructure <br>
68  @par ""
69 
70  @subpage HowToBuildTheolizer <br>
71  @par
72  @ref HowToBuildLibrary <br>
73  @ref HowToBuildDriver <br>
74  @ref VersionNo <br>
75  @ref Documents <br>
76  @par ""
77 
78  @subpage UsageTotal <br>
79  @par
80  @ref Naming <br>
81  @ref BasicUsage <br>
82  @ref Serializers <br>
83  @ref TestProgram <br>
84  @par ""
85 
86  @subpage UsageIndividual <br>
87  @par
88  @ref BasicProcess <br>
89  @ref ClassVariation <br>
90  @ref EnumVariation <br>
91  @ref ObjectTracking <br>
92  @ref Destinations <br>
93  @ref SupportSTL <br>
94  @ref ChangingEnum <br>
95  @ref ChangingClass <br>
96  @ref ErrorReport <br>
97  @par ""
98 
99  @subpage ApiReference <br>
100  @par
101  @ref u8string <br>
102  @ref Unicode <br>
103  @ref Test <br>
104  @par ""
105 */
106 
107 /*!
108  @defgroup Documents Sources of documents
109  @defgroup TheolizerLib Theolizer Library(main)
110  @defgroup SerializationStl Serialization STL
111  @defgroup Unicode Unicode Helper
112  @defgroup RbFor Range-based-for Helper
113  @defgroup Test Test Tools
114 */
115 
116 /*!
117  @page Abstract 概要
118 
119 <br>
120 //############################################################################
121 @section What 1.Theolizerとは
122 //############################################################################
123 
124 ---
125 
126 Theolizerは[C++11](https://ja.wikipedia.org/wiki/C%2B%2B11)で記述されたC++用のシリアライザです。<br>
127 Theolizerを使うことで次のようなプログラムの開発が容易になります。
128 
129 - クラスや構造体等とその組合せで作れられた複雑なデータ構造を
130 - 「ファイルへ保存／回復」するプログラム
131 - 「通信回線で送受信」するプログラム
132 
133 また、C++をベターCとしてお使いの方にも使って頂けるよう設計しておりますのでお気軽にお試し下さい。
134 
135 <br>
136 //############################################################################
137 @section Platforms 2.対応環境
138 //############################################################################
139 
140 ---
141 
142 マルチ・プラットフォームでC++11規格コンパイラに対応できるよう設計しています。<br>
143 現時点でテストできている環境は下記の通りです。
144 
145 @subsection LastVersion 2-1.v1.1.3以降
146 |OS|C++コンパイラ|
147 |--------|--------|
148 |Windows 10 Professional 64bit|[Visual Studio C++ 2017](https://www.visualstudio.com/ja/downloads/) Community Version 15.2<br>[MinGW 7.1.0 32bit posix dwarf](https://sourceforge.net/projects/mingw-w64/)(mingw-w64-install.exe)<br>[MinGW 7.1.0 64bit posix seh](https://sourceforge.net/projects/mingw-w64/)(mingw-w64-install.exe)|
149 |ubuntu 16.04 LTS 64bit|gcc 5.4.0(Ubuntu 5.4.0-6ubuntu1~16.04.2)|
150 
151 将来的にOS X + apple-llvmに対応する準備を進めています。<br>
152 <br>
153 次に、ユーザ・プログラムをビルドする際に関連するツールは以下の通りです。<br>
154 
155 |その他のツール|バージョン|備考|
156 |--------------|----------|----|
157 |CMake|3.8.0以上|ユーザ・プログラムのビルドをアシストする際に用います<br>Theolizerのビルドに使用しています|
158 |boost|1.64.0以上|Theolizerの内部で使用しています|
159 
160 CMakeは必須ではありませんが、使用することを強く推奨します。<br>
161 あなたのプログラムでBoostを使っている場合、それがTheolizerで使っているものと異なるバージョンの時、注意が必要になります。「@ref Selecting 」を参照下さい。<br>
162 
163 なお、CMakeはバージョンによって認識可能なBoostのバージョンが異なります。調べた範囲では以下でした。Linuxではお使いになるBoostのバージョンに合わせて選択下さい。(WindowsではCMake 3.8.0以降のVisual Studio対応機能を用いますのでCMake 3.8.0以降のみ使用可能です。）
164 
165 |CMakeバージョン|Boostバージョン|
166 |---------------|---------------|
167 |3.8.0|1.64.0以下|
168 |3.7.2|1.63.0以下|
169 |3.7.1|1.62.0以下|
170 |3.6.0|1.61.0以下|
171 |3.5.1|1.61.0以下|
172 |3.5.0|1.61.0以下|
173 
174 @subsection OldVersion 2-2.v1.1.2以前
175 |OS|C++コンパイラ|
176 |--------|--------|
177 |Windows 10 Professional 64bit|[Visual Studio C++ 2015](https://www.microsoft.com/ja-jp/dev/products/visual-studio-2015.aspx) Community update 3<br>[MinGW 5.4.0 32bit posix dwarf](https://sourceforge.net/projects/mingw-w64/files/Toolchains%20targetting%20Win32/Personal%20Builds/mingw-builds/5.4.0/threads-posix/dwarf/i686-5.4.0-release-posix-dwarf-rt_v5-rev0.7z/download)<br>[MinGW 5.4.0 64bit posix seh](https://sourceforge.net/projects/mingw-w64/files/Toolchains%20targetting%20Win64/Personal%20Builds/mingw-builds/5.4.0/threads-posix/seh/x86_64-5.4.0-release-posix-seh-rt_v5-rev0.7z/download)|
178 |ubuntu 16.04 LTS 64bit|gcc 5.4.0(Ubuntu 5.4.0-6ubuntu1~16.04.2)|
179 
180 <br>
181 次に、ユーザ・プログラムをビルドする際に関連するツールは以下の通りです。<br>
182 
183 |その他のツール|バージョン|備考|
184 |--------------|----------|----|
185 |CMake|Visual C++は3.8.0以上<br>その他は3.5.0以上|ユーザ・プログラムのビルドをアシストする際に用います<br>Theolizerのビルドに使用しています|
186 |boost|1.59.0以上|Theolizerの内部で使用しています|
187 
188 <br>
189 //############################################################################
190 @section Features 3.Theolizerの特長
191 //############################################################################
192 
193 ---
194 
195 // ***************************************************************************
196 @subsection Features31 3-1.自動シリアライズ
197 // ***************************************************************************
198 C++は、クラスや構造体（以下、まとめてクラスと呼びます）に含まれるメンバのリストをプログラムがアクセスすることはできません。（メンバ1つ1つを名前を指定してアクセスすることはできますが、forループ等でメンバを次々と列挙することができないのです。）
199 ですので、クラスをシリアライズするためにはメンバのリストを、クラス定義とは別に改めて作成する必要がありました。<br>
200 Theolizerは[Clang/LLVM](http://llvm.org/)に含まれるlibTooling[libTooling](http://qiita.com/Chironian/items/6021d35bf2750341d80c)の構文解析機能を用いてクラス定義を解析し、メンバのリストを自動生成します。<br>
201 従って、クラス定義を変更した時もメンバ・リストへの反映漏れが無く、プログラム開発が捗ります。
202 
203 // ***************************************************************************
204 @subsection Features32 3-2.保存先指定
205 // ***************************************************************************
206 １つのクラスに属するメンバ変数を保存する時、複数の異なるファイルへ保存したい時もあると思います。一部のメンバ変数は設定ファイルへ保存し、また別のメンバはデータ・ファイルへ保存したいというケースは少なくないと思います。また、一部のメンバ変数（ファイル・ハンドル等）は保存しないことも多いでしょう。<br>
207 <br>
208 Theolizerはメンバ変数に保存先や保存の有無を指定することでクラスを分割して異なるファイルへ保存したり、一部を通信で他のプログラムへ送信したりすることができます。
209 
210 // ***************************************************************************
211 @subsection Features33 3-3.オブジェクト追跡
212 // ***************************************************************************
213 一般にポインタをファイルへ保存し、プログラムを再起動した後でそのポインタを回復しても意味はありません。ポイント先のメモリ・アドレスはプログラムの再起動前後で異なることが一般的だからです。<br>
214 <br>
215 Theolizerはポイント先のデータも一緒にファイルへ保存するのであればオブジェクト追跡によりポインタを有意味に回復することができます。もちろん通信時も同様です。<br>
216 また、ポイント先がクラスの場合、その各メンバに保存先指定することができますので全てを保存する必要はありません。<br>
217 これにより複雑なデータ構造を容易に保存／回復・送受信できます。<br>
218 オブジェクト追跡機能はboost::serializationを参考に開発しました。
219 
220 // ***************************************************************************
221 @subsection Features34 3-4.プログラム変更対応
222 // ***************************************************************************
223 シリアライザを使って保存するということは、内部データの構造を保ったままファイルへ保存するということです。内部データ構造はプログラムの変更に伴い変更されるため、旧プログラムで保存されたファイルを回復できるようにするためには内部データ構造の変更に強い制限がかかります。<br>
224 <br>
225 Theolizerはその制限を大幅に緩和し、古いプログラムで保存したデータを新しいプログラムで回復できます。<br>
226 更に、新しいプログラムで古いプログラムが読めるデータを保存するプログラムを開発することも可能です。<br>
227 <br>
228 クラス(class/struct)とenum型の定義を変更するに際して、2種類の変更対応方法を用意しています。
229 
230 1. <b>アップデート</b><br>
231 バージョン番号を変更しない方法です。
232 
233 2. <b>バージョン・アップ</b><br>
234 クラスやenum型に割り当てた（ローカル)バージョン番号を１つ上げて対応する方法です。
235 
236 それぞれ特徴があります。
237 
238 |方式|特徴|
239 |----|----|
240 |アップデート|1.変更が容易です。<br>2.自動生成するソース・コードが増えないためコンパイラへの負荷が軽いです。<br>3.古いデータを新しいプログラムで回復できますが、逆はサポートしていません。|
241 |バージョン・アップ|1.より大幅な変更に対応できます。<br>2.旧バージョン形式のデータを保存することができます。<br>3.変更作業は少し手間がかかります。<br>4.旧バージョンの変数リストやシンボル・リストを保持するため、<br>バージョン番号を上げる度に自動生成されるソース・コードが増えます。|
242 
243 可能な時はアップデートにて変更対応し、それでは不足の場合にバージョン・アップすることがお薦めです。<br>
244 <br>
245 まとめると次のような特長があります。
246 
247 1. <b>クラス定義、enum定義の変更（アップデート／バージョンアップ）</b><br>
248  - クラスのメンバ変数の追加／削除／順序変更に対応しています。<br>
249  - enum型のシンボルの追加／削除／定義順序変更に対応しています。<br>
250  また、シンボル名で保存／回復する時はシンボル値を、シンボル値保存の時はシンボル名を自由に変更できます。<br>
251 <br>
252 
253 2. <b>クラスについてバージョン・アップ／ダウン処理を記述できます</b><br>
254  - クラスをバージョン・アップする際に行いたい処理を記述できます。<br>
255 例えば、変数にオフセットを追加した時、そのオフセットを加える処理などです。<br>
256  - バージョン・ダウン処理を定義できます。<br>
257 例えば、オフセットを引く処理などです。<br>
258  - クラスは名前対応と順序対応を、enum型はシンボル名保存とシンボル値保存を切り替えることができます。<br>
259 開発当初は名前対応／シンボル名保存にて変更しやすくしておき、安定したら順序対応／シンボル値保存として効率アップすることが可能です。更に元へ戻すこともできます。<br>
260 <br>
261 
262 3. <b>バージョン・アップ／ダウンをカスケードに処理します</b><br>
263 例えば、Ver.4をVer.5へバージョンアップした時、従来はVer.4→Ver.5のプログラム開発だけでなく、Ver.1～Ver.3→Ver.4のプログラムをVer.1～Ver.3→Ver.5へ改造する必要がありました。Theolizerはバージョン・アップ／ダウン処理をカスケード(Ver.1→Ver.2→Ver.3→Ver.4→Ver.5)に行いますので、Ver.4→Ver.5のプログラムを開発するだけで済みます。<br>
264 これによりバージョンが上がった時のプログラム開発を大きく低減できます。(注)<br>
265 <br>
266 
267 4. <b>旧バージョン形式のデータを保存することができます</b><br>
268 保存したい形式のバージョン番号を指定することで、新しいバージョンのプログラムが古いバージョンのプログラムが保存する形式でデータ保存可能です。<br>
269 なお、指定された古いバージョンに複数のアップデートが含まれる場合は最後のアップデート版が保存されます。
270 
271 <div style="padding: 10px; margin-bottom: 10px; border: 1px solid #333333; border-radius: 10px; background-color: #d0d0d0;">
272 <b>（注）バージョン・アップ／ダウンにおける不可逆性に注意</b><br>
273 Theolizerのバージョン・ダウン機能は旧プログラムで回復可能なデータを保存することを目的としています。<br>
274 <br>
275 バージョン・アップする時はenum値や変数の追加を行うケースが多いですが、古い形式のデータを保存する時には、その追加されたデータを削除します。（古いバージョンのプログラムはその追加されたデータの存在を知らないため、もしも残すと古いプログラムが処理できなくなるためです。）
276 なので、新バージョン・プログラムが保存した<b>旧バージョン</b>・データを、再度新バージョン・プロクラムで回復した時、元のデータに戻ることを本質的に期待できません。<br>
277 </div>
278 
279 
280 
281 <br>
282 //############################################################################
283 @section Mechanism 4.Theolizerの仕組み
284 //############################################################################
285 
286 ---
287 　Theolizerはドライバとライブラリの２つで構成されています。
288 
289 | 項目 | 内容 |
290 |--------|--------|
291 |ドライバ|あなたのソースを解析して、シリアライズ処理に必要なコードを自動生成します。|
292 |ライブラリ|あなたのプログラムとリンクして、シリライズ処理を行います。|
293 
294 // ***************************************************************************
295 @subsection Mechanism41 4-1.ドライバ
296 // ***************************************************************************
297 <b>Theolizerドライバ</b>はあなたのビルド・プロジェクト（makeやVisual Studio）とコンパイラの間に割り込み、下記を自動的に行います。
298 
299 1. ビルド・プロジェクトの指示に従ってあなたのソース・コードを解析します。<br>
300 2. シリアライズ／デシリアライズ処理を行うために必要なソース・コード（主にクラス・メンバのリスト）を自動生成します。<br>
301 C++ソース・コードの解析には、[Clang/LLVM](http://llvm.org/)に含まれるlibToolingを用いて構文解析を行っています。
302 3. 通常のコンパイラとリンカがあなたのプログラムと自動生成されたソース・コードをビルドし、<b>Theolizerライブラリ</b>をリンクします。<br>
303 
304 <div style="padding: 10px; margin-bottom: 10px; border: 1px solid #333333; border-radius: 10px; background-color: #d0d0d0;">
305 <b>自動生成するソースのファイル名</b><br>
306 自動生成するソース・ファイル名は、コンパイルするソースファイル名.theolizer.hppです。
307 例えば、main.cppの場合、main.cpp.theolizer.hppとなります。
308 </div>
309 
310 // ***************************************************************************
311 @subsection Mechanism42 4-2.ライブラリ
312 // ***************************************************************************
313 <b>Theolizerライブラリ</b>はあなたのプログラムとリンクして、データ構造のシリアライズとデシリアライズを行います。
314 
315 // ***************************************************************************
316 @subsection Mechanism43 4-3.Theolizerドライバが割り込む仕組み
317 // ***************************************************************************
318 
319 ビルド・プロジェクトとコンパイラの間にTheolizerドライバを割り込む仕組みのポイントは次の３点です。
320 
321 1. ビルド・システムにTheolizerドライバをコンパイラとして起動させる
322 2. Theolizerドライバにソース自動生成が必要であることを伝達し、自動生成処理する
323 3. Theolizerドライバに元コンパイラのパスを伝達し、元のコンパイラへ処理を引き継ぐ
324 
325 @subsubsection Mechanism431 4-3-1. Theolizerドライバをコンパイラとして起動させる
326 
327 #### 4-3-1-1.Visual Studioの場合
328 
329 - Theolizerインストール時に準備<br>
330 Theolizerのインストール先フォルダにmsbuild-binフォルダを追加し、そこへTheolizerドライバをcl.exeとして保存します。
331 
332 - ビルド・プロジェクト生成
333 
334 CMake 3.8.0にて[VS_USER_PROPS](https://cmake.org/cmake/help/v3.8/prop_tgt/VS_USER_PROPS.html)と言うVC++のプロジェクトへインクルード指定を追加するプロパティが追加されました。<br>
335 これを使ってターゲットのプロジェクト・ファイル（*.vcxproj）に`<Import Project>`キーを追加し、theolizer.propsをインクルードするようにしました。<br>
336 そして、`theolizer.props`にて、コンパイル時に使われる`PATH`を指定する`<ExecutablePath>`の先頭に上記`msbuild-bin`フォルダを追加しました。<br>
337 
338 以上により、Theolizerを使用するプロジェクトにおいてTheolizerドライバがコンパイラとして起動します。
339 
340 #### 4-3-1-2.その他（gcc/mingw)の場合
341 対象のプロジェクトのCMAKE_CXX_COMPILERにTheolizerドライバのフルパスを設定しました。<br>
342 これはmakefileのコンパイラに反映されますので、呼び出すコンパイラを変更できます。<br>
343 （なお、Visual Studioはmakeではなくマイクロソフト独自のMSBuildでビルドするためこの方法が機能しません。）<br>
344 
345 @subsubsection Mechanism432 4-3-2.Theolizerドライバにソース自動生成が必要であることを伝達する
346 
347 CMakeで`THEOLIZER_DO_PROCESS`マクロをコンパイラ・オプションで定義するようにしまた。
348 このマクロがオプションで指定された時、Theolizerドライバはソース自動生成処理を行います。
349 そうでない時は、Theolizer関連オプションを除く全ての引数で元コンパイラを起動（パススルー）します。
350 
351 @subsubsection Mechanism433 4-3-3.Theolizerドライバに元コンパイラのパスを伝達する
352 
353 #### 4-3-3-1.Visual Studioの場合
354 CMakeは*.rspファイルに全てのオプションを記述してコンパイラへ渡します。その為、Theolizerドライバでそのオプションを削除して元コンパイラへ引き継ぐことが難しいです。しかし、削除しないとcl.exeが「知らないオプション」として警告します。
355 そこで、マクロ定義（`/Dtheolizer_original_compiler=<元コンパイラのパス>`）で伝達することで警告表示されないようにしました。マクロ定義はリンカへ伝達する必要がないので伝わらないようです。
356 
357 #### 4-3-3-2.その他（gcc/mingw)の場合
358 CMakeはgcc/mingw用にはコンパイルとリンクを分解してg++を呼び出します。
359 リンクの時ldを直接呼ぶわけでなく、g++にリンク指定して呼び出します。
360 どちらの場合もTheolizerドライバが起動されることになります。
361 そして、リンク動作時は`-D`オプションは渡ってきません。マクロ定義はコンパイラのみ必要なオプションだからだと思います。
362 しかし、その結果、リンク時に起動されたTheolizerドライバが元コンパイラのパスを得ることができず、元コンパイラをパススルー起動できません。
363 
364 そこで、msvc以外の時は`--theolizer_original_compiler=<元コンパイラのパス>`オプションで元コンパイラのパスを伝達するようにしました。
365 
366 @subsubsection Mechanism434 4-3-4. 使い方の変更について
367 上記はfind_packageで用いるTHEOLIZERConfig.cmake内部で対応しました。ですので、ユーザ・プログラム用のCMakeLists.txtは従来のままで使用できます。従来必要であったコンパイラのリプレース操作が不要になります。<br>
368 
369 なお、Visual Studioをお使いの場合は、CMakeを3.8.0以上へアップデートする必要があります。
370 
371 */