// file : libbuild2/module.hxx -*- C++ -*- // copyright : Copyright (c) 2014-2019 Code Synthesis Ltd // license : MIT; see accompanying LICENSE file #ifndef LIBBUILD2_MODULE_HXX #define LIBBUILD2_MODULE_HXX #include #include #include #include #include #include #include #include namespace build2 { // A few high-level notes on the terminology: From the user's perspective, // the module is "loaded" (with the `using` directive). From the // implementation's perspectives, the module library is "loaded" and the // module is "bootstrapped" (or "booted" for short) and then "initialized" // (or "inited"). class module_base { public: virtual ~module_base () = default; }; // Return true if the module should be initialized first (the order of // initialization within each group is unspecified). // using module_boot_function = bool (scope& root, const location&, unique_ptr&); // Return false if the module configuration (normally based on the default // values) was unsuccessful but this is not (yet) an error. One example // would be the optional use of a module. Or a module might remain // unconfigured for as long as it is actually not used (e.g., install, // dist). The return value is used to set the .configured variable. // using module_init_function = bool (scope& root, scope& base, const location&, unique_ptr&, bool first, // First time for this project. bool optional, // Loaded with using? (optional module). const variable_map& hints); // Configuration hints (see below). // If the boot function is not NULL, then such a module is said to require // bootstrapping and must be loaded in bootstrap.build. // struct module_functions { const char* name; // Module/submodule name. module_boot_function* boot; module_init_function* init; }; // The build2__load() function will be written in C++ and will be // called from C++ but we need to suppress name mangling to be able to use // dlsym() or equivalent, thus extern "C". // // The part in the function name is the main module name without // submodule components (for example, `c` in `c.config`) and the load // function is expected to return boot/init functions for all its submodules // (if any) as well as for the module itself as an array of module_functions // terminated with an all-NULL entry. // // Note that the load function is guaranteed to be called during serial // execution (either from main() or during the load phase). // extern "C" using module_load_function = const module_functions* (); // Module state. // struct module_state { bool boot; // True if the module boot'ed but not yet init'ed. bool first; // True if the boot'ed module must be init'ed first. module_init_function* init; unique_ptr module; const location loc; // Boot location. }; struct module_map: std::map { template T* find_module (const string& name) const { auto i (find (name)); return i != end () ? static_cast (i->second.module.get ()) : nullptr; } }; // Boot the specified module loading its library if necessary. // LIBBUILD2_SYMEXPORT void boot_module (scope& root, const string& name, const location&); // Init the specified module loading its library if necessary. Used by the // parser but also by some modules to init prerequisite modules. Return a // pointer to the corresponding module state if the module was both // successfully loaded and configured and NULL otherwise (which can only // happen if optional is true). Note that the return can be used as a bool. // // The config_hints variable map can be used to pass configuration hints // from one module to another. For example, the cxx modude may pass the // target platform (which was extracted from the C++ compiler) to the bin // module (which may not always be able to extract the same information from // its tools). // LIBBUILD2_SYMEXPORT module_state* init_module (scope& root, scope& base, const string& name, const location&, bool optional = false, const variable_map& config_hints = empty_variable_map); // A wrapper over init_module() to use from other modules that incorporates // the .loaded variable check (use init_module() directly to sidestep // this check). // bool load_module (scope& root, scope& base, const string& name, const location&, bool optional, const variable_map& config_hints = empty_variable_map); // As above but always load and return a reference to the module instance // pointer (so it can be moved). // unique_ptr& load_module (scope& root, scope& base, const string& name, const location&, const variable_map& config_hints = empty_variable_map); template inline T& load_module (scope& root, scope& base, const string& name, const location& l, const variable_map& config_hints = empty_variable_map) { return static_cast (*load_module (root, base, name, l, config_hints)); } // Loaded modules (as in libraries). // // A NULL entry for the main module indicates that a module library was not // found. // using loaded_module_map = std::map; // The loaded_modules map is locked per top-level (as opposed to nested) // context (see context.hxx for details). // // Note: should only be constructed during context-wide serial execution. // class LIBBUILD2_SYMEXPORT loaded_modules_lock { public: explicit loaded_modules_lock (context& c) : ctx_ (c), lock_ (mutex_, defer_lock) { if (ctx_.modules_lock == nullptr) { lock_.lock (); ctx_.modules_lock = this; } } ~loaded_modules_lock () { if (ctx_.modules_lock == this) ctx_.modules_lock = nullptr; } private: static mutex mutex_; context& ctx_; mlock lock_; }; LIBBUILD2_SYMEXPORT extern loaded_module_map loaded_modules; // Load a builtin module (i.e., a module linked as a static/shared library // or that is part of the build system driver). // // Note: assumes serial execution. // LIBBUILD2_SYMEXPORT void load_builtin_module (module_load_function*); } #endif // LIBBUILD2_MODULE_HXX