From 8c6222169962411257929d1c21a954d5b4d2ac03 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Petr=20Mr=C3=A1zek?= Date: Fri, 18 Mar 2011 06:07:13 +0100 Subject: [PATCH] Doxygen integration, better defaults for the generated build system. --- CMake/Modules/FindDoxygen.cmake | 185 ++++++++++++++++++++++++++++++++ CMakeLists.txt | 21 +++- COMPILE.rst | 8 +- Compile.html | 6 +- doc/CMakeLists.txt | 15 +-- doc/Doxyfile.in | 6 +- doc/index.dxgen | 33 +----- 7 files changed, 223 insertions(+), 51 deletions(-) create mode 100644 CMake/Modules/FindDoxygen.cmake diff --git a/CMake/Modules/FindDoxygen.cmake b/CMake/Modules/FindDoxygen.cmake new file mode 100644 index 000000000..94d20a9ff --- /dev/null +++ b/CMake/Modules/FindDoxygen.cmake @@ -0,0 +1,185 @@ +# - This module looks for Doxygen and the path to Graphviz's dot +# Doxygen is a documentation generation tool. Please see +# http://www.doxygen.org +# +# This module accepts the following optional variables: +# +# DOXYGEN_SKIP_DOT = If true this module will skip trying to find Dot +# (an optional component often used by Doxygen) +# +# This modules defines the following variables: +# +# DOXYGEN_EXECUTABLE = The path to the doxygen command. +# DOXYGEN_FOUND = Was Doxygen found or not? +# +# DOXYGEN_DOT_EXECUTABLE = The path to the dot program used by doxygen. +# DOXYGEN_DOT_FOUND = Was Dot found or not? +# DOXYGEN_DOT_PATH = The path to dot not including the executable +# +# + +#Copyright 2000-2009 Kitware, Inc., Insight Software Consortium +#All rights reserved. +# +#Redistribution and use in source and binary forms, with or without +#modification, are permitted provided that the following conditions +#are met: +# +#* Redistributions of source code must retain the above copyright +# notice, this list of conditions and the following disclaimer. +# +#* Redistributions in binary form must reproduce the above copyright +# notice, this list of conditions and the following disclaimer in the +# documentation and/or other materials provided with the distribution. +# +#* Neither the names of Kitware, Inc., the Insight Software Consortium, +# nor the names of their contributors may be used to endorse or promote +# products derived from this software without specific prior written +# permission. +# +#THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +#"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +#LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +#A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +#HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +#SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +#LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +#DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +#THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +#(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +#OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +# +#----------------------------------------------------------------------------- +# +#The above copyright and license notice applies to distributions of +#CMake in source and binary form. Some source files contain additional +#notices of original copyright by their contributors; see each source +#for details. Third-party software packages supplied with CMake under +#compatible licenses provide their own copyright notices documented in +#corresponding subdirectories. +# +#----------------------------------------------------------------------------- +# +#CMake was initially developed by Kitware with the following sponsorship: +# +# * National Library of Medicine at the National Institutes of Health +# as part of the Insight Segmentation and Registration Toolkit (ITK). +# +# * US National Labs (Los Alamos, Livermore, Sandia) ASC Parallel +# Visualization Initiative. +# +# * National Alliance for Medical Image Computing (NAMIC) is funded by the +# National Institutes of Health through the NIH Roadmap for Medical Research, +# Grant U54 EB005149. +# +# * Kitware, Inc. + + +# For backwards compatibility support +IF(Doxygen_FIND_QUIETLY) + SET(DOXYGEN_FIND_QUIETLY TRUE) +ENDIF(Doxygen_FIND_QUIETLY) + +# ===== Rationale for OS X AppBundle mods below ===== +# With the OS X GUI version, Doxygen likes to be installed to /Applications and +# it contains the doxygen executable in the bundle. In the versions I've +# seen, it is located in Resources, but in general, more often binaries are +# located in MacOS. +# +# NOTE: The official Doxygen.app that is distributed for OS X uses non-standard +# conventions. Instead of the command-line "doxygen" tool being placed in +# Doxygen.app/Contents/MacOS, "Doxywizard" is placed there instead and +# "doxygen" is placed in Contents/Resources. This is most likely done +# so that something happens when people double-click on the Doxygen.app +# package. Unfortunately, CMake gets confused by this as when it sees the +# bundle it uses "Doxywizard" as the executable to use instead of +# "doxygen". Therefore to work-around this issue we temporarily disable +# the app-bundle feature, just for this CMake module: +if(APPLE) + # Save the old setting + SET(TEMP_DOXYGEN_SAVE_CMAKE_FIND_APPBUNDLE ${CMAKE_FIND_APPBUNDLE}) + # Disable the App-bundle detection feature + SET(CMAKE_FIND_APPBUNDLE "NEVER") +endif() +# FYI: +# In the older versions of OS X Doxygen, dot was included with the +# Doxygen bundle. But the new versions require you to download +# Graphviz.app which contains "dot" in it's bundle. +# ============== End OSX stuff ================ + +# +# Find Doxygen... +# + +FIND_PROGRAM(DOXYGEN_EXECUTABLE + NAMES doxygen + PATHS + "[HKEY_LOCAL_MACHINE\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Uninstall\\doxygen_is1;Inno Setup: App Path]/bin" + /Applications/Doxygen.app/Contents/Resources + /Applications/Doxygen.app/Contents/MacOS + DOC "Doxygen documentation generation tool (http://www.doxygen.org)" +) + +include(FindPackageHandleStandardArgs) +FIND_PACKAGE_HANDLE_STANDARD_ARGS(Doxygen DEFAULT_MSG DOXYGEN_EXECUTABLE) + +# +# Find Dot... +# + +IF(NOT DOXYGEN_SKIP_DOT) + FIND_PROGRAM(DOXYGEN_DOT_EXECUTABLE + NAMES dot + PATHS + "$ENV{ProgramFiles}/Graphviz2.26.3/bin" + "C:/Program Files/Graphviz2.26.3/bin" + "$ENV{ProgramFiles}/Graphviz 2.21/bin" + "C:/Program Files/Graphviz 2.21/bin" + "$ENV{ProgramFiles}/ATT/Graphviz/bin" + "C:/Program Files/ATT/Graphviz/bin" + [HKEY_LOCAL_MACHINE\\SOFTWARE\\ATT\\Graphviz;InstallPath]/bin + /Applications/Graphviz.app/Contents/MacOS + /Applications/Doxygen.app/Contents/Resources + /Applications/Doxygen.app/Contents/MacOS + DOC "Graphviz Dot tool for using Doxygen" + ) + + if(DOXYGEN_DOT_EXECUTABLE) + set(DOXYGEN_DOT_FOUND TRUE) + # The Doxyfile wants the path to Dot, not the entire path and executable + get_filename_component(DOXYGEN_DOT_PATH "${DOXYGEN_DOT_EXECUTABLE}" PATH CACHE) + endif() + +endif(NOT DOXYGEN_SKIP_DOT) + +# +# Backwards compatibility... +# + +if(APPLE) + # Restore the old app-bundle setting setting + SET(CMAKE_FIND_APPBUNDLE ${TEMP_DOXYGEN_SAVE_CMAKE_FIND_APPBUNDLE}) +endif() + +# Maintain the _FOUND variables as "YES" or "NO" for backwards compatibility +# (allows people to stuff them directly into Doxyfile with configure_file()) +if(DOXYGEN_FOUND) + set(DOXYGEN_FOUND "YES") +else() + set(DOXYGEN_FOUND "NO") +endif() +if(DOXYGEN_DOT_FOUND) + set(DOXYGEN_DOT_FOUND "YES") +else() + set(DOXYGEN_DOT_FOUND "NO") +endif() + +# For backwards compatibility support +SET (DOXYGEN ${DOXYGEN_EXECUTABLE} ) +SET (DOT ${DOXYGEN_DOT_EXECUTABLE} ) + +MARK_AS_ADVANCED( + DOXYGEN_EXECUTABLE + DOXYGEN_DOT_EXECUTABLE + DOXYGEN_DOT_PATH + ) diff --git a/CMakeLists.txt b/CMakeLists.txt index 416c51d17..1d54532cb 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -14,11 +14,12 @@ if("${CMAKE_SOURCE_DIR}" STREQUAL "${CMAKE_BINARY_DIR}") message(FATAL_ERROR "In-source builds are not allowed.") endif() + set(DEVEL_RELEASE "-dev") set(CPACK_PACKAGE_VERSION_MAJOR "0") set(CPACK_PACKAGE_VERSION_MINOR "5") set(CPACK_PACKAGE_VERSION_PATCH "8") -set(DFHACK_VERSION "${CPACK_PACKAGE_VERSION_MAJOR}.${CPACK_PACKAGE_VERSION_MINOR}.${CPACK_PACKAGE_VERSION_PATCH}${DEVEL_RELEASE}") +set(DFHACK_VERSION "${CPACK_PACKAGE_VERSION_MAJOR}.${CPACK_PACKAGE_VERSION_MINOR}.${CPACK_PACKAGE_VERSION_PATCH}") set(CPACK_PACKAGE_NAME "dfhack") ## setting the build type @@ -31,7 +32,12 @@ SET(CMAKE_RUNTIME_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/bin") SET(CMAKE_LIBRARY_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/bin") SET(CMAKE_ARCHIVE_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/bin") -SET(DFHACK_INSTALL "portable" CACHE STRING "Choose the install type: 'portable' for a portable zip or tar.gz package, 'linux' for packaging and system installs on linux, 'none' for no install target (default).") +IF(WIN32) + set (DFHACK_INST_DEFAULT "portable") +ELSE() + set (DFHACK_INST_DEFAULT "linux") +ENDIF() +SET( DFHACK_INSTALL ${DFHACK_INST_DEFAULT} CACHE STRING "Choose the install type: 'portable' for a portable zip or tar.gz package (windows default), 'linux' for packaging and system installs on linux (linux default).") SET( MEMXML_DATA_PATH . CACHE PATH "Path to a valid Memory.xml file. This is baked into the library, so when you package DFHack for linux, set it to the right path.") IF(${DFHACK_INSTALL} STREQUAL "portable") @@ -48,6 +54,10 @@ IF(${DFHACK_INSTALL} STREQUAL "portable") SET(DFHACK_DEVLIB_DESTINATION dev) SET(CMAKE_INSTALL_SYSTEM_RUNTIME_DESTINATION .) ENDIF() + # documentation goes here: + SET(DFHACK_USERDOC_DESTINATION .) + SET(DFHACK_DEVDOC_DESTINATION dev) + SET(DFHACK_DOXYGEN_DESTINATION dev/doxygen) ENDIF() IF(${DFHACK_INSTALL} STREQUAL "linux") @@ -59,6 +69,10 @@ IF(${DFHACK_INSTALL} STREQUAL "linux") SET(DFHACK_DATA_DESTINATION share/dfhack) # Includes go here: SET(DFHACK_INCLUDES_DESTINATION include) + # documentation goes here: + SET(DFHACK_USERDOC_DESTINATION share/dfhack/doc) + SET(DFHACK_DEVDOC_DESTINATION share/dfhack/doc) + SET(DFHACK_DOXYGEN_DESTINATION share/dfhack/doc/doxygen) ENDIF() ## some options for the user/developer to play with @@ -74,6 +88,9 @@ include_directories (${CMAKE_SOURCE_DIR}/library/depends/argstream/) add_subdirectory (library) +## install the default documentation files +install(FILES Readme.html Compile.html DESTINATION ${DFHACK_USERDOC_DESTINATION}) + # macro to save on typing in the tool subdirs # builds a tool, links it to the dfhack lib and makes sure the dependency # LOCAL_DEPNAME is built first, in case there is one diff --git a/COMPILE.rst b/COMPILE.rst index 45e1972be..951c0a369 100644 --- a/COMPILE.rst +++ b/COMPILE.rst @@ -25,7 +25,7 @@ is simple. Enter the build folder, run the tools. Like this:: cmake .. -DCMAKE_BUILD_TYPE:string=Release make -This will build the library and its tools and place them in ``/output``. +This will build the library and its tools and place them in a sub-directory ``bin`` inside your build directory. Alternatively, you can use ccmake instead of cmake: @@ -36,7 +36,7 @@ Alternatively, you can use ccmake instead of cmake: This will show a curses-based interface that lets you set all of the extra options. -You can also use a cmake-friendly IDE like KDevelop 4 or the cmake GUI +You can also use a cmake-friendly IDE like KDevelop 4 or the cmake-gui program. To be installed into the system or packaged:: @@ -75,7 +75,7 @@ You'll have to add ``C:\MinGW\`` to your PATH variable. Building -------- open up cmd and navigate to the ``dfhack\build`` folder, run ``cmake`` -and the mingw version of make:: +and the mingw version of make:: cd build cmake .. -G"MinGW Makefiles" -DCMAKE_BUILD_TYPE:string=Release @@ -97,7 +97,7 @@ This will generate MSVC solution and project files. You are working in the ``/build`` folder. Files added to projects from within MSVC will end up there! (and that's wrong). Any changes to the build system should be done - by changing cmake configs and running ``cmake`` on them! + by changing the CMakeLists.txt files and running ``cmake``! ------------------------- Using some other compiler diff --git a/Compile.html b/Compile.html index 8e91e15f2..8f271a655 100644 --- a/Compile.html +++ b/Compile.html @@ -371,7 +371,7 @@ cd build cmake .. -DCMAKE_BUILD_TYPE:string=Release make -

