bootstrap.hpp

Go to the documentation of this file.

//==================================================================================================
/// \file
/// This header-file is part of module \alib_bootstrap of the \aliblong.
///
/// Copyright 2013-2026 A-Worx GmbH, Germany.
/// Published under #"mainpage_license".
//==================================================================================================
ALIB_EXPORT namespace alib {
 
/// State of initialization of the \alibmods that do not dispose over a #"Camp"
/// instance.
extern bool     NonCampModulesInitialized;
 
//##################################################################################################
// Compilation flags
// Create a bitset from the ALib compilation features.
// For this, we ensure that the individual headers tested are included
//##################################################################################################
 
/// This is a simple copyable set of bits comprising the compilation flags.
/// @see Used with methods #"Bootstrap" which calls #"AssertALibVersionAndFlags".
struct TCompilationFlags {
    unsigned char bits[5]; ///< The Flags.
};
 
/// This is a struct composing an entry in #"COMPILATION_FLAG_MEANINGS".
struct CompilationFlagMeaningsEntry {
    int             Flag; ///< The bit number in the bitset.
    const char*     Name; ///< The human-readable meaning of the bit.
};
 
/// This is for the creation of output on information about the bits found in
/// field #"COMPILATION_FLAGS".
/// Declared public to allow exposure, e.g., in verbose logging.
/// \see Method #"AssertALibVersionAndFlags" for more information.
extern ALIB_DLL
CompilationFlagMeaningsEntry    COMPILATION_FLAG_MEANINGS[40];
 
 
/// The module version. Standard \alib versioning scheme is YYMM (as integer number)
/// of the module release date.
/// Besides this version number, field #"REVISION" indicates if this is a revised version
/// of a former release.
extern ALIB_DLL
int                             VERSION;
 
/// The revision number of this release. Usually a module is initially released as
/// revision \e 0. Pure bug-fix releases that do not change the interface of \alib
/// are holding the same #"VERSION" but an increased number in this field.
extern ALIB_DLL
unsigned char                   REVISION;
 
/// These flags are used internally to detect incompatibilities when linking \alib to binaries that
/// use different compilation flags. Declared public to allow exposure, e.g., in verbose logging.
/// \see Function #"AssertALibVersionAndFlags", which is invoked by overloaded functions
///      #"Bootstrap".
extern ALIB_DLL
TCompilationFlags               COMPILATION_FLAGS;
 
/// Compares a given set of compilation flags with the ones set in the \alib library.
/// If a mismatch is found, the configuration mismatch is written to <c>std::cerr</c>
/// and <c>exit(255)</c> is performed.
///
/// This function called in all variants of function #"Bootstrap(BootstrapPhases);2".
/// If a using application wants to act different on such a mismatch, an own check of
/// global variables #"VERSION;2", #"REVISION;2" and #"COMPILATION_FLAGS;2" against
/// configuration macros #"ALIB_VERSION", #"ALIB_REVISION" and
/// #"ALIB_COMPILATION_FLAGS"
/// has to be performed \e before calling #"%Bootstrap".
///
/// \attention A mismatch in \alib library version and compilation flags, may lead to very
///            dubious misbehavior which is almost impossible to debug. This is true for any
///            C/C++ software/library mismatch.
///
/// @param alibVersion      The \alib version required.
///                         Defaults to #"ALIB_VERSION" and <b>must not</b> be passed when invoking
///                         this function.
/// @param alibRevision     The \alib sub-version required.
///                         Defaults to #"ALIB_REVISION" and <b>must not</b> be passed when invoking
///                         this function.
/// @param compilationFlags The flags as defined in invoking compilation unit.
///                         Defaults to \c ALIB_COMPILATION_FLAGS and must not be given.
ALIB_DLL
void            AssertALibVersionAndFlags( int               alibVersion     = ALIB_VERSION,
                                           int               alibRevision    = ALIB_REVISION,
                                           TCompilationFlags compilationFlags= TCompilationFlags{ALIB_COMPILATION_FLAGS} );
 
//==================================================================================================
//========================================= Non-Camp Version =======================================
//==================================================================================================
#if !ALIB_CAMP || DOXYGEN
/// Performs standard bootstrapping of \alib. All details are explained
/// in the #"alib_mod_bs;Programmer's Manual" of module \alib_bootstrap_nl.
///
/// \note In addition, function #"AssertALibVersionAndFlags;2" is invoked.
///       For this, the parameters of this function must not be given, but left to their
///       default values, which are read from corresponding configuration macros.<br>
///       For more information on this topic, see chapter
///       #"alib_mod_bs_assertcomp"  of the #"alib_manual".
///
/// \par Availability
///   This function is replaced by a sibling method of the same name, but with more parameters,
///   in case the module \alib_camp is included in the \alibbuild.
///
/// @param alibVersion      The \alib version used by the caller.
///                         Defaults to #"ALIB_VERSION" and <b>must not</b> be passed.
/// @param alibRevision     The \alib sub-version used by the caller.
///                         Defaults to #"ALIB_REVISION" and <b>must not</b> be passed.
/// @param compilationFlags The flags as defined in invoking compilation unit.
///                         Defaults to #"ALIB_COMPILATION_FLAGS" and <b>must not</b> be passed.
ALIB_DLL    void     Bootstrap(int               alibVersion        = ALIB_VERSION,
                               int               alibRevision       = ALIB_REVISION,
                               TCompilationFlags compilationFlags   = TCompilationFlags{ALIB_COMPILATION_FLAGS});
 
/// Terminates \alib. All details are explained in the
/// #"alib_mod_bs;Programmer's Manual" of module \alib_bootstrap_nl.
/// \par Availability
///   This function is replaced by a sibling method of the same name, but with more parameters,
///   in case the module \alib_camp is included in the \alibbuild.
ALIB_DLL    void    Shutdown();
#endif
 
//==================================================================================================
//=========================================== Camp Version =========================================
//==================================================================================================
#if ALIB_CAMP || DOXYGEN
/// Lists all \alibcamps in the order of bootstrapping. Shutdown is performed in reverse order.
/// This list is used by overloaded functions
/// - #"Bootstrap(BootstrapPhases, camp::Camp*, int, int, TCompilationFlags);2", and
/// - #"Shutdown(ShutdownPhases, camp::Camp*);2".
///
/// For details on when and how to manipulate this list explicitly, see the detailed explanations in
/// the \#"alib_mod_bs;Programmer's Manual" of module \alib_bootstrap_nl.
///
/// \note Should for any reason it is needed to \b not use method #"BootstrapAddDefaultCamps;2"
///       to default-fill this list before adding custom camps, then the allocator of this
///       list has to be set before filling it. This can be done with:
///
///              CAMPS.GetAllocator()=  monomem::GLOBAL_ALLOCATOR;
ALIB_DLL
extern ListMA<camp::Camp*>  CAMPS;
 
/// Fills list #"CAMPS;2", taking the permutation of modules contained in the \alibbuild into
/// account.<br>
/// This function is usually invoked automatically.
///
/// For details on when and how to explicitly invoke this function, see the detailed explanations
/// in the #"alib_mod_bs;Programmer's Manual" of module \alib_bootstrap_nl.
ALIB_DLL
void            BootstrapAddDefaultCamps();
 
//==================================================================================================
/// This function is used to bootstrap \alib. It replaces the overloaded version
/// #"Bootstrap(int", int, TCompilationFlags) in the moment module \alib_camp is included in the
/// \alibbuild.
/// (The term "replace" here in deed means that this other version of this function is not available
/// anymore.)
///
/// The difference of this version is that it makes it possible to fine-tune the bootstrap
/// process in respect to the list of camps that are considered and it introduces
/// different phases of bootstrapping.
///
/// For details on when and how to invoke this method explicitly, see the detailed explanations in
/// the #"alib_mod_bs;Programmer's Manual" of module \alib_bootstrap_nl.
///
/// @param targetPhase      The initialization level to perform.
///                         Defaults to <c>BootstrapPhases::Final</c>.
/// @param targetCamp       The "highest" \alibcamp in the list #"CAMPS;2" to bootstrap.
///                         Defaults to <c>nullptr</c>, which chooses the end of the list.
/// @param alibVersion      The \alib version required.
///                         Defaults to #"ALIB_VERSION" and <b>must not</b> be passed when invoking
///                         this function.
/// @param alibRevision     The \alib sub-version required.
///                         Defaults to #"ALIB_REVISION" and <b>must not</b> be passed when invoking
///                         this function.
/// @param compilationFlags The flags as defined in invoking compilation unit.
///                         Defaults to #"ALIB_COMPILATION_FLAGS" and <b>must not</b> be passed when
///                         invoking this function.
//==================================================================================================
ALIB_DLL
void     Bootstrap( BootstrapPhases       targetPhase     = BootstrapPhases::Final,
                    camp::Camp*           targetCamp      = nullptr,
                    int                   alibVersion     = ALIB_VERSION,
                    int                   alibRevision    = ALIB_REVISION,
                    TCompilationFlags     compilationFlags= TCompilationFlags{ALIB_COMPILATION_FLAGS});
 
//==================================================================================================
/// This function is usually invoked automatically and rightfully with the standard, parameterless
/// version #"alib::Shutdown(").
///
/// For details on when and how to invoke this method explicitly, see the detailed explanations in
/// the #"alib_mod_bs;Programmer's Manual" of module \alib_bootstrap_nl.
///
/// @param targetPhase The termination level to perform.
/// @param targetCamp  The "lowest" \alibcamp in list #"CAMPS;2" to shut down.
///                    Defaults to <c>nullptr</c>, which chooses the start of the list.
//==================================================================================================
ALIB_DLL
void     Shutdown( ShutdownPhases     targetPhase= ShutdownPhases::Destruct,
                   camp::Camp*        targetCamp = nullptr                        );
#endif
 
} // namespace [alib]