Merge pull request #9 from saxbophone/my-hovercraft-is-full-of-eels

Various usability improvements

Author: saxbophone

.github/workflows/build-release.yml

@@ -55,7 +55,7 @@ jobs:
       - name: Upload
         uses: actions/upload-artifact@v2
         with:
-          name: project_build_${{ github.run_number }}_${{ matrix.platform_name }}
+          name: my-hovercraft-is-full-of-eels_build_${{ github.run_number }}_${{ matrix.platform_name }}
           path: ${{github.workspace}}/artifacts
   build-docs:
     runs-on: ubuntu-20.04

CMakeLists.txt

@@ -2,14 +2,14 @@
 # minimum CMake version required for C++20 support, among other things
 cmake_minimum_required(VERSION 3.15)
 
-# detect if Project is being used as a sub-project of another CMake project
+# detect if MyHovercraftIsFullOfEels is being used as a sub-project of another CMake project
 if(NOT DEFINED PROJECT_NAME)
-    set(PROJECT_SUBPROJECT OFF)
+    set(MY_HOVERCRAFT_IS_FULL_OF_EELS_SUBPROJECT OFF)
 else()
-    set(PROJECT_SUBPROJECT ON)
+    set(MY_HOVERCRAFT_IS_FULL_OF_EELS_SUBPROJECT ON)
 endif()
 
-project(project VERSION 0.3.0 LANGUAGES CXX)
+project(my-hovercraft-is-full-of-eels VERSION 0.3.0 LANGUAGES CXX)
 
 find_program(CCACHE_PROGRAM ccache)
 if(CCACHE_PROGRAM)
@@ -27,24 +27,24 @@ endif()
 
 # set some handy custom variables to detect Release-type builds from Debug-type ones
 if(CMAKE_BUILD_TYPE STREQUAL "Debug")
-    set(PROJECT_BUILD_DEBUG ON)
-    set(PROJECT_BUILD_RELEASE OFF)
+    set(MY_HOVERCRAFT_IS_FULL_OF_EELS_BUILD_DEBUG ON)
+    set(MY_HOVERCRAFT_IS_FULL_OF_EELS_BUILD_RELEASE OFF)
 else()
-    set(PROJECT_BUILD_DEBUG OFF)
-    set(PROJECT_BUILD_RELEASE ON)
+    set(MY_HOVERCRAFT_IS_FULL_OF_EELS_BUILD_DEBUG OFF)
+    set(MY_HOVERCRAFT_IS_FULL_OF_EELS_BUILD_RELEASE ON)
 endif()
 
-message(STATUS "[project] Build Mode: ${CMAKE_BUILD_TYPE}")
+message(STATUS "[my-hovercraft-is-full-of-eels] Build Mode: ${CMAKE_BUILD_TYPE}")
 
 # set the C++ standard to use to C++20 always
-set(PROJECT_CXX_STANDARD "20")
-message(STATUS "[project] C++ Standard set to C++${PROJECT_CXX_STANDARD}")
-set(CMAKE_CXX_STANDARD ${PROJECT_CXX_STANDARD})
+set(MY_HOVERCRAFT_IS_FULL_OF_EELS_CXX_STANDARD "20")
+message(STATUS "[my-hovercraft-is-full-of-eels] C++ Standard set to C++${MY_HOVERCRAFT_IS_FULL_OF_EELS_CXX_STANDARD}")
+set(CMAKE_CXX_STANDARD ${MY_HOVERCRAFT_IS_FULL_OF_EELS_CXX_STANDARD})
 set(CMAKE_CXX_STANDARD_REQUIRED ON)
 
 include(CMakeDependentOption)
 # if building in Release mode, provide an option to explicitly enable tests if desired (always ON for other builds, OFF by default for Release builds)
-cmake_dependent_option(ENABLE_TESTS "Build the unit tests in release mode?" OFF PROJECT_BUILD_RELEASE ON)
+cmake_dependent_option(ENABLE_TESTS "Build the unit tests in release mode?" OFF MY_HOVERCRAFT_IS_FULL_OF_EELS_BUILD_RELEASE ON)
 
 # Premature Optimisation causes problems. Commented out code below allows detection and enabling of LTO.
 # It's not being used currently because it seems to cause linker errors with Clang++ on Ubuntu if the library
