Usage and Configuration

Primer is header only -- this means that to use Primer in a C++ project, its include directory needs to be added to your include search path.

This includes the primer subfolder, as well as two extra libraries visit_struct and weak_ref. These both stand alone and are potentially useful outside of Primer, but they are small enough to justify distributing them with Primer.

What to Include

The core of Primer may be included with

#include <primer/primer.hpp>

Container support

To enable support for individual standard and boost containers, you may include any of the extra headers

#include <primer/std/vector.hpp>
#include <primer/std/set.hpp>
...
#include <primer/boost/optional.hpp>
...

or include all standard container headers or all boost container headers with

#include <primer/std.hpp>
#include <primer/boost.hpp>

To include both visit_struct and the related support headers in primer, you may include

#include <primer/visit_struct.hpp>

Api / Persistence

To use the features of primer that require lua-eris, which live in the api namespace, you may include

#include <primer/api.hpp>

Miscellaneous

You may include forward declarations of the core types via

#include <primer/primer_fwd.hpp>

If you only want to get the primer::error or primer::expected types, without pulling in the rest of primer, you may include

#include <primer/error.hpp>
#include <primer/expected.hpp>

and forward declarations of these:

#include <primer/expected_fwd.hpp>

Pulling those in is very lightweight, they only rely on e.g. <new>, <string> and <utility>.

If you just want to get the version number of primer, you may include

#include <primer/version.hpp>

Finally, if you would like to include lua or eris using exactly the same headers that Primer does internally, you may include

#include <primer/lua.hpp>

#include <primer/eris.hpp>

Primer searches for its configuration defines in <primer/conf.hpp>

	Note
	All other headers are considered implementation details, and may be moved or nonexistant in future releases, so you shouldn't include them directly.

Build Configuration

Primer responds to a few configuration defines:

symbol	effect
`PRIMER_DEBUG`	This is used to enable internal assertions that Primer uses to check its integrity. Especially, lua stack discipline assertions. You can turn these on if you are having strange lua errors, they may reveal stack discipline problems in usre specializations of `push` or `read`.
`PRIMER_LUA_AS_CPP`	This should be used if lua is being compiled as C++ rather than as C in your project. It causes primer not to use `extern "C"` when it includes lua headers.
`PRIMER_NO_STATIC_ASSERTS`	Disables all static assertions made by Primer.
`PRIMER_NO_EXCEPTIONS`	Disables all try / catch blocks in primer. Use this if you want to compile with `-fno-exceptions`.
`PRIMER_NO_MEMORY_FAILURE`	Tells primer to use, as an optimization assumption, that lua memory allocation will never fail, and, that when populating `std::string` and standard C++ containers, that `std::bad_alloc` will not be thrown either. This allows a number of try/catch blocks and `pcall` wrappers to be eliminated.

Caution

	Caution
Several data structures and functions in Primer make assumptions that types used with them do not throw exceptions when default constructed, moved, etc. These assumptions are generally true for most user types and standard library types that they would be used with. However, if you are using an old compiler with an old version of the standard library, crucial constructors for objects like `std::string` are not marked `noexcept` which means that these assertions fail. In such a scenario, you can't compile and can't easily work around the problem. To disable the safety checks, you can define `PRIMER_NO_STATIC_ASSERTS`. You should only do this if you have an old compiler and cannot upgrade, and the assertions are in fact true, just not annotated appropriately in your standard library headers. In general the failure of the conditions checked by these assertions can lead to undefined behavior.

Several data structures and functions in Primer make assumptions that types used with them do not throw exceptions when default constructed, moved, etc. These assumptions are generally true for most user types and standard library types that they would be used with.

However, if you are using an old compiler with an old version of the standard library, crucial constructors for objects like std::string are not marked noexcept which means that these assertions fail. In such a scenario, you can't compile and can't easily work around the problem.

To disable the safety checks, you can define PRIMER_NO_STATIC_ASSERTS. You should only do this if you have an old compiler and cannot upgrade, and the assertions are in fact true, just not annotated appropriately in your standard library headers.

In general the failure of the conditions checked by these assertions can lead to undefined behavior.

	Note
	If lua is compiled as C, i.e., `PRIMER_LUA_AS_CPP` is not defined, then `PRIMER_NO_MEMORY_FAILURE` will be defined automatically. See Exception Safety section for rationale.

To enable these, you can add them in your build system, define them in your source files before including primer, or create a custom version of <primer/conf.hpp>.