あなたのプロジェクトが外部ライブラリやツールに依存している場合、Doxygenを実行するたびにそれらのすべてのソースを含めない方が良い理由がいくつかあります。

ディスク容量

一部のドキュメントは、Doxygenの出力ディレクトリの外部、例えばウェブ上のどこかで既に利用可能かもしれません。ローカルの出力ディレクトリにドキュメントを生成する代わりに、これらのページにリンクしたい場合があるでしょう。

処理速度

外部プロジェクトは通常、あなたのプロジェクトとは異なる更新頻度を持っています。何も変更がないにもかかわらず、Doxygenにこれらの外部プロジェクトのソースを何度も解析させるのは、あまり意味がありません。

メモリ

非常に大規模なソースツリーの場合、Doxygenにすべてのソースを解析させると、システムメモリを過度に消費する可能性があります。ソースをいくつかの「パッケージ」に分割することで、1つのパッケージのソースをDoxygenが解析し、そのパッケージが依存する他のすべてのパッケージは外部からリンクされるようにできます。これにより、大幅なメモリ節約になります。

利用可能性

Doxygenでドキュメント化されている一部のプロジェクトでは、ソースが利用できない場合があります。

著作権の問題

もし外部パッケージとそのドキュメントが他者の著作物である場合、プロジェクトのドキュメントにコピーを含めるよりも、それを参照する方が良い、あるいは必要となる場合があります。著作者が再配布を禁じている場合は、これが必須です。著作者が再配布の前提条件として何らかのライセンス条件への準拠を要求し、その条件に拘束されたくない場合、彼らのドキュメントのコピーを参照する方が、コピーを含めるよりも望ましいです。

上記のいずれかに該当する場合、Doxygenのタグファイルメカニズムを使用できます。タグファイルは基本的に、外部ソースで見つかったエンティティのコンパクトな表現です。Doxygenはタグファイルを生成することも読み込むこともできます。

プロジェクトのタグファイルを生成するには、設定ファイルのGENERATE_TAGFILEオプションの後にタグファイルの名前を記述するだけです。

1つまたは複数の外部プロジェクトの出力を自分のプロジェクトと結合するには、設定ファイルのTAGFILESオプションの後にタグファイルの名前を指定する必要があります。

タグファイルには通常、Doxygenが実行された時点からのドキュメントの相対パスのみが含まれています。そのため、他のプロジェクトにタグファイルを含める場合は、このプロジェクトに対して外部ドキュメントがどこにあるかを指定する必要があります。これは、設定ファイルのTAGFILES設定オプションの後に指定されたタグファイルに（相対）パスを割り当てることで行うことができます。相対パスを使用する場合、それはあなたのプロジェクトのHTML出力が生成されるディレクトリに対する相対パスであるべきです。つまり、あるプロジェクトのHTML出力ディレクトリから、リンクされる他のプロジェクトのHTML出力への相対パスとなります。

例: 仮に、ext1とext2という2つの外部プロジェクトを使用するprojというプロジェクトがあるとします。ディレクトリ構造は以下のようになります。

<root>
  +- proj
  |   +- html               HTML output directory for proj
  |   +- src                sources for proj
  |   |- proj.cpp
  +- ext1
  |   +- html               HTML output directory for ext1
  |   |- ext1.tag           tag file for ext1
  +- ext2
  |   +- html               HTML output directory for ext2
  |   |- ext2.tag           tag file for ext2
  |- proj.cfg               Doxygen configuration file for proj
  |- ext1.cfg               Doxygen configuration file for ext1
  |- ext2.cfg               Doxygen configuration file for ext2

: その場合、設定ファイルの関連部分は以下のようになります。

proj.cfg

OUTPUT_DIRECTORY  = proj
INPUT             = proj/src
TAGFILES          = ext1/ext1.tag=../../ext1/html \
                    ext2/ext2.tag=../../ext2/html

ext1.cfg

OUTPUT_DIRECTORY  = ext1
GENERATE_TAGFILE  = ext1/ext1.tag

ext2.cfg

OUTPUT_DIRECTORY  = ext2
GENERATE_TAGFILE  = ext2/ext2.tag

次のセクションへ進むか、目次に戻る。