@@ -54,45 +54,44 @@ cmake_dependent_option(ENABLE_TESTS "Build the unit tests in release mode?" OFF
 
 # include(CheckIPOSupported)
 # check_ipo_supported(RESULT IPO_SUPPORTED)
-# # If we're in Release mode, set PROJECT_USE_IPO to ON by default if it's detected as supported (user can always explicitly enable it in Release mode)
-# cmake_dependent_option(PROJECT_USE_IPO "Use Link-Time/Inter-Procedural Optimisation?" ${IPO_SUPPORTED} PROJECT_BUILD_RELEASE OFF)
-# if(PROJECT_USE_IPO)
-#     message(STATUS "[project] Link-Time-Optimisation Enabled")
+# # If we're in Release mode, set MY_HOVERCRAFT_IS_FULL_OF_EELS_USE_IPO to ON by default if it's detected as supported (user can always explicitly enable it in Release mode)
+# cmake_dependent_option(MY_HOVERCRAFT_IS_FULL_OF_EELS_USE_IPO "Use Link-Time/Inter-Procedural Optimisation?" ${IPO_SUPPORTED} MY_HOVERCRAFT_IS_FULL_OF_EELS_BUILD_RELEASE OFF)
+# if(MY_HOVERCRAFT_IS_FULL_OF_EELS_USE_IPO)
+#     message(STATUS "[my-hovercraft-is-full-of-eels] Link-Time-Optimisation Enabled")
 # endif()
 
 set(
-    PROJECT_VERSION_STRING
+    MY_HOVERCRAFT_IS_FULL_OF_EELS_VERSION_STRING
     "${PROJECT_VERSION_MAJOR}.${PROJECT_VERSION_MINOR}.${PROJECT_VERSION_PATCH}"
 )
-set(PROJECT_ESCAPED_VERSION_STRING "\"${PROJECT_VERSION_STRING}\"")
+set(MY_HOVERCRAFT_IS_FULL_OF_EELS_ESCAPED_VERSION_STRING "\"${MY_HOVERCRAFT_IS_FULL_OF_EELS_VERSION_STRING}\"")
 # end basic metadata
 
 # This is a special target which only exists to capture compilation options
-# used for project and its tests. This is to avoid setting global compiler
+# used for my-hovercraft-is-full-of-eels and its tests. This is to avoid setting global compiler
 # options which would be inherited by dependencies as well, which is bad
-# because project uses strict compiler warning options which not all other
+# because my-hovercraft-is-full-of-eels uses strict compiler warning options which not all other
 # projects can build successfully with.
 # Any target linked with this one will inherit the compiler options used for
-# project.
-add_library(project-compiler-options INTERFACE)
+# my-hovercraft-is-full-of-eels.
+add_library(my-hovercraft-is-full-of-eels-compiler-options INTERFACE)
 
 # used for enabling additional compiler options if supported
 include(CheckCXXCompilerFlag)
 
 function(enable_cxx_compiler_flag_if_supported flag)
-    message(STATUS "[project] Checking if compiler supports warning flag '${flag}'")
+    message(STATUS "[my-hovercraft-is-full-of-eels] Checking if compiler supports warning flag '${flag}'")
     check_cxx_compiler_flag("${flag}" flag_supported)
     if(flag_supported)
-        message(STATUS "[project] Enabling warning flag '${flag}'")
-        target_compile_options(project-compiler-options INTERFACE "${flag}")
+        message(STATUS "[my-hovercraft-is-full-of-eels] Enabling warning flag '${flag}'")
+        target_compile_options(my-hovercraft-is-full-of-eels-compiler-options INTERFACE "${flag}")
     endif()
     unset(flag_supported CACHE)
 endfunction()
 
 # enable a large amount of extra warnings, regardless of build mode
 if (MSVC) # MSVC supports different warning options to GCC/Clang
-    # add_compile_options(/W4) # set warning level 4
-    enable_cxx_compiler_flag_if_supported("/W4")
+    enable_cxx_compiler_flag_if_supported("/W3")  # set warning level 3
     # if tests are enabled, enable converting all warnings to errors too
     if (ENABLE_TESTS)
         # add_compile_options(/WX)
@@ -126,6 +125,7 @@ else() # GCC/Clang warning option
         enable_cxx_compiler_flag_if_supported("-Wno-error=unused-variable")
         enable_cxx_compiler_flag_if_supported("-Wno-error=unused-parameter")
         enable_cxx_compiler_flag_if_supported("-Wno-error=unused-private-field")
+        enable_cxx_compiler_flag_if_supported("-Wno-error=unused-but-set-variable")
     endif()
 endif()
 
@@ -136,10 +136,10 @@ set(CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH} "${CMAKE_CURRENT_SOURCE_DIR}/cmake/Mo
 include(CPM)
 
 # library
-add_subdirectory(project)
+add_subdirectory(my-hovercraft-is-full-of-eels)
 # unit tests --only enable if requested AND we're not building as a sub-project
-if(ENABLE_TESTS AND NOT PROJECT_SUBPROJECT)
-    message(STATUS "[project] Unit Tests Enabled")
+if(ENABLE_TESTS AND NOT MY_HOVERCRAFT_IS_FULL_OF_EELS_SUBPROJECT)
+    message(STATUS "[my-hovercraft-is-full-of-eels] Unit Tests Enabled")
     add_subdirectory(tests)
     enable_testing()
 endif()

Doxyfile

@@ -771,7 +771,7 @@ WARN_LOGFILE           =
 # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  = project
+INPUT                  = my-hovercraft-is-full-of-eels
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses

README.md

@@ -4,30 +4,37 @@ A template for a cross-platform C++20 project including modern CMake, unit-testi
 ## What's included
 - CMake C++20 project skeleton, with strict warning flags enabled when using GCC or Clang.
 - Usage of modern CMake practices for setting project-wide compiler options, etc. in a target-focused way.
-- Properly exported CMake project that can be used by other CMake projects with minimal effort (no hand-written `FindMyProject.cmake` files)
+- Properly exported CMake project that can be used by other CMake projects with minimal effort (no hand-written `FindProject.cmake` files)
 - Unit testing using [Catch2](https://github.com/catchorg/Catch2), with automatic test discovery integration with CTest.
 - Github Actions config files supporting building and running tests on Linux, macOS and Windows using the following compilers:
     - Linux: GCC-10, Clang-10
     - macOS: GCC-10, Clang-12
     - Windows: MSVC 2019
 - Building Releases on each platform when a Github Release is published, uploading these as build Artifacts.
 - Doxygen config file with tweaks from the default config settings to provide a few more graphs (usage, caller/callee relationships) than are enabled by default.
+- Doxygen docs are also built as part of release builds, and these are uploaded to the gh-pages branch under a versioned URL, versioned to the minor version.
+    > For these docs to work properly, you need to observe the expected tag naming format for the tags you select for your Github Releases. The system expects semantic-versioning to be used, with tags of the format `vX.X.X` where `X` is a number. Docs of previous versions of the same minor version are overwritten when a new version for that same minor version is released. Docs of other minor versions are never deleted automatically.
 
 > **Note** There's also a Travis-CI build config for a cross-platform build of similar structure to the Github Actions builds, however this is no longer maintained as Travis-CI has been found to not support more recent versions of CMake on all platforms.
 
 ## Usage
 1. Click the <kbd>Use this template</kbd> button at the top of this page to create your own new copy of this template
 2. Fill in the project details on the next page as you desire
-3. Once you've got your new project produced from this template, make changes in the following files:
-    - `CMakeLists.txt`, `project/CMakeLists.txt`, `project/src/CMakeLists.txt`, `tests/CMakeLists.txt`:
-        - Replace all instances of `PROJECT`, `project` and `Project` with your project's name, capitalised or uncapitalised as appropriate
-    - `Doxyfile`:
-        - Change the `PROJECT_NAME` and `INPUT` settings to your project's name.
-    - `project`:
-        - Rename this directory to the name of your project.
+3. Once you've got your new project produced from this template, do a find-and-replace globally within the project with the following substitutions:
+    - `my-hovercraft-is-full-of-eels` -> your project name in lowercase. You could use `-` to separate words if you like.
+    - `MyHovercraftIsFullOfEels` -> your project name in UpperCamelCase. Recommended to capitalise each word.
+    - `MY_HOVERCRAFT_IS_FULL_OF_EELS` -> your project name in UPPER_SNAKE_CASE. Recommended to separate at the words.
+    - `com::saxbophone::my_hovercraft_is_full_of_eels` -> an appropriate C++ namespace for your project.
+
+    Also rename the following directories in the same way:
+    - `my-hovercraft-is-full-of-eels`
+    - `my-hovercraft-is-full-of-eels/include/my-hovercraft-is-full-of-eels`
+
     - **Choose a Software License for your code** if it is open-source and you want other people to be able to use it with ease!
 
-      This _project template_ is placed into the public domain, but you may want to use a different license for your own projects that you create from this template. Here is the public domain dedication text for this project:
+      This _project template_ is placed into the public domain, but you should make your own choice of software license to use for projects that you create from this template.
+
+      Here is the public domain dedication text for this project:
 
       ```
       This is free and unencumbered software released into the public domain.
@@ -57,4 +64,4 @@ A template for a cross-platform C++20 project including modern CMake, unit-testi
       ```
 4. Enjoy!
 
-> The above instructions are the bare minimum required to get your own project based on this template off of the ground. You'll almost certainly want to change more things in `Doxyfile` and definitely `README.md`, but that should be well within the capabilities of a developer and also beyond the scope of this guide.
+> The above instructions are the bare minimum required to get your own project based on this template off of the ground. You'll almost certainly want to change more things in `Doxyfile` and definitely `README.md`, but these are documented better in other places and also beyond the scope of this guide.

my-hovercraft-is-full-of-eels/CMakeLists.txt

@@ -0,0 +1,84 @@
+include(GNUInstallDirs)
+
+add_library(my-hovercraft-is-full-of-eels STATIC)
+# ALIAS target to export a namespaced target even when building in-tree
+add_library(MyHovercraftIsFullOfEels::my-hovercraft-is-full-of-eels ALIAS my-hovercraft-is-full-of-eels)
+# add source files
+add_subdirectory(src)
+# library public header files location
+target_include_directories(
+    my-hovercraft-is-full-of-eels PUBLIC
+    # different include directory path depending on if using the local or installed version of library
+    $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
+    $<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}>
+)
+# pass in version of project as preprocessor definitions
+target_compile_definitions(
+    my-hovercraft-is-full-of-eels PRIVATE
+    -DMY_HOVERCRAFT_IS_FULL_OF_EELS_VERSION_MAJOR=${PROJECT_VERSION_MAJOR}
+    -DMY_HOVERCRAFT_IS_FULL_OF_EELS_VERSION_MINOR=${PROJECT_VERSION_MINOR}
+    -DMY_HOVERCRAFT_IS_FULL_OF_EELS_VERSION_PATCH=${PROJECT_VERSION_PATCH}
+    -DMY_HOVERCRAFT_IS_FULL_OF_EELS_VERSION_STRING=${MY_HOVERCRAFT_IS_FULL_OF_EELS_ESCAPED_VERSION_STRING}
+)
+# set up version and soversion for the main library object
+set_target_properties(
+    my-hovercraft-is-full-of-eels PROPERTIES
+    VERSION ${MY_HOVERCRAFT_IS_FULL_OF_EELS_VERSION_STRING}
+    SOVERSION ${PROJECT_VERSION_MAJOR}
+    INTERFACE_MyHovercraftIsFullOfEels_MAJOR_VERSION ${PROJECT_VERSION_MAJOR}
+    INTERFACE_MyHovercraftIsFullOfEels_MINOR_VERSION ${PROJECT_VERSION_MINOR}
+)
+set_property(
+    TARGET my-hovercraft-is-full-of-eels
+    APPEND PROPERTY COMPATIBLE_INTERFACE_STRING "${MyHovercraftIsFullOfEels_MAJOR_VERSION}.${MyHovercraftIsFullOfEels_MINOR_VERSION}"
+)
+# inherit common project compiler options
+target_link_libraries(
+    my-hovercraft-is-full-of-eels
+        PRIVATE
+            $<BUILD_INTERFACE:my-hovercraft-is-full-of-eels-compiler-options>
+)
+
+# install if we're not being built as a sub-project
+if (NOT MY_HOVERCRAFT_IS_FULL_OF_EELS_SUBMY_HOVERCRAFT_IS_FULL_OF_EELS)
+    # library
+    install(
+        TARGETS my-hovercraft-is-full-of-eels
+        EXPORT MyHovercraftIsFullOfEelsTargets
+        # when a static library
+        ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}
+        # when a shared library on UNIX
+        LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
+        # when a DLL on Windows
+        RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
+    )
+    # public headers
+    install(
+        DIRECTORY "include/" DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}
+    )
+    # CMake export
+    install(
+        EXPORT MyHovercraftIsFullOfEelsTargets
+        FILE MyHovercraftIsFullOfEelsTargets.cmake
+        NAMESPACE MyHovercraftIsFullOfEels::
+        DESTINATION "${CMAKE_INSTALL_LIBDIR}/cmake/MyHovercraftIsFullOfEels"
+    )
+    # CMake package
+    include(CMakePackageConfigHelpers)
+    configure_package_config_file(${CMAKE_CURRENT_SOURCE_DIR}/Config.cmake.in
+        "${CMAKE_CURRENT_BINARY_DIR}/MyHovercraftIsFullOfEelsConfig.cmake"
+        INSTALL_DESTINATION "${CMAKE_INSTALL_LIBDIR}/cmake/MyHovercraftIsFullOfEels"
+    )
+    # generate the version file for the config file
+    write_basic_package_version_file(
+        "${CMAKE_CURRENT_BINARY_DIR}/MyHovercraftIsFullOfEelsConfigVersion.cmake"
+        VERSION "${version}"
+        COMPATIBILITY SameMinorVersion
+    )
+    install(
+        FILES
+        "${CMAKE_CURRENT_BINARY_DIR}/MyHovercraftIsFullOfEelsConfig.cmake"
+        "${CMAKE_CURRENT_BINARY_DIR}/MyHovercraftIsFullOfEelsConfigVersion.cmake"
+        DESTINATION "${CMAKE_INSTALL_LIBDIR}/cmake/MyHovercraftIsFullOfEels"
+    )
+endif()

