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

ディスク容量

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

コンパイル速度

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

メモリ

非常に大規模なソースツリーの場合、Doxygenにすべてのソースを解析させると、システムメモリが単純に多すぎることがあります。ソースをいくつかの「パッケージ」に分割することで、1つのパッケージのソースはDoxygenによって解析され、このパッケージが依存する他のすべてのパッケージは外部からリンクされます。これにより、多くのメモリが節約されます。

可用性

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

著作権の問題

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

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

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

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

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

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

<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

次のセクションに進むか、インデックスに戻ります。