Your neat C++ application template project
Project is designed to increase the speed of the application creation process at the project startup by providing templated application structure. So developer may just jump straight into implementing a particular application with no or minimum project start structure set up.
Helps you go beyond raw code — build a complete, ready-to-ship software product fast!
Enables rapid creation of a complete software product — not just raw code or a simple program.
Just fork it and implement application straight away!
The template project is not a framework in traditional means so infrastructure implementation items may be altered to fit needs or even erased in case of redundancy.
See more at the kytok.org.ua
đź’µ Donate at http://kytok.org.ua/page/pozertvy
Examine available branches to find your most applicable variant of the template or combine multiple branches by merging them to assemble the best suited template structure for your needs:
mainbranch at [GitHub, GitLab] (current) just the clearmainfunction and all available CMake integrations with no additional app infrastructure classes.appbranch at [GitHub, GitLab] with just general application related classes to generate a single binary executable.applibbranch at [GitHub, GitLab] for the application binary with additional separate library binary and header files (available for the installation) in order to provide library's code reusability across multiple applications.libbranch at [GitHub, GitLab] for the library with the headers include files (and documentation) without target binary.appQt6branch at [GitHub, GitLab] for the application general classes with additional defined structure for the Qt6 QML window application development.appGtkmm3branch at [GitHub, GitLab] for the application general classes with additional defined structure for the Gtkmm-3.0 with C++ window application development.appGtkmm3Gladebranch at [GitHub, GitLab] for the application general classes with additional defined structure for the C++ application development with Gtkmm-3.0 and Glade application with XML UI creation.appGtkmm4branch at [GitHub, GitLab] for the application general classes with additional defined structure for the Gtkmm-4 with C++ window application development.appFreeGlutbranch at [GitHub, GitLab] with just general application related classes to generate a single binary executable with a FreeGlut library for the OpenGL 3D development.appSDL2branch at [GitHub, GitLab] with just general application related classes to generate a single binary executable with a SDL2 library for the OpenGL 3D development and more!appMesonbranch at [GitHub, GitLab] with just general application related classes to generate a single binary executable with the Meson build system.appWt4branch at [GitHub, GitLab] the template infrastructure to fast start Web application developing based on the Wt C++ full stack framework.appPgSQLxxbranch at [GitHub, GitLab] the template infrastructure to fast start application development with the PostgreSQL DBMS usage.appBoostBeastbranch at [GitHub, GitLab] the template infrastructure for the Web application fast start development with the Boost Beast HTTP server.appMySQLCppConnbranch at [GitHub, GitLab] the template infrastructure to fast start application development with the MySQL DBMS usage.appSQLiteCpp3branch at [GitHub, GitLab] the template infrastructure to fast start application development with the SQLite DBMS and SQLiteCpp C++ bind usage.appMongoDBCpp4branch at [GitHub, GitLab] the template infrastructure to fast start application development with the MongoDB NoSQL DBMS usage.appLog4Cpp5branch at [GitHub, GitLab] the template infrastructure to fast start the application development with the log4cpp extended logging library.appBoostLogbranch at [GitHub, GitLab] the template infrastructure to fast start the application development with the Boost.Log extended logging library.appCURLbranch at [GitHub, GitLab] the template infrastructure to fast start the application development with the CURL multi protocol client library (including the HTTP) to download data from the network.
Alter current README.md and a CHANGELOG.md files to match your implementation introduced into the destination new project. Examine the doc directory for possible translations of a current md document:
uk_UAat doc/README.uk_UA.md
In order to fast-start implementing a new application clone this project into your local directory by executing next command in the terminal (GNU/Linux based):
git clone https://github.com/yuriysydor1991/cpp-app-template.git
or
git clone https://gitlab.com/yuriysydor1991/cpp-app-template.git
After this command executes you should find a directory named cpp-app-template inside your current one. So enter it by calling cd cpp-app-template.
In order to copy all the template project into your new clean repository (clean repository with no README.md, .gitignore, LICENCE or any other files) clone the current cpp-app-template project into your local directory and perform origin replacement command from inside the project root directory:
# REPLACE next URL with yours
git remote set-url origin https://github.com/yuriysydor1991/cpp-app-template.git
Replace the https://github.com/yuriysydor1991/cpp-app-template.git URL with one of your newly created project repository URL.
To verify successful repository remote URL (where all the changes will be pushed) replacement execute next command:
git remote -v
Which should show your new project repository.
Finally push your repository to a new location by executing next command:
git push
Forking may be performed in git Web interface panel.
This section contains list of required packages and/or tools that must be present in the system in order to build templated project.
In order to build minimum template project install the GCC C++ compiler with CMake and Git.
sudo apt install -y git g++ cmake
In order to build project binaries download the install tool for the developer tools from the MSVC download page https://visualstudio.microsoft.com/downloads/ and search and enable for the Native C++ application development section.
Separately each project may be downloaded and installed from different sources (may require additional tools download and install):
- The Git versioning system at https://git-scm.com/downloads/win
- The CMake build system at https://cmake.org/download/
- The Windows 10 SDK at https://developer.microsoft.com/en-us/windows/downloads/windows-sdk/
If necessary to build and execute available tests install GTest or ensure available Internet access in order to project make it available by itself (GNU/Linux based):
sudo apt install -y googletest
Examine the Project tests for more info.
If necessary to generate the Doxygen documentation from the sources comments install doc generation system also (GNU/Linux based):
sudo apt install -y doxygen graphviz
Examine the Documentation build section on how to enable documentation enable/build/install.
To auto format code using available clang-format target the clang-format code formatter must be installed (GNU/Linux based):
sudo apt install -y clang-format
Examine configuring details in the Enabling and performing code formatting target subsection.
In order to perform a static code analysis with the cppcheck command install it with next command (GNU/linux based):
sudo apt install -y cppcheck
In order to perform a static code analysis with the clang-tidy command install it with next command (GNU/linux based):
sudo apt install -y clang-tidy
Examine the Enabling the static code analyzer with clang-tidy section on how to enable the cppcheck target.
In order to enable the dynamic application check with the valgrind command install it with the command:
sudo apt install -y valgrind
For more details on how to enable and run the memory check target examine the Enabling the dynamic memory check target with valgrind section.
In order to generate the project flatpak package install the flatpak-builder command:
sudo apt install -y flatpak flatpak-builder
You'll also need the one of it's target SDK which may be installed by a command that may look like this:
flatpak install runtime/org.freedesktop.Sdk/x86_64/20.08
Replace the runtime/org.freedesktop.Sdk/x86_64/20.08 with your preferred SDK. Consult the flatpak documentation on how to list all available options.
Look for the details at the Enabling the flatpak package generation support.
In order to be able to start the Docker containers with the built template application install it with the next command:
sudo apt install -y docker.io docker-buildx
Next, configure the docker service to start to listen the local machine loopback TCP interface with it's configuration file edit with command:
sudo systemctl edit docker
Insert the next lines into the end of the configure file for opened docker service:
[Service]
ExecStart=
ExecStart=/usr/bin/dockerd -H fd:// -H tcp://127.0.0.1:2375
ExecReload=/bin/kill -s HUP $MAINPID
Save and close the configuration file. Now reload the systemctl and the Docker by itself:
sudo systemctl daemon-reload
sudo systemctl restart docker.service
To check if Docker works execute next command to run the simple hello-world container locally:
DOCKER_HOST="tcp://127.0.0.1:2375" docker run hello-world
You may add the export DOCKER_HOST="tcp://127.0.0.1:2375" to your .bashrc file to avoid the DOCKER_HOST environment variable inclusion into every docker command run by executing the command:
echo 'export DOCKER_HOST="tcp://127.0.0.1:2375"' >> ~/.bashrc
Details at the section Enabling the Docker container build and run
To proceed the application implementation right away look for the main.cpp file which is designed to accept initial code of the application. Specifically, new code may be placed into the int main(int argc, char** argv) free function.
But do not forget about the SOLID principles and code decomposing!
It's preferable to create other directories which would contain implemented components of the application and include them into the main.cpp file implementation, rather than put all the code inside the main function itself.
Change the name of the project in the project's root CMakeLists.txt file by introducing a new value for the the PROJECT_NAME and/or PROJECT_BINARY_NAME variable which is located at cmake/template-project-misc-variables-declare.cmake. It is recommended to do so the executable will represent your new application name instead of templated default one - the CppAppTemplate.
The project's CMakeLists.txt files are tracking of a current project git repository commit, project name, configure date and projects version that are forwarded into the projects's configure header file located at src/app/project-global-decls.h.in. The project-global-decls.h.in will be compiled into the build directory as project-global-decls.h. The ApplicationVersionPrinter class includes this project's configure file and uses the information provided to print appropriate version info. Usually, this code is executed by calling generated executable with a -v or --version command line flag. After the version is printed, the default implementation cause the application's ApplicationVersionPrinter instance to return zero value and cause the executable to stop it's execution.
Project already contains some simple test samples. Based on them you may implement full test of the introduced code.
See the Project build subsection to enable unit testing with CMake.
Currently test samples are based on the GTest framework. GTest framework by itself becomes available by the FetchContent_Declare/FetchContent_MakeAvailable CMake-commands if no system GTest is available.
Of course, the project's CMakeLists.txt files are probing the GTest only if tests are enabled by ENABLE_UNIT_TESTS CMake variable. System GTest probe may be turned OFF by setting appropriate value to the GTEST_TRY_SYSTEM_PROBE CMake variable.
Look for a cmake/template-project-GTest-enabler.cmake to see details or change GTest version etc.
There will be introduced some other standard project features in the future.
Of course if your IDE supports CMake build system integration you may just press the Build and/or Run button somewhere in the IDE window with opened project and it's done! No need to perform a search and execute commands.
The project uses the CMake build system so a build command should be familiar to the most of the C++ developers around the world!
Of course, project needs to be git clone-ed and it's root directory must be opened in the terminal or in your IDE first. After that you may execute next commands:
# from the project root
cmake -B build -S . && cmake --build build
Which effectively will create a directory named build (it's already added to the .gitignore list), configure project using the CMake available in the system (see the Requirements section of this README.md file) and finally builds all the targets available in the project.
To enable project unit test availability (for building and running) reconfigure it with enabled ENABLE_UNIT_TESTS variable as follows (GNU/Linux based):
# from the project root
cmake -B build -S . -DENABLE_UNIT_TESTS=ON && cmake --build build
To disable the system available GTest framework assets usage set appropriate value to the GTEST_TRY_SYSTEM_PROBE CMake variable by executing command like (GNU/Linux based):
cmake -B build -S . -DENABLE_UNIT_TESTS=ON -DGTEST_TRY_SYSTEM_PROBE=OFF && cmake --build build
During command execution project build system will try to make GTest available through the Internet only for current project with specified version in the cmake/template-project-GTest-enabler.cmake file.
Currently it's possible to auto-generate the project documentation by the Doxygen tool from the available sources comments.
To enable Doxygen documentation CMake-target during the project configure process call a command that sets the ENABLE_DOC_DOXYGEN CMake variable to the ON value (GNU/Linux based):
# inside the project root directory
cmake -B build -S . -DENABLE_DOC_DOXYGEN=ON
Which effectively will create a directory named build inside the project root directory, enters it by a cd command and configures project to enable Doxygen documentation build.
Finally build the documentation by executing the command:
# inside the project root directory
cmake --build build --target Doxygen-doc
Which in turn will generate the doc/CppAppTemplate-html directory (already added to the .gitignore file) which will contain the HTML-type documentation. In order to open and examine generated documentation open the doc/CppAppTemplate-html/index.html file. The CppAppTemplate-html directory name will change if changed default executable name for the project by setting a new value for the PROJECT_BINARY_NAME variable in the root CMakeLists.txt or the DOXYGEN_OUT_HTML_NAME which in turn set the whole name for the directory.
The doc/Doxyfile.in file contains all available Doxygen configuration parameters which may be changed in order to change the documentation output.
It's possible to enable support for the document installation by setting up the ENABLE_DOC_DOXYGEN and DOXYGEN_DO_INSTALL variables to ON value during the project configure stage.
# inside the project root directory
cmake -B build -S . -DENABLE_DOC_DOXYGEN=ON -DDOXYGEN_DO_INSTALL=ON
The DOXYGEN_OUT_HTML_NAME CMake variable will configure the documentation html directory name (passed into the Doxyfile).
In order to make clang-format target available set the ENABLE_CLANGFORMAT variable value to ON during the project configuration stage (GNU/Linux based):
# inside the project root directory
cmake -B build -S . -DENABLE_CLANGFORMAT=ON
To perform the whole project code format in accordance with available misc/.clang-format code formatter configuration execute next building command:
# inside the project root directory
cmake --build build --target clang-format
The clang-format target details may be examined and/or altered in the cmake/template-project-clang-format-target.cmake CMake submodule file.
In order to make the cppcheck target available for the execution, configure project with enabled ENABLE_CPPCHECK variable:
# inside the project root directory
cmake -B build -S . -DENABLE_CPPCHECK=ON
And to perform the actual static code analysis by itself run the cppcheck target for the build:
# inside the project root directory
cmake --build build --target cppcheck
The cppcheck target details may be examined and/or altered in the cmake/template-project-cppcheck-target.cmake CMake submodule file.
In order to enable the static code check for the each translation unit or each *.cpp file in the project with a clang-tidy application enable it during the project configuration stage by setting the ENABLE_CLANG_TIDY variable value to ON in the configuration command:
# inside the project root directory
cmake -B build -S . -DENABLE_CLANG_TIDY=ON
And to perform the actual static code analysis by itself build any target of interest and the clang-tidy command will perform check on each of the compilation target:
# inside the project root directory
cmake --build build --target all
For more information about the clang-tidy examine the cmake/template-project-clang-tidy-target.cmake, misc/.clang-tidy files
and the clang-tidy application documentation of a used version.
Warning! The clang-tidy static code analysis may dramatically increase the code compilation time.
In order to make the valgrind target available for the execution, configure project with the enabled ENABLE_VALGRIND variable like:
# inside the project root directory
cmake -B build -S . -DENABLE_VALGRIND=ON
To perform the dynamic memory check on the application build run next command:
# inside the project root directory
cmake --build build --target valgrind
The valgrind target details may be examined and/or altered in the cmake/template-project-valgrind-target.cmake CMake submodule file.
Warning! It will start application. The dynamic memory check requires application to be started and go through the full cycle. Ensure that application execution will have a finite time.
In order to be able to generate the deb package file configure project to support the cpack command feature with a ENABLE_DEB variable enabled:
# inside the project root directory
cmake -B build -S . -DENABLE_DEB=ON
Next, build all available targets required for the deb package
# inside the project root directory
cmake --build build --target all
Finally, execute the cpack command inside the template project build directory:
# inside the project build directory
cpack
The package file should be generated inside the project build root directory. For example, if project name was't change and it's version is 0.8.0 so the package name may look like CppAppTemplate-0.8.0-Linux.deb.
In order to examine details of the deb package configuration visit the cmake/template-project-deb-enabler.cmake file.
In order to enable the flatpak generation of the redistribution package on the template project configure it with enabled option ENABLE_FLATPAK (GNU/Linux and alike):
# inside the project root directory
cmake -B build -S . -DENABLE_FLATPAK=ON
Which in order will enable the flatpak target.
And finally to generate the flatpak package run the flatpak target for the build:
# inside the project root directory
cmake --build build --target flatpak
In case of the success target build, there will be created the flatpak file under the root build directory named, for example, the CppAppTemplate-0.9.0.flatpak. In order to examine and/or change the flatpak generation target parameters visit the cmake/template-project-flatpak-target.cmake or misc/flatpak.conf.json.in files.
Refer to the flatpak documentation on how to install and run applications distributed from a flatpaks files. For the current template project's defaults the install and run command may look like this:
# to install (version may change)
# inside the project build directory
flatpak install --user CppAppTemplate-0.9.0.flatpak
# to run the application
flatpak run ua.org.kytok.template.CppAppTemplate
To be able to build and run the Docker container with current template project' target binary file enable it's CMake target with setting the ENABLE_DOCKER variable into value ON by using the next command:
# inside the project root directory
cmake -S . -B build -DENABLE_DOCKER=ON
After that there should be available the Docker build and run CMake target docker-single-run which may be triggered with the command:
# inside the project root directory
cmake --build build --target docker-single-run
Examine the cmake/dockerers/template-project-docker-single-runner-target.cmake file for the docker-single-run target details.
In order to enable the sanitizers to check application at the runtime, configure project with the command:
cmake -S . -B build -DENABLE_SANITIZERS=ON
For a general purpose sanitizers. See the cmake/template-project-sanitizers.cmake to examine available list of the sanitizers.
Alternatively, enable the threads sanitizers with the command:
cmake -S . -B build -DENABLE_SANITIZERS_THREADS=ON
to check the possible data rises of the newly introduced multithreaded application code.
Do not combine the ENABLE_SANITIZERS and ENABLE_SANITIZERS_THREADS.
Any findings will be printed into the application' stdout/stderr after the build and run.
In order to enable libcurl for the project by using the installed system one or by fetching it by the available connection set an ON value to the ENABLE_LIBCURL CMake variable.
# Inside the source root directory
cmake -S . -B build -DENABLE_LIBCURL=ON
In order to perform the application profiler analysis with help of the gprof application enable it's support by setting the ON value for the ENABLE_GPROF CMake variable:
# Inside the source root directory
cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug -DENABLE_GPROF=ON
After configuring project with support for the gprof profiling facility build the gprof-analyse target:
# Inside the source root directory
cmake --build build --target gprof-analyze
Which will execute application and starts the gprof profiling analyze tool for gmon.out generated file under the project's build directory (for example build/gmon.out). The resulting analysis may be examined by gprof-analyze.txt under the project's build directory.
Profiling with the gprof may be enabled only with Debug build mode.
In order to perform the application profiler analysis with help of the valgrind application enable it's support by setting the ON value for the ENABLE_CALLGRIND CMake variable:
# Inside the source root directory
cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug -DENABLE_CALLGRIND=ON
After configuring project with support for the valgrind profiling facility build the callgrind target:
# Inside the source root directory
cmake --build build --target callgrind
After the application run the Valgrind's callgrind module will generate the profiler analysis files called callgrind.out.* under the project's build directory. The build/callgrind.out.* files may be examined with help of the UI application called kcachegrind:
# Inside the source root directory
kcachegrind build/callgrind.out.*
In order to enable the Jenkins pipeline execution inside the Docker container build and start the appropriate container with image by building the jenkins-pipeline-docker-run target:
# Inside the source root directory
# Configuring the project to support Docker with Jenkins targets
cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug -DENABLE_DOCKER=ON -DENABLE_JENKINS_DOCKER_PIPELINE=ON
# Building and starting Jenkins' pipeline Docker container
# or restarting it
cmake --build build --target jenkins-pipeline-docker-run
Locate and save the new generated password for the Jenkins Web GUI in the log output that may look like next:
# ...
*************************************************************
*************************************************************
*************************************************************
Jenkins initial setup is required. An admin user has been created and a password generated.
Please use the following password to proceed to installation:
aefdc6a4a2214c298c821236c739165c
This may also be found at: /var/jenkins_home/secrets/initialAdminPassword
*************************************************************
*************************************************************
*************************************************************
# ...
Go to http://127.0.0.1:8080 (port may change) address with the help of prefered Web browser. Process to finilize the installation of the Jenkins system with the help of it's GUI.
After successfull installation and configuration of the Jenkins create appropriate pipeline for the project inside the Jenkins Web GUI panel.
All the Jenkins pipeline CMake build scripts are located at cmake/dockerers/template-project-docker-Jenkins-pipeline-runner-target.cmake file. The pipeline script located at misc/Jenkinsfile which should be specified in the pipeline source script at the Jenkins Web GUI pipelines configuration page. The Jenkins Web GUI Docker container port may be changed by specifying a new value for the JENKINS_PIPELINES_PANEL_HTTP_PORT CMake variable.
The cmake/dockerers/template-project-docker-Jenkins-pipeline-runner-target.cmake CMake script for the template project Jenkins pipeline Docker container builder by default will restart previously built contianer if target build launched repeatedly.
Of course, if your IDE supports CMake build system integration you may just press the Build and/or Run button somewhere in the IDE window with opened project and it's done! No need to perform a search and execute commands.
To find executable in the project build directory execute the find command:
find . -name 'CppAppTemplate'
The CppAppTemplate is a default executable name. Replace it with your custom one if you change the name of the project in the root CMakeLists.txt file (the PROJECT_NAME and/or PROJECT_BINARY_NAME variable).
If executable compiles and is present in the build directory start it in the terminal with path found from a previous subsection by a command:
# from the build dir
./src/CppAppTemplate
Once again, the CppAppTemplate is the default name of the project. Replace it with our own custom one if it was changed in the project's root CMakeLists.txt file (the PROJECT_NAME and/or PROJECT_BINARY_NAME variable).
If enabled by the developer through the ENABLE_UNIT_TESTS variable and successfully build, the one may run all available test by the ctest command from a project build directory (GNU/Linux based):
# run from the project build directory
ctest
Alternatively, run the ctest command from any location by specifying the test dir (GNU/Linux based):
ctest --tests-dir /path/to/the/project/build/directory
Execute available install commands from the project's build directory.
In order to install generated executable (as shown previous) file into your's system binary default folder execute next command in the command line (GNU/Linux based):
# installs generated binary under the /usr/local/bin/ for example
# run from the project's build directory
sudo cmake --install .
Usually it's the /usr/local/bin/ directory (on the Unix-like OS) which may be inaccessible from the PATH environment variable (e.g. can not be started as a regular command).
To install binary into the system globally available directory add the --prefix parameter to the command above as next:
# replace the /usr path with our own if needed
# run from the project's build directory
sudo cmake --install . --prefix "/usr"
Examine the PATH environment variable to chose directory best suited for your current OS (execute echo $PATH in the terminal). Alternatively, any path may be specified.
If project was configured to support the documentation install by the command which looks like next:
# inside the project build directory
cmake ../ -DENABLE_DOC_DOXYGEN=ON -DDOXYGEN_DO_INSTALL=ON
The installation command (for example, described in the Default installation section) will install the generated HTML documentation files into appropriate directories.