smart-build

Linux/UNIX shell script for building CMake projects and configuring vim linting/completion.

Table Of Contents

• Motivation
• Features
• Design
• Requirements
• Quick Start
• Sample Project Layout
• Sample Config File
• Full Usage / Options
• Examples
• Contributing

Motivation

A basic CMake project requires configuring C/C++ language type/standard, include directories, compile options and definitions, etc. Vim linting and completion plugins require similar configuration. smart-build is a shell script that performs these tasks using one simple .project_config file:

• Generates a custom CMakeLists.txt file, which pulls from .project_config.
• Runs CMake and makes and builds tests.
• Optionally generates a project-local .vimrc file, which pulls from .project_config to configure Vim.

Features

• Single portable smart-build.sh shell script.
• Builds and tests C/C++ projects with CMake with one basic command.
• Auto-configures Vim linting/completion plugin settings.
• Fast project setup via one small config file.
• Easy to use, well-documented config file settings.
• Extensive command options for building, testing, and varied usage.
• Unit-tested with shunit2 in multiple POSIX shells (bash, mksh, dash, zsh).

Design

Requirements

• Linux/UNIX
• A POSIX shell
• CMake version 3.0.2
• Optional: Vim linting plugin (currently runs with ale)
• Optional: Vim completion plugin (currently runs with completor)

Quick Start

1. Copy smart-build.sh into your project root directory.

   • See Sample Project Layout.

2. Generate .project_config, CMakeLists.txt, and .vimrc:

   $ ./smart-build -PLV

3. Configure settings in .project_config.

   • See Sample Config File.

4. As required : Modify CMakeLists.txt and .vimrc.

   • NOTE: smart-build will run normally without any CMakeLists.txt or .vimrc customizations.

5. Build project and run tests:

   $ ./smart-build -dt

6. Run Vim with auto-configured linting/completion plugin settings (Vim must be started from project root directory):

   $ vim .

Sample Project Layout

├─┬ my-project/
│ ├─┬ src/
│ │ ├─┬ somea/
│ │ │ ├── Hello.cpp
│ │ │ └── Hello.hpp
│ │ ├─┬ someb/
│ │ │ ├── Goodbye.cpp
│ │ │ └── Goodbye.hpp
│ │ └── main.cpp
│ ├─┬ tests/
│ │ ├─┬ unit_tests/
│ │ │ └── Goodbye_test.cpp
│ │ └── doctest_testharness.cpp
│ ├─┬ third_party/
│ │ └─┬ doctest/
│ │   └── doctest.h
│ ├── .project_config
│ ├── .vimrc
│ ├── smart-build.sh
│ └── CMakeLists.txt

Sample Config File

Contents of .project_config:

# cmake project title
my-project
# cmake min version required
3.0.2
# language type:"C" or "CPP"
CPP
# language standard
17
# defs and system-include standards: space-separated, "-" if empty
-DGNU_SOURCE -D_LARGEFILE64_SOURCE
# warning levels: space-separated, "-" if empty
-Wall -Wno-unused
# top-level src dirs: colon-separated
src:third_party
# src file with main-executable code: "-" if none, i.e. test only
src/main.cpp
# main executable file to build: "-" if none, i.e. test only
my-exec
# testing language type: "C" or "CPP" (N/A if building without -t/-T)
CPP
# testing language standard (N/A if building without -t/-T)
17
# testing top-level src dirs: colon-separated, "-" if none
tests
# test-driver executable to build (N/A if building without -t/-T)
my-test-driver
# EOF: FILE MUST END WITH THIS LAST LINE

Full Usage / Options

USAGE:

smart-build.sh -h

smart-build.sh -c|-C [-b <dir>] [-p <file>] [-e <file>]
                              [-x <file>] [-q]

smart-build.sh -d|-r|-w|-m [-c|-C] [-g|-l] [-t|-T]
                              [-b <dir>] [-p <file>] [-e <file>|-E] [-x <file>] [-q]

smart-build.sh -P [-L] [-V]

smart-build.sh -L [-P] [-V]

smart-build.sh -V [-P] [-L]

OPTIONS:

-h, --help
        print this help message

-d, --build-type-debug
        compile and link with debug symbols

-r, --build-type-release
        compile and link release

-w, --build-type-release-with-debug
        compile and link release with debug symbols

-m, --build-type-release-min-max
        compile and link release for min-size, max-speed

-c, --clean-all
        remove built program/testing executables and build dir

-C, --clean-executables
        remove built program/testing executables

-g, --use-gnu-compiler
        use GNU gcc/g++ compiler and linker

-l, --use-llvm-compiler
        use LLVM clang/clang++ compiler and linker

-t, --make-and-run-tests
        make and run tests

-T, --make-tests
        make tests

-b <dir>, --build-dir=<dir>
        specify build dir (default is "build")

-p <file>, --project-config-file=<file>
        specify project config file (default is ".project_config")

-e <file>, --executable-name=<file>
        specify program executable to build (override config file)

-E, --no-build-executable
        do not build program executable (override config file)

-x <file>, --test-driver-name=<file>
        specify test-driver executable to build (override config file)

-P, --generate-project-config
        generate template .project_config file

-L, --generate-cmakelists
        generate template CMakeLists.txt file

-V, --generate-vimrc
        generate template .vimrc file

-q, --quiet-mode
        quiet mode

EXIT CODES:

        0     ok

        1     usage, arguments, or options error

        2     build error

        3     test error

    255     unknown error

Examples

• Build with DEBUG, do not make tests:

  $ ./smart-build -d

• Build with RELEASE and make and run tests:

  $ ./smart-build -rt

• Build with RELEASE, make tests but do not run them:

  $ ./smart-build -rT

• Clean build directory and built executables:

  $ ./smart-build -c

• Clean build directory and built executables before building:

  $ ./smart-build -cd

• Build and force use of LLVM compiler (instead of system's default compiler):

  $ ./smart-build -dl

• Build in specified out-of-source CMake build directory (default is build):

  $ ./smart-build -d -b alt_build

• Build and specify name of main executable to build (overrides .project_config):

  $ ./smart-build -d -e my-alt-exec

• Build and run tests, do not build main executable (overrides .project_config):

  $ ./smart-build -dtE

Contributing

• Feel free to report a bug or propose a feature by opening an issue.
• Follow the project's Contributing guidelines.
• Respect the project's Code Of Conduct.