From f04fd6187974da2b07a00324cc7b76d1671c4d05 Mon Sep 17 00:00:00 2001
From: Michele Caini <michele.caini@gmail.com>
Date: Tue, 19 May 2020 00:36:45 +0200
Subject: [PATCH] doc: added config section

---
 docs/CMakeLists.txt |   1 +
 docs/md/config.md   | 100 ++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 101 insertions(+)
 create mode 100644 docs/md/config.md

diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt
index 2b63bf7bb..c4ef3b22c 100644
--- a/docs/CMakeLists.txt
+++ b/docs/CMakeLists.txt
@@ -16,6 +16,7 @@ add_custom_target(
     VERBATIM
     SOURCES
         dox/extra.dox
+        md/config.md
         md/core.md
         md/entity.md
         md/faq.md
diff --git a/docs/md/config.md b/docs/md/config.md
new file mode 100644
index 000000000..bcc750479
--- /dev/null
+++ b/docs/md/config.md
@@ -0,0 +1,100 @@
+# Crash Course: configuration
+
+<!--
+@cond TURN_OFF_DOXYGEN
+-->
+# Table of Contents
+
+* [Introduction](#introduction)
+* [Definitions](#definitions)
+  * [ENTT_NOEXCEPT](#entt_noexcept)
+  * [ENTT_HS_SUFFIX and ENTT_HWS_SUFFIX](#entt_hs_suffix_and_entt_hws_suffix)
+  * [ENTT_USE_ATOMIC](#entt_use_atomic)
+  * [ENTT_ID_TYPE](#entt_id_type)
+  * [ENTT_PAGE_SIZE](#entt_page_size)
+  * [ENTT_ASSERT](#entt_assert)
+  * [ENTT_NO_ETO](#entt_no_eto)
+  * [ENTT_STANDARD_CPP](#entt_standard_cpp)
+
+<!--
+@endcond TURN_OFF_DOXYGEN
+-->
+
+# Introduction
+
+`EnTT` doesn't offer many hooks for customization but it certainly offers
+some.<br/>
+In the vast majority of cases, users will have no interest in changing the
+default parameters. For all other cases, the list of possible configurations
+with which it's possible to adjust the behavior of the library at runtime can be
+found below.
+
+# Definitions
+
+All options are intended as parameters to the compiler (or user-defined macros
+within the compilation units, if preferred).<br/>
+Each parameter can result in internal library definitions. It's not recommended
+to try to also modify these definitions, since there is no guarantee that they
+will remain stable over time unlike the options below.
+
+## ENTT_NOEXCEPT
+
+The purpose of this parameter is to suppress the use of `noexcept` by this
+library.<br/>
+To do this, simply define the variable without assigning any value to it.
+
+## ENTT_HS_SUFFIX and ENTT_HWS_SUFFIX
+
+The `hashed_string` class introduces the `_hs` and `_hws` suffixes to accompany
+its user defined literals.<br/>
+In the case of conflicts or even just to change these suffixes, it's possible to
+do so by associating new ones with these definitions.
+
+## ENTT_USE_ATOMIC
+
+In general, `EnTT` doesn't offer primitives to support multi-threading. Many of
+the features can be split over multiple threads without any explicit control and
+the user is the only one who knows if and when a synchronization point is
+required.<br/>
+However, some features aren't easily accessible to users and can be made
+thread-safe by means of this definition.
+
+## ENTT_ID_TYPE
+
+`entt::id_type` is directly controlled by this definition and widely used within
+the library.<br/>
+By default, its type is `std::uint32_t`. However, users can define a different
+default type if necessary.
+
+## ENTT_PAGE_SIZE
+
+As is known, the ECS module of `EnTT` is based on _sparse sets_. What is less
+known perhaps is that these are paged to reduce memory consumption in some
+corner cases.<br/>
+The default size of a page is 32kB but users can adjust it if appropriate. In
+all case, the chosen value **must** be a power of 2.
+
+## ENTT_ASSERT
+
+For performance reasons, `EnTT` doesn't use exceptions or any other control
+structures. In fact, it offers many features that result in undefined behavior
+if not used correctly.<br/>
+To get around this, the library relies on a lot of `assert`s for the purpose of
+detecting errors in debug builds. However, these assertions may in turn affect
+performance to an extent.<br/>
+This option is meant to disable all controls.
+
+## ENTT_NO_ETO
+
+In order to reduce memory consumption and increase performance, empty types are
+never stored by the ECS module of `EnTT`.<br/>
+Use thi svariable to treat these types like all others and therefore to create a
+dedicated storage for them.
+
+## ENTT_STANDARD_CPP
+
+After many adventures, `EnTT` finally works fine across boundaries.<br/>
+To do this, the library mixes some non-standard language features with others
+that are perfectly compliant.<br/>
+This definition will make the library use only standard techniques, that is,
+functionalities that are fully compliant with the standard C++.