1 /******************************************************************************
5 * Copyright (C) 1997-2014 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 have 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 \c flex, \c bison, \c libiconv and <code>GNU make</code>, and \c strip
38 <li>In order to generate a \c Makefile for your platform, you need
39 <a href="http://www.perl.com/">perl</a>
41 <li>The configure script assume the availability of standard UNIX tools such
42 as <code>sed, date, find, uname, mv, cp, cat, echo, tr, cd</code> and \c rm.
45 To take full advantage of doxygen's features the following additional
46 tools should be installed.
49 <li>Qt Software's GUI toolkit
50 <a href="http://qt-project.org/">Qt</A>
52 version 4.3 or higher (but currently, Qt 5.x is not supported).
53 This is needed to build the GUI front-end doxywizard.
54 <li>A \LaTeX distribution: for instance
55 <a href="http://www.tug.org/interest.html#free">TeX Live</a>
56 This is needed for generating \LaTeX, Postscript, and PDF output.
57 <li><a href="http://www.graphviz.org/">
58 the Graph visualization toolkit version 1.8.10 or higher</a>
59 Needed for the include dependency graphs,
60 the graphical inheritance graphs, and the collaboration graphs.
61 If you compile graphviz yourself, make sure you do include
62 freetype support (which requires the freetype library and header files),
63 otherwise the graphs will not render proper text labels.
64 <li>For formulas or if you do not wish to use `pdflatex, the ghostscript interpreter
65 is needed. You can find it at
66 <a href="http://www.ghostscript.com/">www.ghostscript.com</a>.
67 <li>In order to generate doxygen's own documentation, Python is needed, you
68 can find it at <a href="http://www.python.org">www.python.org</a>.
71 Compilation is now done by performing the following steps:
74 <li>Unpack the archive, unless you already have done that:
76 gunzip doxygen-$VERSION.src.tar.gz # uncompress the archive
77 tar xf doxygen-$VERSION.src.tar # unpack it
79 <li>Run the configure script:
83 The script tries to determine the platform you use, the make tool
84 (which \e must be GNU make) and the perl
85 interpreter. It will report what it finds.
87 To override the auto detected platform and compiler you can run
90 configure --platform platform-type
92 See the <code>PLATFORMS</code> file for a list of possible platform
95 If you have Qt-4.3 or higher installed and want to build the GUI
96 front-end, you should run the configure script with
97 the `--with-doxywizard` option:
99 configure --with-doxywizard
101 For an overview of other configuration options use
105 <li>Compile the program by running make:
109 The program should compile without problems and the binaries
110 (<code>doxygen</code> and optionally <code>doxywizard</code>)
111 should be available in the bin directory of the distribution.
113 <li>Optional: Generate the user manual.
117 To let doxygen generate the HTML documentation.
119 The HTML directory of the distribution will now contain the html
120 documentation (just point a HTML browser to the file
121 <code>index.html</code> in the
122 html directory). You will need the <code>python</code> interpreter
125 <li>Optional: Generate a PDF version of the manual
126 (you will need <code>pdflatex</code>, <code>makeindex</code>, and
127 <code>egrep</code> for this).
131 The PDF manual <code>doxygen_manual.pdf</code> will be located
132 in the latex directory of the distribution. Just
133 view and print it via the acrobat reader.
137 \section install_bin_unix Installing the binaries on UNIX
139 After the compilation of the source code do a <code>make install</code>
140 to install doxygen. If you downloaded the binary distribution for UNIX,
146 Binaries are installed into the directory <code>\<prefix\>/bin</code>.
147 Use <code>make install_docs</code> to install the
148 documentation and examples into <code>\<docdir\>/doxygen</code>.
150 <code>\<prefix\></code> defaults to <code>/usr/local</code> but can be changed with
151 the `--prefix` option of the configure script.
152 The default <code>\<docdir\></code> directory is
153 <code>\<prefix\>/share/doc/packages</code> and can be changed with
154 the `--docdir` option of the configure script.
156 Alternatively, you can also copy the binaries from the <code>bin</code>
157 directory manually to some <code>bin</code> directory in your search path.
158 This is sufficient to use doxygen.
160 \note You need the GNU install tool for this to work (it is part of
161 the coreutils package). Other install tools may put the binaries in
164 If you have a RPM or DEP package, then please follow the
165 standard installation procedure that is required for these packages.
167 \section unix_problems Known compilation problems for UNIX
171 The Qt include files and libraries are not a subdirectory of the
172 directory pointed to by <code>QTDIR</code> on some systems
173 (for instance on Red Hat 6.0 includes are in <code>/usr/include/qt</code> and
174 libs are in <code>/usr/lib</code>).
176 The solution: go to the root of the doxygen distribution and do:
180 ln -s your-qt-include-dir-here include
181 ln -s your-qt-lib-dir-here lib
182 ln -s your-qt-bin-dir-here bin
185 If you have a <code>csh</code>-like shell you should use <code>setenv QTDIR \$PWD</code>
186 instead of the <code>export</code> command above.
188 Now install doxygen as described above.
190 <b>Bison problems</b>
192 Versions 1.31 to 1.34 of \c bison contain a "bug" that results in a
193 compiler errors like this:
195 <code>ce_parse.cpp:348: member `class CPPValue yyalloc::yyvs' with </code>
196 constructor not allowed in union
198 This problem has been solved in version 1.35 (versions before 1.31
201 <b>Sun compiler problems</b>
203 It appears that doxygen doesn't work properly if it is compiled
204 with Sun's C++ WorkShop Compiler. I cannot verify this myself as I do
205 not have access to a Solaris machine with this compiler. With GNU compiler
206 it does work and installing Sun patch 111679-13 has also been reported
207 as a way to fix the problem.
209 when configuring with `--static` I got:
212 Undefined first referenced
214 dlclose /usr/lib/libc.a(nss_deffinder.o)
215 dlsym /usr/lib/libc.a(nss_deffinder.o)
216 dlopen /usr/lib/libc.a(nss_deffinder.o)
219 Manually adding `-Bdynamic` after the target rule in
220 `Makefile.doxygen` will fix this:
222 $(TARGET): $(OBJECTS) $(OBJMOC)
223 $(LINK) $(LFLAGS) -o $(TARGET) $(OBJECTS) $(OBJMOC) $(LIBS) -Bdynamic
225 <b>GCC compiler problems</b>
227 Older versions of the GNU compiler have problems with constant strings
228 containing characters with character codes larger than 127. Therefore
229 the compiler will fail to compile some of the `translator_xx.h` files.
230 A workaround, if you are planning to use the English translation only,
231 is to configure doxygen with the `--english-only` option.
233 On some platforms (such as OpenBSD) using some versions of gcc with
234 -O2 can lead to eating all memory during the compilation of files
235 such as config.cpp. As a workaround use `--debug` as a configure option
236 or omit the `-O2` for the particular files in the Makefile.
238 Gcc versions before 2.95 may produce broken binaries due to bugs in
243 Due to a change in the way image maps are generated, older versions
244 of doxygen (\<=1.2.17) will not work correctly with newer versions of
245 graphviz (\>=1.8.8). The effect of this incompatibility is that
246 generated graphs in HTML are not properly clickable. For doxygen 1.3
247 it is recommended to use at least graphviz 1.8.10 or higher.
248 For doxygen 1.4.7 or higher it is recommended to
249 use GraphViz 2.8 or higher to avoid font issues.
251 <b>Red Hat 9.0 problems</b>
253 If you get the following error after running make
255 tmake error: qtools.pro:70: Syntax error
263 \section install_src_windows Compiling from source on Windows
265 From version 1.7.0 onwards, build files are provided for Visual Studio 2008.
266 Also the free (as in beer) "Express" version of Developer Studio can be used to
267 compile doxygen. Alternatively, you can compile doxygen
268 \ref install_src_unix "the UNIX way" using
269 <a href="http://en.wikipedia.org/wiki/Cygwin">Cygwin</a>
270 or <a href="http://www.mingw.org/">MinGW</a>.
272 The next step is to install modern versions of \c bison and \c flex
273 (see http://sourceforge.net/projects/winflexbison. After installation and adding them to
274 your `path` rename `win_flex.exe` to `flex.exe` and `win_bison.exe` to `bison.exe`)
275 Furthermore you have to install \c python (version 2.6 or higher, see http://www.python.org).
276 These packages are needed during the
277 compilation process if you use a GitHub snapshot of doxygen (the official source releases
278 come with pre-generated sources).
280 Download doxygen's source tarball and put it somewhere (e.g. use <code>c:\\tools</code>)
282 Now start a new command shell and type
285 tar zxvf doxygen-x.y.z.src.tar.gz
287 to unpack the sources (you can obtain \c tar from e.g. http://gnuwin32.sourceforge.net/packages.html).
288 Alternatively you can use an unpack program, like 7-Zip (see http://www.7-zip.org)
289 or use the build in unpack feature of modern Windows systems).
291 Now your environment is setup to build \c doxygen.
293 Inside the \c doxygen-x.y.z directory you will find a \c winbuild directory
294 containing a \c Doxygen.sln file. Open this file in Visual Studio.
295 You can now build the Release or Debug flavor of Doxygen by right-clicking
296 the project in the solutions explorer, and selecting Build.
298 Note that compiling Doxywizard currently requires Qt version 4
299 (see http://qt-project.org/).
301 Also read the next section for additional tools you may need to install to run
302 doxygen with certain features enabled.
306 Currently, I have only compiled doxygen for Windows using Microsoft's
307 Visual C++ (). For other compilers you may need to edit the
308 perl script in <code>wintools/make.pl</code> a bit.
309 Let me know what you had to change if you got Doxygen working with another
310 compiler. If you have Visual Studio you can also use the .dsw file found in
311 the <code>wintools</code> directory. Note that this file is not maintained
312 by me, so it might be outdated a little.
314 If you have Visual C++ 6.0, and the source distribution, you can easily
315 build doxygen using the project files in the \c wintools directory. If
316 you want to build the CVS sources, or want to build from the command line,
317 or with another compiler, you have to follow the steps below.
319 Thomas Baust reported that if you have Visual Studio.NET (2003) then
320 you should be aware that there is a problem with the _popen() and _pclose()
321 implementation, which currently leaks handles, so if you build doxygen with
322 it and use the INPUT_FILTER, you will run to risk of crashing Windows!
323 The problem is reported to and confirmed by Microsoft so maybe it will
324 fixed in the next service pack.
326 Since Windows comes without all the nice tools that UNIX users are
327 used to, you'll need to install a number of these tools before you can compile
328 doxygen for Windows from the command-line.
330 Here is what is required:
332 <li>An unzip/untar tool like WinZip to unpack the tar source distribution.
333 This can be found at http://www.winzip.com/
335 The good, tested, and free alternative is the <code>tar</code> utility
336 supplied with <a href="http://sourceware.cygnus.com/cygwin/">cygwin
337 tools</a>. Anyway, the Cygwin's \c flex, \c bison, and \c sed are also
340 <li>Microsoft Visual C++ (I only tested with version 6.0).
341 Use the <code>vcvars32.bat</code> batch file to set the environment
342 variables (if you did not select to do this automatically during
345 Borland C++ or MINGW (see http://www.mingw.org/) are also supported.
347 <li>Perl 5.0 or higher for Windows. This can be downloaded from:
348 http://www.ActiveState.com/Products/ActivePerl/
350 <li>The GNU tools \c flex, \c bison, and \c sed.
351 To get these working on Windows you should install the
352 <a href="http://sources.redhat.com/cygwin/">cygwin tools</a>
354 Alternatively, you can also choose to
355 download only a <a href="http://www.doxygen.org/dl/cygwin_tools.zip">small subset</a>
356 of the cygwin tools that I put together just to compile doxygen.
358 As a third alternative one could use the GNUWin32 tools that can be
359 found at http://gnuwin32.sourceforge.net/
361 Make sure the <code>BISON_SIMPLE</code> environment variable points to the
362 location where the files <code>bison.simple</code> and
363 is located. For instance if these file is in
364 <code>c:\\tools\\cygwin\\usr\\share</code> then BISON_SIMPLE should
365 be set to <code>c:/tools/cygwin/usr/share/bison.simple</code>
367 Also make sure the tools are available from a dos box, by adding
368 the directory they are in to the search path.
370 For those of you who are very new to cygwin (if you are going to
371 install it from scratch), you should notice that there is an
372 archive file <code>bootstrap.zip</code> which also contains the
373 <code>tar</code> utility (<code>tar.exe</code>), <code>gzip</code>
374 utilities, and the <code>cygwin1.dll</code> core. This also means
375 that you have the <code>tar</code> in hands from the start. It
376 can be used to unpack the tar source distribution instead of
377 using WinZip -- as mentioned at the beginning of this list of
380 <li>From Doxygen-1.2.2-20001015 onwards, the distribution includes the part
381 of Qt that is needed for to compile doxygen.
382 The Windows specific part were also created.
383 As a result doxygen (without the wizard) can be compiled on systems
384 without X11 or (the commercial version of) Qt.
386 <li>If you used WinZip to extract the tar archive it will (apparently) not
387 create empty folders, so you have to add the folders
388 <code>objects</code> and <code>bin</code> manually in the root of the
389 distribution before compiling.
394 Compilation is now done by performing the following steps:
398 Make sure all tools (i.e. <code>nmake</code>, <code>latex</code>,
399 <code>gswin32</code>, <code>dvips</code>, <code>sed</code>,
400 <code>flex</code>, <code>bison</code>, <code>cl</code>,
401 <code>rm</code>, and <code>perl</code>), are accessible from
402 the command-line (add them to the PATH environment variable if
405 Notice: The use of \LaTeX is optional and only needed for compilation
406 of the documentation into PostScript or PDF.
407 It is \e not needed for compiling the doxygen's binaries.
409 <li>Go to the doxygen root dir and type:
415 This should build the executable
416 <code>doxygen.exe</code> using Microsoft's Visual C++ compiler
417 (The compiler should not produce any serious warnings or errors).
419 You can use also the <code>bcc</code> argument to build
420 executables using the Borland C++ compiler, or
421 <code>mingw</code> argument to compile using GNU gcc.
423 <li>To build the examples, go to the <code>examples</code> subdirectory
430 <li>To generate the doxygen documentation, go to the <code>doc</code>
431 subdirectory and type:
437 The generated HTML docs are located in the <code>..\\html</code>
440 The sources for \LaTeX documentation are located in the <code>..\\latex</code>
441 subdirectory. From those sources, the DVI, PostScript, and PDF
442 documentation can be generated.
447 \section install_bin_windows Installing the binaries on Windows
449 Doxygen comes as a self-installing archive, so installation is extremely simple.
450 Just follow the dialogs.
452 After installation it is recommended to also download and install GraphViz
453 (version 2.20 or better is highly recommended). Doxygen can use the \c dot tool
454 of the GraphViz package to render nicer diagrams, see the
455 \ref cfg_have_dot "HAVE_DOT" option in the configuration file.
457 If you want to produce compressed HTML files (see \ref
458 cfg_generate_htmlhelp "GENERATE_HTMLHELP") in the config file, then
459 you need the Microsoft HTML help workshop.
460 You can download it from
461 <a href="http://www.microsoft.com/en-us/download/details.aspx?id=21138">Microsoft</a>.
463 If you want to produce Qt Compressed Help files (see \ref
464 cfg_qhg_location "QHG_LOCATION") in the config file, then
465 you need qhelpgenerator which is part of Qt.
466 You can download Qt from <a href="http://qt-project.org/downloads">Qt Software Downloads</a>.
468 In order to generate PDF output or use scientific formulas you will also need to
469 install <a href="http://en.wikipedia.org/wiki/LaTeX">LaTeX</a> and
470 <a href="http://en.wikipedia.org/wiki/Ghostscript">Ghostscript</a>.
472 For \LaTeX a number of distributions exists. Popular ones that should work with
473 doxygen are <a href="http://www.miktex.org">MikTex</a>
474 and <a href="http://www.tug.org/protext/">proTeXt</a>.
476 Ghostscript can be <a href="http://sourceforge.net/projects/ghostscript/">downloaded</a>
479 After installing \LaTeX and Ghostscript you'll need to make sure the tools
480 latex.exe, pdflatex.exe, and gswin32c.exe are present in the search path of a
481 command box. Follow <a href="http://www.computerhope.com/issues/ch000549.htm">these</a>
482 instructions if you are unsure and run the commands from a command box to verify it works.
485 There is no fancy installation procedure at the moment (if anyone can
486 add it in a location independent way please let me know).
488 To install doxygen, just copy the binaries from the <code>bin</code> directory
489 to a location somewhere in the path. Alternatively, you can include
490 the <code>bin</code> directory of the distribution to the path.
492 There are a couple of tools you may want to install to use all of doxygen's
496 <li>To generate \LaTeX documentation or formulas in HTML you need the tools:
497 <code>latex</code>, <code>dvips</code> and <code>gswin32</code>.
498 To get these working under Windows
499 install the fpTeX distribution. You can find more info at:
500 http://www.fptex.org/ and download it from CTAN or one of its mirrors.
501 In the Netherlands for example this would be:
502 ftp://ftp.easynet.nl/mirror/CTAN/systems/win32/fptex/
504 Make sure the tools are available from a dos box, by adding the
505 directory they are in to the search path.
507 For your information, \LaTeX is a freely available set of so
508 called macros and styles on the top of the famous \TeX program
509 (by famous Donald Knuth) and the accompanied utilities (all
510 available for free). It is used for high quality
511 typesetting. The result -- in the form of so called
512 <code>DVI</code> (DeVice Independent) file -- can be printed or
513 displayed on various devices preserving exactly the same look up
514 to the capability of the device. The <code>dvips</code> allows you
515 to convert the <code>dvi</code> to the high quality PostScript
516 (i.e. PostScript that can be processed by utilities like
517 <code>psnup</code>, <code>psbook</code>, <code>psselect</code>,
518 and others). The derived version of \TeX (the pdfTeX) can be used
519 to produce PDF output instead of DVI, or the PDF can be produced
520 from PostScript using the utility <code>ps2pdf</code>.
522 If you want to use MikTeX then you need to select at least the
523 medium size installation. For really old versions of MikTex or minimal
524 installations, you may need to download the fancyhdr package separately.
525 You can find it in the
526 <a href="ftp://ftp.tex.ac.uk/tex-archive/macros/latex/contrib/supported/fancyhdr/">
527 contrib/supported</a> directory of the tex archives.
529 <li>If you want to generate compressed HTML help
530 (see \ref cfg_generate_htmlhelp "GENERATE_HTMLHELP") in the
531 config file, then you need the Microsoft HTML help workshop.
532 You can download it from
533 <a href="http://msdn.microsoft.com/library/default.asp?url=/library/en-us/htmlhelp/html/vsconHH1Start.asp">Microsoft</a>.
535 <li>If you want to produce Qt Compressed Help files (see \ref
536 cfg_qhelgenerator_loc "QHG_LOCATION") in the config file,
537 then you need qhelpgenerator which is part of Qt.
538 You can download Qt from
539 <a href="http://qt-project.org/downloads">Qt Software Downloads</a>.
541 <li><a href="http://www.graphviz.org/">
542 the Graph visualization toolkit version 1.8.10</a><br>
543 Needed for the include dependency graphs, the graphical inheritance graphs,
544 and the collaboration graphs.
549 \section build_tools Tools used to develop doxygen
551 Doxygen was developed and tested under Linux & MacOSX using the following
554 <li>GCC version 4.6.3 (Linux) and 4.2.1 (MacOSX)
555 <li>GNU flex version 2.5.35
556 <li>GNU bison version 2.5 (Linux) and 2.3 (MacOSX)
557 <li>GNU make version 3.81
558 <li>Perl version 5.12
559 <li>Python version 2.7 and 3.4
560 <li>TeX Live 2009 (or later)
564 Go to the <a href="starting.html">next</a> section or return to the
565 <a href="index.html">index</a>.