INSTALL 9.15 KB
Newer Older
dimitri's avatar
dimitri committed
1
DOXYGEN Version 1.1.4-20000625
mueller's avatar
mueller committed
2 3 4 5 6 7 8 9 10

CONTENTS
--------
  - Installation instructions for UNIX
  - Installation instructions for Windows
  - Known configuration problems:
      * HTML related problems
      * LaTeX related problems
      * HP-UX / Digital UNIX problems
mueller's avatar
mueller committed
11
      * gcc 2.7.2.x related problems
mueller's avatar
mueller committed
12 13 14 15 16 17

INSTALLATION INSTRUCTIONS FOR UNIX:
-----------------------------------

1.  Unpack the archive, unless you already have:
   
dimitri's avatar
dimitri committed
18 19
     gunzip doxygen-1.1.4-20000625.src.tar.gz    # uncompress the archive
     tar xf doxygen-1.1.4-20000625.src.tar       # unpack it
mueller's avatar
mueller committed
20

mueller's avatar
mueller committed
21 22
2.  Run the configure script:
 
mueller's avatar
mueller committed
23
     sh ./configure
mueller's avatar
mueller committed
24

mueller's avatar
mueller committed
25
    The script tries to determine the platform you use, the location
mueller's avatar
mueller committed
26 27 28
    of the Qt library, the make tool (which _must_ be GNU make) and the perl 
    interpreter. It will report what it finds. Use configure --help 
    to see how to override or change the default or detected settings.
mueller's avatar
mueller committed
29

mueller's avatar
mueller committed
30 31 32
    If you have downloaded the binary distribution, you can proceed 
    with step 6 now.

mueller's avatar
mueller committed
33
3.  Compile the program by running make:
mueller's avatar
mueller committed
34

mueller's avatar
mueller committed
35
     make
mueller's avatar
mueller committed
36 37 38 39 40

    The program should compile without problems and three binaries (doxygen,
    doxytag, and doxysearch) should be available in the bin directory of the 
    distribution.

mueller's avatar
mueller committed
41
4.  Generate the user manual (optional, will also be done in step 6).
mueller's avatar
mueller committed
42
    
mueller's avatar
mueller committed
43
     make docs
mueller's avatar
mueller committed
44

mueller's avatar
mueller committed
45
    To let doxygen generate the HTML and LaTeX documentation.
