From: Russ Combs Date: Thu, 9 Jul 2015 18:11:10 +0000 (-0400) Subject: fix cmake build of docs X-Git-Tag: 3.0.0-233~912 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=4983dd2130b39e45d5b5beb9eeee66dab5c64bb5;p=thirdparty%2Fsnort3.git fix cmake build of docs --- diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt index 2d644720b..bc5c21999 100644 --- a/doc/CMakeLists.txt +++ b/doc/CMakeLists.txt @@ -1,7 +1,5 @@ - - -# snort --help-${type} -set(HELP_SOURCES +set ( + HELP_SOURCES commands.txt config.txt counts.txt @@ -10,17 +8,16 @@ set(HELP_SOURCES options.txt signals.txt help.txt -# snort2lua_cmds.txt Get Snort2Lua command line options -) + ) -# snort --list-${type} -set(LIST_SOURCES +set ( + LIST_SOURCES builtin.txt gids.txt -) + ) -# snort --help-module ${module} -set (MODULE_SOURCES +set ( + MODULE_SOURCES basic.txt codec.txt data.txt @@ -28,9 +25,10 @@ set (MODULE_SOURCES ips_action.txt ips_option.txt logger.txt -) + ) -set (UNBUILT_SOURCES +set ( + UNBUILT_SOURCES bugs.txt daq.txt differences.txt @@ -50,268 +48,133 @@ set (UNBUILT_SOURCES style.txt terms.txt usage.txt -# config_changes.txt If ruby executable is not found -) - -if (MAKE_PDF_DOC OR MAKE_HTML_DOC OR MAKE_TEXT_DOC) - set(BUILT_SOURCES - ${HELP_SOURCES} - ${LIST_SOURCES} - ${MODULE_SOURCES} - # version.txt Requires special formatting. manually added below. - # config_changes.txt If ruby executable found ) - set (EXTRA_SOURCES - ${BUILT_SOURCES} - config_changes.txt - snort2lua_cmds.txt - version.txt - ) -endif() - -if (MAKE_HTML_DOC) - set(HTML_DOCS snort_manual.html) -else () - list(APPEND PACKAGED_DIST "default_snort_manual.html") -endif() - -if (MAKE_PDF_DOC) - set(PDF_DOCS snort_manual.pdf) -else () - list(APPEND PACKAGED_DIST "default_snort_manual.pdf") -endif () - -if (MAKE_TEXT_DOC) - set(TEXT_DOCS snort_manual.text) -else () - list(APPEND PACKAGED_DIST "default_snort_manual.text") -endif() - -# Documents to be built -set (EXTRA_DIST ${HTML_DOCS} ${PDF_DOCS} ${TEXT_DOCS}) - - -############################################################################### -############################################################################### - - -############################################################################### -# # -# Since we'd lke to keep the source tree unpolluted, create all targets in # -# the build directory. This section adds custom commands to copy all of the # -# UNBUILT_SOURCES into this directory and create all of the BUILT_SOURCES in # -# this directory. # -# # -# # -############################################################################### - - -if (MAKE_PDF_DOC OR MAKE_HTML_DOC OR MAKE_TEXT_DOC) - - # first, build all of the documents in the binary tree - - foreach (file ${HELP_SOURCES}) - set (output "${CMAKE_CURRENT_BINARY_DIR}/${file}") - get_filename_component(file_name "${file}" NAME_WE) - - add_custom_command( - OUTPUT ${output} - COMMAND ${CMAKE_COMMAND} - -DOUT_FILE=${output} - -DSNORT_EXECUTABLE=$ - -DHELP_TYPE=${file_name} - -P ${CMAKE_CURRENT_LIST_DIR}/cmake_scripts.cmake - DEPENDS snort cmake_scripts.cmake - COMMENT "Documents: building ${file}" - ) - list(APPEND ALL_SOURCES ${output}) - endforeach(file) - - foreach (file ${LIST_SOURCES}) - set (output "${CMAKE_CURRENT_BINARY_DIR}/${file}") - get_filename_component(file_name "${file}" NAME_WE) - - add_custom_command( - OUTPUT ${output} - COMMAND ${CMAKE_COMMAND} - -DOUT_FILE=${output} - -DSNORT_EXECUTABLE=$ - -DLIST_TYPE=${file_name} - -P ${CMAKE_CURRENT_LIST_DIR}/cmake_scripts.cmake - DEPENDS snort cmake_scripts.cmake - COMMENT "Documents: building ${file}" - ) - list(APPEND ALL_SOURCES ${output}) - endforeach(file) - - foreach (module ${MODULE_SOURCES}) - set (output "${CMAKE_CURRENT_BINARY_DIR}/${module}") - get_filename_component(module_name "${module}" NAME_WE) - - add_custom_command( - OUTPUT ${output} - COMMAND ${CMAKE_COMMAND} - -DOUT_FILE=${output} - -DSNORT_EXECUTABLE=$ - -DMODULE_TYPE=${module_name} - -P ${CMAKE_CURRENT_LIST_DIR}/cmake_scripts.cmake - DEPENDS snort cmake_scripts.cmake - COMMENT "Documents: building ${module}" - ) - list(APPEND ALL_SOURCES ${output}) - endforeach(module) - - # build version.txt seperately - set (output ${CMAKE_CURRENT_BINARY_DIR}/version.txt) - add_custom_command( - OUTPUT ${output} - COMMAND $ -V 2>&1 | grep -v Using > ${output} +include ( help.cmake ) + +add_custom_target ( snort_manuals ALL ) + +if ( MAKE_HTML_DOC OR MAKE_TEXT_DOC OR MAKE_PDF_DOC ) + foreach ( output_file ${HELP_SOURCES} ) + add_help_command ( + "${CMAKE_CURRENT_LIST_DIR}/scripts/generate_help.sh" + "${output_file}" + ) + + list ( APPEND BUILT_SOURCES "${output_file}" ) + endforeach () + + foreach ( output_file ${LIST_SOURCES} ) + add_help_command ( + "${CMAKE_CURRENT_LIST_DIR}/scripts/generate_list.sh" + "${output_file}" + ) + + list ( APPEND BUILT_SOURCES "${output_file}" ) + endforeach () + + foreach ( output_file ${MODULE_SOURCES} ) + add_help_command ( + "${CMAKE_CURRENT_LIST_DIR}/scripts/generate_module.sh" + "${output_file}" + ) + + list ( APPEND BUILT_SOURCES "${output_file}" ) + endforeach () + + add_custom_command ( + OUTPUT version.txt + COMMAND $ -V 2>&1 | grep -v Using > version.txt DEPENDS snort COMMENT "Documents: building version.txt" - ) - list(APPEND ALL_SOURCES ${output}) - - # If ruby is present, built the configuration differences - if (RUBY_EXECUTABLE) - set (input ${CMAKE_CURRENT_LIST_DIR}/config_changes.txt) - set (output ${CMAKE_CURRENT_BINARY_DIR}/config_changes.txt) - add_custom_command( - OUTPUT ${output} - COMMAND ${RUBY_EXECUTABLE} - ${CMAKE_CURRENT_LIST_DIR}/get_differences.rb - ${CMAKE_SOURCE_DIR}/tools/snort2lua - > ${input} - COMMAND ${CMAKE_COMMAND} -E copy ${input} ${output} - DEPENDS snort2lua ${CMAKE_CURRENT_LIST_DIR}/get_differences.rb - COMMENT "Documents: building config_changes.txt" ) - list (APPEND ALL_SOURCES ${output}) - else() - list (APPEND UNBUILT_SOURCES config_changes.txt) - endif() + list ( APPEND BUILT_SOURCES version.txt ) - set (output ${CMAKE_CURRENT_BINARY_DIR}/snort2lua_cmds.txt) - add_custom_command( - OUTPUT ${output} - COMMAND $ --markup --help > ${output} + add_custom_command ( + OUTPUT snort2lua_cmds.txt + COMMAND $ --markup --help > snort2lua_cmds.txt DEPENDS snort2lua COMMENT "Documents: building snort2lua_cmds.txt" - ) - list (APPEND ALL_SOURCES ${output}) - - - # next, Copy all distributed files into the binary tree (necessary for asciidocs). - # Then create a dependency between the new and old files. - if (NOT (CMAKE_CURRENT_SOURCE_DIR STREQUAL CMAKE_CURRENT_BINARY_DIR) ) - foreach (file ${UNBUILT_SOURCES}) - set (input "${CMAKE_CURRENT_SOURCE_DIR}/${file}") - set (output "${CMAKE_CURRENT_BINARY_DIR}/${file}") - add_custom_command( - OUTPUT ${output} - COMMAND ${CMAKE_COMMAND} -E copy ${input} ${output} - DEPENDS ${input} - COMMENT "Documents: copying ${file} into binary directory" - ) + ) - list(APPEND ALL_SOURCES "${CMAKE_CURRENT_BINARY_DIR}/${file}") - list(APPEND EXTRA_CLEAN "${CMAKE_CURRENT_BINARY_DIR}/${file}") - endforeach(file) - endif() - -endif() - -############################################################################### -############################################################################### - -# create the recipes for building the files - -set (PDF_ARGUMENTS -a imagesdir=.) -set (HTML_ARGUMENTS --copy --attribute linkcss --attribute stylesdir --attribute disable-javascript) -set (HTML_ARGUMENTS ${HTML_ARGUMENTS} --xsltproc-opts=\"--stringparam chunk.tocs.and.lots 1\") -set (HTML_ARGUMENTS ${HTML_ARGUMENTS} --attribute quirks! ${PDF_ARGUMENTS}) - -if (MAKE_HTML_DOC) - add_custom_command(OUTPUT snort_manual.html - COMMAND ${ASCIIDOC_EXE} - -b xhtml11 - -a toc2 - -a icons - -a imagesdir=. - ${CMAKE_CURRENT_BINARY_DIR}/snort_manual.txt - COMMAND ${ASCIIDOC_A2X_EXE} - -f chunked - ${HTML_ARGUMENTS} - --resource=${CMAKE_CURRENT_BINARY_DIR} - --destination-dir=${CMAKE_CURRENT_BINARY_DIR} - ${CMAKE_CURRENT_BINARY_DIR}/snort_manual.txt - DEPENDS ${ALL_SOURCES} - WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR} - COMMENT "Documents: building snort_manual.html" - ) -endif (MAKE_HTML_DOC) - -# pdf and text depend on xml generated by asciidoc html above - -if (MAKE_PDF_DOC) - add_custom_command(OUTPUT snort_manual.pdf - COMMAND ${ASCIIDOC_A2X_EXE} - -f pdf - ${PDF_ARGUMENTS} - ${CMAKE_CURRENT_BINARY_DIR}/snort_manual.txt - # adding HTML dependency to ensure documents build sequentially - DEPENDS ${ALL_SOURCES} ${HTML_DOCS} - COMMENT "Documents: building snort_manual.pdf" - ) -endif (MAKE_PDF_DOC) - -if (MAKE_TEXT_DOC) - add_custom_command(OUTPUT snort_manual.text - COMMAND ${ASCIIDOC_A2X_EXE} - -f text - ${CMAKE_CURRENT_BINARY_DIR}/snort_manual.txt - # adding pdf dependency to ensure documents build sequentially - DEPENDS ${ALL_SOURCES} ${PDF_DOCS} - COMMENT "Documents: building snort_manual.text" - ) -endif (MAKE_TEXT_DOC) + list ( APPEND BUILT_SOURCES snort2lua_cmds.txt ) -############################################################################### -############################################################################### + if ( RUBY_EXECUTABLE ) + add_custom_command ( + OUTPUT config_changes.txt + COMMAND ${RUBY_EXECUTABLE} + "${CMAKE_CURRENT_LIST_DIR}/get_differences.rb" + "${CMAKE_SOURCE_DIR}/tools/snort2lua" + > config_changes.txt + DEPENDS snort2lua get_differences.rb + COMMENT "Documents: building config_changes.txt" + ) -# Finally, the commands to set the manual dependencies and install the -# built documents + list ( APPEND BUILT_SOURCES config_changes.txt ) + elseif ( RUBY_EXECUTABLE ) + list ( APPEND UNBUILT_SOURCES config_changes.txt ) + endif ( RUBY_EXECUTABLE ) -# Specify binary path so we install the build manuals, not packaged manuals -foreach (file ${EXTRA_DIST} ${EXTRA_SOURCES}) - list(APPEND BUILT_DIST "${CMAKE_CURRENT_BINARY_DIR}/${file}") -endforeach(file) + file ( COPY ${UNBUILT_SOURCES} DESTINATION ${CMAKE_CURRENT_BINARY_DIR} ) -add_custom_target(snort_manuals ALL DEPENDS ${BUILT_DIST}) + add_custom_target ( + all_doc_sources + DEPENDS ${BUILT_SOURCES} ${UNBUILT_SOURCES} + ) -if (BUILT_DIST) - install (FILES ${BUILT_DIST} DESTINATION "${SNORT_DATA_DIR}") -endif() + set ( DOC_BINARY_DIR "${CMAKE_CURRENT_BINARY_DIR}" ) + set ( SNORT_MANUAL_TXT "${CMAKE_CURRENT_BINARY_DIR}/snort_manual.txt" ) + + if ( MAKE_HTML_DOC ) + add_subdirectory ( html ) + list ( APPEND BUILT_DIST "${CMAKE_CURRENT_BINARY_DIR}/html/snort_manual.html" ) + endif ( MAKE_HTML_DOC ) + + if ( MAKE_TEXT_DOC ) + add_subdirectory ( text ) + list ( APPEND BUILT_DIST "${CMAKE_CURRENT_BINARY_DIR}/text/snort_manual.text" ) + endif ( MAKE_TEXT_DOC ) + + if ( MAKE_PDF_DOC ) + add_subdirectory ( pdf ) + list ( APPEND BUILT_DIST "${CMAKE_CURRENT_BINARY_DIR}/pdf/snort_manual.pdf" ) + endif ( MAKE_PDF_DOC ) + + foreach ( file_name ${BUILT_SOURCES} ) + list ( APPEND BUILT_DIST "${CMAKE_CURRENT_BINARY_DIR}/${file_name}" ) + endforeach ( file_name ) + + if ( BUILT_DIST ) + install ( FILES ${BUILT_DIST} DESTINATION "${SNORT_DATA_DIR}" ) + endif ( BUILT_DIST ) + + if ( UNBUILT_SOURCES ) + install ( FILES ${UNBUILT_SOURCES} DESTINATION "${SNORT_DATA_DIR}" ) + endif ( UNBUILT_SOURCES ) + + if ( MAKE_HTML_DOC ) + install ( + DIRECTORY + "${CMAKE_CURRENT_BINARY_DIR}/html/snort_manual.chunked/" + DESTINATION + "${SNORT_DATA_DIR}/snort_manual.chunked" + ) + + list ( APPEND EXTRA_CLEAN "${CMAKE_CURRENT_BINARY_DIR}/snort_manual.chunked" ) + endif ( MAKE_HTML_DOC ) -if (PACKAGED_DIST) - install (FILES ${PACKAGED_DIST} DESTINATION "${SNORT_DATA_DIR}") -endif() + foreach ( file_name ${UNBUILT_SOURCES} ) + list ( APPEND EXTRA_CLEAN "${CMAKE_CURRENT_BINARY_DIR}/${file_name}" ) + endforeach ( file_name ) -if (UNBUILT_SOURCES) - install (FILES ${UNBUILT_SOURCES} DESTINATION "${SNORT_DATA_DIR}") -endif() -if (MAKE_HTML_DOC) - set (HTML_CHUNKED "${CMAKE_CURRENT_BINARY_DIR}/snort_manual.chunked") - install (DIRECTORY ${HTML_CHUNKED}/ DESTINATION "${SNORT_DATA_DIR}/snort_manual.chunked") - list(APPEND EXTRA_CLEAN "${HTML_CHUNKED}") -endif() +endif ( MAKE_HTML_DOC OR MAKE_TEXT_DOC OR MAKE_PDF_DOC ) -if (EXTRA_CLEAN) - set_property( +if ( EXTRA_CLEAN ) + set_property ( DIRECTORY PROPERTY ADDITIONAL_MAKE_CLEAN_FILES ${EXTRA_CLEAN} - ) -endif() + ) +endif ( EXTRA_CLEAN ) diff --git a/doc/help.cmake b/doc/help.cmake new file mode 100644 index 000000000..cbc534d64 --- /dev/null +++ b/doc/help.cmake @@ -0,0 +1,10 @@ +function ( add_help_command generator_script output_file ) + + add_custom_command ( + OUTPUT ${output_file} + COMMAND ${generator_script} $ ${output_file} + DEPENDS snort + COMMENT "Documents: building ${output_file}" + ) + +endfunction ( add_help_command ) diff --git a/doc/html/CMakeLists.txt b/doc/html/CMakeLists.txt new file mode 100644 index 000000000..19369a992 --- /dev/null +++ b/doc/html/CMakeLists.txt @@ -0,0 +1,40 @@ +set ( + HTML_ASCIIDOC_ARGS + -b xhtml11 + -a toc2 + -a icons + -a imagesdir=.. + ) + +set ( + HTML_A2X_ARGS + --format=chunked + --attribute=linkcss --attribute=stylesdir --attribute=disable-javascript + --xsltproc-opts=\"--stringparam chunk.tocs.and.lots 1\" + --attribute=quirks! + --attribute=imagesdir=. + --resource=.. + --destination-dir=. + --keep-artifacts # FIXIT: Do we need keep the build artifacts? + ) + +add_custom_command ( + OUTPUT snort_manual.chunked + COMMAND ${ASCIIDOC_EXE} ${HTML_ASCIIDOC_ARGS} ${SNORT_MANUAL_TXT} + COMMAND ${ASCIIDOC_A2X_EXE} ${HTML_A2X_ARGS} ${SNORT_MANUAL_TXT} + DEPENDS all_doc_sources + COMMENT "Documents: building snort_manual.html" + ) + +add_custom_command ( + OUTPUT snort_manual.html + COMMAND cp ${DOC_BINARY_DIR}/snort_manual.html . + DEPENDS snort_manual.chunked + ) + +add_custom_target ( + snort_manual_html + DEPENDS snort_manual.html snort_manual.chunked + ) + +add_dependencies ( snort_manuals snort_manual_html ) diff --git a/doc/pdf/CMakeLists.txt b/doc/pdf/CMakeLists.txt new file mode 100644 index 000000000..187239e74 --- /dev/null +++ b/doc/pdf/CMakeLists.txt @@ -0,0 +1,22 @@ +set ( + PDF_A2X_ARGS + --format=pdf + --attribute=imagesdir=. + --resource=.. + --destination-dir=. + --keep-artifacts # FIXIT: Do we need keep the build artifacts? + ) + +add_custom_command ( + OUTPUT snort_manual.pdf + COMMAND ${ASCIIDOC_A2X_EXE} ${PDF_A2X_ARGS} ${SNORT_MANUAL_TXT} + DEPENDS all_doc_sources + COMMENT "Documents: building snort_manual.pdf" + ) + +add_custom_target ( + snort_manual_pdf + DEPENDS snort_manual.pdf snort_manual.xml + ) + +add_dependencies ( snort_manuals snort_manual_pdf ) diff --git a/doc/scripts/generate_help.sh b/doc/scripts/generate_help.sh new file mode 100755 index 000000000..e516bee05 --- /dev/null +++ b/doc/scripts/generate_help.sh @@ -0,0 +1,35 @@ +#!/usr/bin/env bash + +SNORT_BINARY="$1" +OUTPUT_FILE="$2" +PLUGIN_PATH="$3" +HELP_ARG="--help" +PLUGIN_ARGS= +SORT_ARGS= + +if [[ -n "${PLUGIN_PATH}" ]]; then + PLUGIN_ARGS="--plugin-path=${PLUGIN_PATH}" +fi + +HELP_TYPE=`basename "${OUTPUT_FILE}" .txt` + +if [[ "${HELP_TYPE}" != "help" ]]; then + HELP_ARG="${HELP_ARG}-${HELP_TYPE}" + + case "${HELP_TYPE}" in + config) + SORT_ARGS="-k 3" + ;; + counts) + SORT_ARGS="-k 2" + ;; + esac +fi + +if [[ -n "${SORT_ARGS}" ]]; then + "${SNORT_BINARY}" ${PLUGIN_ARGS} --markup "${HELP_ARG}" | sort ${SORT_ARGS} \ + > "${OUTPUT_FILE}" +else + "${SNORT_BINARY}" ${PLUGIN_ARGS} --markup "${HELP_ARG}" \ + > "${OUTPUT_FILE}" +fi diff --git a/doc/scripts/generate_list.sh b/doc/scripts/generate_list.sh new file mode 100755 index 000000000..3a6f125cc --- /dev/null +++ b/doc/scripts/generate_list.sh @@ -0,0 +1,27 @@ +#!/usr/bin/env bash + +SNORT_BINARY="$1" +OUTPUT_FILE="$2" +PLUGIN_PATH="$3" +LIST_ARG= +PLUGIN_ARGS= +SORT_OPTIONS= + +if [[ -n "${PLUGIN_PATH}" ]]; then + PLUGIN_ARGS="--plugin-path=${PLUGIN_PATH}" +fi + +LIST_TYPE=`basename ${OUTPUT_FILE} .txt` + +case "${LIST_TYPE}" in + gids) + SORT_OPTIONS="-n -k 1.4" + ;; + builtin) + SORT_OPTIONS="-n -t : -k 1.4 -k 2" + ;; +esac + +"${SNORT_BINARY}" ${PLUGIN_ARGS} --markup "--list-${LIST_TYPE}" \ + | sort ${SORT_OPTIONS} \ + > "${OUTPUT_FILE}" diff --git a/doc/scripts/generate_module.sh b/doc/scripts/generate_module.sh new file mode 100755 index 000000000..34d23760d --- /dev/null +++ b/doc/scripts/generate_module.sh @@ -0,0 +1,22 @@ +#!/usr/bin/env bash + +SNORT_BINARY="$1" +OUTPUT_FILE="$2" +PLUGIN_PATH="$3" +PLUGIN_ARGS= + +if [[ -n "${PLUGIN_PATH}" ]]; then + PLUGIN_ARGS="--plugin-path=${PLUGIN_PATH}" +fi + +MODULE_TYPE=`basename "${OUTPUT_FILE}" .txt` + +rm -f "${OUTPUT_FILE}" + +"${SNORT_BINARY}" ${PLUGIN_ARGS} --list-modules "${MODULE_TYPE}" \ + | while read module_name; do + + "${SNORT_BINARY}" ${PLUGIN_ARGS} --markup --help-module "${module_name}" \ + >> "${OUTPUT_FILE}" + +done diff --git a/doc/text/CMakeLists.txt b/doc/text/CMakeLists.txt new file mode 100644 index 000000000..cbaa1d584 --- /dev/null +++ b/doc/text/CMakeLists.txt @@ -0,0 +1,21 @@ +set ( + TEXT_A2X_ARGS + --format=text + --resource=.. + --keep-artifacts # FIXIT: Do we need keep the build artifacts? + ) + +add_custom_command ( + OUTPUT snort_manual.text + COMMAND ${ASCIIDOC_A2X_EXE} ${TEXT_A2X_ARGS} ${SNORT_MANUAL_TXT} + COMMAND cp ${DOC_BINARY_DIR}/snort_manual.text . + DEPENDS all_doc_sources + COMMENT "Documents: building snort_manual.text" + ) + +add_custom_target ( + snort_manual_text + DEPENDS snort_manual.text + ) + +add_dependencies ( snort_manuals snort_manual_text )