Sane C++ Libraries
C++ Platform Abstraction Libraries
Loading...
Searching...
No Matches
Plugin.h
1// Copyright (c) Stefano Cristiano
2// SPDX-License-Identifier: MIT
3#pragma once
4#include "../Foundation/Function.h"
5#include "../Foundation/StringPath.h"
6#include "../Time/Time.h"
7#include "Internal/DynamicLibrary.h"
8
9namespace SC
10{
11struct PluginDefinition;
12struct PluginScanner;
13struct PluginFile;
14struct PluginIdentity;
15struct PluginDynamicLibrary;
16struct PluginCompiler;
17struct PluginCompilerEnvironment;
18struct PluginSysroot;
19struct PluginRegistry;
20template <int N>
21using FixedString = detail::StringNativeFixed<N>;
22using PluginIdentifier = FixedString<64>;
23using PluginBuildOption = FixedString<32>;
24
25template <typename T, size_t N>
27{
28 constexpr size_t size() const { return numValues; }
29 constexpr void clear() { numValues = 0; }
30
31 operator Span<const T>() const { return {values, numValues}; }
32
33 template <typename U>
34 [[nodiscard]] constexpr bool contains(const U& value, size_t* outIndex = nullptr) const
35 {
36 for (size_t idx = 0; idx < numValues; ++idx)
37 {
38 if (values[idx] == value)
39 {
40 if (outIndex)
41 *outIndex = idx;
42 return true;
43 }
44 }
45 return false;
46 }
47
48 [[nodiscard]] constexpr bool isEmpty() const { return numValues == 0; }
49
50 [[nodiscard]] constexpr bool push_back(const T& value)
51 {
52 if (numValues < N)
53 {
54 values[numValues++] = value;
55 return true;
56 }
57 return false;
58 }
59
60 constexpr T* begin() { return values; }
61 constexpr T* end() { return values + numValues; }
62 constexpr T& operator[](size_t idx) { return values[idx]; }
63 constexpr const T* begin() const { return values; }
64 constexpr const T* end() const { return values + numValues; }
65 constexpr const T& operator[](size_t idx) const { return values[idx]; }
66
67 private:
68 T values[N];
69 size_t numValues = 0;
70};
71
76
79
85
88{
89 PluginIdentifier identifier;
90 FixedString<64> name;
91 FixedString<16> version;
92
96 bool operator==(const PluginIdentity& other) const { return identifier.view() == other.identifier.view(); }
97};
98
101{
103
104 FixedString<256> description;
105 FixedString<64> category;
107
111
114 PluginFile& getMainPluginFile() { return files[pluginFileIndex]; }
115
118 const PluginFile& getMainPluginFile() const { return files[pluginFileIndex]; }
119
124 [[nodiscard]] static bool find(const StringView text, StringView& extracted);
125
130 [[nodiscard]] static bool parse(StringView text, PluginDefinition& pluginDefinition);
131
136
141
142 private:
143 [[nodiscard]] static bool parseLine(StringIteratorASCII& iterator, StringView& key, StringView& value);
144
145 size_t pluginFileIndex = 0;
146 friend struct PluginScanner;
147};
148
151{
158 template <typename T>
159 static Result scanDirectory(const StringView directory, Span<PluginDefinition> definitionsStorage,
160 T& tempFileBuffer, Span<PluginDefinition>& foundDefinitions)
161 {
162 return scanDirectory(directory, definitionsStorage, GrowableBuffer<T>{tempFileBuffer}, foundDefinitions);
163 }
164
165 private:
166 static Result scanDirectory(const StringView directory, Span<PluginDefinition> definitionsStorage,
167 IGrowableBuffer&& tempFileBuffer, Span<PluginDefinition>& foundDefinitions);
168 struct ScannerState;
169};
170
173{
180 Result compile(const PluginDefinition& definition, const PluginSysroot& sysroot,
181 const PluginCompilerEnvironment& environment, Span<char>& compilerLog) const;
182
190 Result link(const PluginDefinition& definition, const PluginSysroot& sysroot,
191 const PluginCompilerEnvironment& environment, StringView executablePath, Span<char>& linkerLog) const;
192
194 enum class Type
195 {
196 ClangCompiler,
197 GnuCompiler,
198 MicrosoftCompiler
199 };
200 Type type = Type::ClangCompiler;
203
205
208
212 [[nodiscard]] static Result findBestCompiler(PluginCompiler& compiler);
213
214 private:
215 mutable native_char_t buffer[4096];
216
217 Result compileFile(const PluginDefinition& definition, const PluginSysroot& sysroot,
218 const PluginCompilerEnvironment& compilerEnvironment, StringView sourceFile,
219 StringView objectFile, Span<char>& compilerLog) const;
220 struct CompilerFinder;
221};
222
237
240{
241 StringView cFlags;
242 StringView ldFlags;
243
244 private:
245 struct Internal;
246 friend struct PluginCompiler;
247};
250{
252 SystemDynamicLibrary dynamicLibrary;
255
256 char errorStorage[1024 * 8] = {};
258
262 template <typename T>
263 [[nodiscard]] bool queryInterface(T*& outInterface) const
264 {
265 if (pluginQueryInterface and instance != nullptr)
266 {
267 return pluginQueryInterface(instance, T::InterfaceHash, reinterpret_cast<void**>(&outInterface));
268 }
269 return false;
270 }
271
272 PluginDynamicLibrary() : lastLoadTime(Time::Realtime::now()) { numReloads = 0; }
273
274 private:
275 void* instance = nullptr;
276 bool (*pluginInit)(void*& instance) = nullptr;
277 bool (*pluginClose)(void* instance) = nullptr;
278
279 bool (*pluginQueryInterface)(void* instance, uint32_t hash, void** instanceInterface) = nullptr;
280
281 friend struct PluginRegistry;
282 Result load(const PluginCompiler& compiler, const PluginSysroot& sysroot, StringView executablePath);
283 Result unload();
284};
285
288{
290 void init(Span<PluginDynamicLibrary> librariesStorage);
291
294
299
301 enum class LoadMode
302 {
303 Load = 0,
304 Reload = 1,
305 };
306
314 Result loadPlugin(const StringView identifier, const PluginCompiler& compiler, const PluginSysroot& sysroot,
315 StringView executablePath, LoadMode loadMode = LoadMode::Load);
316
320 Result unloadPlugin(const StringView identifier);
321
326
330 [[nodiscard]] PluginDynamicLibrary* findPlugin(const StringView identifier);
331
333 [[nodiscard]] size_t getNumberOfEntries() const { return libraries.sizeInElements(); }
334
336 [[nodiscard]] const PluginIdentifier& getIdentifierAt(size_t index) const
337 {
338 return libraries[index].definition.identity.identifier;
339 }
340
342 [[nodiscard]] const PluginDynamicLibrary& getPluginDynamicLibraryAt(size_t index) { return libraries[index]; }
343
349 Function<void(const PluginIdentifier&)> onPlugin);
350
351 private:
354};
355
357} // namespace SC
unsigned int uint32_t
Platform independent (4) bytes unsigned int.
Definition PrimitiveTypes.h:38
char native_char_t
The native char for the platform (wchar_t (4 bytes) on Windows, char (1 byte) everywhere else )
Definition PrimitiveTypes.h:34
Definition Plugin.h:27
Wraps function pointers, member functions and lambdas without ever allocating.
Definition Function.h:19
Reads and holds CFLAGS and LDFLAGS environment variables, mainly to pass down sysroot location.
Definition Plugin.h:240
Compiles a plugin to a dynamic library.
Definition Plugin.h:173
StringPath linkerPath
Path to the linker.
Definition Plugin.h:202
Result link(const PluginDefinition &definition, const PluginSysroot &sysroot, const PluginCompilerEnvironment &environment, StringView executablePath, Span< char > &linkerLog) const
Links a Definition into a dynamic library, with symbols from executablePath
FixedVector< StringPath, 8 > includePaths
Path to include directories used to compile plugin.
Definition Plugin.h:204
Type type
Compile Type.
Definition Plugin.h:200
FixedVector< StringPath, 8 > compilerLibraryPaths
Path to compiler library directories.
Definition Plugin.h:207
Type
Compiler type (clang/gcc/msvc)
Definition Plugin.h:195
static Result findBestCompiler(PluginCompiler &compiler)
Look for best compiler on current system.
FixedVector< StringPath, 8 > compilerIncludePaths
Path to compiler include directories.
Definition Plugin.h:206
Result compile(const PluginDefinition &definition, const PluginSysroot &sysroot, const PluginCompilerEnvironment &environment, Span< char > &compilerLog) const
Compiles a Definition to an object file.
StringPath compilerPath
Path to the compiler.
Definition Plugin.h:201
Plugin description, category, dependencies, files and directory location.
Definition Plugin.h:101
StringPath directory
Path to the directory holding the plugin.
Definition Plugin.h:106
FixedVector< PluginFile, 10 > files
Source files that compose this plugin.
Definition Plugin.h:110
PluginIdentity identity
Uniquely identifier a plugin.
Definition Plugin.h:102
static bool find(const StringView text, StringView &extracted)
Extracts the plugin definition (SC_BEGIN_PLUGIN / SC_END_PLUGIN) comment from a .cpp file.
FixedString< 256 > description
Long description of plugin.
Definition Plugin.h:104
const PluginFile & getMainPluginFile() const
Get main plugin file, holding plugin definition.
Definition Plugin.h:118
FixedVector< PluginIdentifier, 8 > dependencies
Dependencies necessary to load this plugin.
Definition Plugin.h:108
static bool parse(StringView text, PluginDefinition &pluginDefinition)
Parses an extracted plugin definition text.
Result getDynamicLibraryAbsolutePath(StringPath &fullDynamicPath) const
Gets absolute path of where compiled dynamic library will exist after plugin is compiled.
FixedString< 64 > category
Category where plugin belongs to.
Definition Plugin.h:105
Result getDynamicLibraryPDBAbsolutePath(StringPath &fullDynamicPath) const
Gets absolute path of where compiled Program Database File will exist after plugin is compiled.
PluginFile & getMainPluginFile()
Get main plugin file, holding plugin definition.
Definition Plugin.h:114
FixedVector< PluginBuildOption, 8 > build
Build options.
Definition Plugin.h:109
A plugin dynamic library loaded from a SC::PluginRegistry.
Definition Plugin.h:250
Time::Absolute lastLoadTime
Last time when this plugin was last loaded.
Definition Plugin.h:253
SystemDynamicLibrary dynamicLibrary
System handle of plugin's dynamic library.
Definition Plugin.h:252
PluginDefinition definition
Definition of the loaded plugin.
Definition Plugin.h:251
StringView lastErrorLog
Last error log of compiler / linker (if any)
Definition Plugin.h:257
uint32_t numReloads
Number of times that the plugin has been hot-reloaded.
Definition Plugin.h:254
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:263
char errorStorage[1024 *8]
Storage for last error log (below)
Definition Plugin.h:256
Holds path to a given plugin source file.
Definition Plugin.h:82
StringPath absolutePath
Absolute path to a plugin source file.
Definition Plugin.h:83
Represents the unique signature / identity of a Plugin.
Definition Plugin.h:88
bool operator==(const PluginIdentity &other) const
Compares two plugins on Identity::identifier.
Definition Plugin.h:96
PluginIdentifier identifier
Unique string identifying the plugin.
Definition Plugin.h:89
FixedString< 64 > name
Plugin name.
Definition Plugin.h:90
FixedString< 16 > version
Plugin version (x.y.z)
Definition Plugin.h:91
Holds a registry of plugins, loading and compiling them on the fly.
Definition Plugin.h:288
LoadMode
Instructs loadPlugin to Load or Reload the plugin.
Definition Plugin.h:302
void init(Span< PluginDynamicLibrary > librariesStorage)
Init a PluginRegistry with some given storage.
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:333
Result removeAllBuildProducts(const StringView identifier)
Removes all temporary build products of the Plugin with given identifier.
const PluginDynamicLibrary & getPluginDynamicLibraryAt(size_t index)
Returns the PluginIdentifier corresponding to the index entry of the registry.
Definition Plugin.h:342
Result close()
Unregisters all plugins.
const PluginIdentifier & getIdentifierAt(size_t index) const
Returns the PluginIdentifier corresponding to the index entry of the registry.
Definition Plugin.h:336
Result replaceDefinitions(Span< PluginDefinition > &&definitions)
Appends the definitions to registry.
PluginDynamicLibrary * findPlugin(const StringView identifier)
Find a PluginDynamicLibrary in the registry with a given identifier.
void getPluginsToReloadBecauseOf(StringView relativePath, Time::Milliseconds tolerance, Function< void(const PluginIdentifier &)> onPlugin)
Enumerates all plugins that must be reloaded when relativePath is modified.
Scans a directory for PluginDefinition.
Definition Plugin.h:151
static Result scanDirectory(const StringView directory, Span< PluginDefinition > definitionsStorage, T &tempFileBuffer, Span< PluginDefinition > &foundDefinitions)
Scans a directory for PluginDefinition.
Definition Plugin.h:159
Holds include and library paths for a system toolchain, used to let plugins link to libc and libc++.
Definition Plugin.h:225
FixedVector< StringPath, 8 > includePaths
Path to system include directories.
Definition Plugin.h:226
StringPath isysroot
Path to sysroot include (optional)
Definition Plugin.h:229
static Result findBestSysroot(PluginCompiler::Type compiler, PluginSysroot &sysroot)
Finds a reasonable sysroot for the given compiler.
FixedVector< StringPath, 8 > libraryPaths
Path to system library directories.
Definition Plugin.h:227
An ascii string used as boolean result. SC_TRY macro forwards errors to caller.
Definition Result.h:12
View over a contiguous sequence of items (pointer + size in elements).
Definition Span.h:29
A string iterator for ASCII strings.
Definition StringIterator.h:239
Pre-sized char array holding enough space to represent a file system path.
Definition StringPath.h:42
Non-owning view over a range of characters with UTF Encoding.
Definition StringView.h:46
Absolute time as realtime or monotonically increasing clock.
Definition Time.h:109
Type-safe wrapper of uint64 used to represent milliseconds.
Definition Time.h:43