1 /******************************************************************************
5 * Copyright (C) 1997-2012 by Dimitri van Heesch.
7 * Permission to use, copy, modify, and distribute this software and its
8 * documentation under the terms of the GNU General Public License is hereby
9 * granted. No representations are made about the suitability of this software
10 * for any purpose. It is provided "as is" without express or implied warranty.
11 * See the GNU General Public License for more details.
13 * Documents produced by Doxygen are derivative works derived from the
14 * input used in their production; they are not affected by this license.
17 /*! \page install Installation
19 \addindex installation
23 <a href="http://www.doxygen.org/download.html">download</a> page
24 to get the latest distribution, if you did not downloaded doxygen already.
26 \section install_src_unix Compiling from source on UNIX
28 If you downloaded the source distribution, you need at least the
29 following to build the executable:
31 <li>The <a href="ftp://prep.ai.mit.edu/pub/gnu/">GNU</a> tools
32 flex, bison and GNU make, and strip
37 <li>In order to generate a Makefile for your platform, you need
38 <a href="http://www.perl.com/">perl</a>
40 <li>The configure script assume the availability of standard UNIX tools such
41 as sed, date, find, uname, mv, cp, cat, echo, tr, cd, and rm.
44 To take full advantage of doxygen's features the following additional
45 tools should be installed.
48 <li>Qt Software's GUI toolkit
49 <a href="http://qt.nokia.com/">Qt</A>
51 version 4.3 or higher.
52 This is needed to build the GUI front-end doxywizard.
53 <li>A \f$\mbox{\LaTeX}\f$ distribution: for instance
54 <a href="http://www.tug.org/interest.html#free">teTeX 1.0</a>
55 This is needed for generating LaTeX, Postscript, and PDF output.
56 <li><a href="http://www.graphviz.org/">
57 the Graph visualization toolkit version 1.8.10 or higher</a>
58 Needed for the include dependency graphs,
59 the graphical inheritance graphs, and the collaboration graphs.
60 If you compile graphviz yourself, make sure you do include
61 freetype support (which requires the freetype library and header files),
62 otherwise the graphs will not render proper text labels.
63 <li>For formulas or if you do not wish to use pdflatex, the ghostscript interpreter
64 is needed. You can find it at
65 <a href="http://www.ghostscript.com/">www.ghostscript.com</a>.
66 <li>In order to generate doxygen's own documentation, Python is needed, you
67 can find it at <a href="http://www.python.org">www.python.org</a>.
70 Compilation is now done by performing the following steps:
73 <li>Unpack the archive, unless you already have done that:
75 gunzip doxygen-$VERSION.src.tar.gz # uncompress the archive
76 tar xf doxygen-$VERSION.src.tar # unpack it
78 <li>Run the configure script:
82 The script tries to determine the platform you use, the make tool
83 (which \e must be GNU make) and the perl
84 interpreter. It will report what it finds.
86 To override the auto detected platform and compiler you can run
89 configure --platform platform-type
91 See the <code>PLATFORMS</code> file for a list of possible platform
94 If you have Qt-4.3 or higher installed and want to build the GUI
95 front-end, you should run the configure script with
96 the <code>--with-doxywizard</code> option:
98 configure --with-doxywizard
100 For an overview of other configuration options use
104 <li>Compile the program by running make:
108 The program should compile without problems and the binaries
109 (<code>doxygen</code> and optionally <code>doxywizard</code>)
110 should be available in the bin directory of the distribution.
112 <li>Optional: Generate the user manual.
116 To let doxygen generate the HTML documentation.
118 The HTML directory of the distribution will now contain the html
119 documentation (just point a HTML browser to the file
120 <code>index.html</code> in the
121 html directory). You will need the <code>python</code> interpreter
124 <li>Optional: Generate a PDF version of the manual
125 (you will need <code>pdflatex</code>, <code>makeindex</code>, and
126 <code>egrep</code> for this).
130 The PDF manual <code>doxygen_manual.pdf</code> will be located
131 in the latex directory of the distribution. Just
132 view and print it via the acrobat reader.
136 \section install_bin_unix Installing the binaries on UNIX
138 After the compilation of the source code do a <code>make install</code>
139 to install doxygen. If you downloaded the binary distribution for UNIX,
145 Binaries are installed into the directory <code>\<prefix\>/bin</code>.
146 Use <code>make install_docs</code> to install the
147 documentation and examples into <code>\<docdir\>/doxygen</code>.
149 <code>\<prefix\></code> defaults to <code>/usr/local</code> but can be changed with
150 the <code>--prefix</code> option of the configure script.
151 The default <code>\<docdir\></code> directory is
152 <code>\<prefix\>/share/doc/packages</code> and can be changed with
153 the <code>--docdir</code> option of the configure script.
155 Alternatively, you can also copy the binaries from the <code>bin</code>
156 directory manually to some <code>bin</code> directory in your search path.
157 This is sufficient to use doxygen.
159 \note You need the GNU install tool for this to work (it is part of
160 the coreutils package). Other install tools may put the binaries in
163 If you have a RPM or DEP package, then please follow the
164 standard installation procedure that is required for these packages.
166 \section unix_problems Known compilation problems for UNIX
170 The Qt include files and libraries are not a subdirectory of the
171 directory pointed to by QTDIR on some systems
172 (for instance on Red Hat 6.0 includes are in /usr/include/qt and
173 libs are in /usr/lib).
175 The solution: go to the root of the doxygen distribution and do:
179 ln -s your-qt-include-dir-here include
180 ln -s your-qt-lib-dir-here lib
181 ln -s your-qt-bin-dir-here bin
184 If you have a csh-like shell you should use <code>setenv QTDIR \$PWD</code>
185 instead of the <code>export</code> command above.
187 Now install doxygen as described above.
189 <b>Bison problems</b>
191 Versions 1.31 to 1.34 of bison contain a "bug" that results in a
192 compiler errors like this:
194 ce_parse.cpp:348: member `class CPPValue yyalloc::yyvs' with
195 constructor not allowed in union
197 This problem has been solved in version 1.35 (versions before 1.31
200 <b>Latex problems</b>
202 The file <code>a4wide.sty</code> is not available for all distributions. If
203 your distribution does not have it please select another paper type
204 in the config file (see the \ref cfg_paper_type "PAPER_TYPE" tag in the
207 <b>HP-UX \& Digital UNIX problems</b>
209 If you are compiling for HP-UX with aCC and you get this error:
211 /opt/aCC/lbin/ld: Unsatisfied symbols:
214 then you should (according to Anke Selig) edit <code>ce_parse.cpp</code>
218 void *alloca (unsigned int);
225 If that does not help, try removing <code>ce_parse.cpp</code> and let
226 bison rebuild it (this worked for me).
228 If you are compiling for Digital UNIX, the same problem can be solved
229 (according to Barnard Schmallhof) by replacing the following in
233 #else /* not GNU C. */
234 #if (!defined (__STDC__) && defined (sparc)) || defined (__sparc__) \
235 || defined (__sparc) || defined (__sgi)
242 #else /* not GNU C. */
243 #if (!defined (__STDC__) && defined (sparc)) || defined (__sparc__) \
244 || defined (__sparc) || defined (__sgi) || defined (__osf__)
248 Alternatively, one could fix the problem at the bison side.
249 Here is patch for bison.simple (provided by Andre Johansen):
252 --- bison.simple~ Tue Nov 18 11:45:53 1997
253 +++ bison.simple Mon Jan 26 15:10:26 1998
256 #define alloca __builtin_alloca
257 #else /* not GNU C. */
258 -#if (!defined (__STDC__) && defined (sparc)) || defined (__sparc__) \
259 || defined (__sparc) || defined (__sgi)
260 +#if (!defined (__STDC__) && defined (sparc)) || defined (__sparc__) \
261 || defined (__sparc) || defined (__sgi) || defined (__alpha)
263 #else /* not sparc */
264 #if defined (MSDOS) && !defined (__TURBOC__)
267 The generated scanner.cpp that comes with doxygen is build with this
270 <b>Sun compiler problems</b>
272 It appears that doxygen doesn't work properly if it is compiled
273 with Sun's C++ WorkShop 6 Compiler. I cannot verify this myself as I do
274 not have access to a Solaris machine with this compiler. With GNU compiler
275 it does work and installing Sun patch 111679-13 has also been reported
276 as a way to fix the problem.
278 when configuring with `--static` I got:
281 Undefined first referenced
283 dlclose /usr/lib/libc.a(nss_deffinder.o)
284 dlsym /usr/lib/libc.a(nss_deffinder.o)
285 dlopen /usr/lib/libc.a(nss_deffinder.o)
288 Manually adding `-Bdynamic` after the target rule in
289 `Makefile.doxygen` will fix this:
291 $(TARGET): $(OBJECTS) $(OBJMOC)
292 $(LINK) $(LFLAGS) -o $(TARGET) $(OBJECTS) $(OBJMOC) $(LIBS) -Bdynamic
294 <b>GCC compiler problems</b>
296 Older versions of the GNU compiler have problems with constant strings
297 containing characters with character codes larger than 127. Therefore
298 the compiler will fail to compile some of the translator_xx.h files.
299 A workaround, if you are planning to use the English translation only,
300 is to configure doxygen with the <code>--english-only</code> option.
302 On some platforms (such as OpenBSD) using some versions of gcc with
303 -O2 can lead to eating all memory during the compilation of files
304 such as config.cpp. As a workaround use --debug as a configure option
305 or omit the -O2 for the particular files in the Makefile.
307 Gcc versions before 2.95 may produce broken binaries due to bugs in
312 Due to a change in the way image maps are generated, older versions
313 of doxygen (\<=1.2.17) will not work correctly with newer versions of
314 graphviz (\>=1.8.8). The effect of this incompatibility is that
315 generated graphs in HTML are not properly clickable. For doxygen 1.3
316 it is recommended to use at least graphviz 1.8.10 or higher.
317 For doxygen 1.4.7 or higher it is recommended to
318 use GraphViz 2.8 or higher to avoid font issues.
320 <b>Red Hat 9.0 problems</b>
322 If you get the following error after running make
324 tmake error: qtools.pro:70: Syntax error
332 \section install_src_windows Compiling from source on Windows
334 From version 1.7.0 onwards, build files are provided for Visual Studio 2008.
335 Also the free (as in beer) "Express" version of Developer Studio can be used to
336 compile doxygen. Alternatively, you can compile doxygen
337 \ref install_src_unix "the UNIX way" using
338 <a href="http://en.wikipedia.org/wiki/Cygwin">Cygwin</a>
339 or <a href="http://www.mingw.org/">MinGW</a>.
341 The next step is to install unxutils (see http://sourceforge.net/projects/unxutils).
342 This packages contains the tools \c flex and \c bison which are needed during the
343 compilation process if you use a CVS snapshot of doxygen (the official source releases
344 come with pre-generated sources).
345 Download the zip extract it to e.g. <code>c:\\tools\\unxutils</code>.
347 Now you need to add/adjust the following environment variables
348 (via Control Panel/System/Advanced/Environment Variables):
349 - add <code>c:\\tools\\unxutils\\usr\\local\\wbin;</code> to the start of <code>PATH</code>
350 - set <code>BISON_SIMPLE</code> to <code>c:\\tools\\unxutils\\usr\\local\\share\\bison.simple</code>
352 Download doxygen's source tarball and put it somewhere (e.g. use <code>c:\\tools</code>)
354 Now start a new command shell and type
357 gunzip doxygen-x.y.z.src.tar.gz
358 tar xvf doxygen-x.y.z.src.tar
360 to unpack the sources.
362 Now your environment is setup to build \c doxygen.
364 Inside the \c doxygen-x.y.z directory you will find a \c winbuild directory
365 containing a \c Doxygen.sln file. Open this file in Visual Studio.
366 You can now build the Release or Debug flavor of Doxygen by right-clicking
367 the project in the solutions explorer, and selecting Build.
369 Note that compiling Doxywizard currently requires Qt version 4
370 (see http://qt.nokia.com/products/platform/qt-for-windows).
372 Also read the next section for additional tools you may need to install to run
373 doxygen with certain features enabled.
377 Currently, I have only compiled doxygen for Windows using Microsoft's
378 Visual C++ (). For other compilers you may need to edit the
379 perl script in <code>wintools/make.pl</code> a bit.
380 Let me know what you had to change if you got Doxygen working with another
381 compiler. If you have Visual Studio you can also use the .dsw file found in
382 the <code>wintools</code> directory. Note that this file is not maintained
383 by me, so it might be outdated a little.
385 If you have Visual C++ 6.0, and the source distribution, you can easily
386 build doxygen using the project files in the \c wintools directory. If
387 you want to build the CVS sources, or want to build from the command line,
388 or with another compiler, you have to follow the steps below.
390 Thomas Baust reported that if you have Visual Studio.NET (2003) then
391 you should be aware that there is a problem with the _popen() and _pclose()
392 implementation, which currently leaks handles, so if you build doxygen with
393 it and use the INPUT_FILTER, you will run to risk of crashing Windows!
394 The problem is reported to and confirmed by Microsoft so maybe it will
395 fixed in the next service pack.
397 Since Windows comes without all the nice tools that UNIX users are
398 used to, you'll need to install a number of these tools before you can compile
399 doxygen for Windows from the command-line.
401 Here is what is required:
403 <li>An unzip/untar tool like WinZip to unpack the tar source distribution.
404 This can be found at http://www.winzip.com/
406 The good, tested, and free alternative is the <code>tar</code> utility
407 supplied with <a href="http://sourceware.cygnus.com/cygwin/">cygwin
408 tools</a>. Anyway, the cygwin's flex, bison, and sed are also
411 <li>Microsoft Visual C++ (I only tested with version 6.0).
412 Use the <code>vcvars32.bat</code> batch file to set the environment
413 variables (if you did not select to do this automatically during
416 Borland C++ or MINGW (see http://www.mingw.org/) are also supported.
418 <li>Perl 5.0 or higher for Windows. This can be downloaded from:
419 http://www.ActiveState.com/Products/ActivePerl/
421 <li>The GNU tools flex, bison, and sed.
422 To get these working on Windows you should install the
423 <a href="http://sources.redhat.com/cygwin/">cygwin tools</a>
425 Alternatively, you can also choose to
426 download only a <a href="http://www.doxygen.org/dl/cygwin_tools.zip">small subset</a>
427 of the cygwin tools that I put together just to compile doxygen.
429 As a third alternative one could use the GNUWin32 tools that can be
430 found at http://gnuwin32.sourceforge.net/
432 Make sure the <code>BISON_SIMPLE</code> environment variable points to the
433 location where the files <code>bison.simple</code> and
434 is located. For instance if these file is in
435 <code>c:\\tools\\cygwin\\usr\\share</code> then BISON_SIMPLE should
436 be set to <code>c:/tools/cygwin/usr/share/bison.simple</code>
438 Also make sure the tools are available from a dos box, by adding
439 the directory they are in to the search path.
441 For those of you who are very new to cygwin (if you are going to
442 install it from scratch), you should notice that there is an
443 archive file <code>bootstrap.zip</code> which also contains the
444 <code>tar</code> utility (<code>tar.exe</code>), <code>gzip</code>
445 utilities, and the <code>cygwin1.dll</code> core. This also means
446 that you have the <code>tar</code> in hands from the start. It
447 can be used to unpack the tar source distribution instead of
448 using WinZip -- as mentioned at the beginning of this list of
451 <li>From Doxygen-1.2.2-20001015 onwards, the distribution includes the part
452 of Qt that is needed for to compile doxygen.
453 The Windows specific part were also created.
454 As a result doxygen (without the wizard) can be compiled on systems
455 without X11 or (the commerical version of) Qt.
457 <li>If you used WinZip to extract the tar archive it will (apparently) not
458 create empty folders, so you have to add the folders
459 <code>objects</code> and <code>bin</code> manually in the root of the
460 distribution before compiling.
465 Compilation is now done by performing the following steps:
469 Make sure all tools (i.e. <code>nmake</code>, <code>latex</code>,
470 <code>gswin32</code>, <code>dvips</code>, <code>sed</code>,
471 <code>flex</code>, <code>bison</code>, <code>cl</code>,
472 <code>rm</code>, and <code>perl</code>), are accessible from
473 the command-line (add them to the PATH environment variable if
476 Notice: The use of LaTeX is optional and only needed for compilation
477 of the documentation into PostScript or PDF.
478 It is \e not needed for compiling the doxygen's binaries.
480 <li>Go to the doxygen root dir and type:
486 This should build the executable
487 <code>doxygen.exe</code> using Microsoft's Visual C++ compiler
488 (The compiler should not produce any serious warnings or errors).
490 You can use also the <code>bcc</code> argument to build
491 executables using the Borland C++ compiler, or
492 <code>mingw</code> argument to compile using GNU gcc.
494 <li>To build the examples, go to the <code>examples</code> subdirectory
501 <li>To generate the doxygen documentation, go to the <code>doc</code>
502 subdirectory and type:
508 The generated HTML docs are located in the <code>..\\html</code>
511 The sources for LaTeX documentation are located in the <code>..\\latex</code>
512 subdirectory. From those sources, the DVI, PostScript, and PDF
513 documentation can be generated.
518 \section install_bin_windows Installing the binaries on Windows
520 Doxygen comes as a self-installing archive, so installation is extremely simple.
521 Just follow the dialogs.
523 After installation it is recommended to also download and install GraphViz
524 (version 2.20 or better is highly recommended). Doxygen can use the \c dot tool
525 of the GraphViz package to render nicer diagrams, see the
526 \ref cfg_have_dot "HAVE_DOT" option in the configuration file.
528 If you want to produce compressed HTML files (see \ref
529 cfg_generate_htmlhelp "GENERATE_HTMLHELP") in the config file, then
530 you need the Microsoft HTML help workshop.
531 You can download it from
532 <a href="http://msdn.microsoft.com/library/default.asp?url=/library/en-us/htmlhelp/html/vsconHH1Start.asp">Microsoft</a>.
534 If you want to produce Qt Compressed Help files (see \ref
535 cfg_qhg_location "QHG_LOCATION") in the config file, then
536 you need qhelpgenerator which is part of Qt.
537 You can download Qt from <a href="http://trolltech.com/downloads/">Qt Software Downloads</a>.
539 In order to generate PDF output or use scientific formulas you will also need to
540 install <a href="http://en.wikipedia.org/wiki/LaTeX">LaTeX</a> and
541 <a href="http://en.wikipedia.org/wiki/Ghostscript">Ghostscript</a>.
543 For LaTeX a number of distributions exists. Popular ones that should work with
544 doxygen are <a href="http://www.miktex.org">MikTex</a>
545 and <a href="http://www.xemtex.org">XemTex</a>.
547 Ghostscript can be <a href="http://sourceforge.net/projects/ghostscript/">downloaded</a>
550 After installing LaTeX and Ghostscript you'll need to make sure the tools
551 latex.exe, pdflatex.exe, and gswin32c.exe are present in the search path of a
552 command box. Follow <a href="http://www.computerhope.com/issues/ch000549.htm">these</a>
553 instructions if you are unsure and run the commands from a command box to verify it works.
556 There is no fancy installation procedure at the moment (if anyone can
557 add it in a location independent way please let me know).
559 To install doxygen, just copy the binaries from the <code>bin</code> directory
560 to a location somewhere in the path. Alternatively, you can include
561 the <code>bin</code> directory of the distribution to the path.
563 There are a couple of tools you may want to install to use all of doxygen's
567 <li>To generate LaTeX documentation or formulas in HTML you need the tools:
568 <code>latex</code>, <code>dvips</code> and <code>gswin32</code>.
569 To get these working under Windows
570 install the fpTeX distribution. You can find more info at:
571 http://www.fptex.org/ and download it from CTAN or one of its mirrors.
572 In the Netherlands for example this would be:
573 ftp://ftp.easynet.nl/mirror/CTAN/systems/win32/fptex/
575 Make sure the tools are available from a dos box, by adding the
576 directory they are in to the search path.
578 For your information, the LaTeX is freely available set of so
579 called macros and styles on the top of the famous TeX program
580 (by famous Donald Knuth) and the accompanied utilities (all
581 available for free). It is used for high quality
582 typesetting. The result -- in the form of so called
583 <code>DVI</code> (DeVice Independent) file -- can be printed or
584 displayed on various devices preserving exactly the same look up
585 to the capability of the device. The <code>dvips</code> allows you
586 to convert the <code>dvi</code> to the high quality PostScript
587 (i.e. PostScript that can be processed by utilities like
588 <code>psnup</code>, <code>psbook</code>, <code>psselect</code>,
589 and others). The derived version of TeX (the pdfTeX) can be used
590 to produce PDF output instead of DVI, or the PDF can be produced
591 from PostScript using the utility <code>ps2pdf</code>.
593 If you want to use MikTeX then you need to select at least the
594 medium size installation. For really old versions of MikTex or minimal
595 installations, you may need to download the fancyhdr package separately.
596 You can find it in the
597 <a href="ftp://ftp.tex.ac.uk/tex-archive/macros/latex/contrib/supported/fancyhdr/">
598 contrib/supported</a> directory of the tex archives.
600 <li>If you want to generate compressed HTML help
601 (see \ref cfg_generate_htmlhelp "GENERATE_HTMLHELP") in the
602 config file, then you need the Microsoft HTML help workshop.
603 You can download it from
604 <a href="http://msdn.microsoft.com/library/default.asp?url=/library/en-us/htmlhelp/html/vsconHH1Start.asp">Microsoft</a>.
606 <li>If you want to produce Qt Compressed Help files (see \ref
607 cfg_qhelgenerator_loc "QHG_LOCATION") in the config file,
608 then you need qhelpgenerator which is part of Qt.
609 You can download Qt from
610 <a href="http://trolltech.com/downloads/">Qt Software Downloads</a>.
612 <li><a href="http://www.graphviz.org/">
613 the Graph visualization toolkit version 1.8.10</a><br>
614 Needed for the include dependency graphs, the graphical inheritance graphs,
615 and the collaboration graphs.
620 \section build_tools Tools used to develop doxygen
622 Doxygen was developed and tested under Linux & MacOSX using the following
625 <li>GCC version 3.3.6 (Linux) and 4.0.1 (MacOSX)
626 <li>GNU flex version 2.5.33 (Linux) and 2.5.4 (MacOSX)
627 <li>GNU bison version 1.75
628 <li>GNU make version 3.80
629 <li>Perl version 5.8.1
632 <li>Trolltech's tmake version 1.3 (included in the distribution)
633 <li>teTeX version 2.0.2
638 Go to the <a href="starting.html">next</a> section or return to the
639 <a href="index.html">index</a>.