This library enables runtime compilation of source code and dynamic loading of a specified C/C++ function. It also provides support for versioning of the compiled functions.
This software is distributed under the LGPLv3 license. See LICENSE.txt and LICENSE.LESSER.txt for the full text of the license.
An introductory video is available on YouTube.
libVersioningCompiler requires:
- Ubuntu 20.04 LTS or greater / MacOS (tested with Sonoma) / Arch Linux or Manjaro / a linux distribution
- any compiler compliant to the C++17 standard
- cmake 3.20 or greater
- zlib
- libuuid
- (OPTIONAL) LLVM 18 or greater (tested up to LLVM 19)
Compiling without the OPTIONAL dependencies will disable some features, like the Clang-as-a-library compiler implementation.
To install the latest cmake (required in ubuntu focal) from Kitware:
sudo apt-get install --yes ca-certificates gnupg software-properties-common wget
wget -O - https://apt.kitware.com/keys/kitware-archive-latest.asc 2>/dev/null | gpg --dearmor - | sudo tee /etc/apt/trusted.gpg.d/kitware.gpg >/dev/null
sudo apt-add-repository 'deb https://apt.kitware.com/ubuntu/ focal main'To install the required libraries
sudo apt-get install --yes build-essential cmake zlib1g-dev uuid-devThen optionally install llvm 18 or greater (tested up to LLVM 19) and libclang (if needed, on many distributions it come bundled with LLVM/Clang), either using LLVM installer or via Ubuntu packages.
If you use the LLVM installer, with LLVM major version ${LLVM_V}:
wget https://apt.llvm.org/llvm.sh
chmod +x llvm.sh
[sudo] ./llvm.sh ${LLVM_V} allEventually, update the preferred clang and llvm version:
[optional][sudo] update-alternatives --install /usr/bin/clang++ clang++ /usr/bin/clang++-${LLVM_V} 100
[optional][sudo] update-alternatives --install /usr/bin/clang clang /usr/bin/clang-${LLVM_V} 100
[optional][sudo] update-alternatives --install /usr/bin/opt opt /usr/bin/opt-${LLVM_V} 100sudo pacman -S cmake llvm zlib [clang]uuid should not be required to be installed from AUR.
Install homebrew, then:
brew install cmake ossp-uuid zlib [llvm]If you want to install libVersioningCompiler, install the dependencies, then, assuming cloned the repository in ${LIBVC_ROOT}, do:
cd ${LIBVC_ROOT}
cmake -S . -Bbuild [-DCMAKE_INSTALL_PREFIX="/path/to/your/custom/install/folder/"] [-G "make/Ninja/whatever generator"]
cmake --build build
./build/libVC_testUtils &&./build/libVC_test &&./build/libVC_testJit
[sudo] cmake --build build --target install
Please note that if you choose to install libVersioningCompiler in a custom
folder, you will need the FindLibVersioningCompiler.cmake module.
You will find a pre-cooked cmake module in ${LIBVC_ROOT}/config.
The above-mentioned cmake module will export also cmake variables which are useful to build an application that uses libVersioningCompiler, including
$LIBVC_INCLUDE_DIRS = Include path for the header files of libVersioningCompiler
$LIBVC_LIBRARIES = Link these libraries to use libVersioningCompiler
$LIBVC_LIB_DIR = Extra libraries directories
$HAVE_CLANG_LIB_COMPILER = Set to true if libVersioningCompiler can have Clang as a library enabled
If you choose to do not use this cmake module, every time you want to use libVersioningCompiler in another application you have to manually specify:
- include path for the headers
libVersioningCompilerlibrary filelibVersioningCompiler's dependencies (see detailed list above)
If you want to build libVersioningCompiler using verbose flags and a custom compiler, assuming libVersioningCompiler had been cloned into ./libVersioningCompiler directory:
cd libVersioningCompiler
CXX="/usr/bin/clang" cmake -D CMAKE_VERBOSE_MAKEFILE=1 -D LIBCLANG_FIND_VERBOSE=1 -D LLVM_FIND_VERBOSE=1 -D LLVM_FIND_VERBOSE=1 -D JIT_ENABLE=0 -S . -B build
cmake --build build -vIf you want to build libVersioningCompiler using a custom installation of llvm:
cmake \
-D LLVM_FOUND=1 \
-D LLVM_LIBRARY_DIR="/opt/x86_64-linux-gnu-llvm-static/lib" \
-D LLVM_INCLUDE_DIR="/opt/x86_64-linux-gnu-llvm-static/include" \
-D LLVM_TOOLS_BINARY_DIR="/opt/x86_64-linux-gnu-llvm-static/bin" \
-D LLVM_VERSION_MAJOR=18 \
-D LLVM_PACKAGE_VERSION="18.1.3" \
-D ENABLE_JIT=0 \
-S . -B build
cmake --build buildExplanation:
LLVM_FOUND=1means to not look for a system installed llvm versionLLVM_LIBRARY_DIRspecifies where to find llvm librariesLLVM_INCLUDE_DIRspecifies where to find llvm headersLLVM_TOOLS_BINARY_DIRspecifies where to find llvm binaries (llvm-config, opt etc)LLVM_VERSION_MAJORandLLVM_PACKAGE_VERSIONmust be specified because FindLLVM.cmake is (usually) not included into llvm static buildsENABLE_JITOption to include or exclude the JITCompiler, currently not ported to LLVM 18 and upwards
Libclang will be found too after defining those variables.
Tested with MacOS Monterey:
cmake \
-D CMAKE_VERBOSE_MAKEFILE=1 -D LIBCLANG_FIND_VERBOSE=1 -D LLVM_FIND_VERBOSE=1 -D LLVM_FIND_VERBOSE=1 \ # Verbose flags
-D LLVM_FOUND=1 \
-D LLVM_LIBRARY_DIR="/opt/homebrew/opt/llvm/lib" \
-D LLVM_INCLUDE_DIR="/opt/homebrew/opt/llvm/include" \
-D LLVM_TOOLS_BINARY_DIR="/opt/homebrew/opt/llvm/bin" \
-D LLVM_VERSION_MAJOR=18 \ # Update this if required
-D LLVM_SHARED_MODE="static" \
-D LLVM_PACKAGE_VERSION="18.1.3" \ # Update this accordingly to /opt/homebrew/opt/llvm/bin/llvm-config --version
-D ENABLE_JIT=0 \
-S . -B build
cmake --build build -vThe project has legacy versions that are compatible with LLVM 13 to 15. Instructions are provided inside the repository. In order to go back to the legacy libVersioningCompiler versions:
cd ${LIBVC_ROOT}
git checkout b085535f83dc051edeede68905d2eca6f5cdd65c-
Version : it represents a specific version of a function (compiled or to be compiled). It holds references to the source, intermediate representations, compiled files on disk and the dynamically loaded function pointer. It also holds the configuration parameters used to create that function. It has a unique identifier randomly generated.
-
Compiler : it represents a compiler instance used to compile a Version. This library supports different compilers, they all derive from the Compiler abstract class.
-
Option : it represents an options passed to the compiler. It holds a string identifier for the category that can be used to track incompatible options (e.g. -O1 -Ofast are both optimization levels). The option is internally represented as a couple of strings , which are usually queued.
This library comes with two different flavors: low-level and high-level APIs.
Low-level APIs allow full control over the compilation process. Through these APIs it is possible to incrementally construct a Version by selecting the configuration parameter by parameter. It is possible to create clones or partial clones of Version objects. It is possible to configure and select different compilers. It is possible to exploit split-compilation techniques. It is possible to decide the exact moment when the compiler is invoked. It is possible to debug at fine grain.
High-level APIs allow to reduce the verbosity of some operations by aggregating the most common sequence of low-level function calls. All basic functionalities are summarized within 3 functions.
- Initialize
- Create Version object
- Compile a Version object and load function symbol
Disregarding the APIs that are going to be exploited, these modifications should be applied.
You have to provide a few additional pieces of information to the library, such as
- name of the function to be compiled
- name of the source file to be compiled
- signature of the function to be compiled
- ensure the function to be compiled will have C linkage
In the host code.
#define FILENAME_SRC "Kernel.cpp"
#define FUNCTION_NAME "myLovedFunction"
typedef int (*signature_t)(int);
where signature_t is a type definition for a function pointer having the
same signature as the function to be compiled/versioned.
Decoration of the source code of the function declaration: if not compiled as C source code, C linkage must be enforced. An example follows
#ifdef MYLOVEDFUNCTION // uppercase function name
extern "C"
#endif
int myLovedFunction(int parameter);
The enforcing is applied through the extern "C" prefix.
In order to apply this variation only when this source code is compiled with
libVersioningCompiler, it can be wrapped with a define.
This technique can also be applied to isolate the source code that must be
compiled into a Version from the code around it.
By default low-level APIs do not add any extra symbol definition during the
compilation; any extra definition must be manually specified.
High-level APIs include by default a definition of the uppercase name of the
compiled function. Every statement in the source file can be selectively
enabled or disabled by using
#ifdef uppercaseFunctionName | #ifndef uppercaseFunctionName.
Before proceeding any further, be sure you have understood the Common part, which must be addressed in both cases of high-level and low-level APIs.
#include "versioningCompiler/Version.hpp"
In addition -- according to the chosen Compiler implementation -- the corresponding include should be added. E.g.
#include "versioningCompiler/SystemCompilerOptimizer.hpp"
Instantiate and configure all compilers that are going to be used.
Please take a look at the source code documentation of each Compiler
for a more detailed explanation of the constructor parameters.
// default system compiler
vc::compiler_ptr_t cc = vc::make_compiler<vc::SystemCompiler>();
// /usr/bin/gcc using ./test.log as log file
vc::compiler_ptr_t gcc = vc::make_compiler<vc::SystemCompiler>(
"gcc",
std::filesystem::u8path("gcc"),
std::filesystem::u8path("."),
std::filesystem::u8path("./test.log"),
std::filesystem::u8path("/usr/bin"),
false
);
// custom installation of LLVM/clang
// Clang as compiler and LLVM opt as optimizer
vc::compiler_ptr_t clang = vc::make_compiler<vc::SystemCompilerOptimizer>(
"llvm/clang",
std::filesystem::u8path("clang"),
std::filesystem::u8path("opt"),
std::filesystem::u8path("."),
std::filesystem::u8path("./test.log"),
std::filesystem::u8path("/usr/bin"), // compiler path
std::filesystem::u8path("/usr/bin") // optimizer path
);
Changing the configuration of a Version is impossible after its creation. The configuration is done using a builder instance. Once a builder is correctly configured, it is possible to take a snapshot of it by creating a Version. Builder::build() will create a Version.
vc::Version::Builder builder; // MANDATORY instantiate Builder
builder._functionName.push_back(FUNCTION_NAME); // MANDATORY set function name
builder._fileName_src.push_back(FILENAME_SRC); // MANDATORY set source file
builder._compiler = clang; // MANDATORY set clang as compiler for the version
builder.options({ // set compilation option list
vc::Option("o", "-O", "2") // add "-O2"
});
builder._optOptionList = { // set optimizer option list
vc::Option("fp-contract", "-fp-contract=", "fast"),
vc::Option("inline", "-inline"),
vc::Option("unroll", "-loop-unroll"),
vc::Option("mem2reg", "-mem2reg")
};
vc::version_ptr_t v = builder.build(); // MANDATORY finalize Version
After a Version finalization, the builder can be modified and reused to build another Version or it can be destroyed. Version objects constructed from the same builder will not be affected from any kind of change to the Builder object. It is also possible to clone a Version in a new Builder to initialize it.
// reuse builder from v
builder._compiler = cc;
vc::version_ptr_t v2 = builder.build();
// initialize another_builder using v2 configuration
vc::Version::Builder another_builder = vc::Version::Builder(v2);
Once a Version object is finalized it holds the configuration that will be
later used to compile ad optimize that function. It is not compiled yet.
This allows to control separately the configuration and the compilation tasks.
Given a Version object, it can be compiled by calling the compile() method.
signature_t fn_ptr;
bool ok = v->compile();
if (! ok) {
// handle compilation error
} else {
fn_ptr = (signature_t) v->getSymbol(0);
}
If the compiler supports split-compilation, it is possible to generate an intermediate representation via the optimizer.
if (clang->hasIRSupport()) // check if the compiler has IR support
{
v->prepareIR(); // generate IR and run the optimizer.
// Options for IR generation and optimization have to be specified
// during the configuration of the Version object
v->compile(); // compile the optimized IR and load symbol
}
Before proceeding any further, be sure you have understood the Common part, which must be addressed in both cases of high-level and low-level APIs.
High-level APIs are simple functions that wraps the low-level APIs. They rely on builder and compiler static objects. They apply the most common values to the low-level parameters. Please consider to switch to Low-level APIs for a more fine-grained approach.
#include "versioningCompiler/Utils.hpp"
vc::vc_utils_init();
vc::version_ptr_t v = vc::createVersion(FILENAME_SRC,
FUNCTION_NAME,
{vc::Option("O", "-O", "2"), ... }
);
signature_t fn_ptr = (signature_t) vc::compileAndGetSymbol(v);
if (fn_ptr) { // check if correctly compiled and loaded symbol
fn_ptr(42); // run the compiled function version
}