my-hovercraft-is-full-of-eels/Config.cmake.in

@@ -0,0 +1,5 @@
+@PACKAGE_INIT@
+
+include("${CMAKE_CURRENT_LIST_DIR}/MyHovercraftIsFullOfEelsTargets.cmake")
+
+check_required_components(MyHovercraftIsFullOfEels)

project/include/project/Public.hpp renamed to my-hovercraft-is-full-of-eels/include/my-hovercraft-is-full-of-eels/Public.hpp

@@ -14,10 +14,10 @@
  *
  */
 
-#ifndef COM_SAXBOPHONE_PROJECT_PUBLIC_HPP
-#define COM_SAXBOPHONE_PROJECT_PUBLIC_HPP
+#ifndef COM_SAXBOPHONE_MY_HOVERCRAFT_IS_FULL_OF_EELS_PUBLIC_HPP
+#define COM_SAXBOPHONE_MY_HOVERCRAFT_IS_FULL_OF_EELS_PUBLIC_HPP
 
-namespace com::saxbophone::project {
+namespace com::saxbophone::my_hovercraft_is_full_of_eels {
     /**
      * @brief Stub test function for sample project
      * @returns Whether the test library "works" or not, which is a vague

project/src/CMakeLists.txt renamed to my-hovercraft-is-full-of-eels/src/CMakeLists.txt

@@ -1,6 +1,6 @@
 # top-level namespace source files
 target_sources(
-    project
+    my-hovercraft-is-full-of-eels
         PRIVATE
             Private.cpp
             Public.cpp

project/src/Private.cpp renamed to my-hovercraft-is-full-of-eels/src/Private.cpp

@@ -6,7 +6,7 @@
 
 #include "Private.hpp"
 
-namespace com::saxbophone::project::PRIVATE {
+namespace com::saxbophone::my_hovercraft_is_full_of_eels::PRIVATE {
     bool library_works() {
         return true;
     }

my-hovercraft-is-full-of-eels/src/Private.hpp

@@ -0,0 +1,16 @@
+/*
+ * This is a sample private compilation unit.
+ *
+ * <Copyright information goes here>
+ */
+
+#ifndef COM_SAXBOPHONE_MY_HOVERCRAFT_IS_FULL_OF_EELS_PRIVATE_HPP
+#define COM_SAXBOPHONE_MY_HOVERCRAFT_IS_FULL_OF_EELS_PRIVATE_HPP
+
+#include <my-hovercraft-is-full-of-eels/Public.hpp>
+
+namespace com::saxbophone::my_hovercraft_is_full_of_eels::PRIVATE {
+    bool library_works();
+}
+
+#endif // include guard