Skip to content
Manage simple C++ projects with ease.
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
cmake
demos
dox
src
tests
.gitignore
.travis.yml
COPYING
Makefile
README.md
class_template
setup

README.md

CXX-Template

Copyright © 2014, 2015, 2016 Lester Hedges

Build Status

About

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.

Usage

The 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.

make

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

Targets

  • 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

Features

Auto-dependencies

Source and object file auto-dependencies are handled using a recipe taken from here.

Unit testing

Taking inspiration from Learn C The Hard Way, automated testing is handled by a modified version of the MinUnit framework. See MinUnit.h in the src directory for details. Also included are Zed's excellent debugging macros. See 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 simply use make valgrind instead.

Documentation

Comprehensive source code documentation is handled via Doxygen. To compile the documentation, simply run make doc.

Version control

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 COMMIT and BRANCH constants. The included demo codes show examples of how to print version control information.

Clean ouput

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 tput.

Dependencies

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

export LDFLAGS='-L/opt/local/lib'

Tips

  • 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

Helper scripts

Two helper scripts are provided in order to help expedite the process of creating a new C++ project.

setup

This script converts all of the necessary files in the repository ready for the new library. To set things up for a project called new, run

./setup new

This assumes that the clone git repository is left untouched, i.e. all files refer to the default shapes project.

Alternatively, you can convert files from an old project to a new one as follows

./setup new old

class_template

Create a new C++ class template, i.e. default header and source files with constructor and destructor stubs. To create a new class, run

./class_template ClassName

This will generate the files ClassName.h and ClassName.cpp in the current working directory. Alternatively, running

./class_template ClassName path

will move the files to the directory specified by path.

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

:retab

Windows users

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
You can’t perform that action at this time.