Skip to content

Latest commit

 

History

History
282 lines (200 loc) · 7.65 KB

GettingStarted.md

File metadata and controls

282 lines (200 loc) · 7.65 KB

Stars: Getting Started

This is a small C++ template program showing a project build using CMake as build generator with integrated Conan package manager consuming (using and linking) with SQLite and spdlog libraries. For UNIX-like systems this project uses GNU Make build tool, but it can build with other tools like Ninja. Actually there is no restriction for using Ninja even on Windows systems.

How to try it out

These instructions will get you a copy of the Stars project up and running on your local machine for development and testing purposes.

Prerequisites

To build and run Stars you'll need the following requirements:

For project dependencies list see conanfile.txt bundled with this project.

Optional prerequisites are:

  • Static analysis tool for C/C++ code: Cppcheck >= 1.89
  • Static analysis tool for C/C++ code: Cpplint >= 1.5
  • C, C++ formatting tool: clang-format >= 10.0

If you're using Ubuntu, you can install the required packages this way:

$ sudo apt install gcc cmake build-essential sqlite3

On macOS you most likely have a compiler and SQLite so you'll need only CMake:

$ brew install cmake

To use Ninja CMake's generator you will need to install Ninja:

# Arch Linux
$ sudo pacman -S ninja

# Fedora
$ sudo dnf install ninja-build

# Debian/Ubuntu
$ sudo apt install ninja-build

# Gentoo
$ sudo emerge dev-util/ninja

# macOS
$ brew install ninja

# Windows
$ choco install ninja

Please note that specific versions of libraries and programs at the time of reading this guide may vary. The following dependencies is recommended install using pip:

  • conan
  • cpplint

They can be installed using pip as follows:

$ pip install -r requirements.txt

Configure flags

To enable any feature use CMake flags at configure time. To enable FEATURE use -DFEATURE=ON and to disable FEATURE use -DFEATURE=OFF. Custom CMake flags are:

Flag Description
CPPCHECK Perform cppcheck during compilation.
CMAKE_EXPORT_COMPILE_COMMANDS Enable output of compile commands during generation.
WARNINGS_AS_ERRORS Turn all build warnings into errors.
WITH_TESTS Enable testing support.

To use cppcheck you will need to install it as follows:

# Arch Linux
$ sudo pacman -S cppcheck

# Fedora
$ sudo dnf install cppcheck

# Ubuntu
$ sudo snap install cppcheck

# Debian
$ sudo apt install cppcheck

# Gentoo
$ sudo emerge dev-util/cppcheck

# macOS
$ brew install cppcheck

# Windows
$ choco install cppcheck

Build

You may want to install optional dependencies to perform additional code style checks. To install them use pip from the project directory as follows:

$ pip install -r requirements.txt

Note: To be able automatic reformatting C/C++ code you'll need to install clang-format. The clang-format tool itself has already been included in the repositories of popular Linux distributions for a long time. Search for clang-format in your repositories. Otherwise, you can either download pre-built LLVM/clang binaries or build the source code from https://releases.llvm.org/download.html.

Next, initialize project with conan - this is using the conanfile.txt specifying that SQLite is an dependency and that conan should integrate with CMake:

$ conan install . -if=build --build=missing

This example establishes out-of-source build/ folder, so that source folder is not polluted. For a detailed instruction on how to use and customize conan please refer here.

In fact, the default behavior when doing conan install is to try to download a binary, and fail if otherwise. If --build=xxxx argument is provided, then it will build it from sources instead of downloading the binary. You can use --build option w/o argument to force conan build packages from source and don't use binary ones:

$ conan install . -if=build --build

Next, generate the build files using CMake:

$ cmake -H. -Bbuild -DCMAKE_BUILD_TYPE=Release

To use Ninja CMake's generator, simply use CMake's -G command-line option:

$ cmake -H. -Bbuild -GNinja -DCMAKE_BUILD_TYPE=Release

You can specify the build type by using CMAKE_BUILD_TYPE. Supported build types are Debug, Release, RelWithDebInfo and MinSizeRel:

$ cmake   \
  -H.     \
  -Bbuild \
  -DCMAKE_BUILD_TYPE=Debug

Finally build project:

$ cmake --build build

Running the tests

To build with testing support, you have to configure project with special flags:

$ cmake             \
    -H.             \
    -Bbuild         \
    -DWITH_TESTS=ON \
    -DCMAKE_BUILD_TYPE=Debug

$ cmake --build build

Run tests from the project root as follows:

$ cmake --build build --target check

Install

To install program simple use install target:

$ cmake --build build --target install

To be able install program in non standard location you'll need to change the installation prefix. Use -DCMAKE_INSTALL_PREFIX=/new/location to change the prefix, e.g.:

# Configure
$ cmake -DCMAKE_INSTALL_PREFIX=~/.local build

# Build program
$ cmake --build build

# Install. Thi will use custom prefix now
$ cmake --build build --target install

Run

If everything went successfully, you can run the built executable:

$ /usr/local/bin/stars

Expected output will something like:

Chuck Norris can kill two stones with one bird.

If you used a custom prefix, you'll need to use appropriate path:

$ cmake -DCMAKE_INSTALL_PREFIX=~/.local build
$ cmake --build build
$ cmake --build build --target install
$ ~/.local/bin/stars

Further Reading

License

This project is open source software licensed under the Apache License 2.0. See the LICENSE file for more information.