\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 subsections: \begin{CompactItemize}
\item 
\hyperlink{install_src_unix}{Compiling from source on Unix} \item 
\hyperlink{install_bin_unix}{Installating the binaries on Unix} \item 
\hyperlink{unix_problems}{Known compilation problems for Unix} \item 
\hyperlink{install_src_windows}{Compiling from source on Windows} \item 
\hyperlink{install_bin_windows}{Installating the binaries on Windows} \item 
\hyperlink{build_tools}{Tools used to develop doxygen} \end{CompactItemize}
\hypertarget{install_src_unix}{}\subsection{Compiling from source on Unix}\label{install_src_unix}


If you downloaded the source distribution, you need at least the  following to build the executable: \begin{CompactItemize}
\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{CompactItemize}
To take full advantage of doxygen's features the following additional tools should be installed.

\begin{CompactItemize}
\item 
Troll Tech's GUI toolkit version 2.x.y \href{http://www.trolltech.com/products/qt.html}{\tt Qt} (see {\tt http://www.trolltech.com/products/qt.html}). \index{Qt@{Qt}} This is needed to build the GUI front-end.  \item 
A $\mbox{\LaTeX}$ distribution: for instance \href{http://www.tug.org/}{\tt te\-Te\-X 1.0}.\par
 (see {\tt http://www.tug.org/}). This is needed for generating La\-Te\-X, Postscript, and PDF output. \item 
\href{http://www.graphviz.org/}{\tt  the Graph visualization toolkit version 1.5}\par
 (see {\tt http://www.graphviz.org/}). Needed for the include dependency graphs,  the graphical inheritance graphs, and the collaboration graphs. \item 
The ghostscript interpreter. \end{CompactItemize}
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-2.1.x 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}, {\tt doxytag}, and {\tt doxysearch})  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: ]\par
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 Post\-Script and PDF version of the manual (you will need {\tt latex} and {\tt dvips} and the ghostscript package for this).



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


The Post\-Script manual {\tt doxygen\_\-manual.ps} will be located  in the latex directory of the distribution. Just send it to a  Post\-Script printer to print it or use {\tt ghostview} to view it.

\end{enumerate}
\hypertarget{install_bin_unix}{}\subsection{Installating the binaries on Unix}\label{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: ]\par
You need the GNU install tool for this to work. 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{unix_problems}{}\subsection{Known compilation problems for Unix}\label{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 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}

I tried compiling doxygen only with Sun's C++ Work\-Shop Compiler version 5.0 (I used {\tt ./configure --platform solaris-cc})

Qt-2.x.y is required for this compiler (Qt-1.44 has problems with the bool type).

Compiling the {\tt doxygen} binary went ok, but while linking {\tt doxytag} I got a  lot of link errors, like these:



\footnotesize\begin{verbatim}
QList<PageInfo>::__vtbl   /home/dimitri/doxygen/
objects/SunWS_cache/CC_obj_6/6c3eO4IogMT2vrlGCQUQ.o
[Hint: try checking whether the first non-inlined, non-pure 
virtual function of class QList<PageInfo> is defined]
\end{verbatim}\normalsize 


These are generated because the compiler is confused about the object sharing between {\tt doxygen} and {\tt doxytag}. To compile {\tt doxytag} and {\tt doxysearch}  anyway do:



\footnotesize\begin{verbatim}
rm -rf objects
mkdir objects
cd src
gmake -f Makefile.doxytag
gmake -f Makefile.doxysearch
\end{verbatim}\normalsize 


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 GNU 2.7.2.x 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.

\hypertarget{install_src_windows}{}\subsection{Compiling from source on Windows}\label{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.

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

Here is what is required: \begin{CompactItemize}
\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.

Make sure the {\tt BISONLIB} environment variable points to the location where the files {\tt bison.simple} and  {\tt bison.hairy} are located. For instance if these files are in {\tt c:$\backslash$tools$\backslash$cygwin$\backslash$share} then BISONLIB should  be set to {\tt //c/tools/cygwin/share/}

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, doxytag, and doxysearch. 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. You can download the non-commercial version from Troll-Tech web-site. See doxygen download page for a link.

\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 download it at: \href{http://www.ese-metz.fr/~popineau/fptex/wwwfptex.html}{\tt http://www.ese-metz.fr/$\sim$popineau/fptex/wwwfptex.html}

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 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 
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.

\item 
\href{http://www.graphviz.org/}{\tt  the Graph visualization toolkit version 1.5}\par
 (see {\tt http://www.graphviz.org/}). Needed for the include dependency graphs, the graphical inheritance graphs, and the collaboration graphs. \end{CompactItemize}
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}, {\tt doxytag.exe}, and  {\tt doxysearch.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_bin_windows}{}\subsection{Installating the binaries on Windows}\label{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.

For running doxywizard you need to install the non-commercial version of the Qt library first. This library can be downloaded from  \href{http://www.trolltech.com/products/download/freelicense/noncommercial-dl.html}{\tt http://www.trolltech.com/products/download/freelicense/noncommercial-dl.html}

\hypertarget{build_tools}{}\subsection{Tools used to develop doxygen}\label{build_tools}


Doxygen was developed and tested under Linux using the following  open-source tools: \begin{CompactItemize}
\item 
EGCS version 2.91.66 \item 
GNU flex version 2.5.4 \item 
GNU bison version 1.25 \item 
GNU make version 3.76.1 \item 
Perl version 5.005\_\-02  \item 
VIM version 5.4 \item 
Netscape 4.61 \item 
Troll Tech's tmake version 1.3 (included in the distribution)  \item 
te\-Te\-X version 0.9 \item 
CVS 1.10.7 \end{CompactItemize}


