diff -r 000000000000 -r 42188c7ea2d9 Orb/Doxygen/doc/install.doc --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Orb/Doxygen/doc/install.doc Thu Jan 21 17:29:01 2010 +0000 @@ -0,0 +1,699 @@ +/****************************************************************************** + * + * + * + * Copyright (C) 1997-2008 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 +First go to the +download page +\latexonly({\tt http://www.doxygen.org/download.html})\endlatexonly +to get the latest distribution, if you did not have it already. + +This section is divided into the following sections: + + +\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: + + +To take full advantage of doxygen's features the following additional +tools should be installed. + + + +Compilation is now done by performing the following steps: + +
    +
  1. Unpack the archive, unless you already have done that: + +\verbatim + gunzip doxygen-$VERSION.src.tar.gz # uncompress the archive + tar xf doxygen-$VERSION.src.tar # unpack it +\endverbatim + +
  2. Run the configure script: + +\verbatim + sh ./configure +\endverbatim + + 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: + +\verbatim + configure --platform platform-type +\endverbatim + + See the PLATFORMS file for a list of possible platform + options. + + If you have Qt-3.3.x installed and want to build the GUI + front-end, you should run the configure script with + the --with-doxywizard option: + +\verbatim + configure --with-doxywizard +\endverbatim + + For an overview of other configuration options use + +\verbatim + configure --help +\endverbatim + +
  3. Compile the program by running make: + +\verbatim + make +\endverbatim + + The program should compile without problems and three binaries + (doxygen and doxytag) + should be available in the bin directory of the distribution. + +
  4. Optional: Generate the user manual. + +\verbatim + make docs +\endverbatim + + 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 + index.html in the + html directory). You will need the python interpreter + for this. + +
  5. Optional: Generate a PDF version of the manual + (you will need pdflatex, makeindex, and + egrep for this). + +\verbatim + make pdf +\endverbatim + + 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 + + After the compilation of the source code do a make install + to install doxygen. If you downloaded the binary distribution for Unix, + type: + +\verbatim + ./configure + make install +\endverbatim + + Binaries are installed into the directory \/bin. + Use make install_docs to install the + documentation and examples into \/doxygen. + + \ defaults to /usr/local but can be changed with + the --prefix option of the configure script. + The default \ directory is + \/share/doc/packages and can be changed with + the --docdir option of the configure script. + + Alternatively, you can also copy the binaries from the bin + directory manually to some bin 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 + +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: +\verbatim + mkdir qt + cd qt + ln -s your-qt-include-dir-here include + ln -s your-qt-lib-dir-here lib + export QTDIR=$PWD +\endverbatim + +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 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). + +Latex problems + +The file a4wide.sty is not available for all distributions. If +your distribution does not have it please select another paper type +in the config file (see the \ref cfg_paper_type "PAPER_TYPE" tag in the +config file). + +HP-UX \& Digital Unix problems + +If you are compiling for HP-UX with aCC and you get this error: +\verbatim + /opt/aCC/lbin/ld: Unsatisfied symbols: + alloca (code) +\endverbatim + then you should (according to Anke Selig) edit ce_parse.cpp + and replace +\verbatim + extern "C" { + void *alloca (unsigned int); + }; +\endverbatim + with +\verbatim + #include +\endverbatim + + If that does not help, try removing ce_parse.cpp and let + bison rebuild it (this worked for me). + +If you are compiling for Digital Unix, the same problem can be solved +(according to Barnard Schmallhof) by replacing the following in +ce_parse.cpp: + +\verbatim + #else /* not GNU C. */ + #if (!defined (__STDC__) && defined (sparc)) || defined (__sparc__) \ + || defined (__sparc) || defined (__sgi) + #include +\endverbatim + + with + +\verbatim + #else /* not GNU C. */ + #if (!defined (__STDC__) && defined (sparc)) || defined (__sparc__) \ + || defined (__sparc) || defined (__sgi) || defined (__osf__) + #include +\endverbatim + + Alternatively, one could fix the problem at the bison side. + Here is patch for bison.simple (provided by Andre Johansen): + +\verbatim +--- bison.simple~ Tue Nov 18 11:45:53 1997 ++++ bison.simple Mon Jan 26 15:10:26 1998 +@@ -27,7 +27,7 @@ + #ifdef __GNUC__ + #define alloca __builtin_alloca + #else /* not GNU C. */ +-#if (!defined (__STDC__) && defined (sparc)) || defined (__sparc__) \ + || defined (__sparc) || defined (__sgi) ++#if (!defined (__STDC__) && defined (sparc)) || defined (__sparc__) \ + || defined (__sparc) || defined (__sgi) || defined (__alpha) + #include + #else /* not sparc */ + #if defined (MSDOS) && !defined (__TURBOC__) +\endverbatim + + The generated scanner.cpp that comes with doxygen is build with this + patch applied. + +Sun compiler problems + +It appears that doxygen doesn't work properly if it is compiled +with Sun's C++ WorkShop 6 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 and Makefile.doxytag +will fix this: + +\verbatim +$(TARGET): $(OBJECTS) $(OBJMOC) + $(LINK) $(LFLAGS) -o $(TARGET) $(OBJECTS) $(OBJMOC) $(LIBS) -Bdynamic +\endverbatim + +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. + +Red Hat 9.0 problems + +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.5.0 onwards, build files are provided for Visual Studio 2005. +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 +Cygwin +or MinGW. + +Before you can compile doxygen you need to download and install the C++ compiler of +Visual Studio. Since Microsoft apparently wants to lure everyone into using their +.NET stuff, they made things somewhat difficult when you use the Express version. +You need to + +do some manual steps in order to setup a proper working environment for building +native win32 applications such as Doxygen. + +The next step is to install unxutils (see http://sourceforge.net/projects/unxutils). +This packages contains the tools \c flex and \c bison which are needed during the +compilation process if you use a CVS snapshot of doxygen (the official source releases +come with pre-generated sources). +Download the zip extract it to e.g. c:\\tools\\unxutils. + +Now you need to add/adjust the following environment variables +(via Control Panel/System/Advanced/Environment Variables): +- add c:\\tools\\unxutils\\usr\\local\\wbin; to the start of PATH +- set BISON_SIMPLE to c:\\tools\\unxutils\\usr\\local\\share\\bison.simple + +Download doxygen's source tarball and put it somewhere (e.g use c:\\tools) + +Now start a new command shell and type +\verbatim +cd c:\tools +gunzip doxygen-x.y.z.src.tar.gz +tar xvf doxygen-x.y.z.src.tar +\endverbatim +to unpack the sources. + +Now your environment is setup to build \c doxygen and \c doxytag. + +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 and Doxytag by right-clicking +the project in the solutions explorer, and selecting Build. + +Note that compiling Doxywizard currently requires Qt version 3 +(see http://www.trolltech.com/products/qt/qt3). +If you do not have a commercial license, you can build Doxywizard with the open +source version (see http://qtwin.sourceforge.net/qt3-win32/compile-msvc-2005.php), +but I have not tried this myself. + +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. +Just follow the dialogs. + +After installation it is recommended to also download and install GraphViz +(version 2.8 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 +Microsoft. + +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 Qt Software Downloads. + +In order to generate PDF output or use scientific formulas you will also need to +install LaTeX and +Ghostscript. + +For LaTeX a number of distributions exists. Popular onces that should work with +doxygen are MikTex +and XemTex. + +Ghostscript can be downloaded +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 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: +
    +
  • GCC version 3.3.6 (Linux) and 4.0.1 (MacOSX) +
  • GNU flex version 2.5.33 (Linux) and 2.5.4 (MacOSX) +
  • GNU bison version 1.75 +
  • GNU make version 3.80 +
  • Perl version 5.8.1 +
  • VIM version 6.2 +
  • Firefox 1.5 +
  • Trolltech's tmake version 1.3 (included in the distribution) +
  • teTeX version 2.0.2 +
  • CVS 1.12.12 +
+ +\htmlonly +Go to the next section or return to the + index. +\endhtmlonly + +*/ +