install.doc

doxygen(一个自动从源代码生成文档的工具)的源代码

\endverbatim

  The generated scanner.cpp that comes with doxygen is build with this
  patch applied.  

<b>Sun compiler problems</b>

I tried compiling doxygen only with Sun's C++ WorkShop Compiler
version 5.0 (I used <code>./configure --platform solaris-cc</code>)

Qt-2.x.y is required for this compiler (Qt-1.44 has problems with the bool
type).

Compiling the \c doxygen binary went ok, but while linking <code>doxytag</code> I got a 
lot of link errors, like these:

\verbatim
QList<PageInfo>::__vtbl   /home/dimitri/doxygen/
objects/SunWS_cache/CC_obj_6/6c3eO4IogMT2vrlGCQUQ.o
[Hint: try checking whether the first non-inlined, non-pure 
virtual function of class QList<PageInfo> is defined]
\endverbatim

These are generated because the compiler is confused about the object sharing
between \c doxygen and \c doxytag. To compile \c doxytag and \c doxysearch 
anyway do:

\verbatim
rm -rf objects
mkdir objects
cd src
gmake -f Makefile.doxytag
gmake -f Makefile.doxysearch
\endverbatim

when configuring with <code>--static</code> 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 <code>-Bdynamic</code> after the target rule in 
<code>Makefile.doxygen</code> and <code>Makefile.doxytag</code> 
will fix this:

\verbatim
$(TARGET): $(OBJECTS) $(OBJMOC) 
        $(LINK) $(LFLAGS) -o $(TARGET) $(OBJECTS) $(OBJMOC) $(LIBS) -Bdynamic
\endverbatim

<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.  

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.

\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>An unzip/untar tool like WinZip to unpack the tar source distribution. 
    This can be found at http://www.winzip.com/  

    The good, tested, and free alternative is the <code>tar</code> utility
    supplied with <a href="http://sourceware.cygnus.com/cygwin/">cygwin
    tools</a>. Anyway, the cygwin's flex, bison, and sed are also
    recommended below.

