threeal/cpp-starter

A minimalistic GitHub repository template to kickstart your C++ project

Alfi Maulana

A C++ enthusiast who is experienced with building and optimizing native apps on Linux, macOS, and Windows. Also, a fast learner and generalist who can develop multiple things like computer vision programs using OpenCV, shell scripts for CI workflows, web apps using TypeScript, and microservices using Go.

My Works

Aside from my current job, I also work on several personal projects. Currently, most of these projects are GitHub repository templates and GitHub Actions for utilizing my other projects. Please refer to my repositories for a list of all projects that I have done.

C++ Projects

• C++ Starter: A minimalistic GitHub repository template to kickstart your C++ project.
• Errors C++: A C++ package that provides utilities for error handling.
• Result: A simple C++ implementation of Rust Result, an alternative to Abseil Status.

CMake Projects

• CMake Starter: A minimalistic GitHub repository template to kickstart your CMake project.
• Assertion.cmake: A CMake module containing a collection of assertion functions and other utilities for testing CMake code.
• CheckWarning.cmake: Check for compiler warnings in your CMake project.
• FixFormat.cmake: Fix source codes formatting in your CMake project.
• GitCheckout.cmake: Clone and check out a Git repository from a CMake project.
• SetupGo.cmake: Set up a specific version of Go from a CMake project.

Node.js Projects

• Node.js Starter: A minimalistic GitHub repository template to kickstart your Node.js project.
• Google Rank: Retrieve the Google search ranking of your website for specific keywords.
• LeetTest: Tool for compiling and testing solutions to LeetCode problems.

GitHub Actions Projects

• Action Starter: A minimalistic GitHub repository template to kickstart your GitHub Action project.
• Setup Yarn Berry Action: Set up Yarn to a specified version and install Node.js project with cache support on GitHub Actions.
• Pipx Install Action: Install Python packages using pipx with cache support on GitHub Actions.
• CMake Action: Configure, build, and test your CMake project using GitHub Actions.
• Gcovr Action: Generate code coverage reports for a C++ project on GitHub Actions using gcovr.
• LeetTest Action: Compile and test solutions to LeetCode problems on GitHub Actions.

GitHub Composite Actions Projects

• Composite Action Starter: A minimalistic GitHub repository template to kickstart your GitHub composite action project.
• Setup Poetry Action: Set up your GitHub Actions workflow with a specific version of Poetry.
• CTest Action: Test CMake projects using CTest on GitHub Actions.
• ROS 2 Workspace Action: Setup, build and test a ROS 2 workspace using GitHub Actions.

Other Projects

• Project Starter: A minimalistic GitHub repository template to kickstart your project.
• Python Starter: A minimalistic GitHub repository template to kickstart your Python project.
• LeetSpace: A dedicated workspace and archive for my LeetCode submissions.

cpp-starter's Issues

Utilize FixFormat.cmake

This issue suggests utilizing the FixFormat.cmake project to format sample source codes in this template, replacing the currently used Format.cmake.

Replace Function to Get CPM.cmake

This issue suggests replacing the get_cpm function in the root's CMakeLists.txt with a cpmaddpackage function that will shadow the actual cpmaddpackage function from the CPM.cmake module.

Before the actual cpmaddpackage function is available, we will declare a cpmaddpackage function that actually behaves by downloading the CPM.cmake module and including it so that the actual cpmaddpackage function is available. This trick allows the CPM.cmake to be available lazily without the need to call a get_cpm function to make the cpmaddpackage function available.

Add Check Coverage Function

This issue recommends adding a target_check_coverage function to enable test coverage checks on a specific target. This function will be responsible for enabling compiler flags related to test coverage checks and adding a custom command to remove the target's GCDA files before its linking step.

Enable to Treat Warning as Error

This issue suggests to enable treating warnings as errors in the project build process.

Add Option to Enable Install Targets

This issue suggests adding a MY_FIBONACCI_ENABLE_INSTALL option to optionally enable or disable install targets in the sample project. Refer to threeal/cmake-starter#72 for more information and the rationale behind this suggestion.

