From db6a3ab2761a328e74fdccf243ff148af7623062 Mon Sep 17 00:00:00 2001 From: Dimitri van Heesch Date: Sat, 27 Jun 2015 14:26:54 +0200 Subject: Updated installation section of the manual --- doc/install.doc | 414 ++++++-------------------------------------------------- doc/trouble.doc | 2 - src/config.xml | 2 +- 3 files changed, 42 insertions(+), 376 deletions(-) diff --git a/doc/install.doc b/doc/install.doc index 3f5d8ab..295154f 100644 --- a/doc/install.doc +++ b/doc/install.doc @@ -35,11 +35,10 @@ following to build the executable: \addindex libiconv \addindex make \addindex strip + \addindex python
  • In order to generate a \c Makefile for your platform, you need - perl - \addindex perl -
  • The configure script assume the availability of standard UNIX tools such - as sed, date, find, uname, mv, cp, cat, echo, tr, cd and \c rm. + cmake version 2.8.12 or later. + \addindex cmake To take full advantage of doxygen's features the following additional @@ -49,7 +48,7 @@ tools should be installed.
  • Qt Software's GUI toolkit Qt \addindex Qt - version 4.3 or higher (but currently, Qt 5.x is not supported). + version 4.3 or higher (but currently, Qt 5.x is not yet supported). This is needed to build the GUI front-end doxywizard.
  • A \LaTeX distribution: for instance TeX Live @@ -61,11 +60,10 @@ tools should be installed. 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. -
  • For formulas or if you do not wish to use `pdflatex, the ghostscript interpreter - is needed. You can find it at +
  • For formulas in the HTML output (when MathJax is not used) + or in case you do not wish to use `pdflatex, + the ghostscript interpreter is needed. You can find it at www.ghostscript.com. -
  • In order to generate doxygen's own documentation, Python is needed, you - can find it at www.python.org. Compilation is now done by performing the following steps: @@ -76,62 +74,46 @@ Compilation is now done by performing the following steps: gunzip doxygen-$VERSION.src.tar.gz # uncompress the archive tar xf doxygen-$VERSION.src.tar # unpack it -
  • Run the configure script: - - sh ./configure +
  • Create a build directory (for instance inside the source tree) - 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. + cd doxygen-$VERSION + mkdir build - To override the auto detected platform and compiler you can run - configure as follows: +
  • Run cmake with the makefile generator - configure --platform platform-type + cmake -G "Unix Makefiles" .. - See the PLATFORMS file for a list of possible platform - options. + cmake tries to determine the platform you use, and will look + for the requires tools. It will report if something is missing. - 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 `--with-doxywizard` option: + If you have Qt-4.3 or higher installed and want to build the GUI + front-end, you should enable it as follows: - configure --with-doxywizard + cmake -Dbuild_wizard=YES For an overview of other configuration options use - configure --help + cmake -L
  • Compile the program by running make: make - The program should compile without problems and the binaries - (doxygen and optionally doxywizard) - should be available in the bin directory of the distribution. + The program should compile without problems and the binaries + (doxygen and optionally doxywizard) + should be available in the bin directory within the build directory.
  • Optional: Generate the user manual. + cmake -Dbuild_doc=YES make docs - To let doxygen generate the HTML documentation. + To let doxygen generate the HTML and PDF documentation. - The HTML directory of the distribution will now contain the html - documentation (just point a HTML browser to the file - index.html in the - html directory). You will need the python interpreter - for this. + The HTML directory within the build directory will now contain the html + documentation (just point a HTML browser to the file + index.html in the html directory). -
  • Optional: Generate a PDF version of the manual - (you will need pdflatex, makeindex, and - egrep for this). - - make pdf - - The PDF manual doxygen_manual.pdf will be located - in the latex directory of the distribution. Just - view and print it via the acrobat reader. - \section install_bin_unix Installing the binaries on UNIX @@ -164,107 +146,15 @@ 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 - -Qt problems - -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 setenv QTDIR \$PWD -instead of the export command above. - -Now install doxygen as described above. - -Bison problems - -Versions 1.31 to 1.34 of \c 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). - -Sun compiler problems - -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 - -GCC compiler problems - -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 `--english-only` 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. - -Dot problems - -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. +\section install_src_windows Compiling from source on Windows -Red Hat 9.0 problems +From version 1.8.10 onwards, build files need to be generated by cmake. +cmake can be downloaded from http://www.cmake.org/download/ -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 +At the moment only the express version of Visual Studio 2013 is tested, +but other version might also work. -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 +Alternatively, you can compile doxygen \ref install_src_unix "the UNIX way" using Cygwin or MinGW. @@ -273,13 +163,11 @@ The next step is to install modern versions of \c bison and \c flex (see http://sourceforge.net/projects/winflexbison. After installation and adding them to your `path` rename `win_flex.exe` to `flex.exe` and `win_bison.exe` to `bison.exe`) Furthermore you have to install \c python (version 2.6 or higher, see http://www.python.org). -These packages are needed during the -compilation process if you use a GitHub snapshot of doxygen (the official source releases -come with pre-generated sources). +These packages are needed during the compilation process. Download doxygen's source tarball and put it somewhere (e.g. use c:\\tools) -Now start a new command shell and type +Now start a visual studio native command shell (for either x86 or x64) and type \verbatim cd c:\tools tar zxvf doxygen-x.y.z.src.tar.gz @@ -288,12 +176,14 @@ to unpack the sources (you can obtain \c tar from e.g. http://gnuwin32.sourcefor Alternatively you can use an unpack program, like 7-Zip (see http://www.7-zip.org) or use the build in unpack feature of modern Windows systems). -Now your environment is setup to build \c doxygen. +Now your environment is setup to generate the required project files for \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. +cd into the \c doxygen-x.y.z directory, create and cd to a build directory +\verbatim +mkdir build +cd build +cmake -G "Visual Studio 12 2013" +\endverbatim Note that compiling Doxywizard currently requires Qt version 4 (see http://qt-project.org/). @@ -301,149 +191,6 @@ Note that compiling Doxywizard currently requires Qt version 4 Also read the next section for additional tools you may need to install to run doxygen with certain features enabled. - - \section install_bin_windows Installing the binaries on Windows Doxygen comes as a self-installing archive, so installation is extremely simple. @@ -481,85 +228,6 @@ latex.exe, pdflatex.exe, and gswin32c.exe are present in the search path of a command box. Follow these instructions if you are unsure and run the commands from a command box to verify it works. - - -\section build_tools Tools used to develop doxygen - -Doxygen was developed and tested under Linux & MacOSX using the following -open-source tools: - - \htmlonly Go to the next section or return to the index. diff --git a/doc/trouble.doc b/doc/trouble.doc index 718c7bc..47ef623 100644 --- a/doc/trouble.doc +++ b/doc/trouble.doc @@ -18,8 +18,6 @@ \section knowproblems Known Problems