This will build the library and its tools and place them in /output.

+

This will build the library and its tools and place them in a sub-directory bin inside your build directory.

Alternatively, you can use ccmake instead of cmake:

cd build @@ -379,7 +379,7 @@ ccmake .. make

This will show a curses-based interface that lets you set all of the extra options.

-

You can also use a cmake-friendly IDE like KDevelop 4 or the cmake GUI +

You can also use a cmake-friendly IDE like KDevelop 4 or the cmake-gui program.

To be installed into the system or packaged:

@@ -434,7 +434,7 @@ cmake ..
 
You are working in the /build folder. Files added to
 projects from within MSVC will end up there! (and that's
 wrong). Any changes to the build system should be done
-by changing cmake configs and running cmake on them!

+by changing the CMakeLists.txt files and running cmake!

 
 
 

diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt
index 75d462d31..31c456a20 100644
--- a/doc/CMakeLists.txt
+++ b/doc/CMakeLists.txt
@@ -48,16 +48,17 @@ IF(DOXYGEN_FOUND)
   )
 
   STRING(REGEX REPLACE ";" " " CMAKE_DOXYGEN_INPUT_LIST "${DOXYGEN_SOURCE_DIR}")
-
+  set(DOXYFILE_DOT "NO")
+  if(DOXYGEN_DOT_EXECUTABLE)
+      set(DOXYFILE_DOT "YES")
+  endif()
   CONFIGURE_FILE(Doxyfile.in ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile)