Remove GCDA Files Before Linking Test Target

This issue highlights a compilation problem where, after multiple modifications to source files used by the test target, numerous cannot merge previous GCDA file: corrupt arc tag errors occur. While this issue is typically resolved by manually removing the associated GCDA files, this process is cumbersome. Consequently, the recommendation is to automatically remove these GCDA files during compilation before linking the test target.

Remove Badges from Readme

This issue suggests removing badges from the README.md file because the information in the badges does not seem to be important to include in the readme. Refer to threeal/pipx-install-action#119 for more information and the rationale behind this proposal.

Use CMake Action

Use the CMake Action to configure and build C++ project in this template.

Improve Header File Specification Using File Sets

This issue suggests adopting file sets instead of using include directories to specify headers. Refer to this documentation for more details on utilizing file sets as a modern CMake approach for setting header files.

While setting file sets may be more complex than using include directories, it promotes better practices for manually specifying source files, including headers, for a specific target.

Additionally, using file sets allows only the relevant header files for the target to be installed, rather than installing the entire directory, which is beneficial for addressing #62.

Utilize CTest Action

This issue suggests using the CTest Action for running tests in the workflow, replacing the ctest command. This change is proposed to establish a standard for employing the action to test CMake or C++ projects, rather than manually specifying some of the test arguments.

Simplify Dependency Find Package

This issue suggests simplifying the implementation of finding packages for the sample project dependencies. This can be achieved by directly calling the actual find package config and falling back to using CPM if the config is not available.

This change is proposed to simplify the files within the cmake directory and streamline the process of adding a new dependency without the need to create another find package module for that dependency.

Remove `CPM.cmake` File

This issue proposes removing the cmake/CPM.cmake file and, instead, including a line in the root CMakeLists.txt for directly downloading CPM.cmake.

Enhance Project Information in `CMakeLists.txt`

This issue proposes adding more detailed project information to the CMakeLists.txt file by completing the project function. This enhancement will provide additional clarity and context about the project.

Set Warning Flags for Each Target

This issue proposes to set warning flags individually for each target instead of applying them globally using CMAKE_CXX_FLAGS.

Define C++ Standard with `target_compile_features`

This issue proposes utilizing the target_compile_features function instead of the set_property function to define the C++ standards for a target.

Disable Exception Support in Testing

This issue recommends to disable exception support in testing by adding the -fno-exceptions compile option to the test target. This change is recommended because apparently, sometimes the code coverage won't reach 100% test coverage because the testing didn't catch any exception. Since reproducing a case where the function will throw an exception is hard, it is better to just disable the exception instead.

Disable Install on Subproject

This issue suggests disabling project installation if the project is being treated as a subproject. This change is proposed because when the project is included as a subproject, it is unlikely that the project requires support for installation.

Skip CMake Formatting

This issue proposes disabling CMake formatting, introduced through the Format.cmake package, by setting the FORMAT_SKIP_CMAKE option to ON.

The suggestion stems from the fact that the formatting style applied by the mentioned package does not align with the preferred style for this project. Additionally, it lacks support for most functions, leading to potentially undesirable formatting results for certain functions.

Specify Development Scope in CMake

Only allows testing and format checking if this project is in the development root (not included by other project).
We can do that by using this:

if(CMAKE_CURRENT_SOURCE_DIR STREQUAL CMAKE_SOURCE_DIR)
  // allows unit test and format check
endif()

We do this to prevent running unintended unit tests or format check if this project is included by other project.

Simplify CPM Add Package Declaration

This issue suggests simplifying the CPM add package declaration so that the declaration is not called inside a function, as seen here:

https://github.com/threeal/cpp-starter/blob/1f2b4ca66647989b1674a40e9f4a1d5c8696f99e/cmake/CPM.cmake#L10C10-L24

Initially, declaring it inside a function was proposed to treat the CPM.cmake file as a package lock file containing a list of dependencies (without declaring them until each function is called). However, since this template currently does not support dependency caching, the CPM.cmake file is unused when treated as a package lock file. Therefore, this issue suggests simplifying the CPM add package declaration by calling it directly instead of relying on some parent function.

