ALib C++ Library
Library Version: 2510 R0
Documentation generated by doxygen
Loading...
Searching...
No Matches
bootstrap.mpp
Go to the documentation of this file.
1//==================================================================================================
2/// \file
3/// This header-file is part of the \aliblong.
4/// With supporting legacy or module builds, .mpp-files are either recognized by the build-system
5/// as C++20 Module interface files, or are included by the
6/// \ref alib_manual_modules_impludes "import/include headers".
7///
8/// \emoji :copyright: 2013-2025 A-Worx GmbH, Germany.
9/// Published under \ref mainpage_license "Boost Software License".
10//==================================================================================================
11#if !defined(ALIB_C20_MODULES) || ((ALIB_C20_MODULES != 0) && (ALIB_C20_MODULES != 1))
12# error "Symbol ALIB_C20_MODULES has to be given to the compiler as either 0 or 1"
13#endif
14#if ALIB_C20_MODULES
15 module;
16#endif
17// ====================================== Global Fragment ======================================
27
28
29// =========================================== Module ==========================================
30#if ALIB_C20_MODULES
31 /// This is a C++ Module of the \aliblong. Due to the dual-compile option - as either
32 /// C++20 Modules or legacy C++ inclusion, the C++20 Module names are not of further interest
33 /// or use.<br>
34 /// In general, the names equal the names of the header files listed in the chapter
35 /// \ref alib_manual_modules_impludes of the \alib User Manual.
36 /// This chapter, among others, provides further explanations.
37 export module ALib.Bootstrap;
38 import ALib.Lang;
39# if ALIB_CONTAINERS
41# endif
42# if ALIB_CAMP
43 import ALib.Monomem;
44 import ALib.Camp;
45# endif
46
47#else
48 #include "ALib.Lang.H"
49 #include "ALib.Containers.List.H"
50 #include "ALib.Monomem.H"
51 #include "ALib.Camp.H"
52#endif
53
54// ========================================== Exports ==========================================
55ALIB_EXPORT namespace alib {
56
57/// State of initialization of the \alibmods that do not dispose over a \alib{camp::Camp}
58/// instance.
60
61// #################################################################################################
62// Compilation flags
63// Create a bitset from the ALib compilation features.
64// For this, we ensure that the individual headers tested are included
65// #################################################################################################
66
67/// This is a struct composing an entry in #COMPILATION_FLAG_MEANINGS.
69{
70 int Flag; ///< The bit number in the bitset.
71 const char* Name; ///< The human-readable meaning of the bit.
72};
73
74/// This is for the creation of output on information about the bits found in
75/// field #COMPILATION_FLAGS.
76/// Declared public to allow exposure, e.g., in verbose logging.
77/// \see Method #AssertALibVersionAndFlags for more information.
78extern ALIB_DLL
80
81
82/// The module version. Standard \alib versioning scheme is YYMM (as integer number)
83/// of the module release date.
84/// Besides this version number, field #REVISION indicates if this is a revised version
85/// of a former release.
86extern ALIB_DLL
87int VERSION;
88
89/// The revision number of this release. Usually a module is initially released as
90/// revision \e 0. Pure bug-fix releases that do not change the interface of \alib
91/// are holding the same #VERSION but an increased number in this field.
92extern ALIB_DLL
93unsigned char REVISION;
94
95/// These flags are used internally to detect incompatibilities when linking \alib to binaries that
96/// use different compilation flags. Declared public to allow exposure, e.g., in verbose logging.
97/// \see Function #AssertALibVersionAndFlags, which is invoked by overloaded functions
98/// #Bootstrap.
99extern ALIB_DLL
101
102/// Compares a given set of compilation flags with the ones set in the \alib library.
103/// If a mismatch is found, the configuration mismatch is written to <c>std::cerr</c>
104/// and <c>exit(255)</c> is performed.
105///
106/// This function called in all variants of function \ref alib::Bootstrap.
107/// If a using application wants to act different on such a mismatch, an own check of
108/// global variables \ref alib::VERSION, \ref alib::REVISION and \ref alib::COMPILATION_FLAGS against
109/// preprocessor symbols \ref ALIB_VERSION, \ref ALIB_REVISION and
110/// \doxlinkproblem{group__GrpALibPreproMacros.html;gaac71b6511690f5af0abf5213b0434111;ALIB_COMPILATION_FLAGS;ALIB_COMPILATION_FLAGS}
111/// has to be performed \e before calling \b Bootstrap.
112///
113/// \attention A mismatch in \alib library version and compilation flags, may lead to very
114/// dubious misbehavior which is almost impossible to debug. This is true for any
115/// C/C++ software/library mismatch.
116///
117/// @param alibVersion The \alib version required.
118/// Defaults to \ref ALIB_VERSION and \b must not be passed when invoking
119/// this function.
120/// @param alibRevision The \alib sub-version required.
121/// Defaults to \ref ALIB_REVISION and \b must not be passed when invoking
122/// this function.
123/// @param compilationFlags The flags as defined in invoking compilation unit.
124/// Defaults to \c ALIB_COMPILATION_FLAGS and \b must not be given.
126void AssertALibVersionAndFlags( int alibVersion = ALIB_VERSION,
127 int alibRevision = ALIB_REVISION,
128 TCompilationFlags compilationFlags= TCompilationFlags{ALIB_COMPILATION_FLAGS} );
129
130//==================================================================================================
131//================================ Non-Camp Version =======================================
132//==================================================================================================
133#if !ALIB_CAMP || DOXYGEN
134/// Performs standard bootstrapping of \alib. All details are explained
135/// in the \ref alib_mod_bs "Programmer's Manual" of module \alib_bootstrap_nl.
136///
137/// \note In addition, function \ref alib::AssertALibVersionAndFlags is invoked.
138/// For this, the parameters of this function must not be given, but left to their
139/// default values, which are read from corresponding preprocessor symbols.<br>
140/// For more information on this topic, see chapter
141/// \ref alib_mod_bs_assertcomp of the \ref alib_manual.
142///
143/// \par Availability
144/// This function is replaced by a sibling method of the same name, but with more parameters,
145/// in case the module \alib_camp is included in the \alibbuild.
146///
147/// @param alibVersion The \alib version used by the caller.
148/// Defaults to \ref ALIB_VERSION and \b must not be passed.
149/// @param alibRevision The \alib sub-version used by the caller.
150/// Defaults to \ref ALIB_REVISION and \b must not be passed.
151/// @param compilationFlags The flags as defined in invoking compilation unit.
152/// Defaults to
153/// \doxlinkproblem{group__GrpALibPreproMacros.html;gaac71b6511690f5af0abf5213b0434111;ALIB_COMPILATION_FLAGS;ALIB_COMPILATION_FLAGS}
154/// and \b must not be passed.
155ALIB_DLL void Bootstrap(int alibVersion = ALIB_VERSION,
156 int alibRevision = ALIB_REVISION,
157 TCompilationFlags compilationFlags = TCompilationFlags{ALIB_COMPILATION_FLAGS});
158
159/// Terminates \alib. All details are explained in the
160/// \ref alib_mod_bs "Programmer's Manual" of module \alib_bootstrap_nl.
161/// \par Availability
162/// This function is replaced by a sibling method of the same name, but with more parameters,
163/// in case the module \alib_camp is included in the \alibbuild.
165#endif
166
167//==================================================================================================
168//================================== Camp Version =========================================
169//==================================================================================================
170#if ALIB_CAMP || DOXYGEN
171/// Lists all \alibcamps in the order of bootstrapping. Shutdown is performed in reverse order.
172/// This list is used by overloaded functions
173/// - \doxlinkproblem{namespacealib.html;a78bb34888e5142adb87e265e23ee3c2e;alib::Bootstrap(BootstrapPhases, camp::Camp*, int,int,TCompilationFlags)},
174/// and
175/// - \doxlinkproblem{namespacealib.html;a4374717714582ef1a859b773367ec5d9;alib::Shutdown(ShutdownPhases, camp::Camp*)}.
176///
177/// For details on when and how to manipulate this list explicitly, see the detailed explanations in
178/// the \\ref alib_mod_bs "Programmer's Manual" of module \alib_bootstrap_nl.
179///
180/// \note Should for any reason it is needed to \b not use method \alib{BootstrapAddDefaultCamps}
181/// to default-fill this list before adding custom camps, then the allocator of this
182/// list has to be set before filling it. This can be done with:
183///
184/// CAMPS.GetAllocator()= monomem::GLOBAL_ALLOCATOR;
187
188/// Fills list \ref alib::CAMPS, taking the permutation of modules contained in the \alibbuild into
189/// account.<br>
190/// This function is usually invoked automatically.
191///
192/// For details on when and how to explicitly invoke this function, see the detailed explanations
193/// in the \ref alib_mod_bs "Programmer's Manual" of module \alib_bootstrap_nl.
196
197//==================================================================================================
198/// This function is used to bootstrap \alib. It replaces the overloaded version
199/// #Bootstrap(int, int, TCompilationFlags) in the moment module \alib_camp is included in the
200/// \alibbuild.
201/// (The term "replace" here in deed means that this other version of this function is not available
202/// anymore.)
203///
204/// The difference of this version is that it makes it possible to fine-tune the bootstrap
205/// process in respect to the list of camps that are considered and it introduces
206/// different phases of bootstrapping.
207///
208/// For details on when and how to invoke this method explicitly, see the detailed explanations in
209/// the \ref alib_mod_bs "Programmer's Manual" of module \alib_bootstrap_nl.
210///
211/// @param targetPhase The initialization level to perform.
212/// Defaults to <c>BootstrapPhases::Final</c>.
213/// @param targetCamp The "highest" \alibcamp in the list \alib{CAMPS} to bootstrap.
214/// Defaults to <c>nullptr</c>, which chooses the end of the list.
215/// @param alibVersion The \alib version required.
216/// Defaults to \ref ALIB_VERSION and \b must not be passed when invoking
217/// this function.
218/// @param alibRevision The \alib sub-version required.
219/// Defaults to \ref ALIB_REVISION and \b must not be passed when invoking
220/// this function.
221/// @param compilationFlags The flags as defined in invoking compilation unit.
222/// Defaults to
223/// \doxlinkproblem{group__GrpALibPreproMacros.html;gaac71b6511690f5af0abf5213b0434111;ALIB_COMPILATION_FLAGS;ALIB_COMPILATION_FLAGS}
224/// and must not be passed when
225/// invoking this function.
226//==================================================================================================
229 camp::Camp* targetCamp = nullptr,
230 int alibVersion = ALIB_VERSION,
231 int alibRevision = ALIB_REVISION,
232 TCompilationFlags compilationFlags= TCompilationFlags{ALIB_COMPILATION_FLAGS});
233
234//==================================================================================================
235/// This function is usually invoked automatically and rightfully with the standard, parameterless
236/// version \ref alib::Shutdown().
237///
238/// For details on when and how to invoke this method explicitly, see the detailed explanations in
239/// the \ref alib_mod_bs "Programmer's Manual" of module \alib_bootstrap_nl.
240///
241/// @param targetPhase The termination level to perform.
242/// @param targetCamp The "lowest" \alibcamp in list \alib{CAMPS} to shut down.
243/// Defaults to <c>nullptr</c>, which chooses the start of the list.
244//==================================================================================================
247 camp::Camp* targetCamp = nullptr );
248#endif
249
250} // namespace [alib]
251
252
253
#define ALIB_DLL
Definition alib.inl:496
#define ALIB_REVISION
Definition alib.inl:21
#define ALIB_VERSION
Definition alib.inl:20
#define ALIB_EXPORT
Definition alib.inl:488
CompilationFlagMeaningsEntry COMPILATION_FLAG_MEANINGS[40]
void AssertALibVersionAndFlags(int alibVersion, int alibRevision, TCompilationFlags compilationFlags)
unsigned char REVISION
BootstrapPhases
Definition camp.inl:15
@ Final
The final initialization phase. Here, camps are initializing their custom setup.
Definition camp.inl:35
void BootstrapAddDefaultCamps()
ShutdownPhases
Termination levels usable with Bootstrapping ALib Camps.
Definition camp.inl:42
@ Destruct
The main phase of termination that destructs everything.
Definition camp.inl:46
void Bootstrap(BootstrapPhases targetPhase, camp::Camp *targetCamp, int alibVersion, int alibRevision, TCompilationFlags compilationFlags)
int VERSION
bool NonCampModulesInitialized
TCompilationFlags COMPILATION_FLAGS
ALIB_DLL void Shutdown()
containers::List< TAllocator, T, TRecycling > List
Type alias in namespace alib.
Definition list.inl:746
ALIB_DLL List< MonoAllocator, camp::Camp * > CAMPS
This is a struct composing an entry in COMPILATION_FLAG_MEANINGS.
Definition bootstrap.mpp:69
const char * Name
The human-readable meaning of the bit.
Definition bootstrap.mpp:71
int Flag
The bit number in the bitset.
Definition bootstrap.mpp:70