packaging and doc fixes (#420)

Updates and corrects packaging and documentation configurations. These include fixes for cpack generation, the addition of the INSTALL_HEADERS and INSTALL_HTML build options, and fixing all errors.
goatshriek · May 26, 2024 · 3d9cdc4 · 3d9cdc4
1 parent fd62102
commit 3d9cdc4
Show file tree

Hide file tree

Showing 52 changed files with 883 additions and 4,553 deletions.
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -4,7 +4,9 @@ if(POLICY CMP0135)
   cmake_policy(SET CMP0135 NEW)
 endif()
 
-project(stumpless VERSION 2.2.0)
+project(stumpless
+  VERSION 2.2.0
+)
 set(CMAKE_PROJECT_HOMEPAGE_URL "https://goatshriek.github.io/stumpless/")
 
 option(BUILD_SHARED_LIBS "Build using shared libraries" ON)
@@ -29,6 +31,8 @@ option(ENABLE_SQLITE3_TARGETS "support sqlite3 targets" ON)
 option(ENABLE_WINDOWS_EVENT_LOG_TARGETS "support windows event log targets" ON)
 
 option(INSTALL_EXAMPLES "install examples" ON)
+option(INSTALL_HEADERS "install header files" ON)
+option(INSTALL_HTML "install html documentation" ON)
 option(INSTALL_MANPAGES "install generated manpages" ON)
 
 option(COVERAGE "Include coverage information" OFF)
@@ -259,25 +263,31 @@ set(WRAPTURE_SPECS
 
 
 # documentation and doxygen steup
+set(PROJECT_DOCS_DIR "${PROJECT_BINARY_DIR}/docs/${STUMPLESS_LANGUAGE}")
 set(DOXYGEN_MANPAGES
-  ${PROJECT_BINARY_DIR}/docs/man/man3/stumpless.h.3
-  ${PROJECT_BINARY_DIR}/docs/man/man3/config.h.3
+  "${PROJECT_DOCS_DIR}/man/man3/stumpless.h.3"
+  "${PROJECT_DOCS_DIR}/man/man3/config.h.3"
 )
 
-set(PROJECT_DOCS_DIR ${PROJECT_BINARY_DIR}/docs)
 if(DOXYGEN_FOUND)
+  set(INCLUDE_HTML_IN_INSTALL ${INSTALL_HTML})
   set(INCLUDE_MANPAGES_IN_INSTALL ${INSTALL_MANPAGES})
 else()
+  if(INSTALL_HTML)
+    message("doxygen is required to generate and install html documentation")
+  endif()
+
   if(INSTALL_MANPAGES)
     message("doxygen is required to generate and install manpages")
   endif()
 
+  set(INCLUDE_HTML_IN_INSTALL FALSE)
   set(INCLUDE_MANPAGES_IN_INSTALL FALSE)
 endif()
 
-if(${INCLUDE_MANPAGES_IN_INSTALL})
+if(${INCLUDE_HTML_IN_INSTALL} OR ${INCLUDE_MANPAGES_IN_INSTALL})
   # we need to do this before any other install commands that depend on the
-  # manpages generated by doxygen, so that they are generated before use
+  # html or manpages generated by doxygen, so that they are generated before use
   install(CODE
     "execute_process(COMMAND ${CMAKE_COMMAND} --build ${CMAKE_BINARY_DIR} --target docs)"
   )
@@ -591,7 +601,6 @@ endif()
 # library definition
 add_library(stumpless ${STUMPLESS_SOURCES})
 set_target_properties(stumpless PROPERTIES VERSION ${PROJECT_VERSION})
-set_target_properties(stumpless PROPERTIES PUBLIC_HEADER include/stumpless.h)
 
 target_link_libraries(stumpless PRIVATE ${STUMPLESS_LINK_LIBRARIES})
 
@@ -668,8 +677,95 @@ set(FUZZ_CORPORA_DIR ${PROJECT_SOURCE_DIR}/test/corpora)
 configure_file(${PROJECT_SOURCE_DIR}/include/stumpless/config.h.in ${PROJECT_BINARY_DIR}/include/stumpless/config.h)
 configure_file(${PROJECT_SOURCE_DIR}/include/private/config.h.in ${PROJECT_BINARY_DIR}/include/private/config.h)
 configure_file(${PROJECT_SOURCE_DIR}/include/test/config.hpp.in ${PROJECT_BINARY_DIR}/include/test/config.hpp)
-configure_file(${PROJECT_SOURCE_DIR}/tools/portage/stumpless.ebuild.in
-  ${PROJECT_BINARY_DIR}/tools/portage/stumpless-${PROJECT_VERSION}.ebuild
+configure_file(${PROJECT_SOURCE_DIR}/tools/portage/libstumpless.ebuild.in
+  ${PROJECT_BINARY_DIR}/tools/portage/libstumpless-${PROJECT_VERSION}.ebuild
+  @ONLY
+)
+configure_file(${PROJECT_SOURCE_DIR}/tools/portage/libstumpless.ebuild.in
+  ${PROJECT_BINARY_DIR}/tools/portage/libstumpless-9999.ebuild
+  @ONLY
+)
+
+
+# generating level header files
+set(LEVEL_NAME_UPCASE "ALERT")
+set(LEVEL_NAME_DOWNCASE "alert")
+set(LEVEL_SHORTNAME "a")
+configure_file(
+  "${PROJECT_SOURCE_DIR}/include/stumpless/level/level.h.in"
+  "${PROJECT_BINARY_DIR}/include/stumpless/level/${LEVEL_NAME_DOWNCASE}.h"
+  @ONLY
+)
+
+set(LEVEL_NAME_UPCASE "CRIT")
+set(LEVEL_NAME_DOWNCASE "crit")
+set(LEVEL_SHORTNAME "c")
+configure_file(
+  "${PROJECT_SOURCE_DIR}/include/stumpless/level/level.h.in"
+  "${PROJECT_BINARY_DIR}/include/stumpless/level/${LEVEL_NAME_DOWNCASE}.h"
+  @ONLY
+)
+
+set(LEVEL_NAME_UPCASE "DEBUG")
+set(LEVEL_NAME_DOWNCASE "debug")
+set(LEVEL_SHORTNAME "d")
+configure_file(
+  "${PROJECT_SOURCE_DIR}/include/stumpless/level/level.h.in"
+  "${PROJECT_BINARY_DIR}/include/stumpless/level/${LEVEL_NAME_DOWNCASE}.h"
+  @ONLY
+)
+
+set(LEVEL_NAME_UPCASE "EMERG")
+set(LEVEL_NAME_DOWNCASE "emerg")
+set(LEVEL_SHORTNAME "em")
+configure_file(
+  "${PROJECT_SOURCE_DIR}/include/stumpless/level/level.h.in"
+  "${PROJECT_BINARY_DIR}/include/stumpless/level/${LEVEL_NAME_DOWNCASE}.h"
+  @ONLY
+)
+
+set(LEVEL_NAME_UPCASE "ERR")
+set(LEVEL_NAME_DOWNCASE "err")
+set(LEVEL_SHORTNAME "er")
+configure_file(
+  "${PROJECT_SOURCE_DIR}/include/stumpless/level/level.h.in"
+  "${PROJECT_BINARY_DIR}/include/stumpless/level/${LEVEL_NAME_DOWNCASE}.h"
+  @ONLY
+)
+
+set(LEVEL_NAME_UPCASE "INFO")
+set(LEVEL_NAME_DOWNCASE "info")
+set(LEVEL_SHORTNAME "i")
+configure_file(
+  "${PROJECT_SOURCE_DIR}/include/stumpless/level/level.h.in"
+  "${PROJECT_BINARY_DIR}/include/stumpless/level/${LEVEL_NAME_DOWNCASE}.h"
+  @ONLY
+)
+
+set(LEVEL_NAME_UPCASE "NOTICE")
+set(LEVEL_NAME_DOWNCASE "notice")
+set(LEVEL_SHORTNAME "n")
+configure_file(
+  "${PROJECT_SOURCE_DIR}/include/stumpless/level/level.h.in"
+  "${PROJECT_BINARY_DIR}/include/stumpless/level/${LEVEL_NAME_DOWNCASE}.h"
+  @ONLY
+)
+
+set(LEVEL_NAME_UPCASE "WARNING")
+set(LEVEL_NAME_DOWNCASE "warning")
+set(LEVEL_SHORTNAME "w")
+configure_file(
+  "${PROJECT_SOURCE_DIR}/include/stumpless/level/level.h.in"
+  "${PROJECT_BINARY_DIR}/include/stumpless/level/${LEVEL_NAME_DOWNCASE}.h"
+  @ONLY
+)
+
+set(LEVEL_NAME_UPCASE "TRACE")
+set(LEVEL_NAME_DOWNCASE "trace")
+set(LEVEL_SHORTNAME "t")
+configure_file(
+  "${PROJECT_SOURCE_DIR}/include/stumpless/level/level.h.in"
+  "${PROJECT_BINARY_DIR}/include/stumpless/level/${LEVEL_NAME_DOWNCASE}.h"
   @ONLY
 )
 
@@ -682,69 +778,40 @@ install(TARGETS stumpless
   ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}
 )
 
-install(FILES
-  ${PROJECT_BINARY_DIR}/include/stumpless/config.h
-  ${PROJECT_SOURCE_DIR}/include/stumpless/element.h
-  ${PROJECT_SOURCE_DIR}/include/stumpless/entry.h
-  ${PROJECT_SOURCE_DIR}/include/stumpless/error.h
-  ${PROJECT_SOURCE_DIR}/include/stumpless/facility.h
-  ${PROJECT_SOURCE_DIR}/include/stumpless/filter.h
-  ${PROJECT_SOURCE_DIR}/include/stumpless/generator.h
-  ${PROJECT_SOURCE_DIR}/include/stumpless/id.h
-  ${PROJECT_SOURCE_DIR}/include/stumpless/log.h
-  ${PROJECT_SOURCE_DIR}/include/stumpless/memory.h
-  ${PROJECT_SOURCE_DIR}/include/stumpless/option.h
-  ${PROJECT_SOURCE_DIR}/include/stumpless/param.h
-  ${PROJECT_SOURCE_DIR}/include/stumpless/severity.h
-  ${PROJECT_SOURCE_DIR}/include/stumpless/target.h
-  ${PROJECT_SOURCE_DIR}/include/stumpless/version.h
-  ${PROJECT_SOURCE_DIR}/include/stumpless/priority.h
-  ${PROJECT_SOURCE_DIR}/include/stumpless/prival.h
-  DESTINATION "include/stumpless"
-)
-
-install(FILES
-  ${PROJECT_SOURCE_DIR}/include/stumpless/level/alert.h
-  ${PROJECT_SOURCE_DIR}/include/stumpless/level/crit.h
-  ${PROJECT_SOURCE_DIR}/include/stumpless/level/debug.h
-  ${PROJECT_SOURCE_DIR}/include/stumpless/level/emerg.h
-  ${PROJECT_SOURCE_DIR}/include/stumpless/level/err.h
-  ${PROJECT_SOURCE_DIR}/include/stumpless/level/info.h
-  ${PROJECT_SOURCE_DIR}/include/stumpless/level/mask.h
-  ${PROJECT_SOURCE_DIR}/include/stumpless/level/notice.h
-  ${PROJECT_SOURCE_DIR}/include/stumpless/level/trace.h
-  ${PROJECT_SOURCE_DIR}/include/stumpless/level/warning.h
-  DESTINATION "include/stumpless/level"
-)
-
-install(FILES
-  ${PROJECT_SOURCE_DIR}/include/stumpless/target/buffer.h
-  ${PROJECT_SOURCE_DIR}/include/stumpless/target/file.h
-  ${PROJECT_SOURCE_DIR}/include/stumpless/target/function.h
-  ${PROJECT_SOURCE_DIR}/include/stumpless/target/sqlite3.h
-  ${PROJECT_SOURCE_DIR}/include/stumpless/target/stream.h
-  DESTINATION "include/stumpless/target"
-)
+if(INSTALL_HEADERS)
+  include(tools/cmake/install_headers.cmake)
+endif()
 
 include(tools/cmake/cpack.cmake)
 
 include(FindPkgConfig QUIET)
 if(PKG_CONFIG_FOUND)
-  configure_file("${PROJECT_SOURCE_DIR}/tools/pkg-config/stumpless.pc.in" "${PROJECT_BINARY_DIR}/tools/pkg-config/stumpless.pc" @ONLY)
-  install(FILES "${PROJECT_BINARY_DIR}/tools/pkg-config/stumpless.pc"
-    DESTINATION "${CMAKE_INSTALL_PREFIX}/lib/pkgconfig")
+  configure_file(
+    "${PROJECT_SOURCE_DIR}/tools/pkg-config/libstumpless.pc.in"
+    "${PROJECT_BINARY_DIR}/tools/pkg-config/libstumpless.pc"
+    @ONLY
+  )
+
+  install(FILES "${PROJECT_BINARY_DIR}/tools/pkg-config/libstumpless.pc"
+    DESTINATION "${CMAKE_INSTALL_LIBDIR}/pkgconfig")
 endif()
 
 
 # installation of examples if enabled
 if(INSTALL_EXAMPLES)
-  install(DIRECTORY
-    ${PROJECT_SOURCE_DIR}/docs/examples
-    DESTINATION ${CMAKE_INSTALL_DOCDIR}
+  install(
+    DIRECTORY "${PROJECT_SOURCE_DIR}/docs/examples"
+    DESTINATION "${CMAKE_INSTALL_DATAROOTDIR}/doc/libstumpless"
   )
 endif()
 
 
+# installation of html if enabled and supported
+if(INCLUDE_HTML_IN_INSTALL)
+  include(tools/cmake/install_html.cmake)
+endif()
+
+
 # installation of manpages if enabled and supported
 if(INCLUDE_MANPAGES_IN_INSTALL)
   include(tools/cmake/install_manpages.cmake)
@@ -1192,24 +1259,5 @@ endif()
 
 # doxygen build target
 if(DOXYGEN_FOUND)
-  configure_file(${PROJECT_SOURCE_DIR}/tools/doxygen/Doxyfile.in ${PROJECT_BINARY_DIR}/tools/doxygen/Doxyfile)
-
-  file(GLOB_RECURSE DOXYGEN_PUBLIC_HEADERS ${DOXYGEN_INCLUDE_DIR}/stumpless/*.h)
-  set(EXAMPLE_SOURCES
-    ${PROJECT_SOURCE_DIR}/docs/examples/basic/basic_example.c
-  )
-
-  add_custom_command(
-    OUTPUT ${DOXYGEN_MANPAGES}
-    COMMAND ${DOXYGEN_EXECUTABLE} ${CMAKE_BINARY_DIR}/tools/doxygen/Doxyfile
-    MAIN_DEPENDENCY ${PROJECT_BINARY_DIR}/tools/doxygen/Doxyfile
-    DEPENDS
-      ${DOXYGEN_PUBLIC_HEADERS}
-      ${EXAMPLE_SOURCES}
-      ${DOXYGEN_INCLUDE_DIR}/stumpless.h
-      ${PROJECT_BINARY_DIR}/include/stumpless/config.h
-    VERBATIM
-  )
-
-  add_custom_target(docs DEPENDS ${DOXYGEN_MANPAGES})
+  include(tools/cmake/doxygen.cmake)
 endif()
diff --git a/ChangeLog.md b/ChangeLog.md
@@ -9,12 +9,14 @@ fixes, check out the
 [roadmap](https://github.com/goatshriek/stumpless/blob/master/docs/roadmap.md).
 
 
-## [2.2.0] - 2024-03-30
+## [2.2.0] - 2024-05-26
 ### Added 
  - @since format check enforcement in CI pipeline.
  - `single-file` target for rollup `.c` and `.h` files.
  - SQLite3 logging targets.
  - Target chains.
+ - Support for `pkg-config`.
+ - `INSTALL_HEADERS` and `INSTALL_HTML` build options.
  - Localizations for:
     * Albanian (sq-AL :albania:)
     * Danish (da-DK :denmark:)

diff --git a/INSTALL.md b/INSTALL.md
@@ -10,14 +10,25 @@ Stumpless is not currently registered in any online package repositories such
 as Chocolatey or Debian. If you need the library in a location like this, please
 open an issue and the project team will see what we can do.
 
+The provided release packages contain all of the items in the following list.
+If you want a package with only a selection of these items, you'll need to build
+it yourself using `cpack` and the appropriate configuration.
+
+ * shared library
+ * header files
+ * `.pc` file for `pkg-config` implementations
+ * examples
+ * HTML documentation
+ * man pages
+
 
 ## Debian Package
 A `.deb` package is provided for use in environments that support them, like
 Debian and Ubuntu. The package can be installed with the usual command:
 
 ```sh
 # you might need sudo (or root privileges) to install
-dpkg -i stumpless-2.2.0-amd64.deb
+dpkg -i libstumpless-2.2.0-amd64.deb
 ```
 
 
@@ -27,7 +38,17 @@ installed in the traditional way as well:
 
 ```sh
 # again, make sure you have the correct permissions
-rpm -i stumpless-2.2.0-x86_64.rpm
+rpm -i libstumpless-2.2.0-x86_64.rpm
+```
+
+
+## FreeBSD Package
+A `.pkg` package is provided for use in FreeBSD environments. Of course, it is
+installed just as any other pkg would be:
+
+```sh
+# permissions need to be correct, of course
+pkg add libstumpless-2.2.0-amd64.pkg
 ```
 
 
@@ -38,7 +59,7 @@ generated ebuild is in the `tools/portage` folder of the build directory.
 
 The generated ebuild will be named after the version of stumpless you have.
 If you want the latest commit instead of a release, you'll need to rename this
-to version `stumpless-9999.ebuild` to perform what Gentoo refers to as a
+to version `libstumpless-9999.ebuild` to perform what Gentoo refers to as a
 [live ebuild](https://wiki.gentoo.org/wiki/Ebuild#Live_ebuilds). If you have a
 commit in a release that hasn't been published yet and do not rename the ebuild,
 then the download of the source will fail.
@@ -47,7 +68,7 @@ In either case, you could install the ebuild by putting it into a repository and
 running ebuild ultimately as something like:
 
 ```sh
-ebuild stumpless-2.2.0.ebuild clean install merge
+ebuild libstumpless-2.2.0.ebuild clean manifest install merge
 ```
 
 USE flags and other customizations can be done here as well. Gentoo installs are
@@ -66,7 +87,7 @@ files.
 # you might need to do this with sudo!
 # make sure your permissions allow you to write to the install locations
 cd /usr
-./stumpless-2.2.0.sh
+./libstumpless-2.2.0.sh
 ```