<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). 

    Borland C++ or MINGW (see http://www.mingw.org/) are also supported. 

<li>Perl 5.0 or higher for Windows. This can be downloaded from:
    http://www.ActiveState.com/Products/ActivePerl/

<li>The GNU tools flex, bison, and sed.
    To get these working on Windows you should install the 
    <a href="http://sources.redhat.com/cygwin/">cygwin tools</a>
    \latexonly(see {\tt http://sources.redhat.com/cygwin/})\endlatexonly
    
    Alternatively, you can also choose to 
    download only a <a href="http://www.doxygen.org/dl/cygwin_tools.zip">small subset</a> 
    \latexonly(see {\tt http://www.doxygen.org/dl/cygwin\_tools.zip})\endlatexonly
    of the cygwin tools that I put together just to compile doxygen.
    
    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. For instance if these files are in
    <code>c:\\tools\\cygwin\\share</code> then BISONLIB should 
    be set to <code>//c/tools/cygwin/share/</code>

    Also make sure the tools are available from a dos box, by adding 
    the directory they are in to the search path.
    
    For those of you who are very new to cygwin (if you are going to
    install it from scratch), you should notice that there is an
    archive file <code>bootstrap.zip</code> which also contains the
    <code>tar</code> utility (<code>tar.exe</code>), <code>gzip</code>
    utilities, and the <code>cygwin1.dll</code> core. This also means
    that you have the <code>tar</code> in hands from the start. It
    can be used to unpack the tar source distribution instead of
    using WinZip -- as mentioned at the beginning of this list of
    steps.

<li>From Doxygen-1.2.2-20001015 onwards, the distribution includes the part
    of Qt-2.x.y that is needed for to compile doxygen, doxytag,
    and doxysearch. The Windows specific part were also created.
    As a result doxygen can be compiled on systems without X11 or the
    commerical version of Qt. 

    For doxywizard, a complete Qt library is 
    still a requirement however. You can download the non-commercial version
    from Troll-Tech web-site. See doxygen download page for a link.
   
<li>To generate LaTeX documentation or formulas in HTML you need the tools:
    <code>latex</code>, <code>dvips</code> and <code>gswin32</code>. 
    To get these working under Windows
    install the fpTeX distribution. You can download it at:
    http://www.ese-metz.fr/~popineau/fptex/wwwfptex.html

    Make sure the tools are available from a dos box, by adding the 
    directory they are in to the search path.

    For your information, the LaTeX is freely available set of so
    called macros and styles on the top of the famous TeX program
    (by famous Donald Knuth) and the accompanied utilities (all
    available for free). It is used for high quality
    typesetting. The result -- in the form of so called
    <code>DVI</code> (DeVice Independent) file -- can be printed or
    displayed on various devices preserving exactly the same look up
    to the capability of the device. The <code>dvips</code> allows you
    to convert the <code>dvi</code> to the high quality PostScript
    (i.e. PostScript that can be processed by utilities like 
    <code>psnup</code>, <code>psbook</code>, <code>psselect</code>,
    and others). The derived version of TeX (the pdfTeX) can be used
    to produce PDF output instead of DVI, or the PDF can be produced
    from PostScript using the utility <code>ps2pdf</code>.

    If you want to use MikTeX then you need to download the
    fancyhdr package separately. You can find it at:
    ftp://ftp.tex.ac.uk/tex-archive/macros/latex/contrib/supported/fancyhdr/

<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/library/default.asp?url=/library/en-us/htmlhelp/html/vsconHH1Start.asp

<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>
    \latexonly(see {\tt http://www.research.att.com/sw/tools/graphviz/})\endlatexonly.
    Needed for the include dependency graphs, the graphical inheritance graphs,
    and the collaboration graphs.
</ul>

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).

    Notice: The use of LaTeX is optional and only needed for compilation
    of the documentation into PostScript or PDF. 
    It is \e not needed for compiling the doxygen's binaries. 
    
<li>Go to the doxygen root dir and type:

\verbatim
    make.bat msvc
\endverbatim

    This should build the executables 
    <code>doxygen.exe</code>, <code>doxytag.exe</code>, and 
    <code>doxysearch.exe</code> using Microsoft's Visual C++ compiler
    (The compiler should not produce any serious warnings or errors).

    You can use also the <code>bcc</code> argument to build
    executables using the Borland C++ compiler, or
    <code>mingw</code> argument to compile using GNU gcc.

<li>To build the examples, go to the <code>examples</code> subdirectory
    and type:

\verbatim
    nmake
\endverbatim

<li>To generate the doxygen documentation, go to the <code>doc</code> 
    subdirectory and type:

\verbatim
    nmake
\endverbatim

    The generated HTML docs are located in the <code>..\html</code>
    subdirectory.

    The sources for LaTeX documentation are located in the <code>..\latex</code>
    subdirectory. From those sources, the DVI, PostScript, and PDF
    documentation can be generated. 
</ol>

\subsection install_bin_windows Installating the binaries on Windows

There is no fancy installation procedure at the moment (if anyone can
add it in a location independent way 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.

For running doxywizard you need to install the non-commercial version of
the Qt library first. This library can be downloaded from 
http://www.trolltech.com/products/download/qt-win-noncomm.html

\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
<li>GNU bison version 1.25
<li>GNU make version 3.76.1
<li>Perl version 5.005_02 
<li>VIM version 5.4
<li>Netscape 4.61
<li>Troll Tech's tmake version 1.3 (included in the distribution) 
<li>teTeX version 0.9
<li>CVS 1.10.7
</ul>

\htmlonly
Go to the <a href="starting.html">next</a> section or return to the
 <a href="index.html">index</a>.
\endhtmlonly

*/