≡ C++ submodule manager

Poor man's submodule management, build scripts, and CI integration for simple, "conventional" C++ libraries, executable tests, and executable programs on top of

• CMake,
• git,
• Travis CI, and
• Codecov.

The idea is to minimize boilerplate by relying on simple conventions over excessive configuration.

See GitHub repositories with the #cppsm topic.

C++ submodule manager GitHub organization subprojects:

• C++ submodule manager documentation
• C++ submodule manager command-line interface
• C++ submodule manager boilerplate

• Install
• Synopsis
• Project structure
• CMake
  • conventional.cmake
    • add_conventional_executable(name)
    • add_conventional_executable_tests(...)
    • add_conventional_library(name)
• Travis
  • Configuration
    • CODECOV
    • XTRACE

Clone the cppsm-cli somewhere:

git clone https://github.com/cppsm/cppsm-cli.git

Add to your .bash_profile:

CPPSM="path to cppsm-cli directory"
export PATH="$CPPSM/bin:$PATH"
. "$CPPSM/bash_completion"

For code formatting you need to have both clang-format and prettier commands in path.

For the optional auto completion of git urls you must have both curl and jq commands in path.

Create a new project:

mkdir PROJECT && cd "$_"
git init
cppsm init

Try the hello world example (after init):

cppsm hello
cppsm test
.build*/internals/hello

Start hacking:

emacs internals/program/hello.cpp &
cppsm test-watch

Format project files inplace:

cppsm format

Clone an existing project:

cppsm clone URL BRANCH

Or clone an existing project using plain git:

git clone -b BRANCH URL/NAME.git
cd NAME
git submodule update --init     # NOTE: non-recursive

Add a required library:

cppsm add requires URL/NAME.git BRANCH

Remove a previously required library:

cppsm remove requires/NAME/BRANCH

Upgrade all required libraries:

cppsm upgrade

At the root of a project there are three directories as follows:

• The equipment directory may contain any number of project submodules that the project internally depends upon.
• The internals directory may contain one or more target directories that are internal to the project.
• The provides directory may contain one or more target directories that are provided for dependant projects.
• The requires directory may contain any number of project submodules that the provided targets depend upon.

In other words, both internals and provides may contain one or more target directories. In case only a single internal or provides target directory is needed, there is no need to create a nested directory.

A single target directory may simultaneously contain

• a library in the include/${name} and library directories,
• an executable test in the testing directory, and
• an executable program in the program directory.

Try the cppsm hello script. It generates a simple example project that has essentially the following structure:

CMakeLists.txt
equipment/
  testing.cpp/
    v1/
      provides/
        CMakeLists.txt
        include/
          testing_v1/
            test_synopsis.hpp
            test.hpp
        library/
          test.cpp
internals/
  CMakeLists.txt
  testing/
    message_test.cpp
  program/
    hello.cpp
provides/
  CMakeLists.txt
  include/
    message_v1/
      hello.hpp
  library/
    hello.cpp

Note that the include directories are versioned as are CMake target names and C++ namespace names. This allows multiple major versions of a library to be used simultaneously.

CMake boilerplate is provided for simple libraries, tests, and executables.

Adds an executable target. Assumes that the target directory has the following structure:

CMakeLists.txt
program/
  *.(cpp|hpp)

Add dependencies using target_link_libraries separately.

Adds an executable test target per .cpp file. Assumes that the target directory has the following structure:

CMakeLists.txt
testing/
  *.cpp

The arguments given to add_conventional_executable_tests are passed to target_link_libraries for each added test target.

Adds a library target. Assumes that the target directory has the following structure:

CMakeLists.txt
include/
  ${name}/
    *.hpp
library/
  *.(cpp|hpp)

Note that inside include there is a directory with the target ${name} (which should also include the major version) to differentiate between the header files of different targets (and their major versions).

Add dependencies using target_link_libraries separately.

A Travis CI configuration file is provided to build and test both Debug and Release builds on various OS and compiler configurations:

• Linux
  • GCC (8)
  • Clang (7)
• OS X
  • GCC (8)
  • Apple Clang (10)
• Windows
  • Visual Studio (2017)
  • MinGW GCC (8)

Just add your project to Travis CI.

By default the CI scripts do not generate and push code coverage results to Codecov. Set CODECOV=1 to enable code coverage.

By default the CI scripts do not set -x to enable Bash xtrace to avoid unnecessary verbosity. Set XTRACE=1 to enable Bash xtrace.