-  SET(HTML_TARGET "html" )
-
-  ADD_CUSTOM_TARGET(${HTML_TARGET} ALL
-        /usr/bin/doxygen ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile
+  ADD_CUSTOM_TARGET(doxygen ALL
+        ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile
         DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile)
 
-  # INSTALL( DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/html/" DESTINATION "/usr/share/doc/dfhack-${DFHACK_VERSION}" )
-
+  INSTALL( DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/html/" DESTINATION ${DFHACK_DOXYGEN_DESTINATION} )
+  INSTALL( FILES "Doxygen.html" DESTINATION ${DFHACK_DEVDOC_DESTINATION})
 ELSE(DOXYGEN_FOUND)
   MESSAGE (WARNING "Doxygen binary couldn't be found. Can't build development documentation.'")
 ENDIF(DOXYGEN_FOUND)
\ No newline at end of file
diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in
index 1db63239d..a08f3f355 100644
--- a/doc/Doxyfile.in
+++ b/doc/Doxyfile.in
@@ -31,7 +31,7 @@ PROJECT_NAME           = dfhack
 # This could be handy for archiving the generated documentation or
 # if some version control system is used.
 
-PROJECT_NUMBER         = @DFHACK_VERSION@
+PROJECT_NUMBER         = "@DFHACK_VERSION@"
 
 # The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute)
 # base path where the generated documentation will be put.
@@ -1392,7 +1392,7 @@ HIDE_UNDOC_RELATIONS   = YES
 # toolkit from AT&T and Lucent Bell Labs. The other options in this section
 # have no effect if this option is set to NO (the default)
 
-HAVE_DOT               = NO
+HAVE_DOT               = @DOXYFILE_DOT@
 
 # By default doxygen will write a font called FreeSans.ttf to the output
 # directory and reference it in all dot files that doxygen generates. This
@@ -1498,7 +1498,7 @@ DOT_IMAGE_FORMAT       = png
 # The tag DOT_PATH can be used to specify the path where the dot tool can be
 # found. If left blank, it is assumed the dot tool can be found in the path.
 
-DOT_PATH               =
+DOT_PATH               = "@DOXYGEN_DOT_PATH@"
 
 # The DOTFILE_DIRS tag can be used to specify one or more directories that
 # contain dot files that are included in the documentation (see the
diff --git a/doc/index.dxgen b/doc/index.dxgen
index 2a2a29084..bfb6b2312 100644
--- a/doc/index.dxgen
+++ b/doc/index.dxgen
@@ -31,43 +31,12 @@ distribution.
 
 
 
Introduction

-DFHack is a Dwarf Fortress memory access library and a set of basic tools using 
+DFHack is a Dwarf Fortress memory access library and a set of basic tools using
 this library. The library is a work in progress, so things might change as more
 tools are written for it.
 
 It is an attempt to unite the various ways tools access DF memory and allow for
 easier development of new tools. In general, you can use it to move memory
 objects in and out of Dwarf Fortress really fast, regardless of DF version or OS.
-
-First part of the manual deals with the basic of using DFHack as a library:
-
    
-PLACEHOLDER TERRITORY!
-
-
  • Section \ref blah discusses some weird stuff 
-      this is a link
-
  • Section \ref starting tells you how to cromulate at a distance!
-

-
-Second part has some details on DFHack development:
-
-
    
-
  • Section \ref starting tells you how to cromulate at a distance, with a difference!
-

-
-The third part describes how to use the supported DFHack utilities
-
-
    
-
  • Section \ref dfattachtest shows how to use the \c dfattachtest program
-
  • Section \ref dfcleanmap shows how to use the \c dfcleanmap program
-
  • Section \ref dfexpbench shows how to use the \c dfexpbench program
-
  • Section \ref dfflows shows how to use the \c dfflows program
-
  • Section \ref dfliquids shows how to use the \c dfliquids program
-
  • Section \ref dfprobe shows how to use the \c dfprobe program
-
  • Section \ref dfprospector shows how to use the \c dfprospector program
-
  • Section \ref dfreveal shows how to use the \c dfreveal program
-
  • Section \ref dfsuspend shows how to use the \c dfsuspend program
-
  • Section \ref dfunstuck shows how to use the \c dfunstuck program
-
  • Section \ref dfvdig shows how to use the \c dfvdig program
-

 */