mueller's avatar
mueller committed
46 47
    (you will need the stream editor `sed' for this)

mueller's avatar
mueller committed
48
5.   make ps
mueller's avatar
mueller committed
49 50 51 52 53 54 55 56 57 58 59 60

    to generate a postscript version of the manual. 
    (you will need latex and dvips for this)

    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).
    
    The postscript manual doxygen_manual.ps will be located in the latex
    directory of the distribution. Just send it to a postscript printer to 
    print it or use ghostview to view it. 

mueller's avatar
mueller committed
61 62 63 64
6.  Install the doxygen binaries, manual and examples

     make install

mueller's avatar
mueller committed
65 66 67 68 69
    Binaries are installed in the directory <prefix>/bin 
    Documentation and examples in the directory <prefix>/doc/doxygen

    <prefix> defaults to /usr but can be changed with the --prefix
    option of the configure script. 
mueller's avatar
mueller committed
70

mueller's avatar
mueller committed
71 72 73
INSTALLATION INSTRUCTIONS FOR WINDOWS:
--------------------------------------

dimitri's avatar
dimitri committed
74
Currently, only Microsoft Visual C++ (version 5.0 or higher) is supported. 
mueller's avatar
mueller committed
75
(For other compilers you may need to edit the perl script in wintools/make.pl
mueller's avatar
mueller committed
76 77
a bit). Let me know what you had to change if you got Doxygen working with 
another windows compiler. 
mueller's avatar
mueller committed
78 79 80

You will need to install the windows/dos versions of following tools:
- Perl 5.0+
mueller's avatar
mueller committed
81 82 83 84 85 86
  You can download it at: http://www.ActiveState.com/pw32/
- the GNU tools flex, bison and sed.
  To get these working on Windows you can install the cygwin tools.
  You can download them at: http://sourceware.cygnus.com/cygwin/
  Make sure the BISONLIB environment variable points to the
  location where bison.simple and bison.hairy are located.
dimitri's avatar
dimitri committed
87 88 89 90 91 92 93
- Qt-1.xx (Qt-2.xx does not work without adding some extra code) 
  Only the tools section is required, so you can use the free 
  X-windows version (use Qt-1.44) and build a library called qt.lib out of 
  the sources in src/tools. The library should be put in the lib directory
  of the Qt distribution. You can get Qt-1.44 at http://www.trolltech.com
  Before continuing make sure the QTDIR environment variable points to the 
  root of the Qt distribution.  
mueller's avatar
mueller committed
94 95
- Microsoft Visual C++ (I only tested with version 5.0).
  Use the vcvars32.bat to set the environment variables 
mueller's avatar
mueller committed
96
  (if you did not select to do this automatically during installation).
mueller's avatar
mueller committed
97 98 99 100 101 102 103 104
- 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/
- If you want to generate compressed HTML help (see 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
mueller's avatar
mueller committed
105 106 107 108
- If you used WinZip to extract the tar archive it will (apparently) not 
  create empty folders, so you have to add the folders
  `objects' and `bin' manually in the root of the distribution before 
  compiling.
mueller's avatar
mueller committed
109

mueller's avatar
mueller committed
110 111 112 113
Open a dos box.
Make sure all tools (i.e. nmake, latex, gswin32, dvips, sed, flex, bison, 
cl, rm and perl), are accessible from the command-line (add them to the
PATH environment variable if needed).
mueller's avatar
mueller committed
114

mueller's avatar
mueller committed
115
goto the doxygen root dir and type:
mueller's avatar
mueller committed
116 117 118 119

make.bat

This should build the executables doxygen.exe, doxytag.exe, and doxysearch.exe
mueller's avatar
mueller committed
120
(The compiler should not produce any serious warnings or errors).
mueller's avatar
mueller committed
121 122 123

To build the examples type:

mueller's avatar
mueller committed
124 125 126 127 128 129 130 131 132 133 134 135
nmake examples

To generate the HTML documentation type:

nmake docs

The generated docs are located in the html directory.
To generate the postscript manual type:

nmake ps

The manual should now be here latex/doxygen_manual.ps
mueller's avatar
mueller committed
136 137 138 139

-----------------------------------------------------------------------------
KNOWN CONFIGURATION PROBLEMS

mueller's avatar
mueller committed
140
QT RELATED PROBLEMS:
mueller's avatar
mueller committed
141 142 143 144 145 146 147 148 149 150 151
- 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 doxygen distribution
  - do "mkdir qt"
  - do "cd qt"
  - do "ln -s your-qt-include-dir-here include",
  - do "ln -s your-qt-lib-dir-here lib",
dimitri's avatar
dimitri committed
152
  - do "export QTDIR=$PWD" (or "setenv QTDIR $PWD if you have a csh-like shell)
mueller's avatar
mueller committed
153 154 155
  
  Now install doxygen as described above.  

mueller's avatar
mueller committed
156 157
- Qt-2.01 contains a bug that makes some special characters appear as 
  question marks (?) in the HTML output.
mueller's avatar
mueller committed
158

mueller's avatar
mueller committed
159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178
  Bernhard Ristow provided a fix for this:

  % in QT-2.0.1 is a bug in the member function
  % QTextStream &QTextStream::operator<<( char c ).
  % 
  % If the character is negative the cast to int in
  % ts_putc( c ) produces an invalid char as unsigned
  % short (e.g. char c = -4 -> unsigned short: 65532).
  % This produces a strange output.
  % If we modify the function into:
  %
  % QTextStream &QTextStream::operator<<( char c )
  % {
  %     CHECK_STREAM_PRECOND
  %     unsigned char uc = (unsigned char) c;
  %     ts_putc( uc );
  %     return *this;
  % }
  % it works correctly.

mueller's avatar
mueller committed
179 180 181
HTML RELATED PROBLEMS:
- the indent continuously increases.
  This seems to be a problem that can be observed with Netscape 4.01.
mueller's avatar
mueller committed
182
  It is not present in many later and earlier versions I tested.
mueller's avatar
mueller committed
183

mueller's avatar
mueller committed
184 185 186 187 188
LATEX RELATED PROBLEMS:
- the LaTeX translation of HTML tables doesn't seem to work for all 
  compilers. It is known to work for teTeX (versions 0.4 and 0.9)
- the file a4wide.sty is not available for all distributions. If
  your distribution does not have it please select another paper type
mueller's avatar
mueller committed
189
  in the config file (see the PAPER_TYPE tag in the config file)
mueller's avatar
mueller committed
190 191 192
- the file fancyheader.sty is known as fancyhdr.sty on some systems.
  Please change that in src/latexgen.cpp

mueller's avatar
mueller committed
193
HP-UX / DIGITAL UNIX PROBLEMS:
mueller's avatar
mueller committed
194 195 196
- If you are compiling for HP-UX with aCC and you get this error:
    /opt/aCC/lbin/ld: Unsatisfied symbols:
    alloca (code)
mueller's avatar
mueller committed
197
  then you should (according to Anke Selig) edit ce_parse.cpp and replace
mueller's avatar
mueller committed
198 199 200 201 202
    extern "C" {
      void *alloca (unsigned int);
    };
  with
    #include <alloca.h>  
mueller's avatar
mueller committed
203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218
- 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:
   
    #else /* not GNU C.  */
    #if (!defined (__STDC__) && defined (sparc)) || defined (__sparc__) ||
    defined (__sparc) || defined (__sgi)
    #include <alloca.h>

  with

    #else /* not GNU C.  */
    #if (!defined (__STDC__) && defined (sparc)) || defined (__sparc__) ||
    defined (__sparc) || defined (__sgi) || defined (__osf__)
    #include <alloca.h>

mueller's avatar
mueller committed
219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235
  Alternatively, one could fix the problem at the bison side.
  Here is patch for bison.simple (provided by Andre Johansen):
 
------------------------------------------------------------------------------
--- 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__)
------------------------------------------------------------------------------

mueller's avatar
mueller committed
236 237 238
  The generated scanner.cpp that comes with doxygen is build with this
  patch applied.  

mueller's avatar
mueller committed
239 240 241 242 243 244 245 246
GCC 2.7.2.X PROBLEMS

Old versions of the GNU compiler have problems with constant strings
containing characters with ascii codes >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.  

mueller's avatar
mueller committed
247 248 249 250 251 252 253 254 255 256 257
-----------------------------------------------------------------------------

That's it!

Please report any problems to dimitri@stack.nl

The latest version of doxygen can be obtained at
  http://www.stack.nl/~dimitri/doxygen

Enjoy,

dimitri's avatar
dimitri committed
258
Dimitri van Heesch (25 June 2000)