Skip to content

Latest commit

 

History

History
165 lines (127 loc) · 7.46 KB

README.md

File metadata and controls

165 lines (127 loc) · 7.46 KB

C++ template-based finite state machines

-+- Build Status -+-

develop

Build status - develop

master

Build status - master

-+-

Latest release Commits Linux Windows Mac OS License CII Best Practices

Key FeaturesProject DocumentationGetting StartedContributingCredits

Key Features

This is a C++ template-based implementation of state machines. The FSM has a set of possible states and a set of rules that govern transitions between the current state and some other state upon receiving an event.

A state can be an arbitrary object, which type is used to distinguish it from other states. Therefore, there is no need to maintain a list of known states (in an enumeration for example). We also don't want to enforce any relationship between those types to keep them completely independent. The state machine is a variadic template that gets to know its states through the parameter pack and stores them in a tuple.

Transitions from the current state to other states are triggered by events. This requires that all the state types have a Handle method that accepts an event of the type of event being handled. To avoid creating unnecessary dependencies between the state types and the state machine type, a state's Handle method will return an object of a specific type (an action) that will describe what action should the machine take.

Events are produced outside the state machine and fed into it by an external event loop which calls the state machine's Handle method. The latter dispatches the event to the current state, which returns a specific action that gets executed to eventually transition to a new state.

Project Documentation

We have detailed guides for setting up an efficient development environment, the development process, project structure, etc. Take a look at the available guides here.

In addition to that, specific documentation for the API, its usage and APIs, is provided in the project GitHub Pages site here.

Getting Started

It is strongly recommended that you take some time to browse the project documentation to familiarize yourself with its structure and development workflows.

Make sure you have a C++ compiler with C++-17 capabilities at least. Gnu, Clang and MSVC all can do that with a recent version.

git clone --recurse-submodules -j4 https://github.com/asap-projects/asap-fsm.git
mkdir _build && cd _build && cmake .. && cmake --build .

or just use one of the predefined CMake presets. Detailed instructions are in the project documentation, and many useful commands are listed here.

CMake configurable build options

# Project options
option(BUILD_SHARED_LIBS        "Build shared instead of static libraries."              ON)
option(ASAP_BUILD_TESTS         "Build tests."                                           OFF)
option(ASAP_BUILD_EXAMPLES      "Build examples."                                        OFF)
option(ASAP_WITH_GOOGLE_ASAN    "Instrument code with address sanitizer"                 OFF)
option(ASAP_WITH_GOOGLE_UBSAN   "Instrument code with undefined behavior sanitizer"      OFF)
option(ASAP_WITH_GOOGLE_TSAN    "Instrument code with thread sanitizer"                  OFF)
option(ASAP_WITH_VALGRIND       "Builds targets with valgrind profilers added"           OFF)

Contributing

If you would like to contribute code you can do so through GitHub by forking the repository and sending a pull request. When submitting code, please make every effort to follow existing conventions and style in order to keep the code as readable as possible.

By contributing your code, you agree to license your contribution under the terms of the BSD-3-Clause or a more permissive license. All files are released with the BSD-3-Clause license.

Read the developer guides.

Submitting a PR

  • For every PR there should be an accompanying issue which the PR solves
  • The PR itself should only contain code which is the solution for the given issue
  • If you are a first time contributor check if there is a suitable issue for you

Getting updates from upstream asap

In order to pull and merge updates from the upstream project, make sure to add it to the repo's remotes and disable pulling/merging tags from the upstream. We want tags to be limited to those made in this repo, not in the upstream.

git remote add upstream https://github.com/abdes/asap.git
git config remote.upstream.tagopt --no-tags

Credits

  • The multitude of other open-source projects used to implement this project or to get inspiration - credits in the source code or the documentation as appropriate