Re: [fluid-dev] Building the Doxygen documentation

[Pedro Lopez-Cabanillas]

On Friday 03 December 2010, Matt Giuca wrote:
> I had a bit of trouble building the Doxygen docs for FluidSynth. I've sort
> of resolved it now, but I'll still report the problems I had.
> 
> It looks like it has undergone "CMakeization" but I can't get it to work
> properly on Ubuntu 10.10 (doxygen 1.7.1).
> 
> I tried the following:
> 
> 1. cd doc ; cmake .

Wrong. You should only invoke cmake once, from the root build directory and 
providing the root source directory as argument.
 
> this produces the error:

Of course. Wrong results from random commands.

> CMake Error at CMakeLists.txt:33 (install):
>   install FILES given no DESTINATION!
> 
> I'm not sure why this is, as the script has on line 33 "install ( FILES
> fluidsynth.1 DESTINATION ${MAN_INSTALL_DIR} )". Maybe $MAN_INSTALL_DIR isn't
> defined properly. So I just changed it to "install ( FILES fluidsynth.1
> DESTINATION .)" and then it worked.
> 
> 2. make doxygen

This is the correct command, but you executed it from the wrong place.
The correct procedure to create the doxygen documentation is:

SOURCE=$HOME/fluidsynth-source-dir
BUILD=$HOME/your-build-dir

$ cd $BUILD
$ cmake $SOURCE 
$ make
$ make doxygen
 
> This runs fine, but it produces a completely blank page (only index.html is
> generated). The page has a heading "libfluidsynth documentation" and the
> Doxygen logo, but no other content. On the command-line, it didn't say it
> was scanning any files.
> 
> Ah, I have found the problem. The generated Doxyfile had the wrong paths.
>
> Here are the lines which were wrong:
> 
> Note that I am in the directory
> "/home/matt/src-pkg/fluidsynth/trunk/fluidsynth/doc":
>
> STRIP_FROM_PATH = /home/matt/src-pkg/fluidsynth/trunk/fluidsynth/doc/
> STRIP_FROM_INC_PATH =
> /home/matt/src-pkg/fluidsynth/trunk/fluidsynth/doc/include/
> INPUT =
> /home/matt/src-pkg/fluidsynth/trunk/fluidsynth/doc/doc/fluidsynth-v11-devdoc.txt
> /home/matt/src-pkg/fluidsynth/trunk/fluidsynth/doc/include
> /home/matt/src-pkg/fluidsynth/trunk/fluidsynth/doc/include/fluidsynth
> /home/matt/src-pkg/fluidsynth/trunk/fluidsynth/doc/src
> EXAMPLE_PATH = /home/matt/src-pkg/fluidsynth/trunk/fluidsynth/doc/doc
> 
> Note that every one of those paths is relative to 'fluidsynth/doc' and then
> puts paths on the end which are actually found in 'fluidsynth'. So I fixed
> this by removing one 'doc/' from each path:
> 
> STRIP_FROM_PATH = /home/matt/src-pkg/fluidsynth/trunk/fluidsynth/
> STRIP_FROM_INC_PATH =
> /home/matt/src-pkg/fluidsynth/trunk/fluidsynth/include/
> INPUT =
> /home/matt/src-pkg/fluidsynth/trunk/fluidsynth/doc/fluidsynth-v11-devdoc.txt
> /home/matt/src-pkg/fluidsynth/trunk/fluidsynth/include
> /home/matt/src-pkg/fluidsynth/trunk/fluidsynth/include/fluidsynth
> /home/matt/src-pkg/fluidsynth/trunk/fluidsynth/src
> EXAMPLE_PATH = /home/matt/src-pkg/fluidsynth/trunk/fluidsynth/doc
> 
> So did I do something wrong or did CMake? 

You. 

> Note that the README in the doc
> directory doesn't really explain how to use cmake to build documentation
> (and "make doxygen" doesn't work without it). I have also tried running
> CMake from the parent directory ('cmake doc') but that generates the same
> buggy file.

This README file instructions belong to the auto-tools based build system. I've 
updated it with the specific details for each build system.

Regards,
Pedro