Build Instructions

How to build the core library (for integrators, not end users).

This guide provides detailed instructions for building Plugify on Windows, Linux, and macOS. It also covers advanced customization options and troubleshooting tips.

Prerequisites

Before building Plugify, ensure you have the following tools installed:

Windows

Linux

  • Build essentials (e.g., gcc, g++, make)
  • CMake
  • Ninja (optional, for faster builds)
  • Git

macOS

Cloning the Repository

To get started, clone the Plugify repository with its submodules:

git clone https://github.com/untrustedmodders/plugify.git --recursive
cd plugify

Building on Windows

Using Visual Studio 2022 with CMake

Install CMake Tools:

Ensure you have CMake tools installed with Visual Studio.

Open the Project:

  • Open Visual Studio 2022.
  • Select File > Open > CMake.
  • Navigate to the repository directory and open the CMakeLists.txt file.

Configure and Build:

  • Visual Studio will automatically configure and generate the necessary build files.
  • Choose Release or Debug configuration.
  • Build the project by selecting Build > Build All from the menu.

Using Visual Studio 2022 Project

Generate Project Files:

  • Open a command prompt and navigate to the repository directory.
  • Create a build directory and navigate into it: 
    mkdir build
cd build
  • Generate Visual Studio project files using CMake: 
    cmake -G "Visual Studio 17 2022" ..

Build the Solution:

  • Open the generated plugify.sln file in Visual Studio.
  • Choose Release or Debug configuration.
  • Build the solution by selecting Build > Build Solution from the menu.

Using MinGW

Generate Makefiles:

  • Open a command prompt and navigate to the repository directory.
  • Create a build directory and navigate into it: 
    mkdir build
cd build
  • Generate Makefiles using CMake: 
    cmake -G "MinGW Makefiles" ..

Build the Project:

  • Use mingw64-make to build the project: 
    mingw64-make

Using Command Prompt

Generate Build Files:

  • Open a Visual Studio command prompt and navigate to the repository directory.
  • Create a build directory and navigate into it: 
    mkdir build
cd build
  • Generate Makefiles using CMake: 
    cmake ..

Build the Project:

  • Use cmake to build the project: 
    cmake --build . --target plugify --preset Release -- /m

Building on Linux

Install Dependencies:

  • Open a terminal and install the required dependencies: 
    sudo apt-get install -y build-essential cmake ninja-build libcurl4-openssl-dev

Generate Makefiles:

  • Navigate to the repository directory.
  • Create a build directory and navigate into it: 
    mkdir build
cd build
  • Generate Makefiles using CMake: 
    cmake ..

Build the Project:

  • Use cmake to build the project: 
    cmake --build . --target plugify --preset Release -- -j

Building on macOS

Install Dependencies:

  • Open a terminal and install the required dependencies: 
    brew install cmake ninja curl

Generate Makefiles:

  • Navigate to the repository directory.
  • Create a build directory and navigate into it: 
    mkdir build
cd build
  • Generate Makefiles using CMake: 
    cmake ..

Build the Project:

  • Use cmake to build the project: 
    cmake --build . --target plugify --preset Release -- -j

Building with CLion

CLion can be used to build the project on all platforms (Windows, Linux, macOS):

Open the Project:

  • Open CLion.
  • Select File > Open.
  • Navigate to the repository directory and open the CMakeLists.txt file.

Configure and Build:

  • CLion will automatically configure and generate the necessary build files.
  • Build the project by selecting Build > Build Project from the menu.

Upgrading

To update your local repository to the latest version:

git fetch
git pull
git submodule update --remote --merge

If the build fails, try removing the build directory and re-creating it as described above. Note that the build process makes no modifications outside the build directory.

Build Types

Plugify supports multiple build types, which can be specified using the CMAKE_BUILD_TYPE variable. The default build type is RelWithDebInfo. Additionally, Plugify provides presets for Debug and Release builds to simplify the process.

Available Build Types

  • Debug:
    • Enables debugging symbols and disables optimizations.
    • Ideal for development and troubleshooting.
    • Use this preset for local builds when you need detailed debugging information.
  • Release:
    • Enables optimizations and produces a smaller, faster binary.
    • Uses RelWithDebInfo to include debugging symbols for local builds.
    • Ideal for production builds where performance is critical.
  • RelWithDebInfo:
    • Enables optimizations while including debugging symbols.
    • This is the default build type and is used by the Release preset.
  • MinSizeRel:
    • Enables optimizations for the smallest possible binary size.
    • Ideal for environments where disk space or memory usage is a concern.
    • Does not include debugging symbols.

Using Presets

Plugify provides two presets to simplify the build process:

  1. Debug Preset:
    • Builds the project with the Debug configuration.
    • Use this preset for local development and debugging.
    • Example: 
      cmake ..
cmake --build . --preset Debug
  2. Release Preset:
    • Builds the project with the Release configuration, which uses RelWithDebInfo to include debugging symbols for local builds.
    • Use this preset for production-ready builds.
    • Example: 
      cmake ..
cmake --build . --preset Release

Specifying Build Types Manually

If you prefer to specify the build type manually, you can use the CMAKE_BUILD_TYPE variable:

cmake -DCMAKE_BUILD_TYPE=Debug -G Ninja ..
cmake -DCMAKE_BUILD_TYPE=Release -G Ninja ..
cmake -DCMAKE_BUILD_TYPE=RelWithDebInfo -G Ninja ..
cmake -DCMAKE_BUILD_TYPE=MinSizeRel -G Ninja ..

