roland/xo-alloc
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

xo-ratio: build: streamline docs+utest setup

Browse source
This commit is contained in:
Roland Conybeare 2024-04-25 18:15:24 -04:00
commit 562bcaa395
7 changed files with 39 additions and 296 deletions
Download patch file Download diff file Expand all files Collapse all files

42
CMakeLists.txt
View file

@ -5,45 +5,15 @@ cmake_minimum_required(VERSION 3.10)
project(xo_ratio VERSION 1.0)
enable_language(CXX)
# common XO cmake macros (see proj/xo-cmake)
include(GNUInstallDirs)
include(cmake/xo-bootstrap-macros.cmake)
# ----------------------------------------------------------------
# unit test setup
enable_testing()
xo_cxx_toplevel_options2()
# ----------------------------------------------------------------
# cmake -DCMAKE_BUILD_TYPE=coverage
if (NOT DEFINED PROJECT_CXX_FLAGS_COVERAGE)
# note: for clang would use -fprofile-instr-generate -fcoverage-mapping here instead and also at link time
set(PROJECT_CXX_FLAGS_COVERAGE ${PROJECT_CXX_FLAGS} -ggdb -Og -fprofile-arcs -ftest-coverage
CACHE STRING "coverage c++ compiler flags")
endif()
message("-- PROJECT_CXX_FLAGS_COVERAGE: coverage c++ flags are [${PROJECT_CXX_FLAGS_COVERAGE}]")
add_compile_options("$<$<CONFIG:COVERAGE>:${PROJECT_CXX_FLAGS_COVERAGE}>")
# when -DCMAKE_BUILD_TYPE=coverage, link executables with gcov
link_libraries("$<$<CONFIG:COVERAGE>:gcov>")
find_program(LCOV_EXECUTABLE NAMES lcov)
find_program(GENHTML_EXECUTABLE NAMES genhtml)
# with coverage build:
# 1. invoke instrumented executables for which you want coverage:
# (cd path/to/build && ctest)
# 2. post-process low-level coverage data
# (path/to/build/gen-ccov)
# 3. point browser to generated html data
# file:///path/to/build/ccov/html/index.html
#
configure_file(
${PROJECT_SOURCE_DIR}/cmake/gen-ccov.in
${PROJECT_BINARY_DIR}/gen-ccov)
file(CHMOD ${PROJECT_BINARY_DIR}/gen-ccov PERMISSIONS OWNER_READ OWNER_EXECUTE GROUP_READ GROUP_EXECUTE WORLD_READ WORLD_EXECUTE)
xo_toplevel_coverage_config2()
# ----------------------------------------------------------------
# c++ settings
@ -53,13 +23,10 @@ set(PROJECT_CXX_FLAGS "")
#set(PROJECT_CXX_FLAGS "-fconcepts-diagnostics-depth=2")
add_definitions(${PROJECT_CXX_FLAGS})
xo_toplevel_compile_options()
# ----------------------------------------------------------------
add_subdirectory(example)
add_subdirectory(utest)
add_subdirectory(docs)
# ----------------------------------------------------------------
# provide find_package() support for projects using this library
@ -69,6 +36,11 @@ xo_add_headeronly_library(${SELF_LIB})
xo_install_library4(${SELF_LIB} ${PROJECT_NAME}Targets)
xo_export_cmake_config(${PROJECT_NAME} ${PROJECT_VERSION} ${PROJECT_NAME}Targets)
# ----------------------------------------------------------------
# docs targets depend on all the other library/utest targets
#
add_subdirectory(docs)
# ----------------------------------------------------------------
# dependencies

2
README.md
View file

