Skip to content
This repository has been archived by the owner on Jan 6, 2024. It is now read-only.

Commit

Permalink
Refactor document generation
Browse files Browse the repository at this point in the history 
Check for all tools: Doxygen, Latex and Graphviz
Optional generation of HTML, Latex, PDF and man pages.
Optional install/packaging of HTML, Latex, PDF and man docs.
Reorganized different CMake cache variables into groups.
Fix missing example in program wrapper documentation.
  • Loading branch information
@nunofachada
nunofachada committed Oct 13, 2014
1 parent 934b0e1 commit 8503f51
Show file tree
Hide file tree
Showing 8 changed files with 158 additions and 2,277 deletions.
170 changes: 127 additions & 43 deletions CMakeLists.txt
View file
Expand Up @@ -35,10 +35,12 @@ if(MINGW)
endif()

# How to get Glib location
option(USE_PKGCONFIG "Use package config for Glib? (will cause problems with MSVC)" ON)
if(USE_PKGCONFIG)
option(GLIB_USE_PKGCONFIG "Use package config for Glib? (will cause problems with MSVC)" ON)
if(GLIB_USE_PKGCONFIG)
# Search for glib with pkg-config (this will cause problems with
# Visual Studio). Works on Linux, Mac and MinGW32
unset(GLIB_INCLUDE_DIR CACHE)
unset(GLIB_CONFIG_INCLUDE_DIR CACHE)
find_package(PkgConfig REQUIRED)
pkg_check_modules(GLIB REQUIRED glib-2.0>=2.32.1)
else()
Expand All @@ -50,20 +52,23 @@ else()
set(GLIB_INCLUDE_DIRS "${GLIB_INCLUDE_DIR}" "${GLIB_CONFIG_INCLUDE_DIR}")
endif()

# Find required libraries
# Find OpenCL
find_package(OpenCL REQUIRED)

# Find optional executables for creating docs
find_package(Doxygen 1.8.3 QUIET)
find_package(LATEX QUIET)

# Use provided OpenCL headers or system OpenCL headers?
if (NOT APPLE) # Not for Apple, which handles these headers differently

option(USE_LOCAL_OPENCL_HEADERS "Use local OpenCL headers?" OFF)
option(OPENCL_USE_LOCAL_HEADERS "Use local OpenCL headers?" OFF)

SET(LOCAL_OPENCL_HEADERS "1.2" CACHE STRING "OpenCL header version selected at CMake configure time")
set(OPENCL_LOCAL_HEADERS "1.2" CACHE STRING "OpenCL header version selected at CMake configure time")

SET_PROPERTY(CACHE LOCAL_OPENCL_HEADERS PROPERTY STRINGS "1.0" "1.1" "1.2" "2.0")
set_property(CACHE OPENCL_LOCAL_HEADERS PROPERTY STRINGS "1.0" "1.1" "1.2" "2.0")

if (USE_LOCAL_OPENCL_HEADERS)
if (OPENCL_USE_LOCAL_HEADERS)
SET(OPENCL_INCLUDE_DIRS "${CMAKE_SOURCE_DIR}/ocl/${LOCAL_OPENCL_HEADERS}")
endif()

Expand All @@ -76,7 +81,8 @@ include_directories(${GLIB_INCLUDE_DIRS} ${OPENCL_INCLUDE_DIRS}
${CMAKE_BINARY_DIR}/src/${PROJECT_NAME})

# Define install subdirs
set(INSTALL_SUBDIR_DOCS_HTML share/doc/${PROJECT_NAME})
set(INSTALL_SUBDIR_DOCS_HTML share/doc/${PROJECT_NAME}/html)
set(INSTALL_SUBDIR_DOCS_PDF share/doc/${PROJECT_NAME})
set(INSTALL_SUBDIR_DOCS_MAN share/man/)
set(INSTALL_SUBDIR_INCLUDE include)
set(INSTALL_SUBDIR_BIN bin)
Expand All @@ -88,48 +94,111 @@ add_subdirectory(src)
# Add scripts folder
add_subdirectory(scripts)

# ########################### #
# BUILD DOCUMENTATION SECTION #
# ########################### #

# add a target to generate API documentation with Doxygen
if(DOXYGEN_FOUND AND GIT_FOUND)
if(DOXYGEN_FOUND AND DOXYGEN_DOT_FOUND AND LATEX_COMPILER)

# Set doc directory
# Set doc generation directory
set(DOCS_DIRECTORY "doc")

