contracts

The contracts branch includes an implementation of assertion contracts as outlined by the working draft N4820, P1332R0, P1429R0, and P1290R1. Each proposal is implemented using the same underlying framework which maps roles and various modes onto a small set of concrete semantics. A description of an earlier implementation is available in P1680R0.

The four of the five concrete semantics defined in P1332 are implemented and usable as explicit semantics in source. These are:

• ignore
• assume
• check_never_continue
• check_maybe_continue

Flags

Required to enable contract support:
-fcontracts Enables draft c++ contracts features.

From the working draft:
-fcontract-build-level=<off|default|audit> Determines the highest level of contract for which runtime checks are emitted.
-fcontract-continuation-mode=<on|off> Determines whether execution resumes after a failed contract check (default off).

From P1290:
-fcontract-assumption-mode=<on|off> Determines whether a compile time assumption is emitted for axioms. If set to on (the default) the optimizer may assume the contract condition is true.

From P1429:
-fcontract-mode=<on|off> When set to off, treats all contracts as if they have the ignore semantic
-fcontract-semantic=<level>:<semantic> Treats the specified level as having the given concrete semantic.
Ex: -fcontract-semantic=default:check_maybe_continue

From P1332:
-fcontract-role=<id>:<semantics> Given a comma delimited set of semantics, create or update a role's semantic mapping.
Ex: -fcontract-role=custom:check_never_continue,check_never_continue,ignore

Other flags:
-fcontract-strict-declarations=[on|off] When turned on, issues warning diagnostics for generalized redeclaration of functions (default off).

Semantics using WD and P1290 flags

Semantics for each level are selected through a combination of modes. With the contract level shown as rows and the -fcontract-build-level shown as columns the defaults are:

	off	default	audit
default	ignore	check_never_continue	check_never_continue
audit	ignore	ignore	check_never_continue
axiom	assume	assume	assume

When -fcontract-continuation-mode=on is given, the check_never_continue above are replaced with check_maybe_continue.
When -fcontract-axiom-mode=off is given, the axiom row turns into ignore under all build levels.
When -fcontract-mode=off is given, each entry is turned into ignore.

Semantics using P1429 and P1332 flags

The default semantics using explicit assignment switches are:

• default: check_never_continue
• audit: ignore
• axiom: assume
  (this corresponds to the default semantics from the previous section)

Any individual level's semantic can be changed using -fcontract-semantic=<level>:<semantic>.
All three semantics can be changed at once using -fcontract-role=default:<semantics>.
All contract semantics (including ones explicitly defined in the source) can be changed to ignore by using the -fcontract-mode=off flag.

Violation Handler

A custom contract violation handler can be installed by defining void handle_contract_violation(const std::contract_violation &violation) (you must #include <contract> for this to work) or by using LD_PRELOAD. An example of defining the handler in the main TU can be found in the testsuite here. Examples of how to use LD_PRELOAD to install a custom violation handler are available in the contracts folder inside the testsuite.

General examples of valid and invalid usage can also be found in the contract*.C files in gcc/testsuite/g++.dg/cpp2a.