Copyright © 2014, 2015, 2016 Lester Hedges
This repository provides a set of simple templates and helper files for
managing a small C++ project. A comprehensive
Makefile is used to build a
static library along with its demos, unit tests, and documentation. This may
be of use for anyone looking to build and deploy a codebase on a remote server
or high-performance computing cluster, those wanting to free themselves from
the shackles of an integrated development environment, or perhaps simply wishing
to better understand how to use GNU Make.
This project was largely inspired by Zed Shaw's Learn C The Hard Way.
src directory contains header files and source code for the (illustrative,
but essentially useless) Shapes library which can be compiled using the included
Makefile. To get detailed information regarding usage of the
Makefile and the
available targets simply run make on the command-line with no arguments, i.e.
If you would prefer to use CMake, e.g. if you aren't using make as your generator, simply copy the contents of the cmake directory into the root of the project folder then run cmake, i.e. (assuming that you are currently in the root directory)
cp -r cmake/* . cmake .
Be warned that if you use make as your cmake generator then the original
Makefile will be overwritten. To recover it simply run
git co Makefile
- help --> print help message
- build --> build library, demos, and tests (default=release)
- devel --> build using development compiler flags (debug)
- release --> build using release compiler flags (optimized)
- doc --> generate source code documentation with doxygen
- test --> run unit tests
- valgrind --> run unit tests via valgrind
- clean --> remove object and dependency files
- clobber --> remove all files generated by make
- install --> install library, demos, and documentation
- uninstall --> uninstall library, demos, and documentation
Source and object file auto-dependencies are handled using a recipe taken from here.
Taking inspiration from Learn C The Hard Way,
automated testing is handled by a modified version of the MinUnit framework.
MinUnit.h in the
src directory for details. Also included are Zed's
excellent debugging macros.
Debug.h for details.
Unit tests can be compiled and run directly by typing
make test on the
command-line. To run the test code via Valgrind
make valgrind instead.
Comprehensive source code documentation is handled via
To compile the documentation, simply run
In a rapidly evolving codebase it is helpful that the library knows the version of
the source code from which it was compiled. This allows any bugs to be traced to
a specific version of the code. As such, an abbreviated version of the git commit
hash is passed as a command-line
#define directive. When using the library the
user can access version information through the
The included demo codes show examples of how to print version control information.
By default make's rather verbose output is entirely suppressed using the
.SILENT target. (Simply comment out this line if you are trying to debug
a problem.) Instead, simple cmake-like information is provided using custom
echo commands with colorized output achieved via
Make sure that any external libraries are are accessible to your shell environment. The LIBS variable should be used for any linker flags, e.g. -lfftw3. Use the LDFLAGS environment variable for any non-standard paths. This can be set in your shell profile, on the command-line, or passed directly to make as an option. For example, if using MacPorts on OS X
- To set a different installation path run
make PREFIX=path install
- Additional CXXFLAGS can be passed using OPTFLAGS, e.g.
make OPTFLAGS=-Wall devel
- Targets can be chained together, e.g.
make release doc test
Two helper scripts are provided in order to help expedite the process of creating a new C++ project.
This script converts all of the necessary files in the repository ready
for the new library. To set things up for a project called
This assumes that the clone git repository is left untouched, i.e. all files
refer to the default
Alternatively, you can convert files from an
old project to a
new one as
./setup new old
Create a new C++ class template, i.e. default header and source files with constructor and destructor stubs. To create a new class, run
This will generate the files
ClassName.cpp in the current
working directory. Alternatively, running
./class_template ClassName path
will move the files to the directory specified by
Note that the template files use tabs. If you prefer to use spaces (as I do) then you can fix this afterwards in your editor, e.g. in Vim you can run
Although intended to be used on a Unix-like operating system, the simple build system works fine on Windows using MinGW. For modern, 64-bit Windows systems, we recommend using MYSYS2. This has been used to successfully build on Windows 7 and 10. After installing MYSYS2 (following the instructions on the website) you will need to install several additional packages:
pacman -S gcc git diffutils make