contract/doc/getting_started.qbk

[/ Copyright (C) 2008-2012 Lorenzo Caminiti ]
[/ Distributed under the Boost Software License, Version 1.0 ]
[/ (see accompanying file LICENSE_1_0.txt or a copy at ]
[/ http://www.boost.org/LICENSE_1_0.txt) ]
[/ Home at http://sourceforge.net/projects/contractpp ]

[section Getting Started]

This section explains how to setup a system to use this library.

[section This Documentation]

Programmers should have enough knowledge to use this library after reading the __Introduction__, __Getting_Started__, and __Tutorial__ sections.
The other sections can be consulted to gain a more in depth knowledge of the library.

Some footnotes are marked by the word "*Rationale*". They explain reasons behind decisions made during the design and implementation of this library.

In most of the examples presented in this documentation the Boost.Detail/LightweightTest macro `BOOST_TEST` is used to assert test conditions (see also =boost/detail/lightweight_test.hpp=).
The `BOOST_TEST` macro is conceptually similar to C++ `assert` but a failure of the checked condition does not abort the program, instead it makes `boost::report_errors` return a non-zero program exit code.
[footnote
*Rationale.*
Using Boost.Detail/LightweightTest allows to add the examples to the library regression tests so to make sure that they always compile and run correctly.
]

[endsect]

[section Compilers and Platforms]

The implementation of this library uses preprocessor and template meta-programming (as supported  by __Boost_Preprocessor__ and __Boost_MPL__ respectively), templates with partial specializations and function pointers (similarly to __Boost_Function__), and local functions (as supported by __Boost_LocalFunction__).
The authors originally developed and tested the library on:

# GCC 4.5.3 on Cygwin (with and without __CXX11__ features enabled =-std=c++0x=).
[footnote
When using GCC to compile large projects that use this library, it might be necessary to appropriately set the `--param gcc-min-expand` option to avoid internal compiler errors due to excessive virtual memory usage.
]

# Microsoft Visual C++ (MSVC) 8.0 on Windows XP and Windows 7.

At present, the library has not been tested on other compilers or platforms.

[endsect]

[section Installation]

This library is composed of header files only.
Therefore there is no pre-compiled object file which needs to be installed or linked.
Programmers can simply instruct the C++ compiler where to find the library header files and they can start compiling code using this library.

[important
This library extensively uses __Boost__ libraries.
__Boost__ version 1.50 must be properly installed in order for this library to compile.
]

Let ['=ROOT=] be the root directory of this library installation then the directory structure is as follow:

[pre
['ROOT]/
    doc/
        html/   # This documentation.
    example/    # Examples using this library.
    include/    # This library source files (headers only).
]

For example, the following commands can be used to compile code using this library:
[footnote
For convenience, a =Jamfile.v2= file is provided in the example directory that can be used to compile and test all the examples using __Boost_Jam__.
However, it is not necessary to use __Boost_Jam__ to compile code that uses this library.
]

[pre
$ g++ -I ['ROOT]/include ...    # For GCC.
> cl  /I ['ROOT]\include ...    # For MSVC.
]

All necessary library headers are included in the source code by the following instruction (it is not necessary to include single headers separately):

    #include <contract.hpp> // Include this library headers.

The following symbols are part of the library private interface, they are not documented, and they should not be directly used by programmers:
[footnote
*Rationale.*
This library concatenates symbols specified by programmers (e.g., the function name) with other symbols (e.g., special prefixes and line numbers) to make internal symbols with unique names to avoid name clashes.
These symbols are separated by the letter `X` when they are concatenated so they read more easily during debugging (unfortunately, the underscore character `_` could not be used instead of the letter `X` because if the original symbol already contained a leading or trailing underscore, the concatenation could result in a symbol with double underscores `__` which is reserved by the C++ standard).
The ["aux] symbols are internal to the implementation of this library.
The ["detail] symbols are not officially part of the library public interface and they are not documented however they constitute a separate set of standalone libraries that could be added to the library public interface in the future.
]

* Any symbol defined by files within the =contract/aux_/= or =contract/detail/= directories (these header files should not be directly included by programmers).
* Any symbol within the `contract::aux` or `contract::detail` namespace.
* Any symbol prefixed by `contract_aux_...` or `contract_detail_...` (regardless of its namespace).
* Any symbol prefixed by `CONTRACT_AUX_...` or `CONTRACT_DETAIL_...` (regardless of its namespace).

Symbols starting with `ERROR_...` are used to report compile-time errors via static assertions and programmers should not use these symbols to define macros or other constructs in the global namespace.

[endsect]

[section Disable Contract Compilation]

Some of the library behaviour can be customized at compile-time by defining special /configuration macros/ (see [headerref contract/config.hpp]).
In particular, the following configuration macros can be used to selectively turn on or off contract compilation and the related run-time checks:

* Defining the [macroref CONTRACT_CONFIG_NO_PRECONDITIONS] macro turns off compilation and run-time checking of all preconditions.
* Defining the [macroref CONTRACT_CONFIG_NO_POSTCONDITIONS] macro turns off compilation and run-time checking of all postconditions.
* Defining the [macroref CONTRACT_CONFIG_NO_CLASS_INVARIANTS] macro turns off compilation and run-time checking of all class invariants.
* Defining the [macroref CONTRACT_CONFIG_NO_BLOCK_INVARIANTS] macro turns off compilation and run-time checking of all block invariants.
* Defining the [macroref CONTRACT_CONFIG_NO_LOOP_VARIANTS] macro turns off compilation and run-time checking of all loop variants.

By default, all contracts are compiled and checked at run-time (i.e., all the macros above are not defined).

[important
In Contract Programming, it is usually important to selectively turn off contract compilation to reduce run-time, binary size, and compilation-time overhead associated with the contracts (see __Meyer97__).
This library guarantees zero run-time and binary size overhead when all contracts are all turned off (however, even when contracts are all turned off there is a limited compile-time overhead associated with expanding the contract macros to generate the original class and function declarations).
Note that when contracts are turned off their assertions are completely ignored by the compiler so the assertion code might not even be syntactically correct.
]

For example, the following commands compile and check preconditions and class invariants, but they do not compile and check postconditions, block invariants, and loop variants:

[pre
$ g++ -DCONTRACT_CONFIG_NO_POSTCONDITONS -DCONTRACT_CONFIG_NO_BLOCK_INVARIANTS -DCONTRACT_CONFIG_NO_LOOP_VARIANTS ...   # For GCC.
> cl  /DCONTRACT_CONFIG_NO_POSTCONDITONS /DCONTRACT_CONFIG_NO_BLOCK_INVARIANTS /DCONTRACT_CONFIG_NO_LOOP_VARIANTS ...   # For MSVC.
]

Other configuration macros are provided to customize other aspects of the library.
For example, the [macroref CONTRACT_CONFIG_FUNCTION_ARITY_MAX] macro is used to specify the maximum number of function parameters and the [macroref CONTRACT_CONFIG_INHERITANCE_MAX] macro is used to specify the maxim number of base classes.
All configuration macros have appropriate default values when they are left undefined by programmers.

[endsect]

[endsect]