Sane C++ Libraries
C++ Platform Abstraction Libraries
Plugin.h
1// Copyright (c) Stefano Cristiano
2// SPDX-License-Identifier: MIT
3#pragma once
4#include "../Containers/SmallVector.h"
5#include "../Containers/VectorMap.h"
6#include "../Strings/SmallString.h"
7#include "../Time/Time.h"
8#include "Internal/DynamicLibrary.h"
9
10namespace SC
11{
12struct PluginDefinition;
13struct PluginScanner;
14struct PluginFile;
15struct PluginIdentity;
16struct PluginDynamicLibrary;
17struct PluginCompiler;
18struct PluginCompilerEnvironment;
19struct PluginSysroot;
20struct PluginRegistry;
21using PluginIdentifier = SmallString<30>;
22} // namespace SC
23
26
29
32{
34};
35
38{
42
46 bool operator==(const PluginIdentity& other) const { return identifier == other.identifier; }
47};
48
51{
56
60
63 PluginFile& getMainPluginFile() { return files[pluginFileIndex]; }
64
67 const PluginFile& getMainPluginFile() const { return files[pluginFileIndex]; }
68
73 [[nodiscard]] static bool find(const StringView text, StringView& extracted);
74
79 [[nodiscard]] static bool parse(StringView text, PluginDefinition& pluginDefinition);
80
84 [[nodiscard]] Result getDynamicLibraryAbsolutePath(String& fullDynamicPath) const;
85
89 [[nodiscard]] Result getDynamicLibraryPDBAbsolutePath(String& fullDynamicPath) const;
90
91 private:
92 [[nodiscard]] static bool parseLine(StringIteratorASCII& iterator, StringView& key, StringView& value);
93
94 size_t pluginFileIndex = 0;
95 friend struct PluginScanner;
96};
97
100{
105 [[nodiscard]] static Result scanDirectory(const StringView directory, Vector<PluginDefinition>& definitions);
106};
107
110{
117 Result compile(const PluginDefinition& definition, const PluginSysroot& sysroot,
118 const PluginCompilerEnvironment& environment, String& compilerLog) const;
119
127 Result link(const PluginDefinition& definition, const PluginSysroot& sysroot,
128 const PluginCompilerEnvironment& environment, StringView executablePath, String& linkerLog) const;
129
131 enum class Type
132 {
133 ClangCompiler,
134 GnuCompiler,
135 MicrosoftCompiler
136 };
137 Type type = Type::ClangCompiler;
140
142
145
149 [[nodiscard]] static Result findBestCompiler(PluginCompiler& compiler);
150
151 private:
152 [[nodiscard]] Result compileFile(const PluginDefinition& definition, const PluginSysroot& sysroot,
153 const PluginCompilerEnvironment& compilerEnvironment, StringView sourceFile,
154 StringView objectFile, String& compilerLog) const;
155 struct Internal;
156};
157
160{
163
165
170 [[nodiscard]] static Result findBestSysroot(PluginCompiler::Type compiler, PluginSysroot& sysroot);
171};
172
175{
176 StringView cFlags;
177 StringView ldFlags;
178
179 private:
180 struct Internal;
181 friend struct PluginCompiler;
182};
185{
187 SystemDynamicLibrary dynamicLibrary;
191
195 template <typename T>
196 [[nodiscard]] bool queryInterface(T*& outInterface) const
197 {
198 if (pluginQueryInterface and instance != nullptr)
199 {
200 return pluginQueryInterface(instance, T::InterfaceHash, reinterpret_cast<void**>(&outInterface));
201 }
202 return false;
203 }
204
205 PluginDynamicLibrary() : lastLoadTime(Time::Absolute::now()) { numReloads = 0; }
206
207 private:
208 void* instance = nullptr;
209 bool (*pluginInit)(void*& instance) = nullptr;
210 bool (*pluginClose)(void* instance) = nullptr;
211
212 bool (*pluginQueryInterface)(void* instance, uint32_t hash, void** instanceInterface) = nullptr;
213
214 friend struct PluginRegistry;
215 [[nodiscard]] Result load(const PluginCompiler& compiler, const PluginSysroot& sysroot, StringView executablePath);
216 [[nodiscard]] Result unload();
217};
218
221{
226
228 enum class LoadMode
229 {
230 Load = 0,
231 Reload = 1,
232 };
233
241 [[nodiscard]] Result loadPlugin(const StringView identifier, const PluginCompiler& compiler,
242 const PluginSysroot& sysroot, StringView executablePath,
243 LoadMode loadMode = LoadMode::Load);
244
248 [[nodiscard]] Result unloadPlugin(const StringView identifier);
249
253 [[nodiscard]] Result removeAllBuildProducts(const StringView identifier);
254
258 [[nodiscard]] const PluginDynamicLibrary* findPlugin(const StringView identifier);
259
261 [[nodiscard]] size_t getNumberOfEntries() const { return libraries.size(); }
262
264 [[nodiscard]] const PluginIdentifier& getIdentifierAt(size_t index) const { return libraries.items[index].key; }
265
267 [[nodiscard]] const PluginDynamicLibrary& getPluginDynamicLibraryAt(size_t index)
268 {
269 return libraries.items[index].value;
270 }
271
272 private:
274};
275
unsigned int uint32_t
Platform independent (4) bytes unsigned int.
Definition: PrimitiveTypes.h:38
@ Native
Encoding is UTF8.
Reads and holds CFLAGS and LDFLAGS environment variables, mainly to pass down sysroot location.
Definition: Plugin.h:175
Compiles a plugin to a dynamic library.
Definition: Plugin.h:110
SmallVector< StringNative< 256 >, 8 > includePaths
Path to include directories used to compile plugin.
Definition: Plugin.h:141
SmallVector< StringNative< 256 >, 8 > compilerIncludePaths
Path to compiler include directories.
Definition: Plugin.h:143
SmallVector< StringNative< 256 >, 8 > compilerLibraryPaths
Path to compiler library directories.
Definition: Plugin.h:144
StringNative< 256 > compilerPath
Path to the compiler.
Definition: Plugin.h:138
Type type
Compile Type.
Definition: Plugin.h:137
Result compile(const PluginDefinition &definition, const PluginSysroot &sysroot, const PluginCompilerEnvironment &environment, String &compilerLog) const
Compiles a Definition to an object file.
Type
Compiler type (clang/gcc/msvc)
Definition: Plugin.h:132
static Result findBestCompiler(PluginCompiler &compiler)
Look for best compiler on current system.
StringNative< 256 > linkerPath
Path to the linker.
Definition: Plugin.h:139
Result link(const PluginDefinition &definition, const PluginSysroot &sysroot, const PluginCompilerEnvironment &environment, StringView executablePath, String &linkerLog) const
Links a Definition into a dynamic library, with symbols from executablePath
Plugin description, category, dependencies, files and directory location.
Definition: Plugin.h:51
Result getDynamicLibraryAbsolutePath(String &fullDynamicPath) const
Gets absolute path of where compiled dynamic library will exist after plugin is compiled.
SmallString< 255 > description
Long description of plugin.
Definition: Plugin.h:53
SmallVector< PluginIdentifier, 8 > dependencies
Dependencies necessary to load this plugin.
Definition: Plugin.h:57
PluginIdentity identity
Uniquely identifier a plugin.
Definition: Plugin.h:52
static bool find(const StringView text, StringView &extracted)
Extracts the plugin definition (SC_BEGIN_PLUGIN / SC_END_PLUGIN) comment from a .cpp file.
const PluginFile & getMainPluginFile() const
Get main plugin file, holding plugin definition.
Definition: Plugin.h:67
SmallString< 255 > directory
Path to the directory holding the plugin.
Definition: Plugin.h:55
Result getDynamicLibraryPDBAbsolutePath(String &fullDynamicPath) const
Gets absolute path of where compiled Program Database File will exist after plugin is compiled.
SmallVector< PluginFile, 10 > files
Source files that compose this plugin.
Definition: Plugin.h:59
static bool parse(StringView text, PluginDefinition &pluginDefinition)
Parses an extracted plugin definition text.
SmallVector< SmallString< 10 >, 8 > build
Build options.
Definition: Plugin.h:58
SmallString< 10 > category
Category where plugin belongs to.
Definition: Plugin.h:54
PluginFile & getMainPluginFile()
Get main plugin file, holding plugin definition.
Definition: Plugin.h:63
A plugin dynamic library loaded from a SC::PluginRegistry.
Definition: Plugin.h:185
String lastErrorLog
Last error log of compiler / linker (if any)
Definition: Plugin.h:190
Time::Absolute lastLoadTime
Last time when this plugin was last loaded.
Definition: Plugin.h:188
SystemDynamicLibrary dynamicLibrary
System handle of plugin's dynamic library.
Definition: Plugin.h:187
PluginDefinition definition
Definition of the loaded plugin.
Definition: Plugin.h:186
uint32_t numReloads
Number of times that the plugin has been hot-reloaded.
Definition: Plugin.h:189
bool queryInterface(T *&outInterface) const
Try to obtain a given interface as exported by a plugin through SC_PLUGIN_EXPORT_INTERFACES macro.
Definition: Plugin.h:196
Holds path to a given plugin source file.
Definition: Plugin.h:32
SmallString< 255 > absolutePath
Absolute path to a plugin source file.
Definition: Plugin.h:33
Represents the unique signature / identity of a Plugin.
Definition: Plugin.h:38
bool operator==(const PluginIdentity &other) const
Compares two plugins on Identity::identifier.
Definition: Plugin.h:46
SmallString< 10 > version
Plugin version (x.y.z)
Definition: Plugin.h:41
PluginIdentifier identifier
Unique string identifying the plugin.
Definition: Plugin.h:39
SmallString< 30 > name
Plugin name.
Definition: Plugin.h:40
Holds a registry of plugins, loading and compiling them on the fly.
Definition: Plugin.h:221
LoadMode
Instructs loadPlugin to Load or Reload the plugin.
Definition: Plugin.h:229
Result unloadPlugin(const StringView identifier)
Unloads an already loaded plugin by its identifier.
Result loadPlugin(const StringView identifier, const PluginCompiler &compiler, const PluginSysroot &sysroot, StringView executablePath, LoadMode loadMode=LoadMode::Load)
Loads a plugin with given identifier, compiling it with given PluginCompiler.
size_t getNumberOfEntries() const
Returns the total number of registry entries (counting both loaded and unloaded plugins)
Definition: Plugin.h:261
Result removeAllBuildProducts(const StringView identifier)
Removes all temporary build products of the Plugin with given identifier.
const PluginDynamicLibrary * findPlugin(const StringView identifier)
Find a PluginDynamicLibrary in the registry with a given identifier.
const PluginDynamicLibrary & getPluginDynamicLibraryAt(size_t index)
Returns the PluginIdentifier corresponding to the index entry of the registry.
Definition: Plugin.h:267
const PluginIdentifier & getIdentifierAt(size_t index) const
Returns the PluginIdentifier corresponding to the index entry of the registry.
Definition: Plugin.h:264
Result replaceDefinitions(Vector< PluginDefinition > &&definitions)
Appends the definitions to registry.
Scans a directory for PluginDefinition.
Definition: Plugin.h:100
static Result scanDirectory(const StringView directory, Vector< PluginDefinition > &definitions)
Scans a directory for PluginDefinition.
Holds include and library paths for a system toolchain, used to let plugins link to libc and libc++.
Definition: Plugin.h:160
SmallVector< StringNative< 256 >, 8 > includePaths
Path to system include directories.
Definition: Plugin.h:161
static Result findBestSysroot(PluginCompiler::Type compiler, PluginSysroot &sysroot)
Finds a reasonable sysroot for the given compiler.
SmallVector< StringNative< 256 >, 8 > libraryPaths
Path to system library directories.
Definition: Plugin.h:162
StringNative< 256 > isysroot
Path to sysroot include (optional)
Definition: Plugin.h:164
An ascii string used as boolean result. SC_TRY macro forwards errors to caller.
Definition: Result.h:11
String with compile time configurable inline storage (small string optimization)
Definition: SmallString.h:21
A Vector that can hold up to N elements inline and > N on heap.
Definition: SmallVector.h:27
A non-modifiable owning string with associated encoding.
Definition: String.h:30
A string iterator for ASCII strings.
Definition: StringIterator.h:232
Non-owning view over a range of characters with UTF Encoding.
Definition: StringView.h:47
Absolute time represented with milliseconds since epoch.
Definition: Time.h:74
A contiguous sequence of heap allocated elements.
Definition: Vector.h:51
A map holding VectorMapItem key-value pairs in an unsorted Vector.
Definition: VectorMap.h:33