-+- Build Status -+-
master
-+-
Key Features • Project Documentation • Getting Started • Contributing • Credits •
This is a partial implementation of contract checking fir C++ inspired by the proposal for Contract Checking in C++: A (long-term) Road Map and the implementation of libcontract.
Additionally, optional helpers for unit testing contracts without the need for death tests are provided as a separate library.
Examples of usage include:
// The simplest contract
ASAP_EXPECT(x !=0);
// Expect
ASAP_EXPECT(x > 0, "should not be > 0 but I got " << x);
// Assert
ASAP_ASSERT(x > 0, "should not be > 0 but I got " << x);
// Assert that some code branch is unreachable, e.g. after a fully covered
// switch / case statement.
ASAP_ASSERT_UNREACHABLE("should never reach here")
// Assert with complex expression (note the true at the start to avoid starting
// the expression with parenthesis), assertion failure message and a return
// value in case of the assertion failure and the violation handler does not
// abort; also to keep the compiler happy with the return statement.
ASAP_ENSURE(true && ((0<x) || (x == -1)), "failed", Result::kFailed);
For a full documentation of what is available refer to the project docs.
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 contract checking module, its usage and APIs, are provided in the project GitHub Pages site here.
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-contract.gitmkdir _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.
# 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)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.
- 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- libcontract for inspiration
- 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