0
0
Fork 0
mirror of https://github.com/matrix-construct/construct synced 2024-12-25 15:04:10 +01:00
construct/modules/README.md
2020-01-11 23:31:53 -08:00

66 lines
2.1 KiB
Markdown

# Module Tree
This directory contains dynamically loadable functionality to libircd.
#### Approach
Unlike most of the module systems found in traditional C free software
projects, our approach is oriented around *global symbol* availability to the
address space rather than explicit imports from self-contained modules. This
direction is made viable by C++ and advances in the compiler and linker
toolchains. The result is significantly simpler and more convenient for
developers to work with.
##### GLOBAL SYMBOLS
Modules are loaded with `RTLD_GLOBAL` on both posix and windows platforms.
Use of C++ namespaces, visibility attributes, `STB_GNU_UNIQUE`, etc are
adequate to make this modernization.
##### WEAK UNDEFINED SYMBOLS
All project code is built to silently weaken undefined symbols. This means
a complicated interface declared in a header, like a class interface with
public and private and static members (typical in C++) can be included
by itself into any part of the project without knowing where the definitions
of that interface are until they are *first used* at runtime.
If definitions are not available because they are in an unloaded module: a C++
exception is thrown directly from the callsite. We have built this action
is built into the lookup mechanism of the runtime dynamic linker; none of
this requires knowledge or effort from developers to use.
#### Layout
(TODO)
## Getting started
The header `mods/mapi.h` is specific to modules and included for modules in
addition to the core `ircd.h`. Both of these are included automatically
via the compiler's command-line and the developer does not have to `#include`
either in the module.
1. Every loadable module requires a static `ircd::mapi::header` with the explicit
name of `IRCD_MODULE`. This is an object which will be sought by the module
loader in libircd.
```
// Example of a trivial module
ircd::mapi::header
IRCD_MODULE
{
"My Module", []
{
puts("hi\n");
}
};
```
2. Add an `_la_SOURCES` entry for your module in the appropriate place in
Makefile.am.
3. Add the module `.la` name to the appropriate LTLIBRARIES list
in Makefile.am.