/******************************************************************************

 *

 * 

 *

 * Copyright (C) 1997-2008 by Dimitri van Heesch.

 *

 * Permission to use, copy, modify, and distribute this software and its

 * documentation under the terms of the GNU General Public License is hereby 

 * granted. No representations are made about the suitability of this software 

 * for any purpose. It is provided "as is" without express or implied warranty.

 * See the GNU General Public License for more details.

 *

 * Documents produced by Doxygen are derivative works derived from the

 * input used in their production; they are not affected by this license.

 *

 */

/*! \page install Installation

\addindex installation

First go to the 

<a href="http://www.doxygen.org/download.html">download</a> page

\latexonly({\tt http://www.doxygen.org/download.html})\endlatexonly

to get the latest distribution, if you did not have it already.

This section is divided into the following sections:

<ul>

<li>\ref install_src_unix  "Compiling from source on Unix"

<li>\ref install_bin_unix  "Installing the binaries on Unix"

<li>\ref unix_problems "Known compilation problems for Unix"

<li>\ref install_src_windows "Compiling from source on Windows"

<li>\ref install_bin_windows "Installing the binaries on Windows"

<li>\ref build_tools "Tools used to develop doxygen"

</ul>

\section install_src_unix    Compiling from source on Unix

If you downloaded the source distribution, you need at least the 

following to build the executable:

<ul>

<li>The <a href="ftp://prep.ai.mit.edu/pub/gnu/">GNU</a> tools 

    flex, bison and GNU make, and strip

    \addindex flex

    \addindex bison

    \addindex make

    \addindex strip

<li>In order to generate a Makefile for your platform, you need 

    <a href="http://www.perl.com/">perl</a>

    \latexonly(see {\tt http://www.perl.com/})\endlatexonly.

    \addindex perl

<li>The configure script assume the availibility of standard Unix tools such 

    as sed, date, find, uname, mv, cp, cat, echo, tr, cd, and rm.

</ul>

To take full advantage of doxygen's features the following additional

tools should be installed.

<ul>

<li>Qt Software's GUI toolkit 

    <A HREF="http://www.trolltech.com/products/qt.html">Qt</A>

    \latexonly(see {\tt http://www.trolltech.com/products/qt.html})\endlatexonly

    \addindex Qt

    This is needed to build the GUI front-end doxywizard. 

<li>A \f$\mbox{\LaTeX}\f$ distribution: for instance

    <a href="http://www.tug.org/interest.html#free">teTeX 1.0</a>

    \latexonly \\par (see {\tt http://www.tug.org/interest.html\#free})\endlatexonly.

    This is needed for generating LaTeX, Postscript, and PDF output.

<li><a href="http://www.graphviz.org/">

    the Graph visualization toolkit version 1.8.10 or higher</a>

    \latexonly \\par (see {\tt http://www.graphviz.org/})\endlatexonly.

    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.

<li>For formulas or if you do not wish to use pdflatex, the ghostscript interpreter

    is needed. You can find it at 

    <a href="http://www.ghostscript.com/">www.ghostscript.com</a>.

<li>In order to generate doxygen's own documentation, Python is needed, you

    can find it  at <a href="http://www.python.org">www.python.org</a>.

</ul>

Compilation is now done by performing the following steps:

<ol>

<li> Unpack the archive, unless you already have done that:

\verbatim

    gunzip doxygen-$VERSION.src.tar.gz    # uncompress the archive

    tar xf doxygen-$VERSION.src.tar       # unpack it

\endverbatim

<li>Run the configure script:

\verbatim

    sh ./configure

\endverbatim

    The script tries to determine the platform you use, the make tool 

    (which \e 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:

\verbatim

    configure --platform platform-type

\endverbatim

    See the <code>PLATFORMS</code> file for a list of possible platform

    options.

    front-end, you should run the configure script with 

    the <code>--with-doxywizard</code> option:

\verbatim

    configure --with-doxywizard

\endverbatim

    For an overview of other configuration options use

\verbatim

    configure --help

\endverbatim

<li>Compile the program by running make:

\verbatim

    make

\endverbatim

    The program should compile without problems and three binaries 

    (<code>doxygen</code> and <code>doxytag</code>) 

    should be available in the bin directory of the distribution.

<li>Optional: Generate the user manual.

\verbatim

    make docs

\endverbatim

    To let doxygen generate the HTML documentation.

    The HTML directory of the distribution will now contain the html 

    documentation (just point a HTML browser to the file 

    <code>index.html</code> in the 

    html directory). You will need the <code>python</code> interpreter 

    for this.

<li>Optional: Generate a PDF version of the manual

    (you will need <code>pdflatex</code>, <code>makeindex</code>, and

     <code>egrep</code> for this).

\verbatim

    make pdf

\endverbatim

    The PDF manual <code>doxygen_manual.pdf</code> will be located 

    in the latex directory of the distribution. Just 

    view and print it via the acrobat reader. 

</ol>

\section install_bin_unix    Installing the binaries on Unix

    After the compilation of the source code do a <code>make install</code>

    to install doxygen. If you downloaded the binary distribution for Unix,

    type:

\verbatim

    ./configure

    make install

\endverbatim   

    Binaries are installed into the directory <code>\<prefix\>/bin</code>.

    Use <code>make install_docs</code> to install the

    documentation and examples into <code>\<docdir\>/doxygen</code>. 

    <code>\<prefix\></code> defaults to <code>/usr/local</code> but can be changed with 

    the <code>--prefix</code> option of the configure script. 

    The default <code>\<docdir\></code> directory is 

    <code>\<prefix\>/share/doc/packages</code> and can be changed with

    the <code>--docdir</code> option of the configure script.

    Alternatively, you can also copy the binaries from the <code>bin</code> 

    directory manually to some <code>bin</code> directory in your search path.

    This is sufficient to use doxygen.

    \note You need the GNU install tool for this to work (it is part of

    the coreutils package). Other install tools may put the binaries in 

    the wrong directory!

    If you have a RPM or DEP package, then please follow the 

    standard installation procedure that is required for these packages. 

\section unix_problems Known compilation problems for Unix

<b>Qt problems</b>

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:

\verbatim

   mkdir qt

   cd qt

   ln -s your-qt-include-dir-here include

   ln -s your-qt-lib-dir-here lib

   export QTDIR=$PWD

\endverbatim 

If you have a csh-like shell you should use <code>setenv QTDIR \$PWD</code>

instead of the <code>export</code> command above.

Now install doxygen as described above.  

<b>Bison problems</b>

Versions 1.31 to 1.34 of bison contain a "bug" 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).

<b>Latex problems</b>

The file <code>a4wide.sty</code> is not available for all distributions. If

your distribution does not have it please select another paper type

in the config file (see the \ref cfg_paper_type "PAPER_TYPE" tag in the 

config file).

<b>HP-UX \& Digital Unix problems</b>

If you are compiling for HP-UX with aCC and you get this error:

\verbatim

    /opt/aCC/lbin/ld: Unsatisfied symbols:

    alloca (code)

\endverbatim

  then you should (according to Anke Selig) edit <code>ce_parse.cpp</code> 

  and replace

\verbatim

    extern "C" {

      void *alloca (unsigned int);

    };

\endverbatim

  with

\verbatim

    #include <alloca.h>  

\endverbatim

  If that does not help, try removing <code>ce_parse.cpp</code> 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:

\verbatim

    #else /* not GNU C.  */

    #if (!defined (__STDC__) && defined (sparc)) || defined (__sparc__) \

        || defined (__sparc) || defined (__sgi)

    #include <alloca.h>

