DOXYGEN Version 1.1.1 CONTENTS -------- - Installation instructions for UNIX - Installation instructions for Windows - Known configuration problems: * HTML related problems * LaTeX related problems * HP-UX / Digital UNIX problems * gcc 2.7.2.x related problems INSTALLATION INSTRUCTIONS FOR UNIX: ----------------------------------- 1. Unpack the archive, unless you already have: gunzip doxygen-1.1.1.src.tar.gz # uncompress the archive tar xf doxygen-1.1.1.src.tar # unpack it 2. Run the configure script: sh ./configure The script tries to determine the platform you use, the location 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. If you have downloaded the binary distribution, you can proceed with step 6 now. 3. Compile the program by running make: make The program should compile without problems and three binaries (doxygen, doxytag, and doxysearch) should be available in the bin directory of the distribution. 4. Generate the user manual (optional, will also be done in step 6). make docs To let doxygen generate the HTML and LaTeX documentation. (you will need the stream editor `sed' for this) 5. make ps 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. 6. Install the doxygen binaries, manual and examples make install Binaries are installed in the directory /bin Documentation and examples in the directory /doc/doxygen defaults to /usr but can be changed with the --prefix option of the configure script. INSTALLATION INSTRUCTIONS FOR WINDOWS: -------------------------------------- Currently, only Microsoft Visual C++ (version 5.0 or higher) is supported. (For other compilers you may need to edit the perl script in wintools/make.pl a bit). Let me know what you had to change if you got Doxygen working with another windows compiler. You will need to install the windows/dos versions of following tools: - Perl 5.0+ 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. - Qt-1.xx (Qt-2.xx should also work, but I didn't test it for Windows) (Hint: only the tools section is required, so you can use the free X-windows version (use Qt-1.44) as well!) You can get it at http://www.troll.no - Microsoft Visual C++ (I only tested with version 5.0). Use the vcvars32.bat to set the environment variables (if you did not select to do this automatically during installation). - 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 - 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. 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). goto the doxygen root dir and type: make.bat This should build the executables doxygen.exe, doxytag.exe, and doxysearch.exe (The compiler should not produce any serious warnings or errors). To build the examples type: 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 ----------------------------------------------------------------------------- KNOWN CONFIGURATION PROBLEMS QT RELATED PROBLEMS: - 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", - do "export QTDIR=$PWD" (or "setenv QTDIR $PWD if you have a csh) Now install doxygen as described above. - Qt-2.01 contains a bug that makes some special characters appear as question marks (?) in the HTML output. 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. HTML RELATED PROBLEMS: - the indent continuously increases. This seems to be a problem that can be observed with Netscape 4.01. It is not present in many later and earlier versions I tested. 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 in the config file (see the PAPER_TYPE tag in the config file) - the file fancyheader.sty is known as fancyhdr.sty on some systems. Please change that in src/latexgen.cpp HP-UX / DIGITAL UNIX PROBLEMS: - If you are compiling for HP-UX with aCC and you get this error: /opt/aCC/lbin/ld: Unsatisfied symbols: alloca (code) then you should (according to Anke Selig) edit ce_parse.cpp and replace extern "C" { void *alloca (unsigned int); }; with #include - 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 with #else /* not GNU C. */ #if (!defined (__STDC__) && defined (sparc)) || defined (__sparc__) || defined (__sparc) || defined (__sgi) || defined (__osf__) #include 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 #else /* not sparc */ #if defined (MSDOS) && !defined (__TURBOC__) ------------------------------------------------------------------------------ The generated scanner.cpp that comes with doxygen is build with this patch applied. 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. ----------------------------------------------------------------------------- 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 van Heesch (12 March 2000)