doc/install.doc

   1 /******************************************************************************
   2  *
   3  *
   4  *
   5  * Copyright (C) 1997-2015 by Dimitri van Heesch.
   6  *
   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.
  12  *
  13  * Documents produced by Doxygen are derivative works derived from the
  14  * input used in their production; they are not affected by this license.
  15  *
  16  */
  17 /*! \page install Installation
  18
  19 \addindex installation
  20 \tableofcontents
  21
  22 First go to the
  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.
  25
  26 \section install_src_unix Compiling from source on UNIX
  27
  28 If you downloaded the source distribution, you need at least the
  29 following to build the executable:
  30 <ul>
  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
  33     \addindex flex
  34     \addindex bison
  35     \addindex libiconv
  36     \addindex make
  37     \addindex strip
  38     \addindex python
  39 <li>In order to generate a \c Makefile for your platform, you need
  40     <a href="https://cmake.org/">cmake</a> version 2.8.12 or later.
  41     \addindex cmake
  42 </ul>
  43
  44 To take full advantage of doxygen's features the following additional
  45 tools should be installed.
  46
  47 <ul>
  48 <li>Qt Software's GUI toolkit
  49     <a href="http://qt-project.org/">Qt</A>
  50     \addindex Qt
  51     version 4.3 or higher (but currently, Qt 5.x is not yet supported).
  52     This is needed to build the GUI front-end doxywizard.
  53 <li>A \LaTeX distribution: for instance
  54     <a href="http://www.tug.org/interest.html#free">TeX Live</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 in the HTML output (when MathJax is not used)
  64     or in case you do not wish to use `pdflatex`,
  65     the ghostscript interpreter is needed. You can find it at
  66     <a href="https://www.ghostscript.com/">www.ghostscript.com</a>.
  67 </ul>
  68
  69 Compilation is now done by performing the following steps:
  70
  71 <ol>
  72 <li>Unpack the archive, unless you already have done that:
  73
  74         gunzip doxygen-$VERSION.src.tar.gz    # uncompress the archive
  75         tar xf doxygen-$VERSION.src.tar       # unpack it
  76
  77 <li>Create a build directory (for instance inside the source tree)
  78
  79         cd doxygen-$VERSION
  80         mkdir build
  81         cd build
  82
  83 <li>Run cmake with the makefile generator
  84
  85         cmake -G "Unix Makefiles" ..
  86
  87     <code>cmake</code> tries to determine the platform you use, and will look
  88     for the requires tools. It will report if something is missing.
  89
  90     If you have Qt-4.3 or higher installed and want to build the GUI
  91     front-end, you should enable it as follows:
  92
  93         cmake -Dbuild_wizard=YES ..
  94
  95     For an overview of other configuration options use
  96
  97         cmake -L ..
  98
  99 <li>Compile the program by running make:
 100
 101         make
 102
 103     The program should compile without problems and the binaries
 104     (<code>doxygen</code> and optionally <code>doxywizard</code>)
 105     should be available in the bin directory within the build directory.
 106
 107 <li>Optional: Generate the user manual.
 108
 109         cmake -Dbuild_doc=YES ..
 110         make docs
 111
 112     To let doxygen generate the HTML and PDF documentation.
 113
 114     The HTML directory within the build directory will now contain the html
 115     documentation (just point a HTML browser to the file
 116     <code>index.html</code> in the html directory).
 117
 118 </ol>
 119
 120 \section install_bin_unix    Installing the binaries on UNIX
 121
 122 After the compilation of the source code do a <code>make install</code>
 123 to install doxygen. If you downloaded the binary distribution for UNIX,
 124 type:
 125
 126     ./configure
 127     make install
 128
 129 Binaries are installed into the directory <code>\<prefix\>/bin</code>.
 130 Use <code>make install_docs</code> to install the
 131 documentation and examples into <code>\<docdir\>/doxygen</code>.
 132
 133 <code>\<prefix\></code> defaults to <code>/usr/local</code> but can be changed with
 134 the `--prefix` option of the configure script.
 135 The default <code>\<docdir\></code> directory is
 136 <code>\<prefix\>/share/doc/packages</code> and can be changed with
 137 the `--docdir` option of the configure script.
 138
 139 Alternatively, you can also copy the binaries from the <code>bin</code>
 140 directory manually to some <code>bin</code> directory in your search path.
 141 This is sufficient to use doxygen.
 142
 143 \note You need the GNU install tool for this to work (it is part of
 144 the coreutils package). Other install tools may put the binaries in
 145 the wrong directory!
 146
 147 If you have a RPM or DEP package, then please follow the
 148 standard installation procedure that is required for these packages.
 149
 150 \section install_src_windows Compiling from source on Windows
 151
 152 From version 1.8.10 onwards, build files need to be generated by cmake.
 153 cmake can be downloaded from https://cmake.org/download/
 154
 155 At the moment only the express version of Visual Studio 2013 is tested,
 156 but other version might also work.
 157
 158 Alternatively, you can compile doxygen
 159 \ref install_src_unix "the UNIX way" using
 160 <a href="https://en.wikipedia.org/wiki/Cygwin">Cygwin</a>
 161 or <a href="http://www.mingw.org/">MinGW</a>.
 162
 163 The next step is to install modern versions of \c bison and \c flex
 164 (see https://sourceforge.net/projects/winflexbison/. After installation and adding them to
 165 your `path` rename `win_flex.exe` to `flex.exe` and `win_bison.exe` to `bison.exe`)
 166 Furthermore you have to install \c python (version 2.6 or higher, see https://www.python.org).
 167 These packages are needed during the compilation process.
 168
 169 Download doxygen's source tarball and put it somewhere (e.g. use <code>c:\\tools</code>)
 170
 171 Now start a visual studio native command shell (for either x86 or x64) and type
 172 \verbatim
 173 cd c:\tools
 174 tar zxvf doxygen-x.y.z.src.tar.gz
 175 \endverbatim
 176 to unpack the sources (you can obtain \c tar from e.g. http://gnuwin32.sourceforge.net/packages.html).
 177 Alternatively you can use an unpack program, like 7-Zip (see http://www.7-zip.org)
 178 or use the build in unpack feature of modern Windows systems).
 179
 180 Now your environment is setup to generate the required project files for \c doxygen.
 181
 182 cd into the \c doxygen-x.y.z directory, create and cd to a build directory
 183 \verbatim
 184 mkdir build
 185 cd build
 186 cmake -G "Visual Studio 12 2013" ..
 187 \endverbatim
 188
 189 Note that compiling Doxywizard currently requires Qt version 4
 190 (see http://qt-project.org/).
 191
 192 Also read the next section for additional tools you may need to install to run
 193 doxygen with certain features enabled.
 194
 195 \section install_bin_windows Installing the binaries on Windows
 196
 197 Doxygen comes as a self-installing archive, so installation is extremely simple.
 198 Just follow the dialogs.
 199
 200 After installation it is recommended to also download and install GraphViz
 201 (version 2.20 or better is highly recommended). Doxygen can use the \c dot tool
 202 of the GraphViz package to render nicer diagrams, see the
 203 \ref cfg_have_dot "HAVE_DOT" option in the configuration file.
 204
 205 If you want to produce compressed HTML files (see \ref
 206 cfg_generate_htmlhelp "GENERATE_HTMLHELP") in the config file, then
 207 you need the Microsoft HTML help workshop.
 208 You can download it from
 209 <a href="http://www.microsoft.com/en-us/download/details.aspx?id=21138">Microsoft</a>.
 210
 211 If you want to produce Qt Compressed Help files (see \ref
 212 cfg_qhg_location "QHG_LOCATION") in the config file, then
 213 you need qhelpgenerator which is part of Qt.
 214 You can download Qt from <a href="http://qt-project.org/downloads">Qt Software Downloads</a>.
 215
 216 In order to generate PDF output or use scientific formulas you will also need to
 217 install <a href="https://en.wikipedia.org/wiki/LaTeX">LaTeX</a> and
 218 <a href="https://en.wikipedia.org/wiki/Ghostscript">Ghostscript</a>.
 219
 220 For \LaTeX a number of distributions exists. Popular ones that should work with
 221 doxygen are <a href="https://miktex.org/">MikTex</a>
 222 and <a href="http://www.tug.org/protext/">proTeXt</a>.
 223
 224 Ghostscript can be <a href="https://sourceforge.net/projects/ghostscript/">downloaded</a>
 225 from Sourceforge.
 226
 227 After installing \LaTeX and Ghostscript you'll need to make sure the tools
 228 latex.exe, pdflatex.exe, and gswin32c.exe are present in the search path of a
 229 command box. Follow <a href="https://www.computerhope.com/issues/ch000549.htm">these</a>
 230 instructions if you are unsure and run the commands from a command box to verify it works.
 231
 232 \htmlonly
 233 Go to the <a href="starting.html">next</a> section or return to the
 234  <a href="index.html">index</a>.
 235 \endhtmlonly
 236
 237 */
 238