\endverbatim

  with

\verbatim

    #else /* not GNU C.  */

    #if (!defined (__STDC__) && defined (sparc)) || defined (__sparc__) \

        || defined (__sparc) || defined (__sgi) || defined (__osf__)

    #include <alloca.h>

\endverbatim

  Alternatively, one could fix the problem at the bison side.

  Here is patch for bison.simple (provided by Andre Johansen):

\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__)

\endverbatim

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

  patch applied.  

<b>Sun compiler problems</b>

It appears that doxygen doesn't work properly if it is compiled 

with Sun's C++ WorkShop 6 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 and installing Sun patch 111679-13 has also been reported 

as a way to fix the problem.

when configuring with <code>--static</code> I got:

\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)

\endverbatim

Manually adding <code>-Bdynamic</code> after the target rule in 

<code>Makefile.doxygen</code> and <code>Makefile.doxytag</code> 

will fix this:

\verbatim

$(TARGET): $(OBJECTS) $(OBJMOC) 

        $(LINK) $(LFLAGS) -o $(TARGET) $(OBJECTS) $(OBJMOC) $(LIBS) -Bdynamic

\endverbatim

<b>GCC compiler problems</b>

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 <code>--english-only</code> option.  

On some platforms (such as OpenBSD) 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. 

<b>Dot problems</b>

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.

For doxygen 1.4.7 or higher it is recommended to 

use GraphViz 2.8 or higher to avoid font issues.

<b>Red Hat 9.0 problems</b>

If you get the following error after running make

\verbatim

tmake error: qtools.pro:70: Syntax error

\endverbatim

then first type

\verbatim

export LANG=

\endverbatim

before running make.

\section install_src_windows Compiling from source on Windows

From version 1.5.0 onwards, build files are provided for Visual Studio 2005.

Also the free (as in beer) "Express" version of Developer Studio can be used to 

compile doxygen. Alternatively, you can compile doxygen 

\ref install_src_unix "the Unix way" using 

<a href="http://en.wikipedia.org/wiki/Cygwin">Cygwin</a>

or <a href="http://www.mingw.org/">MinGW</a>.

Before you can compile doxygen you need to download and install the C++ compiler of

Visual Studio. Since Microsoft apparently wants to lure everyone into using their 

.NET stuff, they made things somewhat difficult when you use the Express version.

