Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add application-help-to-doxygen #533

Merged
merged 6 commits into from
Jan 20, 2017
Merged

Add application-help-to-doxygen #533

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
65a364d
Add application-help-to-doxygen
Jan 16, 2017
69aab09
CR #533
Jan 18, 2017
fb29ac2
CR #533 2
Jan 18, 2017
e4cb3b9
Fix graph generation dependencies
Jan 18, 2017
853434f
CR #533 3
Jan 18, 2017
14ca5fd
Exclude -help from default targets
Jan 20, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
2 changes: 2 additions & 0 deletions CHANGES.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# git master

* [533](https://github.com/Eyescale/CMake/pull/533):
Add application-help-to-doxygen extraction
* [532](https://github.com/Eyescale/CMake/pull/532):
Only update SHA-1s in .gitsubprojects after ```update``` instead of rewriting
the whole file
Expand Down
45 changes: 42 additions & 3 deletions CommonApplication.cmake
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,13 @@
# Copyright (c) 2014-2016 Stefan.Eilemann@epfl.ch
# Copyright (c) 2014-2017 Stefan.Eilemann@epfl.ch
# Raphael.Dumusc@epfl.ch

# Configures the build for a simple application:
# common_application(<Name> [GUI] [EXAMPLE])
# common_application(<Name> [GUI] [EXAMPLE] [NOHELP])
#
# Arguments:
# * GUI: if set, build cross-platform GUI application
# * EXAMPLE: install all sources in share/Project/examples/Name
# * NOHELP: opt out of doxygen help extraction
#
# Input:
# * NAME_SOURCES for all compilation units
Expand All @@ -19,6 +20,9 @@
# * NAME_ICON optional .icns file (Mac OS GUI applications only)
# * NAME_COPYRIGHT optional copyright notice (Mac OS GUI applications only)
#
# Output Global Properties
# * ${PROJECT_NAME}_HELP help page names generated (see DoxygenRule.cmake)
#
# Builds Name application and installs it.

include(AppleCheckOpenGL)
Expand All @@ -27,7 +31,7 @@ include(CMakeParseArguments)
include(StringifyShaders)

function(common_application Name)
set(_opts GUI EXAMPLE WIN32)
set(_opts GUI EXAMPLE NOHELP WIN32)
set(_singleArgs)
set(_multiArgs)
cmake_parse_arguments(THIS "${_opts}" "${_singleArgs}" "${_multiArgs}"
Expand Down Expand Up @@ -122,6 +126,41 @@ function(common_application Name)
endif()
endif()

if(NOT THIS_NOHELP)
# run binary with --help to capture output for doxygen
set(_doc "${PROJECT_BINARY_DIR}/help/${Name}.md")
set(_cmake "${CMAKE_CURRENT_BINARY_DIR}/${Name}.cmake")
file(WRITE ${_cmake} "
execute_process(COMMAND \${APP} --help
OUTPUT_FILE ${_doc} ERROR_FILE ${_doc}.error)
file(READ ${_doc} _doc_content)
if(NOT _doc_content)
message(FATAL_ERROR \"${Name} is missing --help\")
endif()
file(WRITE ${_doc} \"${Name} {#${Name}}
============

```
\${_doc_content}
```
\")
")
add_custom_command(OUTPUT ${_doc}
COMMAND ${CMAKE_COMMAND} -DAPP=$<TARGET_FILE:${Name}> -P ${_cmake}
DEPENDS ${Name} COMMENT "Creating help for ${Name}")
add_custom_target(${Name}-help DEPENDS ${_doc})
set_target_properties(${Name}-help PROPERTIES
EXCLUDE_FROM_DEFAULT_BUILD ON FOLDER ${PROJECT_NAME}/doxygen)
set_property(GLOBAL APPEND PROPERTY ${PROJECT_NAME}_HELP ${Name})

if(NOT TARGET ${PROJECT_NAME}-help)
add_custom_target(${PROJECT_NAME}-help)
set_target_properties(${PROJECT_NAME}-help PROPERTIES
EXCLUDE_FROM_DEFAULT_BUILD ON FOLDER ${PROJECT_NAME}/doxygen)
endif()
add_dependencies(${PROJECT_NAME}-help ${Name}-help)
endif()

if(NOT ${NAME}_OMIT_CHECK_TARGETS)
common_check_targets(${Name})
endif()
Expand Down
2 changes: 1 addition & 1 deletion CommonGraph.cmake
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -68,7 +68,7 @@ function(common_graph Name)
add_custom_command(OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/${Name}_tred.dot
COMMAND ${TRED_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/${Name}.dot >
${CMAKE_CURRENT_BINARY_DIR}/${Name}_tred.dot
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/${Name}.dot)
DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/${Name}.dot)
add_custom_command(OUTPUT ${dest}/${Name}.png
COMMAND ${CMAKE_COMMAND} -E make_directory ${dest}
COMMAND ${DOT_EXECUTABLE} -o ${dest}/${Name}.png -Tpng ${CMAKE_CURRENT_BINARY_DIR}/${Name}_tred.dot
Expand Down
24 changes: 22 additions & 2 deletions DoxygenRule.cmake
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,10 @@
# * ${PROJECT_NAME}_VERSION_(MINOR|MAJOR) The project's major/minor version,
# generally set by the project() command in the top-level CMakeLists.txt.
#
# Input Global Properties
# * ${PROJECT_NAME}_HELP a list of doxygen page anchors to add to the
# "Application Help" page
#
# Optional project information
# Output to a metadata file for html index page generation by Jekyll
# * ${UPPER_PROJECT_NAME}_DESCRIPTION A short description of the project
Expand Down Expand Up @@ -88,6 +92,20 @@ if(NOT COMMON_ORGANIZATION_NAME)
set(COMMON_ORGANIZATION_NAME Unknown)
endif()

# collect application help page
get_property(__help GLOBAL PROPERTY ${PROJECT_NAME}_HELP)
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How about file(GLOB __help "${PROJECT_BINARY_DIR}/help/*.md") instead of a global property? Potentially a bit more flexible and decoupled (for someone who wants to add his own help files in there).

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No, it would pick up stale files (see above for manual checks during release...)

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The release is made by a Jenkin plan which does a clean build, and anyone doing a manual release will (should) do the same... But I see your point, as you prefer. ${PROJECT_NAME}_HELP should be documented as an IN variable here for consistency, and as an OUT variable in CommonApplication.cmake normally.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we document this if the user is not supposed to use them?

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's a fair question. My take on this is to try to document every in/out variable of each CMake file, because it makes the interdependence between different files explicit. Having hidden global variables is not good for maintenance in the long run. Regarding this specific case, I am not sure if there is a reason users should be discouraged to add their own help file for a python application for instance (tide, rtneuron-app.py, ...)

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

if(__help)
list(APPEND DOXYGEN_EXTRA_INPUT ${PROJECT_BINARY_DIR}/help)
set(__index "${PROJECT_BINARY_DIR}/help/applications.md")
file(WRITE ${__index} "Application Help {#apps}
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Applications in plural ?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Afaik that is frenglish.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK, my bad then :-)

============

")
foreach(_help ${__help})
file(APPEND ${__index} "* @subpage ${_help}\n")
endforeach()
endif()

# list-to-string transform
string(REPLACE ";" " " DOXYGEN_EXTRA_INPUT "${DOXYGEN_EXTRA_INPUT}")

Expand All @@ -114,6 +132,9 @@ set_target_properties(${PROJECT_NAME}-doxygen PROPERTIES
if(TARGET ${PROJECT_NAME}-coverage) # CoverageReport generated by "tests" in this case
add_dependencies(${PROJECT_NAME}-doxygen ${PROJECT_NAME}-coverage)
endif()
if(TARGET ${PROJECT_NAME}-help)
add_dependencies(${PROJECT_NAME}-doxygen ${PROJECT_NAME}-help)
endif()

if(NOT TARGET doxygen)
add_custom_target(doxygen)
Expand Down Expand Up @@ -200,7 +221,6 @@ set_target_properties(${PROJECT_NAME}-doxycopy PROPERTIES

if(NOT TARGET doxycopy)
add_custom_target(doxycopy)
set_target_properties(doxycopy PROPERTIES
EXCLUDE_FROM_DEFAULT_BUILD ON)
set_target_properties(doxycopy PROPERTIES EXCLUDE_FROM_DEFAULT_BUILD ON)
endif()
add_dependencies(doxycopy ${PROJECT_NAME}-doxycopy)