From 17da91409a47d294949325fcb227daf2ac6535b6 Mon Sep 17 00:00:00 2001 From: Dan Rose Date: Thu, 2 Apr 2020 10:25:16 -0500 Subject: [PATCH] Fix and simplify building docs and schemas (#441) Fix and simplify building docs and schemas 1. Do an in-source build of derived schemas instead of building into build and checking that the files match. 2. Fix paths of installed docs, which were failing on me 3. Consolidate docs into same cmakelists that generates schema files 4. Trang is usually available as an executable, so find it with find_program. 5. Add doc dependencies to package.xml Signed-off-by: Dan Rose --- .travis.yml | 22 ++++++++--- CMakeLists.txt | 5 ++- cmake/Modules/FindTrang.cmake | 53 ++++++++++++++++++++++++++ docs/CMakeLists.txt | 72 +++++++++++++++++++---------------- docs/compare.pl | 8 ---- docs/manual/CMakeLists.txt | 23 ----------- package.xml | 6 +++ 7 files changed, 118 insertions(+), 71 deletions(-) create mode 100644 cmake/Modules/FindTrang.cmake delete mode 100644 docs/compare.pl delete mode 100644 docs/manual/CMakeLists.txt diff --git a/.travis.yml b/.travis.yml index 3d2f4cd..4a1ed53 100644 --- a/.travis.yml +++ b/.travis.yml @@ -45,7 +45,7 @@ linux_gcc8: &linux_gcc8 apt: update: true sources: [ ubuntu-toolchain-r-test ] - packages: [ gcc-8 g++-8 ] + packages: [ gcc-8, g++-8, trang ] before_install: - eval "export CC=gcc-8" - eval "export CXX=g++-8" @@ -61,6 +61,7 @@ linux_clang: &linux_clang addons: apt: update: true + packages: [ trang ] before_install: - eval "export CC=clang" - eval "export CXX=clang++" @@ -74,7 +75,7 @@ osx_xcode: &osx_xcode compiler: clang addons: homebrew: - packages: [ python3 ] + packages: [ python3, trang ] before_install: - eval "export CC=clang" - eval "export CXX=clang++" @@ -88,7 +89,7 @@ osx_xcode9: &osx_xcode9 osx_image: xcode9 addons: homebrew: - packages: [ python3 ] + packages: [ python3, trang ] # Homebrew must be updated before packages can be installed on outdated # macOS images. The update process unfortunately takes a VERY long time # and can even cause Travis to terminate the build. Travis caching is @@ -195,6 +196,7 @@ script: - mkdir build - cd build - conan install -b missing -s arch=${ARCH} -s build_type=${BUILD_TYPE} .. + - which trang && BUILD_SCHEMA=1 || BUILD_SCHEMA=0 - cmake -DCMAKE_BUILD_TYPE=${BUILD_TYPE} -DCMAKE_INSTALL_PREFIX=${INSTALLPREFIX} -DUSE_SANITIZER=${ASAN} @@ -202,9 +204,11 @@ script: -DENABLE_LIFESPAN=${LIFESPAN} -DENABLE_DEADLINE_MISSED=${DEADLINE} -DBUILD_TESTING=on + -DBUILD_SCHEMA=${BUILD_SCHEMA} -DWERROR=on -G "${GENERATOR}" .. - - case "${GENERATOR}" in + - | + case "${GENERATOR}" in "Unix Makefiles") ${SCAN_BUILD} cmake --build . --config ${BUILD_TYPE} --target install -- -j 4 ;; @@ -216,14 +220,20 @@ script: ;; esac - CYCLONEDDS_URI='alltrueconfigstderr' ctest -j 4 --output-on-failure -T test -E '^CUnit_ddsrt_random_default_random$' -C ${BUILD_TYPE} - - if [ "${ASAN}" = "none" ]; then + - | + if [ "${ASAN}" = "none" ]; then ${SHELL} ../src/tools/ddsperf/sanity.bash; fi - - if [ "${ASAN}" != "none" ]; then + - | + if [ "${ASAN}" != "none" ]; then CMAKE_LINKER_FLAGS="-DCMAKE_LINKER_FLAGS=-fsanitize=${USE_SANITIZER}"; CMAKE_C_FLAGS="-DCMAKE_C_FLAGS=-fsanitize=${USE_SANITIZER}"; fi - cd .. + - | + if [ ${BUILD_SCHEMA} ]; then + git diff --exit-code; # check that no files (e.g. generated schemas) are changed + fi - mkdir helloworld_build - cd helloworld_build - cmake -DCMAKE_PREFIX_PATH=${INSTALLPREFIX} diff --git a/CMakeLists.txt b/CMakeLists.txt index fd7878f..1ef9330 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -205,6 +205,9 @@ set(MEMORYCHECK_COMMAND_OPTIONS "--track-origins=yes --leak-check=full --trace-c option(BUILD_TESTING "Build the testing tree." OFF) include(CTest) +option(BUILD_DOCS "Build documentation." OFF) +option(BUILD_SCHEMA "Build generated schema for configuration options." OFF) + # Build all executables and libraries into the top-level /bin and /lib folders. set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/bin") set(CMAKE_LIBRARY_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/lib") @@ -215,7 +218,7 @@ if(BUILD_IDLC) add_subdirectory(examples) endif() -option(BUILD_DOCS "Build documentation." OFF) + add_subdirectory(docs) # Pull-in CPack and support for generating Config.cmake and packages. diff --git a/cmake/Modules/FindTrang.cmake b/cmake/Modules/FindTrang.cmake new file mode 100644 index 0000000..c0096c8 --- /dev/null +++ b/cmake/Modules/FindTrang.cmake @@ -0,0 +1,53 @@ +# Copyright(c) 2020 ADLINK Technology Limited and others +# +# This program and the accompanying materials are made available under the +# terms of the Eclipse Public License v. 2.0 which is available at +# http://www.eclipse.org/legal/epl-2.0, or the Eclipse Distribution License +# v. 1.0 which is available at +# http://www.eclipse.org/org/documents/edl-v10.php. +# +# SPDX-License-Identifier: EPL-2.0 OR BSD-3-Clause +# + +#[=======================================================================[.rst: +FindTrang +--------- +Finds Trang, an xml schema transpiler + +Result Variables +^^^^^^^^^^^^^^^^ + +This will define the following variables: + +``Trang_FOUND`` + True if the system has the Foo library. +``Trang_VERSION`` + The version of the Foo library which was found. +``Trang_TRANG_CMD`` + List of command line args to run Trang. +``Trang_TRANG_EXECUTABLE`` + Path to the Trang executable file + +#]=======================================================================] + +find_program(Trang_TRANG_EXECUTABLE trang) + +execute_process( + COMMAND "${Trang_TRANG_EXECUTABLE}" + ERROR_VARIABLE trang_output +) +if(trang_output MATCHES "Trang version ([0-9]+)") + set(TRANG_VERSION "${CMAKE_MATCH_1}") +else() + message(ERROR "Could not parse version from Trang output: '${trang_output}'") + set(TRANG_VERSION "0") +endif() + +set(Trang_TRANG_CMD "${Trang_TRANG_EXECUTABLE}") + +include(FindPackageHandleStandardArgs) +FIND_PACKAGE_HANDLE_STANDARD_ARGS( + Trang + REQUIRED_VARS Trang_TRANG_CMD + VERSION_VAR TRANG_VERSION +) diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt index 0cf8b26..82fe266 100644 --- a/docs/CMakeLists.txt +++ b/docs/CMakeLists.txt @@ -8,43 +8,49 @@ # http://www.eclipse.org/org/documents/edl-v10.php. # # SPDX-License-Identifier: EPL-2.0 OR BSD-3-Clause -include(FindPerl) -if(PERL_FOUND) + +# These are all various expressions of the configuration schema +get_filename_component(config_c_PATH "../src/core/ddsi/src/q_config.c" REALPATH BASE_DIR "${CMAKE_CURRENT_SOURCE_DIR}") + +# although the following files are generated, we check them into source control for convenience +get_filename_component(config_rnc_PATH "../etc/cyclonedds.rnc" REALPATH BASE_DIR "${CMAKE_CURRENT_SOURCE_DIR}") +get_filename_component(config_xsd_PATH "../etc/cyclonedds.xsd" REALPATH BASE_DIR "${CMAKE_CURRENT_SOURCE_DIR}") +get_filename_component(config_md_PATH "./manual/options.md" REALPATH BASE_DIR "${CMAKE_CURRENT_SOURCE_DIR}") + +if(BUILD_SCHEMA OR BUILD_DOCS) + find_package(Perl REQUIRED) add_custom_command( OUTPUT - options.md cyclonedds.rnc + "${config_md_PATH}" "${config_rnc_PATH}" COMMAND - ${PERL_EXECUTABLE} -w "${CMAKE_CURRENT_SOURCE_DIR}/makernc.pl" "${CMAKE_CURRENT_SOURCE_DIR}/../src/core/ddsi/src/q_config.c" options.md cyclonedds.rnc - COMMAND - ${PERL_EXECUTABLE} -w "${CMAKE_CURRENT_SOURCE_DIR}/compare.pl" options.md "${CMAKE_CURRENT_SOURCE_DIR}/manual/options.md" - COMMAND - ${PERL_EXECUTABLE} -w "${CMAKE_CURRENT_SOURCE_DIR}/compare.pl" cyclonedds.rnc "${CMAKE_CURRENT_SOURCE_DIR}/../etc/cyclonedds.rnc" + ${PERL_EXECUTABLE} -w "${CMAKE_CURRENT_SOURCE_DIR}/makernc.pl" "${config_c_PATH}" "${config_md_PATH}" "${config_rnc_PATH}" + COMMENT "Generating Relax NG schema and Markdown documentation for config options" DEPENDS - "${CMAKE_CURRENT_SOURCE_DIR}/makernc.pl" - "${CMAKE_CURRENT_SOURCE_DIR}/../src/core/ddsi/src/q_config.c") - add_custom_target(options_doc ALL DEPENDS "options.md" "cyclonedds.rnc") + "${CMAKE_CURRENT_SOURCE_DIR}/makernc.pl" + "${config_c_PATH}") + add_custom_target(options_doc ALL DEPENDS "${config_md_PATH}" "${config_rnc_PATH}") - find_package(Java COMPONENTS Runtime) - if(JAVA_FOUND AND EXISTS "${TRANG_PATH}" OR EXISTS "$ENV{TRANG}") - if(NOT EXISTS "${TRANG_PATH}" AND EXISTS "$ENV{TRANG}") - message(STATUS "Setting TRANG_PATH to $ENV{TRANG}") - set(TRANG_PATH "$ENV{TRANG}" CACHE FILEPATH "Location of 'trang' for converting XML schemas" FORCE) - endif() - add_custom_command( - OUTPUT - cyclonedds.xsd - COMMAND - ${Java_JAVA_EXECUTABLE} -jar "${TRANG_PATH}" -I rnc -O xsd cyclonedds.rnc cyclonedds.xsd - COMMAND - ${PERL_EXECUTABLE} -w "${CMAKE_CURRENT_SOURCE_DIR}/compare.pl" cyclonedds.xsd "${CMAKE_CURRENT_SOURCE_DIR}/../etc/cyclonedds.xsd" - DEPENDS - "cyclonedds.rnc") - add_custom_target(options_xsd ALL DEPENDS "cyclonedds.xsd") - else() - message(STATUS "Java or not trang not found: not converting/checking RNC to XSD") - endif() -else() - message(STATUS "perl not found: not generating/checking options documentation and RNC") + find_package(Trang REQUIRED) + + add_custom_command( + OUTPUT "${config_xsd_PATH}" + COMMAND ${Trang_TRANG_CMD} -I rnc -O xsd "${config_rnc_PATH}" "${config_xsd_PATH}" + COMMENT "Translating schema into XSD" + DEPENDS "${config_rnc_PATH}") + add_custom_target(options_xsd ALL DEPENDS "${config_xsd_PATH}") endif() -add_subdirectory(manual) +if(BUILD_DOCS) + find_package(Sphinx REQUIRED breathe) + sphinx_add_docs( + docs + BREATHE_PROJECTS ddsc_api_docs + BUILDER html + SOURCE_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}") + add_dependencies(docs options_doc) + + install( + DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}" + DESTINATION "${CMAKE_INSTALL_DOCDIR}/manual" + COMPONENT dev) +endif() diff --git a/docs/compare.pl b/docs/compare.pl deleted file mode 100644 index a8451a1..0000000 --- a/docs/compare.pl +++ /dev/null @@ -1,8 +0,0 @@ -open A, "< $ARGV[0]" or die "can't open $ARGV[0]"; -open B, "< $ARGV[1]" or die "can't open $ARGV[1]"; -while (defined ($a = ) && defined ($b = )) { - $a =~ s/[\r\n]+$//s; - $b =~ s/[\r\n]+$//s; - exit 1 unless $a eq $b; -} -exit 0; diff --git a/docs/manual/CMakeLists.txt b/docs/manual/CMakeLists.txt deleted file mode 100644 index de5d686..0000000 --- a/docs/manual/CMakeLists.txt +++ /dev/null @@ -1,23 +0,0 @@ -# -# Copyright(c) 2006 to 2019 ADLINK Technology Limited and others -# -# This program and the accompanying materials are made available under the -# terms of the Eclipse Public License v. 2.0 which is available at -# http://www.eclipse.org/legal/epl-2.0, or the Eclipse Distribution License -# v. 1.0 which is available at -# http://www.eclipse.org/org/documents/edl-v10.php. -# -# SPDX-License-Identifier: EPL-2.0 OR BSD-3-Clause -if(BUILD_DOCS) - find_package(Sphinx REQUIRED breathe) - sphinx_add_docs( - docs - BREATHE_PROJECTS ddsc_api_docs - BUILDER html - SOURCE_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}") - install( - DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/docs/" - DESTINATION "${CMAKE_INSTALL_DOCDIR}/manual" - COMPONENT dev) -endif() - diff --git a/package.xml b/package.xml index efb8e8a..9f058fe 100644 --- a/package.xml +++ b/package.xml @@ -12,9 +12,15 @@ https://github.com/eclipse-cyclonedds/cyclonedds cmake + openssl libcunit-dev + + doxygen + perl + python3-breathe python3-sphinx + trang cmake