summaryrefslogtreecommitdiffstats
path: root/doc/install.doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc/install.doc')
-rw-r--r--doc/install.doc407
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