\hypertarget{install}{}\section{Installation}\label{install}
\index{installation@{installation}} First go to the \href{http://www.doxygen.org/download.html}{\tt download} page  ({\tt http://www.doxygen.org/download.html}) to get the latest distribution, if you did not have it already.

This section is divided into the following sections: \begin{itemize}
\item \hyperlink{install_install_src_unix}{Compiling from source on Unix} \item \hyperlink{install_install_bin_unix}{Installing the binaries on Unix} \item \hyperlink{install_unix_problems}{Known compilation problems for Unix} \item \hyperlink{install_install_src_windows}{Compiling from source on Windows} \item \hyperlink{install_install_bin_windows}{Installing the binaries on Windows} \item \hyperlink{install_build_tools}{Tools used to develop doxygen} \end{itemize}
\hypertarget{install_install_src_unix}{}\subsection{Compiling from source on Unix}\label{install_install_src_unix}
If you downloaded the source distribution, you need at least the following to build the executable: \begin{itemize}
\item The \href{ftp://prep.ai.mit.edu/pub/gnu/}{\tt GNU} tools flex, bison and make \index{flex@{flex}} \index{bison@{bison}} \index{make@{make}} \item In order to generate a Makefile for your platform, you need \href{http://www.perl.com/}{\tt perl}  (see {\tt http://www.perl.com/}). \index{perl@{perl}} \end{itemize}


To take full advantage of doxygen's features the following additional tools should be installed.

\begin{itemize}
\item Troll Tech's GUI toolkit \href{http://www.trolltech.com/products/qt.html}{\tt Qt}  (see {\tt http://www.trolltech.com/products/qt.html}) \index{Qt@{Qt}} version 3.2 or higher. This is needed to build the GUI front-end doxywizard. \item A $\mbox{\LaTeX}$ distribution: for instance \href{http://www.tug.org/interest.html#free}{\tt te\-Te\-X 1.0}  \\par (see {\tt http://www.tug.org/interest.html\#free}). This is needed for generating La\-Te\-X, Postscript, and PDF output. \item \href{http://www.research.att.com/sw/tools/graphviz/}{\tt the Graph visualization toolkit version 1.8.10 or higher}  \\par (see {\tt http://www.research.att.com/sw/tools/graphviz/}). Needed for the include dependency graphs, the graphical inheritance graphs, and the collaboration graphs. If you compile graphviz yourself, make sure you do include freetype support (which requires the freetype library and header files), otherwise the graphs will not render proper text labels. \item The ghostscript interpreter. To be found at \href{http://www.ghostscript.com/}{\tt www.ghostscript.com}. \end{itemize}


Compilation is now done by performing the following steps:

\begin{enumerate}
\item Unpack the archive, unless you already have done that:



\footnotesize\begin{verbatim}    gunzip doxygen-$VERSION.src.tar.gz    # uncompress the archive
    tar xf doxygen-$VERSION.src.tar       # unpack it
\end{verbatim}
\normalsize


\item Run the configure script:



\footnotesize\begin{verbatim}    sh ./configure
\end{verbatim}
\normalsize


The script tries to determine the platform you use, the make tool (which {\em must\/} be GNU make) and the perl interpreter. It will report what it finds.

To override the auto detected platform and compiler you can run configure as follows:



\footnotesize\begin{verbatim}    configure --platform platform-type
\end{verbatim}
\normalsize


See the {\tt PLATFORMS} file for a list of possible platform options.

If you have Qt-3.2.x or higher installed and want to build the GUI front-end, you should run the configure script with the {\tt --with-doxywizard} option:



\footnotesize\begin{verbatim}    configure --with-doxywizard
\end{verbatim}
\normalsize


For an overview of other configuration options use



\footnotesize\begin{verbatim}    configure --help
\end{verbatim}
\normalsize


\item Compile the program by running make:



\footnotesize\begin{verbatim}    make
\end{verbatim}
\normalsize


The program should compile without problems and three binaries ({\tt doxygen} and {\tt doxytag}) should be available in the bin directory of the distribution.

\item Optional: Generate the user manual.



\footnotesize\begin{verbatim}    make docs
\end{verbatim}
\normalsize


To let doxygen generate the HTML documentation.

\begin{Desc}
\item[Note:]You will need the stream editor {\tt sed} for this, but this should be available on any Unix platform.\end{Desc}
The HTML directory of the distribution will now contain the html documentation (just point a HTML browser to the file {\tt index.html} in the html directory).

\item Optional: Generate a PDF version of the manual (you will need {\tt pdflatex}, {\tt makeindex}, and {\tt egrep} for this).



\footnotesize\begin{verbatim}    make pdf
\end{verbatim}
\normalsize


The PDF manual {\tt doxygen\_\-manual.pdf} will be located in the latex directory of the distribution. Just view and print it via the acrobat reader.

\end{enumerate}
\hypertarget{install_install_bin_unix}{}\subsection{Installing the binaries on Unix}\label{install_install_bin_unix}
After the compilation of the source code do a {\tt make install} to install doxygen. If you downloaded the binary distribution for Unix, type:



\footnotesize\begin{verbatim}    ./configure
    make install
\end{verbatim}
\normalsize


Binaries are installed into the directory {\tt $<$prefix$>$/bin}. Use {\tt make install\_\-docs} to install the documentation and examples into {\tt $<$docdir$>$/doxygen}.

{\tt $<$prefix$>$} defaults to {\tt /usr} but can be changed with the {\tt --prefix} option of the configure script. The default {\tt $<$docdir$>$} directory is {\tt $<$prefix$>$/share/doc/packages} and can be changed with the {\tt --docdir} option of the configure script.

Alternatively, you can also copy the binaries from the {\tt bin} directory manually to some {\tt bin} directory in your search path. This is sufficient to use doxygen.

\begin{Desc}
\item[Note:]You need the GNU install tool for this to work (it is part of the fileutils package). Other install tools may put the binaries in the wrong directory!\end{Desc}
If you have a RPM or DEP package, then please follow the standard installation procedure that is required for these packages.\hypertarget{install_unix_problems}{}\subsection{Known compilation problems for Unix}\label{install_unix_problems}
{\bf Qt problems}

The Qt include files and libraries are not a subdirectory of the directory pointed to by QTDIR on some systems (for instance on Red Hat 6.0 includes are in /usr/include/qt and libs are in /usr/lib).

The solution: go to the root of the doxygen distribution and do: 

\footnotesize\begin{verbatim}   mkdir qt
   cd qt
   ln -s your-qt-include-dir-here include
   ln -s your-qt-lib-dir-here lib
   export QTDIR=$PWD
\end{verbatim}
\normalsize


If you have a csh-like shell you should use {\tt setenv QTDIR \$PWD} instead of the {\tt export} command above.

Now install doxygen as described above.

{\bf Bison problems}

Versions 1.31 to 1.34 of bison contain a \char`\"{}bug\char`\"{} that results in a compiler errors like this:

ce\_\-parse.cpp:348: member `class CPPValue yyalloc::yyvs' with constructor not allowed in union

This problem has been solved in version 1.35 (versions before 1.31 will also work).

{\bf Latex problems}

The file {\tt a4wide.sty} is not available for all distributions. If your distribution does not have it please select another paper type in the config file (see the \hyperlink{config_cfg_paper_type}{PAPER\_\-TYPE} tag in the config file).

{\bf HP-UX \& Digital Unix problems}

If you are compiling for HP-UX with a\-CC and you get this error: 

\footnotesize\begin{verbatim}    /opt/aCC/lbin/ld: Unsatisfied symbols:
    alloca (code)
\end{verbatim}
\normalsize
 then you should (according to Anke Selig) edit {\tt ce\_\-parse.cpp} and replace 

\footnotesize\begin{verbatim}    extern "C" {
      void *alloca (unsigned int);
    };
\end{verbatim}
\normalsize
 with 

\footnotesize\begin{verbatim}    #include <alloca.h>  
\end{verbatim}
\normalsize


If that does not help, try removing {\tt ce\_\-parse.cpp} and let bison rebuild it (this worked for me).

If you are compiling for Digital Unix, the same problem can be solved (according to Barnard Schmallhof) by replacing the following in ce\_\-parse.cpp:



\footnotesize\begin{verbatim}    #else  not GNU C.  
    #if (!defined (__STDC__) && defined (sparc)) || defined (__sparc__) \
        || defined (__sparc) || defined (__sgi)
    #include <alloca.h>
\end{verbatim}
\normalsize


with



\footnotesize\begin{verbatim}    #else  not GNU C.  
    #if (!defined (__STDC__) && defined (sparc)) || defined (__sparc__) \
        || defined (__sparc) || defined (__sgi) || defined (__osf__)
    #include <alloca.h>
\end{verbatim}
\normalsize


Alternatively, one could fix the problem at the bison side. Here is patch for bison.simple (provided by Andre Johansen):



\footnotesize\begin{verbatim}--- bison.simple~       Tue Nov 18 11:45:53 1997
+++ bison.simple        Mon Jan 26 15:10:26 1998
@@ -27,7 +27,7 @@
 #ifdef __GNUC__
 #define alloca __builtin_alloca
 #else  not GNU C.  
-#if (!defined (__STDC__) && defined (sparc)) || defined (__sparc__) \
     || defined (__sparc) || defined (__sgi)
+#if (!defined (__STDC__) && defined (sparc)) || defined (__sparc__) \
     || defined (__sparc) || defined (__sgi) || defined (__alpha)
 #include <alloca.h>
 #else  not sparc 
 #if defined (MSDOS) && !defined (__TURBOC__)
\end{verbatim}
\normalsize


The generated scanner.cpp that comes with doxygen is build with this patch applied.

{\bf Sun compiler problems}

It appears that doxygen doesn't work properly if it is compiled with Sun's C++ Work\-Shop Compiler. I cannot verify this myself as I do not have access to a Solaris machine with this compiler. With GNU compiler it does work.

when configuring with {\tt --static} I got:



\footnotesize\begin{verbatim}Undefined                       first referenced
 symbol                             in file
dlclose                             /usr/lib/libc.a(nss_deffinder.o)
dlsym                               /usr/lib/libc.a(nss_deffinder.o)
dlopen                              /usr/lib/libc.a(nss_deffinder.o)
\end{verbatim}
\normalsize


Manually adding {\tt -Bdynamic} after the target rule in {\tt Makefile.doxygen} and {\tt Makefile.doxytag} will fix this:



\footnotesize\begin{verbatim}$(TARGET): $(OBJECTS) $(OBJMOC) 
        $(LINK) $(LFLAGS) -o $(TARGET) $(OBJECTS) $(OBJMOC) $(LIBS) -Bdynamic
\end{verbatim}
\normalsize


{\bf GCC compiler problems}

Older versions of the GNU compiler have problems with constant strings containing characters with character codes larger than 127. Therefore the compiler will fail to compile some of the translator\_\-xx.h files. A workaround, if you are planning to use the English translation only, is to configure doxygen with the {\tt --english-only} option.

On some platforms (such as Open\-BSD) using some versions of gcc with -O2 can lead to eating all memory during the compilation of files such as config.cpp. As a workaround use --debug as a configure option or omit the -O2 for the particular files in the Makefile.

Gcc versions before 2.95 may produce broken binaries due to bugs in these compilers.

{\bf Dot problems}

Due to a change in the way image maps are generated, older versions of doxygen ($<$=1.2.17) will not work correctly with newer versions of graphviz ($>$=1.8.8). The effect of this incompatibility is that generated graphs in HTML are not properly clickable. For doxygen 1.3 it is recommended to use at least graphviz 1.8.10 or higher.

{\bf Red Hat 9.0 problems}

If you get the following error after running make 

\footnotesize\begin{verbatim}tmake error: qtools.pro:70: Syntax error
\end{verbatim}
\normalsize
 then first type 

\footnotesize\begin{verbatim}export LANG=
\end{verbatim}
\normalsize
 before running make.\hypertarget{install_install_src_windows}{}\subsection{Compiling from source on Windows}\label{install_install_src_windows}
Currently, I have only compiled doxygen for Windows using Microsoft's Visual C++ (version 6.0). For other compilers you may need to edit the perl script in {\tt wintools/make.pl} a bit. Let me know what you had to change if you got Doxygen working with another compiler. If you have Visual Studio you can also use the .dsw file found in the {\tt wintools} directory. Note that this file is not maintained by me, so it might be outdated a little.

If you have Visual C++ 6.0, and the source distribution, you can easily build doxygen using the project files in the {\tt wintools} directory. If you want to build the CVS sources, or want to build from the command line, or with another compiler, you have to follow the steps below.

Thomas Baust reported that if you have Visual Studio.NET (2003) then you should be aware that there is a problem with the \_\-popen() and \_\-pclose() implementation, which currently leaks handles, so if you build doxygen with it and use the INPUT\_\-FILTER, you will run to risk of crashing Windows! The problem is reported to and confirmed by Microsoft so maybe it will fixed in the next service pack.

Since Windows comes without all the nice tools that Unix users are used to, you'll need to install a number of these tools before you can compile doxygen for Windows from the command-line.

Here is what is required: \begin{itemize}
\item An unzip/untar tool like Win\-Zip to unpack the tar source distribution. This can be found at \href{http://www.winzip.com/}{\tt http://www.winzip.com/}

The good, tested, and free alternative is the {\tt tar} utility supplied with \href{http://sourceware.cygnus.com/cygwin/}{\tt cygwin tools}. Anyway, the cygwin's flex, bison, and sed are also recommended below.

\item Microsoft Visual C++ (I only tested with version 6.0). Use the {\tt vcvars32.bat} batch file to set the environment variables (if you did not select to do this automatically during installation).

Borland C++ or MINGW (see \href{http://www.mingw.org/}{\tt http://www.mingw.org/}) are also supported.

\item Perl 5.0 or higher for Windows. This can be downloaded from: \href{http://www.ActiveState.com/Products/ActivePerl/}{\tt http://www.Active\-State.com/Products/Active\-Perl/}

\item The GNU tools flex, bison, and sed. To get these working on Windows you should install the \href{http://sources.redhat.com/cygwin/}{\tt cygwin tools}  (see {\tt http://sources.redhat.com/cygwin/})

Alternatively, you can also choose to download only a \href{http://www.doxygen.org/dl/cygwin_tools.zip}{\tt small subset}  (see {\tt http://www.doxygen.org/dl/cygwin\_tools.zip}) of the cygwin tools that I put together just to compile doxygen.

As a third alternative one could use the GNUWin32 tools that can be found at \href{http://gnuwin32.sourceforge.net/}{\tt http://gnuwin32.sourceforge.net/}

Make sure the {\tt BISON\_\-SIMPLE} environment variable points to the location where the files {\tt bison.simple} and is located. For instance if these file is in {\tt c:$\backslash$tools$\backslash$cygwin$\backslash$usr$\backslash$share} then BISON\_\-SIMPLE should be set to {\tt c:/tools/cygwin/usr/share/bison.simple}

Also make sure the tools are available from a dos box, by adding the directory they are in to the search path.

For those of you who are very new to cygwin (if you are going to install it from scratch), you should notice that there is an archive file {\tt bootstrap.zip} which also contains the {\tt tar} utility ({\tt tar.exe}), {\tt gzip} utilities, and the {\tt cygwin1.dll} core. This also means that you have the {\tt tar} in hands from the start. It can be used to unpack the tar source distribution instead of using Win\-Zip -- as mentioned at the beginning of this list of steps.

\item From Doxygen-1.2.2-20001015 onwards, the distribution includes the part of Qt-2.x.y that is needed for to compile doxygen and doxytag, The Windows specific part were also created. As a result doxygen can be compiled on systems without X11 or the commerical version of Qt.

For doxywizard, a complete Qt library is still a requirement however. A commercial license to build doxywizard with the latest Qt library was kindly donated to me by the nice people at \href{http://www.trolltech.com}{\tt Troll\-Tech}. See doxygen download page for a link.

\item If you used Win\-Zip to extract the tar archive it will (apparently) not create empty folders, so you have to add the folders {\tt objects} and {\tt bin} manually in the root of the distribution before compiling.

\end{itemize}


Compilation is now done by performing the following steps:

\begin{enumerate}
\item Open a dos box. Make sure all tools (i.e. {\tt nmake}, {\tt latex}, {\tt gswin32}, {\tt dvips}, {\tt sed}, {\tt flex}, {\tt bison}, {\tt cl}, {\tt rm}, and {\tt perl}), are accessible from the command-line (add them to the PATH environment variable if needed).

Notice: The use of La\-Te\-X is optional and only needed for compilation of the documentation into Post\-Script or PDF. It is {\em not\/} needed for compiling the doxygen's binaries.

\item Go to the doxygen root dir and type:



\footnotesize\begin{verbatim}    make.bat msvc
\end{verbatim}
\normalsize


This should build the executables {\tt doxygen.exe} and {\tt doxytag.exe} using Microsoft's Visual C++ compiler (The compiler should not produce any serious warnings or errors).

You can use also the {\tt bcc} argument to build executables using the Borland C++ compiler, or {\tt mingw} argument to compile using GNU gcc.

\item To build the examples, go to the {\tt examples} subdirectory and type:



\footnotesize\begin{verbatim}    nmake
\end{verbatim}
\normalsize


\item To generate the doxygen documentation, go to the {\tt doc} subdirectory and type:



\footnotesize\begin{verbatim}    nmake
\end{verbatim}
\normalsize


The generated HTML docs are located in the {\tt ..$\backslash$html} subdirectory.

The sources for La\-Te\-X documentation are located in the {\tt ..$\backslash$latex} subdirectory. From those sources, the DVI, Post\-Script, and PDF documentation can be generated. \end{enumerate}
\hypertarget{install_install_bin_windows}{}\subsection{Installing the binaries on Windows}\label{install_install_bin_windows}
There is no fancy installation procedure at the moment (if anyone can add it in a location independent way please let me know).

To install doxygen, just copy the binaries from the {\tt bin} directory to a location somewhere in the path. Alternatively, you can include the {\tt bin} directory of the distribution to the path.

There are a couple of tools you may want to install to use all of doxygen's features:

\begin{itemize}
\item To generate La\-Te\-X documentation or formulas in HTML you need the tools: {\tt latex}, {\tt dvips} and {\tt gswin32}. To get these working under Windows install the fp\-Te\-X distribution. You can find more info at: \href{http://www.fptex.org/}{\tt http://www.fptex.org/} and download it from CTAN or one of its mirrors. In the Netherlands for example this would be: \href{ftp://ftp.easynet.nl/mirror/CTAN/systems/win32/fptex/}{\tt ftp://ftp.easynet.nl/mirror/CTAN/systems/win32/fptex/}

Make sure the tools are available from a dos box, by adding the directory they are in to the search path.

For your information, the La\-Te\-X is freely available set of so called macros and styles on the top of the famous Te\-X program (by famous Donald Knuth) and the accompanied utilities (all available for free). It is used for high quality typesetting. The result -- in the form of so called {\tt DVI} (De\-Vice Independent) file -- can be printed or displayed on various devices preserving exactly the same look up to the capability of the device. The {\tt dvips} allows you to convert the {\tt dvi} to the high quality Post\-Script (i.e. Post\-Script that can be processed by utilities like {\tt psnup}, {\tt psbook}, {\tt psselect}, and others). The derived version of Te\-X (the pdf\-Te\-X) can be used to produce PDF output instead of DVI, or the PDF can be produced from Post\-Script using the utility {\tt ps2pdf}.

If you want to use Mik\-Te\-X then you need to select at least the medium size installation. For really old versions of Mik\-Tex or minimal installations, you may need to download the fancyhdr package separately. You can find it at: \href{ftp://ftp.tex.ac.uk/tex-archive/macros/latex/contrib/supported/fancyhdr/}{\tt ftp://ftp.tex.ac.uk/tex-archive/macros/latex/contrib/supported/fancyhdr/}

\item If you want to generate compressed HTML help (see \hyperlink{config_cfg_generate_htmlhelp}{GENERATE\_\-HTMLHELP}) in the config file, then you need the Microsoft HTML help workshop. You can download it at: \href{http://msdn.microsoft.com/library/default.asp?url=/library/en-us/htmlhelp/html/vsconHH1Start.asp}{\tt http://msdn.microsoft.com/library/default.asp?url=/library/en-us/htmlhelp/html/vscon\-HH1Start.asp}

\item \href{http://www.research.att.com/sw/tools/graphviz/}{\tt the Graph visualization toolkit version 1.8.10}\par
  (see {\tt http://www.research.att.com/sw/tools/graphviz/}). Needed for the include dependency graphs, the graphical inheritance graphs, and the collaboration graphs. \end{itemize}
\hypertarget{install_build_tools}{}\subsection{Tools used to develop doxygen}\label{install_build_tools}
Doxygen was developed and tested under Linux using the following open-source tools: \begin{itemize}
\item GCC version 3.3.1 \item GNU flex version 2.5.4 \item GNU bison version 1.75 \item GNU make version 3.80 \item Perl version 5.8.1 \item VIM version 6.2 \item Mozilla 1.0 \item Troll Tech's tmake version 1.3 (included in the distribution) \item te\-Te\-X version 1.0 \item CVS 1.10.7 \end{itemize}


 