You need to

<a href="http://msdn2.microsoft.com/en-gb/express/aa700755.aspx">

do some manual steps</a> in order to setup a proper working environment for building

native win32 applications such as Doxygen.

The next step is to install unxutils (see http://sourceforge.net/projects/unxutils).

This packages contains the tools \c flex and \c bison which are needed during the

compilation process if you use a CVS snapshot of doxygen (the official source releases 

come with pre-generated sources).

Download the zip extract it to e.g. <code>c:\\tools\\unxutils</code>.

Now you need to add/adjust the following environment variables 

(via Control Panel/System/Advanced/Environment Variables):

- add <code>c:\\tools\\unxutils\\usr\\local\\wbin;</code> to the start of <code>PATH</code>

- set <code>BISON_SIMPLE</code> to <code>c:\\tools\\unxutils\\usr\\local\\share\\bison.simple</code>

Download doxygen's source tarball and put it somewhere (e.g use <code>c:\\tools</code>)

Now start a new command shell and type

\verbatim

cd c:\tools

gunzip doxygen-x.y.z.src.tar.gz

tar xvf doxygen-x.y.z.src.tar

\endverbatim

to unpack the sources.

Now your environment is setup to build \c doxygen and \c doxytag.

Inside the \c doxygen-x.y.z directory you will find a \c winbuild directory 

containing a \c Doxygen.sln file. Open this file in Visual Studio. 

You can now build the Release or Debug flavor of Doxygen and Doxytag by right-clicking

the project in the solutions explorer, and selecting Build.

(see http://www.trolltech.com/products/qt/qt3).

If you do not have a commercial license, you can build Doxywizard with the open

source version (see http://qtwin.sourceforge.net/qt3-win32/compile-msvc-2005.php), 

but I have not tried this myself.

Also read the next section for additional tools you may need to install to run

doxygen with certain features enabled.

<!--

Currently, I have only compiled doxygen for Windows using Microsoft's 

Visual C++ (). For other compilers you may need to edit the 

perl script in <code>wintools/make.pl</code> 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 <code>wintools</code> 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 \c 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:

<ul>

<li>An unzip/untar tool like WinZip to unpack the tar source distribution. 

    This can be found at http://www.winzip.com/  

    The good, tested, and free alternative is the <code>tar</code> utility

    supplied with <a href="http://sourceware.cygnus.com/cygwin/">cygwin

    tools</a>. Anyway, the cygwin's flex, bison, and sed are also

    recommended below.

<li>Microsoft Visual C++ (I only tested with version 6.0).

    Use the <code>vcvars32.bat</code> batch file to set the environment 

    variables (if you did not select to do this automatically during 

    installation). 

    Borland C++ or MINGW (see http://www.mingw.org/) are also supported. 

<li>Perl 5.0 or higher for Windows. This can be downloaded from:

    http://www.ActiveState.com/Products/ActivePerl/

<li>The GNU tools flex, bison, and sed.

    To get these working on Windows you should install the 

    <a href="http://sources.redhat.com/cygwin/">cygwin tools</a>

    \latexonly(see {\tt http://sources.redhat.com/cygwin/})\endlatexonly

    Alternatively, you can also choose to 

    download only a <a href="http://www.doxygen.org/dl/cygwin_tools.zip">small subset</a> 

    \latexonly(see {\tt http://www.doxygen.org/dl/cygwin\_tools.zip})\endlatexonly

    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 http://gnuwin32.sourceforge.net/ 

    Make sure the <code>BISON_SIMPLE</code> environment variable points to the

    location where the files <code>bison.simple</code> and 

    is located. For instance if these file is in

    <code>c:\\tools\\cygwin\\usr\\share</code> then BISON_SIMPLE should 

    be set to <code>c:/tools/cygwin/usr/share/bison.simple</code>

    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 <code>bootstrap.zip</code> which also contains the

    <code>tar</code> utility (<code>tar.exe</code>), <code>gzip</code>

    utilities, and the <code>cygwin1.dll</code> core. This also means

    that you have the <code>tar</code> in hands from the start. It

    can be used to unpack the tar source distribution instead of

    using WinZip -- as mentioned at the beginning of this list of

    steps.

<li>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 <a href="http://www.trolltech.com">Qt Software</a>. 

    See doxygen download page for a link. 

<li>If you used WinZip to extract the tar archive it will (apparently) not 

    create empty folders, so you have to add the folders

    <code>objects</code> and <code>bin</code> manually in the root of the 

    distribution before compiling.

</ul>

Compilation is now done by performing the following steps:

<ol>

<li>Open a dos box.

    Make sure all tools (i.e. <code>nmake</code>, <code>latex</code>, 

    <code>gswin32</code>, <code>dvips</code>, <code>sed</code>, 

    <code>flex</code>, <code>bison</code>, <code>cl</code>,

    <code>rm</code>, and <code>perl</code>), are accessible from

    the command-line (add them to the PATH environment variable if

    needed).