Plugins

Table of Contents

• Create a New In-Tree Plugin
• Create a Third-Party Plugin
  • Third-Party Plugin Discovery
• Extract an Existing In-Tree Plugin
• Standalone Third-Party Builds
• Normalizers

Check out the demo plugin for a minimal example. It uses our custom add_mim_plugin CMake command. A plugin generally consists of two halves with the same name: a <plugin>.mim file that declares the public annexes and a shared library that registers the runtime behavior.

Plugin names may only contain letters, digits, and underscores, and are limited to 8 characters.

Create a New In-Tree Plugin

Create a new in-tree plugin foobar based on the demo plugin:

./scripts/new_plugin.sh foobar

The script also supports -h/--help and prints the same usage text when called incorrectly.

By default, the script creates an in-tree plugin and updates src/mim/plug/CMakeLists.txt. The generated files are:

• src/mim/plug/<plugin>/<plugin>.mim
• src/mim/plug/<plugin>/CMakeLists.txt
• src/mim/plug/<plugin>/<plugin>.cpp
• src/mim/plug/<plugin>/normalizers.cpp
• include/mim/plug/<plugin>/<plugin>.h
• lit/<plugin>/const.mim

Create a Third-Party Plugin

To create a self-contained third-party plugin repository in extra/, use:

./scripts/new_plugin.sh foobar --extra

This creates extra/<plugin>/ with:

• <plugin>.mim
• CMakeLists.txt
• src/<plugin>.cpp
• src/normalizers.cpp
• include/mim/plug/<plugin>/<plugin>.h
• lit/const.mim

In --extra mode, the script also initializes a new Git repository for the plugin.

Third-Party Plugin Discovery

If you clone a plugin repository into extra/, MimIR picks it up automatically during configuration when the repository contains a CMakeLists.txt as a direct child of extra/.

If the plugin repository also contains lit/*.mim tests, they are picked up automatically by the main lit target as well.

Extract an Existing In-Tree Plugin

To move an existing in-tree plugin into extra/foobar, use:

./scripts/extract_plugin.sh foobar

This moves:

• src/mim/plug/<plugin>/ into extra/<plugin>/
• include/mim/plug/<plugin>/ into extra/<plugin>/include/...
• lit/<plugin>/ into extra/<plugin>/lit/

It also rewrites the extracted CMakeLists.txt for out-of-tree use and removes the plugin from the in-tree plugin list so it is picked up through extra/ instead.

Standalone Third-Party Builds

After installing MimIR, a third-party plugin only needs to find the mim package. For example, a plugin called foo can be set up like this:

cmake_minimum_required(VERSION 3.25 FATAL_ERROR)
project(foo)
 
if(NOT COMMAND add_mim_plugin)
    find_package(mim REQUIRED)
endif()
 
add_mim_plugin(foo
    SOURCES
        src/foo.cpp
        src/normalizers.cpp
)

Configure the project standalone with:

cmake .. -Dmim_DIR=<MIM_INSTALL_PREFIX>/lib/cmake/mim

The authoritative reference for add_mim_plugin itself lives in cmake/Mim.cmake.

Normalizers

Normalizers usually obtain the owning World from one of their arguments, often type->world(), and then build the replacement directly in that world. Small normalizers are expected to be direct and side-effect free.

That often leads to tiny functions of the form:

const Def* normalize_const(const Def* type, const Def*, const Def* arg) {
    auto& world = type->world();
    return world.lit(world.type_idx(arg), 42);
}