# lib_xassert: Assertions library£££doc/rst/lib_xassert.html#lib-xassert-assertions-library

## lib_xassert: Assertions library$$$Introduction£££doc/rst/lib_xassert.html#introduction

This library provides a lightweight and flexible replacement for the standard C header `assert.h`.

The assertions in this library can be be enabled/disabled and configured as to how much information they show. This configuration can be per xassert unit (i.e. for sets of files).

`lib_xassert` is intended to be used with the XCommon CMake , the XMOS application build and dependency management system.

## lib_xassert: Assertions library$$$API£££doc/rst/lib_xassert.html#api

To use this module, include `lib_xassert` in the application’s `APP_DEPENDENT_MODULES` list and include the `xassert.h` header file.

### lib_xassert: Assertions library$$$API$$$Assertions£££doc/rst/lib_xassert.html#assertions

An assertion can be inserted into code with the `assert` macro e.g.:

    assert(i < n);

Optionally a debug message can be added with the `msg` macro:

    assert(i < n && msg("i must be less than the array bound"));

If assertions are enabled and the expression in the assertion is false than a trap will occur.

### lib_xassert: Assertions library$$$API$$$Unreachable£££doc/rst/lib_xassert.html#unreachable

If the logic of a program dictates that certain code cannot be reached, the `unreachable` macro can be used e.g.:

    switch (message) {
    case 0:
       ...
    case 1:
       ...
    default:
      unreachable("message must be 0 or 1");
      break;
    }

If assertions are enabled then this macro will cause a trap if executed.

### lib_xassert: Assertions library$$$API$$$Fail£££doc/rst/lib_xassert.html#fail

A failure can be indicated with the `fail` macro e.g.:

    if (reg_value != 0xA5)
      fail("device not connected properly")

A fail will always cause a trap if executed. A failure differs from unreachable in that an unreachable macro should never execute in a correct program whereas a fail could happen in catastrophic circumstances even if the program is correct.

## lib_xassert: Assertions library$$$Controlling assertions£££doc/rst/lib_xassert.html#controlling-assertions

Assertions can be enabled/disabled via command line options to your application build. The following defines can be set by using the `-D` option to the compiler. For example, the following in your application CMakeLists.txt will enable line numbers in assertion messages:

    set(APP_COMPILER_FLAGS -DXASSERT_ENABLE_LINE_NUMBERS=1)

The following defines can be set:

XASSERT_ENABLE_ASSERTIONS

  This define can be used to turn assertions on or off (defaults to 1).

XASSERT_ENABLE_DEBUG

  This define will cause assertions to print out the failing expression before trapping (defaults to 0). Note that this option could significantly increase the code size of your application.

XASSERT_ENABLE_LINE_NUMBERS

  This define will cause assertions to print the file and line number of the assertion before trapping. Note that this option could significantly increase the code size of your application.

If `XASSERT_UNIT` is defined when `xassert.h` is included then all the assertions in that file belong to that unit. Assertions can then be controlled per debug unit. The mechanism is similar to that used in `module_logging`.

XASSERT_ENABLE_ASSERTIONS_[xassert unit]

  Enable asserts for a particular debug unit. If set to 1, this overrides the default set by `XASSERT_ENABLE_ASSERTIONS` for that debug unit.

XASSERT_ENABLE_DEBUG_[xassert unit]

  Enable debug messages for a particular debug unit. If set to 1, this overrides the default set by `XASSERT_ENABLE_DEBUG` for that debug unit .

XASSERT_DISABLE_ASSERTIONS_[xassert unit]

  Disable asserts for a particular debug unit. If set to 1, this overrides the default set by `XASSERT_ENABLE_ASSERTIONS` for that debug unit.

XASSERT_DISABLE_DEBUG_[xassert unit]

  Disable debug messages for a particular debug unit. If set to 1, this overrides the default set by `XASSERT_ENABLE_DEBUG` for that debug unit .