Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
334 lines (219 loc) · 7.71 KB

CONTRIBUTING.md

File metadata and controls

334 lines (219 loc) · 7.71 KB
Raw

Contributing

You want to contribute to this repo? Nice! And of course: you are the best! Here is a guide on how to work with it and what to expect.

Build status:

CircleCI

Contents

Required tools

cmake

CMake is an open-source, cross-platform family of tools designed to build, test and package software.

Install on macOS (if not already present):

brew install cmake

LLVM

The LLVM Project is a collection of modular and reusable compiler and toolchain technologies. Some tools from the LLVM toolchain are used.

To install LLVM on macOS run:

brew install llvm

Tools used from the toolset:

  • clang-tidy (linting)
  • clang-format (formatting)

To link these tools run (may need to be run as root, you can also pick a different location in your PATH):

ln -s "$(brew --prefix llvm)/bin/clang-format" "/usr/local/bin/clang-format"
ln -s "$(brew --prefix llvm)/bin/clang-tidy" "/usr/local/bin/clang-tidy"

Ninja

Ninja is a small build system with a focus on speed.

You can install Ninja on macOS via brew:

brew install ninja

Litr

This repo uses Litr itself for its tasks. So installing it will make things easier (though, it is optional). To install Litr:

brew tap krieselreihe/litr
brew install litr

Setup

Clone the project:

git clone git@github.com:krieselreihe/litr.git

Update

litr update

Build

For a quick overview of build options run litr build --help.

Debug

Build a debug build:

litr build

Run Litr with the following options if needed:

  • Enable detailed execution flow tracing including disassemble any parser statements litr build --trace
  • Disable any logging via litr build --nolog.
  • Set debug mode, even if build type differs (for debugging purposes) litr build --debug

Profiling

A debug build will always also produce profiling information. Running the executable directly will generate a litr-profile.json file that can be used with any Chromium based browser tracing tool, e.g. chrome://tracing. Just drag and drop the file into the tracing view. To generate the file run the local build directly:

./build/release/src/client/Client

Nevertheless, you can generate profiling data on other build targets as well, e.g. "release":

litr build --target=release --profile

Release

Build a release version:

litr build --target=release

For a release that can be published, and the release process in full, visit the wiki.

Tests

After building the application you can run unit tests for the build output with ctest.

# Run all tests for debugging build
litr test

# Run all tests for release build
litr test --target=release

Formatting code

Using clang-format you can run Litr to format all project files:

litr format

Usage without Litr

Click to expand

Update without Litr

git pull

Build without Litr

Debug without Litr

Build the configuration files with cmake:

cmake -GNinja -DCMAKE_BUILD_TYPE=Debug -B build/debug

Build the application:

cmake --build build/debug

Run cmake with the following options if needed:

  • Disassemble any parser statements for debugging using -DDISASSEMBLE=ON.
  • Disable any logging via -DDEACTIVATE_LOGGING=ON.
  • Enable detailed execution flow tracing -DTRACE=ON
  • Set debug mode, even if build type differs (for debugging purposes) -DDEBUG=ON

Release without Litr

Build the configuration files with cmake:

cmake -GNinja -DCMAKE_BUILD_TYPE=Release -B build/release

Build the application:

cmake --build build/release

Tests without Litr

After building the application you can run unit tests for the build output with ctest.

Note: With CMake 3.20 it will be possible to specify the --test-dir option for ctest [source], making test execution easier.

# Run all tests for debugging build
cd build/debug/src/tests && ctest && ../../../..

# Run all tests for release build
cd build/release/src/tests && ctest && ../../../..

Profiling without Litr

There is a profiling build you can generate running cmake with PROFILE=ON (build type is up to you, for real world results use "Release"):

# Create config files
cmake -GNinja -DPROFILE=ON -DCMAKE_BUILD_TYPE=Release -B build/profile

# Build profile runner
cmake --build build/profile

Running the profiler executable will generate a litr-profile.json file that can be used with any Chromium based browser tracing tool, e.g. chrome://tracing. Just drag and drop the file into the tracing view. To generate the file run:

./build/profile/src/client/Client

Different compiler

To create builds on a different compiler the variables CMAKE_C_COMPILER and CMAKE_CXX_COMPILER can be set, specifying the path to the compiler.

Example for clang on macOS, creating a debug build:

cmake -GNinja -DCMAKE_BUILD_TYPE=Debug -DCMAKE_C_COMPILER=/usr/bin/clang -DCMAKE_CXX_COMPILER=/usr/bin/clang++ -B build/debug
cmake --build build/debug

Example for gcc on macOS, creating a debug build:

cmake -GNinja -DCMAKE_BUILD_TYPE=Debug -DCMAKE_C_COMPILER=/usr/bin/gcc -DCMAKE_CXX_COMPILER=/usr/bin/g++ -B build/debug
cmake --build build/debug

Run

After building the application you can either run the local client:

# Debug
./build/debug/src/client/Client

# Release
./build/release/src/client/Client

Files and Directories

Here an overview of a few important files and folders when working with the code.

Client

What: Contains all client code to run the application inside the terminal.

Core

What: The core library code.

Debug

  • src/core/Core/Debug: Code for debugging the application

Error

  • src/core/Core/Error: Error handling related code
  • src/core/Core/Error/BaseError.hpp: Base error class

Config

  • src/core/Core/Config: All code related to loading and handling the configuration file
  • src/core/Core/Config/Loader.hpp: Configuration file loader
  • src/core/Core/Config/Command.hpp: Configuration command description
  • src/core/Core/Config/Parameter.hpp: Configuration parameter description

CLI

  • src/core/Core/CLI/Parser.hpp: Command line argument parser
  • src/core/Core/CLI/Interpreter.cpp: Execute parsed instructions
  • src/core/Core/CLI/Shell.hpp: Script runner

Script

  • src/core/Core/Script/Compiler.cpp: Compile CLI instructions to a valid executable script

Tests

What: All test code for unit and integration tests.

  • src/tests/Fixtures: Tests fixtures, e.g. test configuration files for integration tests
  • src/tests/Helpers: Test helper functions
  • src/tests/Tests: Test cases