Creating a Rootbeer Plugin¶

Tip

This document covers creating a Rootbeer plugin in C. For information on riting plugins in Lua, see the Lua API documentation.

Plugins are what allow a user to define system configurations and behaviors. Without plugins, Rootbeer is essentially a glorified Lua interpreter. Your plugin is able to use the public Rootbeer API to hook into the revision system and define extra files that can be used for a system configuration.

Getting Started¶

At its core, a Rootbeer plugin is a static C library that is compiled into the main rb executable. The plugin defines various functions that are exposed into the Lua environment, allowing the user to interact with your plugin.

To get started, you’ll want to create a new directory in src/plugins and create a meson.build file in that directory. This file will look something like this:

rootbeer_lib = static_library(
	'myplugin_name',
	sources: files(
		'src/main.c',
		...
	),
	# Root include allows you to access the Rootbeer API headers
	include_directories: [include_directories('src'), root_include],

	# The only required dependency is luajit, which is used to
	# interact with the Lua environment. You can add more dependencies
	# as needed for the functionality of your plugin.
	dependencies: [dependency('luajit')],
)

# These 2 are VERY important, the name tells exactly how the plugin
# will be registered in the Lua environment (`rootbeer.myplugin_name`).
register_plugin_lib = rootbeer_lib
register_plugin_name = 'myplugin_name'

Warning

In theory you can use another build system, but the Rootbeer build system is designed to work with Meson. Try at your own risk.

Plugin Structure¶

Let’s take a look at what is inside that src/main.c file. This is the entry point for your plugin and is where you will define the functions that will be exposed to the Lua environment. A simple plugin may look like this:

#include "rb_plugin.h"

const luaL_Reg myplugin_funcs[] = {
	{"my_function", my_function},
	{NULL, NULL} // REQUIRED to terminate the array
};

// It's imperative that myplugin_name matches the name in the meson.build
// file in the `register_plugin_name` variable.
RB_PLUGIN(myplugin_name, "Description", "0.0.1", myplugin_funcs)

You can define your own functions in the my_function variable, which will be called when the user calls rootbeer.myplugin_name.my_function() from Lua. These plugins are expected to be global functions in your plugin.

From here you can get as complex as you want and split up your plugin into multiple files. As long as you include the rb_plugin.h header and the call to RB_PLUGIN, you can define as many functions as you want.

`rb_plugin.h` Reference¶

This header defines the structure and macros for Rootbeer plugins. Using the RB_PLUGIN macro, developers can easily create plugins for Rootbeer, without having to deal with boilerplate code. See src/plugins/rootbeer_core for an example of a plugin.

Defines

RB_PLUGIN(name, desc, ver, f)¶

Macro to define a Rootbeer plugin. It will automatically generate the necessary entrypoint function and globals so that the rootbeer CLI can recognize the plugin and load it.

This macro simplifies the process of defining a plugin by automatically generating the necessary entrypoint function and populating the plugin structure with the provided name, description, version, and functions.

Parameters:

name – The name of the plugin, used in Lua as rootbeer.<name>.
desc – A short description of the plugin for CLI help.
ver – The version of the plugin, used for CLI and Lua.
f – An array of functions to be registered in Lua.

struct rb_plugin_t¶

#include <rb_plugin.h>

The internal structure for a Rootbeer plugin. This structure defines a plugin’s metadata and the functions it provides to the Lua environment. Internally, the CLI will parse this structure to make the plugin available in the Lua environment.

Instead of manually defining this, use RB_PLUGIN to define a plugin.

Public Members

const char *plugin_name¶: Registers a rootbeer.<name> module in Lua.

const char *description¶: Description of the plugin for the CLI.

const char *version¶: Version of the plugin, used for CLI and Lua.

const luaL_Reg *functions¶: Array of functions to be registered in Lua.

int (*entrypoint)(lua_State *L)¶: Generates a function for the package.preload table.

Creating a Rootbeer Plugin¶

Getting Started¶

Plugin Structure¶

rb_plugin.h Reference¶

`rb_plugin.h` Reference¶