c-cpp-app - C/C++ App GitHub Template

1. ✏️ Setup
2. 👩‍🏫 Usage
3. 🧑‍🏫 Contributing
4. ⚖️ License
5. 🔄 Changelog
6. 🐛 Bugs and TODO
7. 🎨 Logo and Icons

Like this template ? We have other templates ready for you ⭐ !

• python-app - Python App GitHub Template
• c-cpp-app - C/C++ App GitHub Template

✏️ Setup

This repository is a template for a C/C++ app. It is meant to be used as a starting point for any app. As such, this document is not meant to be entirely read as is, but rather to be used as a base for your own documentation. Nevertheless, you can still find usefull information here since it is a great way to see how the template is used. You will still need to do some (minor) work when using this template - like changing the name of the app, the name of the author, etc. - but it should be fairly easy to do.

Please note we do not officially support Windows or MacOS. Windows users should use wls2 and MacOS users should use a virtual machine. We do not provide support for these platforms.

First, 🔗 generate a new repository from this template. Then, clone it and cd into it :

# Clones the repository
git clone <your-repository-url>
cd <your-repository-name>

Build your app (add release to build in release mode) :

# Builds the app
make

Finally, run the app in the background with nohup and tee :

# Runs the app in the background
nohup ./bin/main run 2>&1 | tee -a .log &

or in the foreground :

# Runs the app (lets you Ctrl+C to stop it)
./bin/main

The makefile contains a few other commands that you can use :

# Cleans the build directory and removes the binary
make clean

# Builds the doc (requires doxygen and graphviz)
make docs

# Formats the code (requires clang-format)
make format

# Run the app (requires valgrind for debug mode only)
# (you can edit the makefile to tweak predefined commands)
make run[-debug|-release ]

👩‍🏫 Usage

In this section, we generally present the app, put a nice screenshot of the GUI - if any, or the CLI, and explain how to use it. The src/main.cpp file is the entry point of the app. It already contains an example of a CLI app. You can use it as a starting point for your own app. For graphical interfaces, we recommend using Qt.

We also provide premade config files for linting, testing and formating purposes. Please make sure you have the required dependencies installed before running the commands below. Of course you can tweak these files to match your needs, but they should be good enough for most use cases.

# Testing (requires valgrind)
cd tests && make check_quiet

Last is our scripts folder which contains

• a bash script that acts as dos2unix for malicious Windows users
• a python file to automatically build the "changelog" section of this README

In the root directory, when needed, type :

bash scripts/crlf-lf.bash

python scripts/changelog.py

External dependencies are compiled from source (please see lib folder). Note that if not specified, all files are written by @ThomasByr.

Notable ones are :

• clipp.hpp, a single-file header-only library for command line parsing (by André Müller)
• ctpl.hpp, a C++11 header-only library for thread pools
• ini.hpp, a single-file header-only library for INI files
• json.hpp, a single-file header-only library for JSON (by Niels Lohmann)

🧑‍🏫 Contributing

If you ever want to contribute, either request the contributor status, or, more manually, fork the repo and make a pull request !

We are using clang-format to format the code, so make sure you have it installed and run :

make format

The standard procedure is :

fork -> git branch -> push -> pull request

Note that we won't accept any PR :

• that does not follow our Contributing Guidelines
• that is not sufficiently commented or isn't well formated
• without any proper test suite
• with a failing or incomplete test suite

Happy coding ! 🙂

⚖️ License

This repository is a template. Working source code is licensed under AGPL, the rest is unlicensed. If you whish not to use source code, please use the license of your choice. The following license only applies to the template itself and is not legal advice. The license of this repo does not apply to the resources used in it. Please check the license of each resource before using them.

This project is licensed under the AGPL-3.0 new or revised license. Please read the LICENSE file. Additionally :

• Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

• Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

• Neither the name of the c-cpp-app authors nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

c-cpp-app - C/C++ App GitHub Template
Copyright (C) 2023 Thomas BOUYER

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>.

🔄 Changelog

Please read the changelog file for the full history !

Title for major version (click here to expand)

v0.1 title for minor version

• list
• of
• changes

🐛 Bugs and TODO

TODO (first implementation version)

• TODO 1
• TODO 2

Known Bugs (latest fix)

• BUG 1 (fixed in v0.1)
• BUG 2

🎨 Logo and Icons

Unless otherwise stated, all icons and logos are made by the author. Copyright (C) 2023 Thomas BOUYER, all rights reserved.

Tools used :

• Microsoft Designer
• Clip Studio Paint
• Canva