# Install docs?
option(DOC_INSTALL_HTML "Install HTML API documentation?" OFF)
if (UNIX)
option(DOC_INSTALL_MAN "Install man pages?" OFF)
# Document generation options
option(DOC_GENERATE_HTML "Generate HTML documentation?" ON)
option(DOC_GENERATE_LATEX "Generate Latex documentation?" OFF)
if (CMAKE_MAKE_PROGRAM AND DOC_GENERATE_LATEX)
option(DOC_GENERATE_PDF "Generate PDF documentation?" OFF)
else()
unset(DOC_GENERATE_PDF CACHE)
endif()

# Create links to OpenCL API when OpenCL functions are mentioned?
# This is slow and requires Bash and other command-line utilties
option(DOC_OPENCL_FUNCTION_URLS "Create links to OpenCL API (much slower)?" OFF)
if (DOC_OPENCL_FUNCTION_URLS)
# Create those links
set(DOC_OPENCL_FUNCTION_URLS_FILTER "${PROJECT_SOURCE_DIR}/auxbuild/docfilter.sh")
if(UNIX)
option(DOC_GENERATE_MAN "Generate man pages?" OFF)
endif()

# Set doxygen document generation options
if (DOC_GENERATE_HTML)
set(DOX_GENERATE_HTML "YES")
else()
set(DOX_GENERATE_HTML "NO")
endif()
if (DOC_GENERATE_LATEX)
set(DOX_GENERATE_LATEX "YES")
else()
set(DOX_GENERATE_LATEX "NO")
endif()
if (DOC_GENERATE_MAN)
set(DOX_GENERATE_MAN "YES")
else()
set(DOX_GENERATE_MAN "NO")
endif()

# Document install options
if (DOC_GENERATE_HTML)
option(DOC_INSTALL_HTML "Install HTML documentation?" OFF)
else()
unset(DOC_INSTALL_HTML CACHE)
endif()
if (DOC_GENERATE_PDF)
option(DOC_INSTALL_PDF "Install Latex documentation?" OFF)
else()
unset(DOC_INSTALL_PDF CACHE)
endif()
if (DOC_GENERATE_MAN)
option(DOC_INSTALL_MAN "Install HTML API documentation?" OFF)
else()
unset(DOC_INSTALL_MAN CACHE)
endif()

# If git is found, set document file version filter to last
# commit where file was changed
if (GIT_FOUND)
set(DOX_FILE_VERSION_FILTER
"${GIT_EXECUTABLE} log -n 1 --pretty=%h --")
endif()

# Linux/OSX options
if (UNIX)

# Create links to OpenCL API when OpenCL functions are mentioned?
# This is slow and requires Bash and other command-line utilties
option(DOC_OPENCL_FUNCTION_URLS "Create links to OpenCL API (much slower)?" OFF)
if (DOC_OPENCL_FUNCTION_URLS)
# Create those links
set(DOX_OPENCL_FUNCTION_URLS_FILTER "${PROJECT_SOURCE_DIR}/auxbuild/docfilter.sh")
endif()

# Required for Doxyfile
if(UNIX)
set(GENERATE_MAN "YES")
endif()

