summaryrefslogtreecommitdiffstats
path: root/doc/install.doc
blob: a4fe2f77f2766281c50d4c83587d8485d8538608 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
/******************************************************************************
 *
 * 
 *
 * Copyright (C) 1997-2013 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 
    \c flex, \c bison, \c libiconv and <code>GNU make</code>, and \c strip
    \addindex flex
    \addindex bison
    \addindex libiconv
    \addindex make
    \addindex strip
<li>In order to generate a \c 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 <code>sed, date, find, uname, mv, cp, cat, echo, tr, cd</code> and \c 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-project.org/">Qt</A>
    \addindex Qt
    version 4.3 or higher (but currently, Qt 5.x is not supported).
    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">TeX Live</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 <code>QTDIR</code> on some systems
(for instance on Red Hat 6.0 includes are in <code>/usr/include/qt</code> and
libs are in <code>/usr/lib</code>).
  
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 <code>csh</code>-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 \c bison contain a "bug" that results in a 
compiler errors like this:

<code>ce_parse.cpp:348: member `class CPPValue yyalloc::yyvs' with </code>
constructor not allowed in union

This problem has been solved in version 1.35 (versions before 1.31 
will also work).

<b>Sun compiler problems</b>

It appears that doxygen doesn't work properly if it is compiled 
with Sun's C++ WorkShop 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 \c bison, \c flex, and \c tar
(see http://gnuwin32.sourceforge.net/packages.html).
This packages are needed during the
compilation process if you use a CVS snapshot of doxygen (the official source releases 
come with pre-generated sources).

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
tar zxvf doxygen-x.y.z.src.tar.gz
\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-project.org/).

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 \c flex, \c bison, and \c 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 \c flex, \c bison, and \c 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 commercial 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://www.microsoft.com/en-us/download/details.aspx?id=21138">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://qt-project.org/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.tug.org/protext/">proTeXt</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://qt-project.org/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 &amp; MacOSX using the following 
open-source tools:
<ul>
<li>GCC version 4.6.3 (Linux) and 4.2.1 (MacOSX)
<li>GNU flex version 2.5.35 
<li>GNU bison version 2.5 (Linux) and 2.3 (MacOSX)
<li>GNU make version 3.81
<li>Perl version 5.12
<li>TeX Live 2009 (or later)
</ul>

\htmlonly
Go to the <a href="starting.html">next</a> section or return to the
 <a href="index.html">index</a>.
\endhtmlonly

*/