\hypertarget{external}{}\section{Linking to external documentation}\label{external}
 If your project depends on external libraries or tools, there are several  reasons to not include all sources for these with every run of doxygen:

\begin{description}
 \item[Disk space:]
 Some documentation may be available outside of the output  directory of doxygen already, for instance somewhere on the web.  You may want to link to these pages instead of generating the documentation  in your local output directory. \item[Compilation speed:]
 External projects typically have a different update  frequency from your own project. It does not make much sense to let doxygen  parse the sources for these external project over and over again, even if  nothing has changed. \item[Memory:]
 For very large source trees, letting doxygen parse all sources  may simply take too much of your system's memory. By dividing the sources  into several \char`\"{}packages\char`\"{}, the sources of one package can be parsed by  doxygen, while all other packages that this package depends on, are  linked in externally. This saves a lot of memory. \item[Availability:]
 For some projects that are documented with doxygen, the sources may just not be available. \end{description}


If any of the above apply, you can use doxygen's tag file mechanism. A tag file is basically a compact representation of the entities found in the external sources. Doxygen can both generate and read tag files.

To generate a tag file for your project, simply put the name of the tag file after the \hyperlink{config_cfg_generate_tagfile}{GENERATE\_\-TAGFILE} option in  the configuration file.

To combine the output of one or more external projects with your own project  you should specify the name of the tag files after  the \hyperlink{config_cfg_tagfiles}{TAGFILES} option in the configuration file.

A tag file does not contain information about where the external documentation is located. This could be a directory or an URL. So when you include a tag  file you have to specify where the external documentation is located.  There are two ways to do this: \begin{description}
 \item[At configuration time:]
 just assign the location of the output to the tag files specified after the \hyperlink{config_cfg_tagfiles}{TAGFILES} configuration option. If you use a relative path it should be relative with respect to  the directory where the HTML output of your project is generated. \item[After compile time:]
 if you do not assign a location to a tag file, doxygen will generate dummy links for all external HTML references. It will also generate a perl script called \hyperlink{installdox_usage}{installdox} in  the HTML output directory. This script should be run to replace the  dummy links with real links for all generated HTML files. \end{description}
\begin{Desc}
\item[Example:]\par
Suppose you have a project {\tt proj} that uses two external  projects called {\tt ext1} and {\tt ext2}. The directory structure looks as follows:



\footnotesize\begin{verbatim}
<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
\end{verbatim}\normalsize 


Then the relevant parts of the configuration files look as follows: 

proj.cfg: 

\footnotesize\begin{verbatim}
OUTPUT_DIRECTORY  = proj
INPUT             = proj/src
TAGFILES          = ext1/ext1.tag=../../ext1/html \
                    ext2/ext2.tag=../../ext2/html 
\end{verbatim}\normalsize 
  ext1.cfg: 

\footnotesize\begin{verbatim}
OUTPUT_DIRECTORY  = ext1
GENERATE_TAGFILE  = ext1/ext1.tag 
\end{verbatim}\normalsize 
  ext2.cfg: 

\footnotesize\begin{verbatim}
OUTPUT_DIRECTORY  = ext2
GENERATE_TAGFILE  = ext2/ext2.tag
\end{verbatim}\normalsize 
\end{Desc}
In some (hopefully exceptional) cases you may have the documentation generated by doxygen, but not the sources nor a tag file. In this case you can use the \hyperlink{doxytag_usage}{doxytag} tool to extract a tag file from  the generated HTML sources. This tool depends on the particular structure of the generated output and on some special markers that are generated by doxygen. Since this type of extraction is brittle and error prone I suggest you to only use this approach if there is no alternative. The doxytag tool may even become obsolete in the future.