# Copy and configure doxigen configuration file
configure_file(${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile @ONLY)
configure_file(${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in
${CMAKE_CURRENT_BINARY_DIR}/Doxyfile @ONLY)

# Add a build docs target
add_custom_target(doc
${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
COMMENT "Generating API documentation with Doxygen" VERBATIM
)

# Copy images to doc directory
add_custom_command(TARGET doc POST_BUILD
COMMAND ${CMAKE_COMMAND} -E copy_directory
${CMAKE_CURRENT_SOURCE_DIR}/images
${DOCS_DIRECTORY}/html/images)

# Compress man pages created by Doxygen
if(UNIX)
if (DOC_GENERATE_HTML OR DOC_GENERATE_LATEX OR DOC_GENERATE_MAN)
add_custom_target(doc
${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
COMMENT "Generating API documentation with Doxygen" VERBATIM
)
else()
add_custom_target(doc
${CMAKE_COMMAND} -E echo "Enable at least one document format."
COMMENT "All document generation formats are disabled!" VERBATIM
)
endif()

# Generate PDF from latex files
if (DOC_GENERATE_PDF)
add_custom_command(TARGET doc POST_BUILD
COMMAND ${CMAKE_MAKE_PROGRAM}
COMMAND ${CMAKE_COMMAND} -E make_directory ../pdf
COMMAND ${CMAKE_COMMAND} -E copy refman.pdf ../pdf
WORKING_DIRECTORY ${DOCS_DIRECTORY}/latex)
endif()

# Post-process man pages created by Doxygen
if(DOC_GENERATE_MAN)
add_custom_command(TARGET doc POST_BUILD
COMMAND ${CMAKE_SOURCE_DIR}/auxbuild/buildman.sh
WORKING_DIRECTORY ${CMAKE_BINARY_DIR}/${DOCS_DIRECTORY}/man/)
Expand All @@ -140,21 +209,33 @@ if(DOXYGEN_FOUND AND GIT_FOUND)
install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/${DOCS_DIRECTORY}/html/
DESTINATION ${INSTALL_SUBDIR_DOCS_HTML} OPTIONAL)
endif()
if (UNIX AND DOC_INSTALL_MAN)

if (DOC_INSTALL_PDF)
install(FILES ${CMAKE_CURRENT_BINARY_DIR}/${DOCS_DIRECTORY}/latex/refman.pdf
DESTINATION ${INSTALL_SUBDIR_DOCS_PDF} OPTIONAL)
endif()

if (DOC_INSTALL_MAN)
install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/${DOCS_DIRECTORY}/man/
DESTINATION ${INSTALL_SUBDIR_DOCS_MAN} OPTIONAL
FILES_MATCHING REGEX "(ccl|CCL).*gz")
endif()

endif()

# ################# #
# PACKAGING SECTION #
# ################# #

# build a CPack driven installer package
include(InstallRequiredSystemLibraries)

# Determine architecture
target_architecture(BUILD_ARCH_GET)
set(BUILD_ARCH "${BUILD_ARCH_GET}" CACHE STRING "Build architecture (for packaging only)")
set(PACKAGE_ARCH_NAME "${BUILD_ARCH_GET}" CACHE STRING "Build architecture (for packaging only)" FORCE)
mark_as_advanced(PACKAGE_ARCH_NAME)

# Generic packaging settings
set(CPACK_GENERATOR "TGZ")
set(CPACK_PACKAGE_VERSION_MAJOR "${${PROJECT_NAME}_VERSION_MAJOR}")
set(CPACK_PACKAGE_VERSION_MINOR "${${PROJECT_NAME}_VERSION_MINOR}")
Expand All @@ -164,16 +245,19 @@ set(CPACK_PACKAGE_DESCRIPTION_FILE "${CMAKE_CURRENT_SOURCE_DIR}/README.md")
set(CPACK_RESOURCE_FILE_README "${CMAKE_CURRENT_SOURCE_DIR}/README.md")
set(CPACK_RESOURCE_FILE_LICENSE "${CMAKE_CURRENT_SOURCE_DIR}/COPYING")
set(CPACK_PACKAGE_DESCRIPTION_SUMMARY "A cross-platform pure C99 object-oriented framework for developing and benchmarking OpenCL projects in C/C++")
set(CPACK_PACKAGE_FILE_NAME "${PROJECT_NAME}-${CPACK_PACKAGE_VERSION}-${CMAKE_SYSTEM_NAME}.${BUILD_ARCH}")
set(CPACK_PACKAGE_FILE_NAME "${PROJECT_NAME}-${CPACK_PACKAGE_VERSION}-${CMAKE_SYSTEM_NAME}.${PACKAGE_ARCH_NAME}")
set(CPACK_RESOURCE_VENDOR "fakenmc.com")

if(WIN32)
# Windows packaging settings
set(CPACK_GENERATOR "NSIS" "ZIP")
set(CPACK_PACKAGE_INSTALL_DIRECTORY "${PROJECT_NAME}")
set(CPACK_NSIS_URL_INFO_ABOUT "http://fakenmc.github.io/cf4ocl/" )
elseif(APPLE)

# OSX packaging settings
# Use defaults
elseif(UNIX)
# Linux packaging settings
set(CPACK_GENERATOR "DEB" "RPM" "TGZ")

set(CPACK_DEBIAN_PACKAGE_MAINTAINER "Nuno Fachada <faken@fakenmc.com>")
Expand Down
22 changes: 11 additions & 11 deletions Doxyfile.in
View file
Expand Up @@ -555,7 +555,7 @@ SHOW_NAMESPACES = NO
# provided by doxygen. Whatever the program writes to standard output
# is used as the file version. See the manual for examples.

FILE_VERSION_FILTER = "git log -n 1 --pretty=%h --"
FILE_VERSION_FILTER = "@DOX_FILE_VERSION_FILTER@"

# The LAYOUT_FILE tag can be used to specify a layout file which will be parsed
# by doxygen. The layout file controls the global structure of the generated
Expand Down Expand Up @@ -708,7 +708,7 @@ RECURSIVE = YES
# Note that relative paths are relative to the directory from which doxygen is
# run.

EXCLUDE = @DOC_EXCLUDE_PATHS@
EXCLUDE = @DOX_EXCLUDE_PATHS@

# The EXCLUDE_SYMLINKS tag can be used to select whether or not files or
# directories that are symbolic links (a Unix file system feature) are excluded
Expand Down Expand Up @@ -756,7 +756,7 @@ EXAMPLE_RECURSIVE = NO
# directories that contain image that are included in the documentation (see
# the \image command).

IMAGE_PATH = @PROJECT_BINARY_DIR@/doc/html/images
IMAGE_PATH = @PROJECT_SOURCE_DIR@/images

# The INPUT_FILTER tag can be used to specify a program that doxygen should
# invoke to filter for each input file. Doxygen will invoke the filter program
Expand All @@ -766,7 +766,7 @@ IMAGE_PATH = @PROJECT_BINARY_DIR@/doc/html/images
# to standard output. If FILTER_PATTERNS is specified, this tag will be
# ignored.

INPUT_FILTER = "@DOC_OPENCL_FUNCTION_URLS_FILTER@"
INPUT_FILTER = "@DOX_OPENCL_FUNCTION_URLS_FILTER@"

# The FILTER_PATTERNS tag can be used to specify filters on a per file pattern
# basis. Doxygen will compare the file name with each pattern and apply the
Expand Down Expand Up @@ -876,7 +876,7 @@ IGNORE_PREFIX =
# If the GENERATE_HTML tag is set to YES (the default) Doxygen will
# generate HTML output.

GENERATE_HTML = YES
GENERATE_HTML = @DOX_GENERATE_HTML@

# The HTML_OUTPUT tag is used to specify where the HTML docs will be put.
# If a relative path is entered the value of OUTPUT_DIRECTORY will be
Expand Down Expand Up @@ -1223,7 +1223,7 @@ SERVER_BASED_SEARCH = NO
# If the GENERATE_LATEX tag is set to YES (the default) Doxygen will
# generate Latex output.

GENERATE_LATEX = NO
GENERATE_LATEX = @DOX_GENERATE_LATEX@

# The LATEX_OUTPUT tag is used to specify where the LaTeX docs will be put.
# If a relative path is entered the value of OUTPUT_DIRECTORY will be
Expand All @@ -1237,13 +1237,13 @@ LATEX_OUTPUT = latex
# generating bitmaps for formulas in the HTML output, but not in the
# Makefile that is written to the output directory.

LATEX_CMD_NAME = latex
LATEX_CMD_NAME = @LATEX_COMPILER@

# The MAKEINDEX_CMD_NAME tag can be used to specify the command name to
# generate index for LaTeX. If left blank `makeindex' will be used as the
# default command name.

MAKEINDEX_CMD_NAME = makeindex
MAKEINDEX_CMD_NAME = @MAKEINDEX_COMPILER@

# If the COMPACT_LATEX tag is set to YES Doxygen generates more compact
# LaTeX documents. This may be useful for small projects and may help to
Expand Down Expand Up @@ -1294,7 +1294,7 @@ USE_PDFLATEX = YES
# running if errors occur, instead of asking the user for help.
# This option is also used when generating formulas in HTML.

LATEX_BATCHMODE = NO
LATEX_BATCHMODE = YES

# If LATEX_HIDE_INDICES is set to YES then doxygen will not
# include the index chapters (such as File Index, Compound Index, etc.)
Expand Down Expand Up @@ -1364,7 +1364,7 @@ RTF_EXTENSIONS_FILE =
# If the GENERATE_MAN tag is set to YES (the default) Doxygen will
# generate man pages

GENERATE_MAN = @GENERATE_MAN@
GENERATE_MAN = @DOX_GENERATE_MAN@

# The MAN_OUTPUT tag is used to specify where the man pages will be put.
# If a relative path is entered the value of OUTPUT_DIRECTORY will be
Expand Down Expand Up @@ -1722,7 +1722,7 @@ INTERACTIVE_SVG = NO
# 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
Expand Down
2 changes: 1 addition & 1 deletion VERSION
View file
@@ -1 +1 @@
v2.0.0-beta.1+1.c82cae1*v2.0.0-beta.1*2*0*0*beta.1*1*c82cae1
v2.0.0-beta.1+2.934b0e1*v2.0.0-beta.1*2*0*0*beta.1*2*934b0e1
Binary file added images/gantt_ca.png
View file
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.

0 comments on commit 8503f51

Please sign in to comment.