@ -40,7 +40,7 @@ $ git clone https://github.com/Rconybea/xo-ratio
$ cd xo-ratio
$ PREFIX=/usr/local # for example
$ BUILDDIR=.build # for example
$ make ${BUILDDIR}
$ mkdir ${BUILDDIR}
$ cmake --build .build
$ cmake --install .build
```

20
cmake/gen-ccov.in
View file

@ -1,20 +0,0 @@
#!/usr/bin/env bash
srcdir=@PROJECT_SOURCE_DIR@
builddir=@PROJECT_BINARY_DIR@
lcov=@LCOV_EXECUTABLE@
genhtml=@GENHTML_EXECUTABLE@
if [[ $lcov == "LCOV_EXECUTABLE-NOTFOUND" ]]; then
echo "gen-ccov: lcov executable not found"
exit 1
fi
if [[ $genhtml == "GENHTML_EXECUTABLE-NOTFOUND" ]]; then
echo "gen-ccov: genhtml executable not found"
exit 1
fi
mkdir $builddir/ccov
$srcdir/cmake/lcov-harness $srcdir $builddir $builddir/ccov/out $lcov $genhtml

114
cmake/lcov-harness
View file

@ -1,114 +0,0 @@
#!/usr/bin/env bash
srcdir=$1
builddir=$2
outputstem=$3
lcov=$4
genhtml=$5
if [[ -z "${srcdir}" ]]; then
echo "lcov-harness: expected non-empty srcdir"
exit 1
fi
if [[ -z ${builddir} ]]; then
echo "lcov-harness: expected non-empty builddir"
exit 1
fi
if [[ -z ${outputstem} ]]; then
echo "lcov-harness: expected non-empty outputstem"
exit 1
fi
if [[ -z ${lcov} ]]; then
echo "lcov-harness: exepcted non-empty lcov"
exit 1
fi
if [[ -z ${genhtml} ]]; then
echo "lcov-harness: expected non-empty genhtml"
exit 1
fi
# directory stems for location of {.gcda, gcno} coverage information,
#
# if we have source tree:
#
# ${srcdir}
# +- foo
# | \- foo.cpp
# \- bar
# \- quux
# +- quux.cpp
# \- quux_main.cpp
#
# then we expect build tree:
#
# ${builddir}
# +- foo
# | \- CMakeFiles
# | \- foo_target.dir
# | +- foo.cpp.gcda
# | \- foo.cpp.gcno
# +- bar
# \- quux
# \- CMakeFiles
# \- target4quux.dir
# +- quux.cpp.gcda
# +- quux.cpp.gcno
# +- quux_main.cpp.gcda
# \- quux_main.cpp.gcno
#
# in which case will have cmd_body:
#
# ${primarydirs}
# ./foo/CMakeFiles/foo_target.dir
# ./bar/quux/CMakeFiles/target4quux.dir
#
# here foo_target, quux_target are whatever build is using for corresponding cmake target names.
#
# We want to invoke lcov like:
#
# lcov --capture \
# --output ${builddir}/ccov \
# --exclude /utest/ \
# --base-directory ${srcdir}/foo --directory ${builddir}/foo/CMakeFiles/foo_target.dir \
# --base-directory ${srcdir}/bar/quux --directory ${builddir}/bar/quux/CMakeFiles/target4quux.dir
#
primarydirs=$(cd ${builddir} && find -name '*.gcno' \
| xargs --replace=xx dirname xx \
| uniq \
| sed -e 's:^\./::')
#echo "primarydirs=${primarydirs}"
cmd="${lcov} --output ${outputstem}.info --capture --ignore-errors source"
for bdir in ${primarydirs}; do
sdir=$(dirname $(dirname ${bdir}))
cmd="${cmd} --base-directory ${srcdir}/${sdir} --directory ${builddir}/${bdir}"
done
#echo cmd=${cmd}
set -x
# capture
${cmd}
# keep only files with paths under source tree
# (don't want coverage for external libraries such as libstdc++ etc)
${lcov} --extract ${outputstem}.info "${srcdir}/*" --output ${outputstem}2.info
# remove unit test dirs
# (we're interested in coverage of our installed code, not of the unit tests that exercise it)
${lcov} --remove ${outputstem}2.info '*/utest/*' --output ${outputstem}3.info
# generate .html tree
mkdir -p ${builddir}/ccov/html
${genhtml} --ignore-errors source --show-details --prefix ${srcdir} --output-directory ${builddir}/ccov/html ${outputstem}3.info
# also send report to stdout
${lcov} --list ${outputstem}3.info

30
cmake/xo-bootstrap-macros.cmake
View file

@ -1,15 +1,33 @@
# ----------------------------------------------------------------
# for example:
# $ PREFIX=/usr/local # for example
# $ cmake -DCMAKE_MODULE_PATH=prefix -DCMAKE_INSTALL_PREFIX=$PREFIX -B .build
#
# will get
# CMAKE_MODULE_PATH
# from xo-cmake-config --cmake-module-path
#
# and expect .cmake macros in
# CMAKE_MODULE_PATH/xo_macros/xo_cxx.cmake
# ----------------------------------------------------------------
find_program(XO_CMAKE_CONFIG_EXECUTABLE NAMES xo-cmake-config REQUIRED)
if (("${CMAKE_MODULE_PATH}" STREQUAL "") OR ("${CMAKE_MODULE_PATH}" STREQUAL "prefix"))
# default to typical install location for xo-project-macros
set(CMAKE_MODULE_PATH ${CMAKE_INSTALL_PREFIX}/share/cmake)
message(FATAL "could not find xo-cmake-config executable")
endif()
if (NOT XO_SUBMODULE_BUILD)
message("-- GUESSED_CMAKE_CMD=cmake -DCMAKE_CXX_STANDARD=${CMAKE_CXX_STANDARD} -DCMAKE_INSTALL_PREFIX=${CMAKE_INSTALL_PREFIX} -DCMAKE_MODULE_PATH=${CMAKE_MODULE_PATH} -DCMAKE_PREFIX_PATH=${CMAKE_PREFIX_PATH} -DCMAKE_BUILD_TYPE=${CMAKE_BUILD_TYPE} -DCMAKE_INSTALL_DOCDIR=${CMAKE_INSTALL_DOCDIR} -B ${CMAKE_BINARY_DIR}")
message("-- CMAKE_INSTALL_PREFIX=${CMAKE_INSTALL_PREFIX}")
message("-- CMAKE_MODULE_PATH=${CMAKE_MODULE_PATH}")
if (("${CMAKE_MODULE_PATH}" STREQUAL "") OR ("${CMAKE_MODULE_PATH}" STREQUAL prefix))
# default to typical install location for xo-project-macros
execute_process(COMMAND ${XO_CMAKE_CONFIG_EXECUTABLE} --cmake-module-path OUTPUT_VARIABLE CMAKE_MODULE_PATH)
message(STATUS "CMAKE_MODULE_PATH=${CMAKE_MODULE_PATH}")
endif()
endif()
# needs to have been installed somewhere on CMAKE_MODULE_PATH,
# (e.g. from xo-cmake with the same value for CMAKE_INSTALL_PREFIX)
#
include(xo_macros/xo-project-macros)
include(xo_macros/xo_cxx)
xo_cxx_bootstrap_message()

121
docs/CMakeLists.txt
View file

@ -1,118 +1,5 @@
# xo-ratio/docs/CMakeLists.txt
# xo-flatstring/docs/CMakeLists.txt
if (XO_SUBMODULE_BUILD)
# in submodule build, rely on toplevel docs/CMakeLists.txt file instead
else()
# build docs starting from here only in standalone build.
# otherwise use top-level doxygen setup instead.
set(ALL_LIBRARY_TARGETS xo_ratio) # todo: automate this from xo-cmake macros
set(ALL_UTEST_TARGETS utest.ratio xo_ratio_ex1 ) # todo: automate this from xo-cmake macros
# look for doxygen executable
find_program(DOXYGEN_EXECUTABLE NAMES doxygen REQUIRED)
message("-- DOXYGEN_EXECUTABLE=${DOXYGEN_EXECUTABLE}")
# look for sphinx-build executable
find_program(SPHINX_EXECUTABLE NAMES sphinx-build REQUIRED)
message("-- SPHINX_EXECUTABLE=${SPHINX_EXECUTABLE}")
set(DOX_CONFIG_FILE ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile)
set(DOX_INPUT_DIR ${PROJECT_SOURCE_DIR})
set(DOX_OUTPUT_DIR ${CMAKE_CURRENT_BINARY_DIR}/dox)
set(DOX_INDEX_FILE ${DOX_OUTPUT_DIR}/html/index.html)
# .hpp files reachable from xo-ratio/include
#
# REMINDER: for reliability will need to re-run cmake when the set of .hpp files changes
#
file(GLOB_RECURSE DOX_HPP_FILES_GLOB ${PROJECT_SOURCE_DIR}/include *.hpp)
set(SPHINX_OUTPUT_DIR ${CMAKE_CURRENT_BINARY_DIR}/sphinx/html)
set(SPHINX_INDEX_FILE ${SPHINX_OUTPUT_DIR}/index.html)
#
# sphinx .rst files reachable from cmake-examples/docs
#
# REMINDER: for reliability will need to re-run cmake when the set of .rst files changes
#
file(GLOB_RECURSE SPHINX_RST_FILES_GLOB ${CMAKE_CURRENT_SOURCE_DIR} *.rst)
set(SPHINX_RST_FILES index.rst
#install.rst
#lessons.rst
#flatstring-reference.rst
#flatstring-class.rst
)
# TODO:
# 1. move Doxyfile.in to xo-cmake project
# 2. replace this command section with xo-cmake macro
#
configure_file(
Doxyfile.in ${DOX_CONFIG_FILE}
FILE_PERMISSIONS OWNER_READ OWNER_EXECUTE GROUP_READ GROUP_EXECUTE WORLD_READ WORLD_EXECUTE
@ONLY)
set(DOX_DEPS ${ALL_LIBRARY_TARGETS} ${ALL_UTEST_TARGETS} ${DOX_HPP_FILES_GLOB})
file(MAKE_DIRECTORY ${DOX_OUTPUT_DIR})
add_custom_command(
OUTPUT ${DOX_INDEX_FILE}
DEPENDS ${DOX_DEPS}
COMMAND "${DOXYGEN_EXECUTABLE}" ${DOX_CONFIG_FILE}
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
MAIN_DEPENDENCY ${DOX_CONFIG_FILE}
COMMENT "Generating docs (doxygen)")
# To build this target
# $ cmake --build .build -j -- doxygen
# or
# $ cd .build
# $ make doxygen
#
add_custom_target(
doxygen
DEPENDS ${DOX_INDEX_FILE} ${DOX_DEPS}
)
# root of sphinx doc tree
set(SPHINX_SOURCE ${CMAKE_CURRENT_SOURCE_DIR})
set(SPHINX_DEPS doxygen conf.py ${SPHINX_RST_FILES} ${SPHINX_RST_FILES_GLOB} ${DOX_DEPS})
add_custom_command(
OUTPUT ${SPHINX_INDEX_FILE}
DEPENDS ${SPHINX_DEPS}
COMMAND ${SPHINX_EXECUTABLE}
-b html -Dbreathe_projects.xodoxxml=${CMAKE_CURRENT_BINARY_DIR}/dox/xml
${SPHINX_SOURCE} ${SPHINX_OUTPUT_DIR}
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
COMMENT "Generating docs (sphinx) -> [${SPHINX_OUTPUT_DIR}]")
# make sphinx --> generate sphinx documentation
#
add_custom_target(
sphinx
DEPENDS ${SPHINX_INDEX_FILE})
# - html docs generated in build/docs/sphinx
# - copy the doc tree to share/doc/xo_unit/html
#
# DESTINATION: CMAKE_INSTALL_DOCDIR
# => DATAROOTDIR/doc/PROJECT_NAME
# => CMAKE_INSTALL_PREFIX/share/doc/xo_flatstring
# OPTIONAL: install directory tree if it exists,
# but don't complain if it's missing
install(
DIRECTORY ${SPHINX_OUTPUT_DIR}
FILE_PERMISSIONS OWNER_READ GROUP_READ WORLD_READ
DESTINATION ${CMAKE_INSTALL_DOCDIR}
COMPONENT Documentation
OPTIONAL)
# make docs --> generate sphinx documentation
add_custom_target(
docs
DEPENDS sphinx)
endif()
xo_doxygen_collect_deps()
xo_docdir_doxygen_config()
xo_docdir_sphinx_config(index.rst install.rst ratio-reference.rst ratio-class.rst ratio-functions.rst)

6
utest/CMakeLists.txt
View file

@ -5,9 +5,7 @@ set(SELF_SRCS
ratio_utest_main.cpp
ratio.test.cpp)
add_executable(${SELF_EXE} ${SELF_SRCS})
xo_include_options2(${SELF_EXE})
add_test(NAME ${SELF_EXE} COMMAND ${SELF_EXE})
xo_add_utest_executable(${SELF_EXE} ${SELF_SRCS})
# ----------------------------------------------------------------
# in coverage build, target to build+install coverage report
@ -55,3 +53,5 @@ xo_self_headeronly_dependency(${SELF_EXE} xo_ratio)
xo_dependency(${SELF_EXE} randomgen)
xo_dependency(${SELF_EXE} indentlog)
xo_external_target_dependency(${SELF_EXE} Catch2 Catch2::Catch2)
# end CMakeLists.txt