Enhance README with Key Features and Usage

This issue proposes the addition of a "Key Features" section and a "Usage" section to the README.md file. The suggested format for these sections can be adopted from the README.md of the Python Starter template.

Organize Jobs in the CI Workflow

This issue suggests to organize jobs in the CI workflow as follows:

• Rename Build job into Build Release job.
• Merge Unit Tests and Check Formatting jobs into Build Testing job.

Modify Sample Function to Generate Fibonacci Sequence

This issue proposes replacing the existing is_odd function with a fibonacci_sequence function to align with the pattern used in the Python Starter and Node.js Starter templates.

Refactor Sample Target Names

This issue proposes renaming the sample targets to exclude the my_fibonacci name, as this name should be reserved solely for the namespace. Additionally, it suggests making the target names clearer; for instance, changing the executable name to generate_sequence instead of my_fibonacci_main. Furthermore, instead of my_fibonacci::my_fibonacci, the library should be renamed to my_fibonacci::sequence for improved clarity.

Reorder Included Headers

This issue suggests reordering the include headers of the sample project in the following order:

• The paired header file.
• Other headers from the project.
• Third-party library headers.
• Standard library headers.

Refer to this for the rationale behind this ordering system. It may also be useful to modify the include blocks sorting strategy in Clang Format by setting the IncludeBlocks option to prevent the order of the header files from being modified by Clang Format.

Enable Export and Installation of Targets

This issue proposes adjusting the CMakeLists.txt in this project to enable the exporting and installation of targets using the cmake --install command. Aligning with the standard CMake project structure, this adjustment ensures that targets built in this project can be exported and installed to a specific directory. This modification facilitates the use of the project without the necessity of building it first.

Add Executable Target

This issue suggests to add an example executable target for this project. The target itself will be used to generate a Fibonacci sequence from the given argument input. This suggestion is proposed so that this template have the same entrypoint executable as other template like in Node.js Starter and Python Starter.

Lazily Add CPM Package

This issue suggests modifying how a CPM package is added only if the dependencies are not available locally when searched using the find_package function.

Although CPM.cmake supports local packages through the CPM_USE_LOCAL_PACKAGES option, it still requires downloading CPM.cmake to enable the use of local packages.

To address this, we can enhance how a package is searched and added to CPM by utilizing a combination of find_package in both configuration and module modes. This approach involves initially finding the package using the module mode. In the FindXXX.cmake file, we can then locate the actual package using config mode. If it is not available, we can download the actual package using CPM.cmake.

Utilize `PROJECT_IS_TOP_LEVEL` Variable

This issue suggests utilizing the PROJECT_IS_TOP_LEVEL variable, replacing the SUBPROJECT variable. Refer to threeal/cmake-starter#66 for more information and the rationale behind this suggestion.

Remove Export of CMake Module Path to Parent Scope

This issue suggests removing the export of the CMAKE_MODULE_PATH variable to the parent scope because there is nothing useful inside this project's CMake module path (cmake directory) for any parent project. Removing this may simplify the top-level CMakeLists.txt of this project and prevent a parent project from having an unnecessary path inside the CMAKE_MODULE_PATH variable.

Organize CPM.cmake Download and Inclusion in Separate Module

This issue recommends organizing the lines responsible for downloading and including CPM.cmake into a distinct module. Refer to this link for a reference module file.

Utilize UT for Testing

This issue suggests utilizing UT as the testing framework for this template, replacing the currently used Catch2.

Avoid Formatting of CPM Package Lock File

This issue proposes preventing the formatting of the CPM package lock file. One potential solution is to simplify the name of the package lock file from package-lock.cmake to just package-lock.

Bump Minimum CMake Version to 3.5

This issue suggests to bump the minimum CMake version to 3.5 because compatibility with CMake < 3.5 will be removed from a future version of CMake as could be seen in the following screenshot:

Use CheckWarning.cmake

This issue recommends utilizing CheckWarning.cmake to facilitate compiler warning checks, rather than manually specifying warning flags using the target_compile_options function.