Customizing Plugify

Plugify provides several CMake options for customization:

OptionDescription
-DPLUGIFY_BUILD_TESTS=ONEnable building tests
-DPLUGIFY_BUILD_JIT=OFFBuild JIT object library
-DPLUGIFY_BUILD_ASSEMBLY=OFFBuild assembly object library
-DPLUGIFY_BUILD_DOCS=OFFEnable building with documentation
-DPLUGIFY_BUILD_OBJECT_LIB=OFFBuild Plugify as an object library
-DPLUGIFY_BUILD_SHARED_LIB=ONBuild Plugify as a shared library
-DPLUGIFY_BUILD_SHARED_ASMJIT=OFFBuild AsmJit as a shared library
-DPLUGIFY_BUILD_SHARED_CURL=OFFBuild cURL as a shared library
-DPLUGIFY_USE_EXTERNAL_ASMJIT=OFFUse an external AsmJit library
-DPLUGIFY_USE_EXTERNAL_GLAZE=OFFUse an external Glaze library
-DPLUGIFY_USE_EXTERNAL_CURL=ONUse an external cURL library
-DPLUGIFY_USE_EXTERNAL_FMT=OFFUse an external fmt library
-DPLUGIFY_INTERFACE=OFFBuild as a lightweight interface for language modules
-DPLUGIFY_DOWNLOADER=ONEnable the downloader for the package manager
-DPLUGIFY_LOGGING=ONEnable the logging system
-DPLUGIFY_DEBUG=ONEnable debugging mode (asserts)
-DPLUGIFY_USE_LIBCPP=OFFUse libc++ by adding -stdlib=libc++ flag if available
-DPLUGIFY_USE_STATIC_STDLIB=OFFEnable static standard library linkage to avoid ABI issues by adding -static-* flags if available
-DPLUGIFY_USE_SANITIZER=OFFEnable sanitizers by adding -fsanitize=address -fno-omit-frame-pointer -fsanitize=undefined flags if available
-DPLUGIFY_USE_CLANG_TIDY=OFFEnable static analysis with clang-tidy
-DPLUGIFY_USE_ABI0=ONEnable use of the older C++ ABI, which was the default in GCC versions before GCC 5

Testing the Build

Plugify includes a custom testing system designed to validate the functionality of containers (e.g., strings, variants, vectors) used in language modules and plugins. This system relies on two key components:

  • cross_call_worker: A plugin that implements methods to be called by the cross_call_master.
  • cross_call_master: A plugin that calls methods from the cross_call_worker and instructs it to call methods back.

These plugins are used to test marshalling (data exchange between plugins written in different languages) and ensure compatibility across language modules.

How It Works

  1. cross_call_master calls methods from the cross_call_worker of another language module.
  2. cross_call_worker calls methods back on the cross_call_master.
  3. This bidirectional communication tests the marshalling system and ensures that data is correctly passed between plugins.

Running the Tests

To run the tests, you need to:

  1. Build the testing app (plug).
  2. Build the language modules and plugins (cross_call_worker and cross_call_master).
  3. Configure the res directory to include the required plugins and language modules.

Build the Testing App

Follow the Installation instructions to get the plug testing app.

Build Language Modules and Plugins

  1. Navigate to the repository directory and create a build folder:
mkdir build
cd build
  1. Generate build files and enable testing:
cmake -DPLUGIFY_BUILD_TESTS=ON ..
  1. Build the language modules and plugins individually. For example:
cmake --build . --target cross_call_worker
cmake --build . --target cross_call_master

Note: Ensure each plugin or language module is built separately to avoid conflicts and ensure proper compilation.

Configure the res Directory

  1. Create a res folder in the root of the repository:
mkdir ../res
  1. Inside the res folder, create two subfolders:
mkdir ../res/plugins
mkdir ../res/modules
  1. Copy the built plugins and language modules to the res folder:
  • Place cross_call_worker and cross_call_master in res/plugins/.
  • Place the language modules (e.g., cpp-module, python-module) in res/modules/.

Run the Tests

  1. Navigate to the build directory and run the plug app: 
    ./plug
  2. The app will load the plugins and language modules, and the tests will run automatically.

Example Test Workflow

  1. cross_call_master calls a method from cross_call_worker to pass a string.
  2. cross_call_worker processes the string and calls a method back on cross_call_master to return a modified string.
  3. The test verifies that the string was correctly passed and returned.

Building Documentation

Plugify's documentation can be built locally using Doxygen. To build the documentation:

Install Doxygen:

  • On Linux: 
    sudo apt-get install doxygen
  • On macOS: 
    brew install doxygen
  • On Windows:
    Download and install Doxygen from the official website.

Generate Documentation:

  • Navigate to the repository directory and create a build folder: 
    mkdir build
cd build
  • Enable documentation building: 
    cmake -DPLUGIFY_BUILD_DOCS=ON ..
  • Build the documentation: 
    cmake --build . --target docs

View the Documentation:

  • Open the generated documentation in your browser: 
    your_favorite_browser docs/html/index.html
Edit this page on GitHub
Directory Structure
Learn about the file and folder structure required for Plugify, including the `res` directory and configuration files.
Integrating
How to embed Plugify into your own projects.