diff options
Diffstat (limited to 'doc/install.doc')
| -rw-r--r-- | doc/install.doc | 407 |
1 files changed, 353 insertions, 54 deletions
diff --git a/doc/install.doc b/doc/install.doc index 461e730..c03a529 100644 --- a/doc/install.doc +++ b/doc/install.doc @@ -20,96 +20,395 @@ First go to the <a href="http://www.stack.nl/~dimitri/doxygen/download.html">download</a> page \latexonly({\tt http://www.stack.nl/$\sim$dimitri/doxygen/download.html})\endlatexonly -to get the latest distribution and unpack it. +to get the latest distribution, if you did not have it already. + +\subsection 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>Troll Tech's GUI toolkit <A HREF="http://www.trolltech.com/products/qt.html">Qt</A> +<ul> +<li>Troll Tech's GUI toolkit + <A HREF="http://www.trolltech.com/products/qt.html">Qt</A> \latexonly(see {\tt http://www.trolltech.com/products/qt.html})\endlatexonly. \addindex Qt -<LI>The <a href="ftp://prep.ai.mit.edu/pub/gnu">GNU</a> tools + You can download either version 1.44 or version 2.1.x. + If want to build the GUI front-end you will need Qt 2.1.x. If you do + not need it, using Qt 1.44 will result in a somewhat smaller executable. +<li>The <a href="ftp://prep.ai.mit.edu/pub/gnu">GNU</a> tools flex, bison and make \addindex flex \addindex bison \addindex make -<LI>In order to generate a Makefile for your platform, you need +<li>In order to generate a Makefile for your platform, you need <a href="http://www.perl.com>perl</a> \latexonly(see {\tt http://www.perl.com})\endlatexonly. \addindex perl -</UL> -For platform specific installation instructions see the \c INSTALL file -that is included in the package. +</ul> + +To take full advantage of doxygen's features the following additional +tools should be installed. + +<ul> +<li>A \f$\mbox{\LaTeX}\f$ distribution: for instance + <a href="http://www.tug.org">teTeX 1.0</a>.<br> + This is needed for generating LaTeX, Postscript, and PDF output. +<li><a href="http://www.research.att.com/sw/tools/graphviz/"> + the Graph visualization toolkit version 1.5</a><br> + Needed for the include dependency graphs, + the graphical inheritance graphs, + and the collaboration graphs. +<li>The ghostscript interpreter. +</ul> + +Compilation is now done by performing the following steps: + +<ol> +<li> 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 + +<li>Run the configure script: + +\verbatim + sh ./configure +\endverbatim -\addindex HTTP -\addindex CGI -To use the search engine \c doxysearch, you will also need -a HTTP daemon running on the target system and permission to execute a -CGI binary. + The script tries to determine the platform you use, the location + of the Qt library, 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: -If you are running Unix, and have Qt installed correctly, you can simply enter \verbatim -configure + configure --platform platform-type \endverbatim -to set up the makefiles for your platform. For Windows this step can be -skipped. -To override the auto detected platform you can specify + See the <code>PLATFORMS</code> file for a list of possible platform + options. + + If you have Qt-2.1.x installed and want to build the GUI front-end, you + should run the configure script with the <code>--with-doxywizard</code> + option. + + For an overview of other configuration options use + \verbatim -configure --platform platform-type + configure --help \endverbatim -See the file \c PLATFORMS for a list of possible platforms. -For more configuration options use <code>configure --help</code> -To compile and link the sources enter +<li>Compile the program by running make: + \verbatim -make + make \endverbatim -in the root of the distribution. -Doxygen should compile without errors or warnings. -If it does not, please send the compilation errors or warnings along -with a description of your platform to -<a href="mailto:dimitri@stack.nl>dimitri@stack.nl</a>. -After compilation, the binaries will be located in the \c bin -directory of the distribution. -You may want to copy these files to a location in your path -(\c /usr/local/bin for instance) or add the \c bin -directory of the distribution to your search path. + The program should compile without problems and three binaries + (<code>doxygen</code>, <code>doxytag</code>, and <code>doxysearch</code>) + should be available in the bin directory of the distribution. -On Unix you can also type: +<li>Optional: Generate the user manual. + \verbatim -make install + make docs \endverbatim -The following binaries should now be available: -<UL> -<LI>\c doxygen: for generating the class browser. -<LI>\c doxytag: for creating a tag file containing references - to external documentation. -<LI>\c doxysearch: the search engine. This binary should not be - executed directly. It must be called from an CGI script that will be - generated by doxygen. -</UL> + To let doxygen generate the HTML documentation. + + \note you will need the stream editor <code>sed</code> for this, + but this should be available on any Unix platform. -To take full advantage of doxygen's features the following additional -tools should be installed. + 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). + +<li>Optional: Generate a postscript and pdf version of the manual. + (you will need <code>latex</code> and <code>dvips</code> and + the ghostscript package for this). + +\verbatim + make pdf +\endverbatim + The postscript manual <code>doxygen_manual.ps</code> will be located + in the latex directory of the distribution. Just send it to a + postscript printer to print it or use <code>ghostview</code> to view it. + +</ol> + +\subsection install_bin_unix Installating the binaries on Unix + + If you downloaded the binary distribution for Unix, you can install + doxygen by typing: + +\verbatim + ./configure + make install +\endverbatim + + Binaries are installed in the directory <code>\<prefix\>/bin</code> + Documentation and examples in the directory + <code>\<prefix\>/doc/doxygen</code> + + <code>\<prefix\></code> defaults to /usr but can be changed with + the <code>--prefix</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. 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. + +\subsection unix_problems Known compilation problems for Unix + +<b>Qt problems</b> + +The Qt include files and libraries are not a sub directory 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: goto 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 <code>setenv QTDIR $PWD</code> +instead of the <code>export</code> command above. + +Now install doxygen as described above. + +<b>Latex problems</b> + +the file <code>a4wide.sty</code> 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). + +<b>HP-UX & Digital Unix problems</b> + +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 <code>ce_parse.cpp</code> + and replace +\verbatim + extern "C" { + void *alloca (unsigned int); + }; +\endverbatim + with +\verbatim + #include <alloca.h> +\endverbatim + +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 <alloca.h> +\endverbatim + + with + +\verbatim + #else /* not GNU C. */ + #if (!defined (__STDC__) && defined (sparc)) || defined (__sparc__) || defined (__sparc) || defined (__sgi) || defined (__osf__) + #include <alloca.h> +\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 <alloca.h> + #else /* not sparc */ + #if defined (MSDOS) && !defined (__TURBOC__) +\endverbatim + + The generated scanner.cpp that comes with doxygen is build with this + patch applied. + +<b>Sun compiler problems</b> + + + +<b>GNU 2.7.2.x 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. + +\subsection install_src_windows Compiling from source on Windows + +Currently, I have only compiled doxygen for Windows using Microsoft's +Visual C++ (version 6.0). 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. + +Since Windows comes without all the nice tools that Unix users are +used to, you need to install a number of these tools before you can compile +doxygen for Windows. + +Here is what is required: <ul> -<li>\f$\mbox{\LaTeX}\f$: - <a href="http://www.tug.org">teTeX 1.0</a> (for Unix) or - <a href="ftp://ctan.tug.org/tex-archive/systems/win32/web2c/fptex-0.3/">fpTeX 0.3</a> (for Windows)<br> - Needed for LaTeX and PDF output. +<li>WinZip to unpack the tar source distribution. This can be found at + http://www.winzip.com +<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). +<li>Perl 5.0 or higher for Windows. This can be download from: + http://www.ActiveState.com/pw32 +<li>The GNU tools flex, bison and sed. + To get these working on Windows you should install the + <a href="http://sourceware.cygnus.com/cygwin/">cygwin tools</a> + \latexonly(see {\tt http://sourceware.cygnus.com/cygwin/})\endlatexonly. + + Make sure the <code>BISONLIB</code> environment variable points to the + location where the files <code>bison.simple</code> and + <code>bison.hairy</code> are located. + + Also make sure the tools are available from a dos box, by adding + the directory they are in to the search path. + +<li>A professional license of + <A HREF="http://www.trolltech.com/products/qt.html">Qt for Windows</A><br> + \latexonly(see {\tt http://www.trolltech.com/products/qt.html})\endlatexonly. + + If you do not have that and you can live without the GUI front-end + you can also download Qt-1.44 for X11. Doxygen only the depends on + the tools section of the Qt library, which happens also to compile + on Windows. (Qt version 2.1.x does not work anymore, at least not + without adding some window's specific code). + + Now create the following directories: + +\verbatim + qtools/src + qtools/include + qtools/lib +\endverbatim + + Copy the contents of the <code>src/tools</code> directory of the + Qt-1.44 for X11 archive to <code>qtools/src</code>. Also copy the include + files in <code>src/tools</code> to <code>qtools/include</code>. Create a + static library project resulting in <code>qtools/lib/qt.lib</code> and + add the files in <code>qtools/src</code> to that project. Then + build the library and set the environment variable <code>QTDIR</code> + to the absolute path of the qtools directory. + +<li>To generate LaTeX documentation or formulas in HTML you need the tools: + latex, dvips and gswin32 + To get these working under Windows install the fpTeX distribution + You can download it at: + ftp://ctan.tug.org/tex-archive/systems/win32/web2c/fptex-0.3/ + + Make sure the tools are available from a dos box, by adding the + directory they are in to the search path. + +<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 at: + http://msdn.microsoft.com/workshop/author/htmlhelp +<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. <li><a href="http://www.research.att.com/sw/tools/graphviz/"> the Graph visualization toolkit version 1.5</a><br> Needed for the include dependency graphs, the graphical inheritance graphs, and the collaboration graphs.<br> -<li><a href="http://msdn.microsoft.com/workshop/author/htmlhelp"> - the HTML help workshop</a> (for Windows only)<br> - Needed for compiling compressed HTML output (a.k.a. the new Windows help format). </ul> -Doxygen was developed and tested under Linux using the following tools: +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). + +<li>goto the doxygen root dir and type: + +\verbatim + make.bat +\endverbatim + + This should build the executables + <code>doxygen.exe</code>, <code>doxytag.exe</code>, and + <code>doxysearch.exe</code> (The compiler should not produce any + serious warnings or errors). + +<li>To build the examples type: + +\verbatim + nmake examples +\endverbatim + +<li>To generate the HTML documentation type: + +\verbatim + nmake docs +\endverbatim + + The generated docs are located in the html directory. + +<li> + To generate the postscript and PDF manual type: + +\verbatim + nmake pdf +\endverbatim + + The manual should now be in <code>latex/doxygen_manual.pdf</code> + +</ol> + +\subsection install_bin_windows Installating the binaries on Windows + +There is no fancy installation procedure at the moment (If anyone wants +to add it 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. + +\subsection build_tools Tools used to develop doxygen + +Doxygen was developed and tested under Linux using the following +open-source tools: <ul> <li>EGCS version 2.91.66 <li>GNU flex version 2.5.4 |