Replace `package-lock` File With Declaration Inside `CPM.cmake` Module

This issue suggests removing the package-lock file and declaring each package dependency inside the CPM.cmake module file. Internally, the purpose of the package-lock file is essentially the same as calling its content directly from any CMake module. Therefore, it is better to remove the package-lock file in favor of declaring each package dependency directly from a CMake module.

Utilize CDeps.cmake

This issue suggests utilizing the CDeps.cmake module for installing missing dependencies in the project, replacing the CPM.cmake module.

CDeps is proposed for use because, compared to CPM, CDeps will build and install the project during the configuration time, with a scope separated from the main project. This will allow the find_package function to behave the same whether it finds the missing package on the system or not. This is different from CPM, which includes the missing package as a subdirectory and builds the target altogether, potentially cluttering the main project target with the targets from dependencies.

Add MSVC Support

This issue recommends adding support for building the sample project in this template using MSVC on Windows. It is also suggested to update the build-project and test-project to run on Windows and be compiled using MSVC.

Limit Coverage Flags to Specific Target

This pull request addresses the concern raised in the following line by suggesting the restriction of coverage flags to a specific target.

cpp-starter/CMakeLists.txt

Line 26 in 6501f60

set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fprofile-arcs -ftest-coverage -fPIC -O0")

Currently, the flags are set globally, potentially impacting all targets. By implementing this change, we aim to mitigate any unintended effects on other targets.

Format and Check Warnings Only When Build Testing Is Enabled

This issue suggests modifying the build rules so that code formatting and warnings check are only enabled if the BUILD_TESTING option is turned on.

Currently, the warning check is always enabled even when BUILD_TESTING is off. While this is a good practice, it may prevent client users from using this library if the warning check fails. The build result remains consistent regardless of whether the warning check is enabled or not. Therefore, the warning check should be intended for development purposes only.

The same rationale applies to code formatting, which is unnecessary for client users to download Format.cmake and make format targets available.

Ignore All Dot Prefixed Files in Git

Modifies the .gitignore to ignore all dot-prefixed files (.*).

Merge Workflows into a Single CI Workflow

This issue suggests combining the existing workflows, specifically the build.yml and test.yml workflows, into a unified ci.yaml workflow. This consolidated workflow will include a single job that encompasses both the build and test processes. This consolidation will help streamline the project's CI process and improve maintainability.

Separate Check Project Job into Check Workflow

This issue suggests separating the check-project job in the test workflow into a new check workflow. This suggestion is proposed to create a clear separation between testing and checking.

Add Include Guard in Sample Modules

This issue suggests adding an include_guard function at the beginning of all sample modules. This function is useful for preventing a module from being included twice, potentially fixing a bug caused by appending a variable multiple times (see this) and improving performance because a function is only defined once.

To utilize the include_guard function, one first needs to determine what is provided by the module. If the module only provides a function, it is recommended to use include_guard(GLOBAL) to prevent the redefinition of functions in all scopes. If the module also contains a variable, utilizing include_guard() is sufficient because the variable will need to be redefined in a different scope.

Check Warnings Globally

After upgrading the CheckWarning.cmake to version 2.0.0 in #86, it is recommended to replace the usage of the target_check_warning function with the add_check_warning function. This change allows setting warning flags on all targets in the directory collectively, instead of configuring them individually. This modification aims to simplify and shorten the content of the CMakeLists.txt file.

Add Option to Enable Test Targets

This issue suggests adding a MY_FIBONACCI_ENABLE_TESTS option to optionally enable or disable test targets in the sample project. Refer to threeal/cmake-starter#76 for more information and the rationale behind this suggestion.

Separate Workflow for Build and Test

This issue suggests to separate workflow for building and testing this project. This suggestion is proposed to align with other template in which there are separate workflows for build and testing as could be see in the Node.js Starter template.

Rename Project to "C++ Starter"

This issue suggests renaming the project to "C++ Starter" in order to align with the naming convention used for other template projects. This change in project name will provide consistency and make it easier for users to identify and understand the purpose of this template.