diff options
Diffstat (limited to 'doc/install.doc')
| -rw-r--r-- | doc/install.doc | 643 |
1 files changed, 643 insertions, 0 deletions
diff --git a/doc/install.doc b/doc/install.doc new file mode 100644 index 0000000..d8a75a2 --- /dev/null +++ b/doc/install.doc @@ -0,0 +1,643 @@ +/****************************************************************************** + * + * + * + * Copyright (C) 1997-2012 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 +\tableofcontents + +First go to the +<a href="http://www.doxygen.org/download.html">download</a> page +to get the latest distribution, if you did not downloaded doxygen already. + +\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> + \addindex perl +<li>The configure script assume the availability 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://qt.nokia.com/">Qt</A> + \addindex Qt + version 4.3 or higher. + 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> + 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> + 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: + + gunzip doxygen-$VERSION.src.tar.gz # uncompress the archive + tar xf doxygen-$VERSION.src.tar # unpack it + +<li>Run the configure script: + + sh ./configure + + 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: + + configure --platform platform-type + + See the <code>PLATFORMS</code> file for a list of possible platform + options. + + If you have Qt-4.3 or higher installed and want to build the GUI + front-end, you should run the configure script with + the <code>--with-doxywizard</code> option: + + configure --with-doxywizard + + For an overview of other configuration options use + + configure --help + +<li>Compile the program by running make: + + make + + The program should compile without problems and the binaries + (<code>doxygen</code> and optionally <code>doxywizard</code>) + should be available in the bin directory of the distribution. + +<li>Optional: Generate the user manual. + + make docs + + 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). + + make pdf + + 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: + + ./configure + make install + +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: + + mkdir qt + cd qt + ln -s your-qt-include-dir-here include + ln -s your-qt-lib-dir-here lib + ln -s your-qt-bin-dir-here bin + export QTDIR=$PWD + +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: + + /opt/aCC/lbin/ld: Unsatisfied symbols: + alloca (code) + +then you should (according to Anke Selig) edit <code>ce_parse.cpp</code> +and replace + + extern "C" { + void *alloca (unsigned int); + }; + +with + + #include <alloca.h> + +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 `--static` 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 `-Bdynamic` after the target rule in +`Makefile.doxygen` will fix this: + + $(TARGET): $(OBJECTS) $(OBJMOC) + $(LINK) $(LFLAGS) -o $(TARGET) $(OBJECTS) $(OBJMOC) $(LIBS) -Bdynamic + +<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.7.0 onwards, build files are provided for Visual Studio 2008. +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>. + +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. + +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 by right-clicking +the project in the solutions explorer, and selecting Build. + +Note that compiling Doxywizard currently requires Qt version 4 +(see http://qt.nokia.com/products/platform/qt-for-windows). + +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> + + Alternatively, you can also choose to + download only a <a href="http://www.doxygen.org/dl/cygwin_tools.zip">small subset</a> + 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 that is needed for to compile doxygen. + The Windows specific part were also created. + As a result doxygen (without the wizard) can be compiled on systems + without X11 or (the commerical version of) Qt. + +<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). + + Notice: The use of LaTeX is optional and only needed for compilation + of the documentation into PostScript or PDF. + It is \e not needed for compiling the doxygen's binaries. + +<li>Go to the doxygen root dir and type: + +\verbatim + make.bat msvc +\endverbatim + + This should build the executable + <code>doxygen.exe</code> using Microsoft's Visual C++ compiler + (The compiler should not produce any serious warnings or errors). + + You can use also the <code>bcc</code> argument to build + executables using the Borland C++ compiler, or + <code>mingw</code> argument to compile using GNU gcc. + +<li>To build the examples, go to the <code>examples</code> subdirectory + and type: + +\verbatim + nmake +\endverbatim + +<li>To generate the doxygen documentation, go to the <code>doc</code> + subdirectory and type: + +\verbatim + nmake +\endverbatim + + The generated HTML docs are located in the <code>..\\html</code> + subdirectory. + + The sources for LaTeX documentation are located in the <code>..\\latex</code> + subdirectory. From those sources, the DVI, PostScript, and PDF + documentation can be generated. +</ol> + +--> + +\section install_bin_windows Installing the binaries on Windows + +Doxygen comes as a self-installing archive, so installation is extremely simple. +Just follow the dialogs. + +After installation it is recommended to also download and install GraphViz +(version 2.20 or better is highly recommended). Doxygen can use the \c dot tool +of the GraphViz package to render nicer diagrams, see the +\ref cfg_have_dot "HAVE_DOT" option in the configuration file. + +If you want to produce compressed HTML files (see \ref +cfg_generate_htmlhelp "GENERATE_HTMLHELP") in the config file, then +you need the Microsoft HTML help workshop. +You can download it from +<a href="http://msdn.microsoft.com/library/default.asp?url=/library/en-us/htmlhelp/html/vsconHH1Start.asp">Microsoft</a>. + +If you want to produce Qt Compressed Help files (see \ref +cfg_qhg_location "QHG_LOCATION") in the config file, then +you need qhelpgenerator which is part of Qt. +You can download Qt from <a href="http://trolltech.com/downloads/">Qt Software Downloads</a>. + +In order to generate PDF output or use scientific formulas you will also need to +install <a href="http://en.wikipedia.org/wiki/LaTeX">LaTeX</a> and +<a href="http://en.wikipedia.org/wiki/Ghostscript">Ghostscript</a>. + +For LaTeX a number of distributions exists. Popular ones that should work with +doxygen are <a href="http://www.miktex.org">MikTex</a> +and <a href="http://www.xemtex.org">XemTex</a>. + +Ghostscript can be <a href="http://sourceforge.net/projects/ghostscript/">downloaded</a> +from Sourceforge. + +After installing LaTeX and Ghostscript you'll need to make sure the tools +latex.exe, pdflatex.exe, and gswin32c.exe are present in the search path of a +command box. Follow <a href="http://www.computerhope.com/issues/ch000549.htm">these</a> +instructions if you are unsure and run the commands from a command box to verify it works. + +<!-- +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 <code>bin</code> directory +to a location somewhere in the path. Alternatively, you can include +the <code>bin</code> 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: + +<ul> +<li>To generate LaTeX documentation or formulas in HTML you need the tools: + <code>latex</code>, <code>dvips</code> and <code>gswin32</code>. + To get these working under Windows + install the fpTeX distribution. You can find more info at: + http://www.fptex.org/ and download it from CTAN or one of its mirrors. + In the Netherlands for example this would be: + 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 LaTeX is freely available set of so + called macros and styles on the top of the famous TeX 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 + <code>DVI</code> (DeVice Independent) file -- can be printed or + displayed on various devices preserving exactly the same look up + to the capability of the device. The <code>dvips</code> allows you + to convert the <code>dvi</code> to the high quality PostScript + (i.e. PostScript that can be processed by utilities like + <code>psnup</code>, <code>psbook</code>, <code>psselect</code>, + and others). The derived version of TeX (the pdfTeX) can be used + to produce PDF output instead of DVI, or the PDF can be produced + from PostScript using the utility <code>ps2pdf</code>. + + If you want to use MikTeX then you need to select at least the + medium size installation. For really old versions of MikTex or minimal + installations, you may need to download the fancyhdr package separately. + You can find it in the + <a href="ftp://ftp.tex.ac.uk/tex-archive/macros/latex/contrib/supported/fancyhdr/"> + contrib/supported</a> directory of the tex archives. + +<li>If you want to generate compressed HTML help + (see \ref cfg_generate_htmlhelp "GENERATE_HTMLHELP") in the + config file, then you need the Microsoft HTML help workshop. + You can download it from + <a href="http://msdn.microsoft.com/library/default.asp?url=/library/en-us/htmlhelp/html/vsconHH1Start.asp">Microsoft</a>. + +<li>If you want to produce Qt Compressed Help files (see \ref + cfg_qhelgenerator_loc "QHG_LOCATION") in the config file, + then you need qhelpgenerator which is part of Qt. + You can download Qt from + <a href="http://trolltech.com/downloads/">Qt Software Downloads</a>. + +<li><a href="http://www.graphviz.org/"> + the Graph visualization toolkit version 1.8.10</a><br> + Needed for the include dependency graphs, the graphical inheritance graphs, + and the collaboration graphs. +</ul> + +--> + +\section build_tools Tools used to develop doxygen + +Doxygen was developed and tested under Linux & MacOSX using the following +open-source tools: +<ul> +<li>GCC version 3.3.6 (Linux) and 4.0.1 (MacOSX) +<li>GNU flex version 2.5.33 (Linux) and 2.5.4 (MacOSX) +<li>GNU bison version 1.75 +<li>GNU make version 3.80 +<li>Perl version 5.8.1 +<li>VIM version 6.2 +<li>Firefox 1.5 +<li>Trolltech's tmake version 1.3 (included in the distribution) +<li>teTeX version 2.0.2 +<li>CVS 1.12.12 +</ul> + +\htmlonly +Go to the <a href="starting.html">next</a> section or return to the + <a href="index.html">index</a>. +\endhtmlonly + +*/ + |