MakeMe Plugins

MakeMe can be extended via modular plugins that add functionality to the core MakeMe capabilities. These capabilities are then available to any project that references the plugin. Plugins can contribute standard targets, goals or scripts. Examples of plugins are:

• Targets to create installable packages
• Targets to run a unit test framework
• Git integration targets
• And so on ...

Plugins are referenced by the project via the plugins property. For example:

 Me.load({
    plugins: [ 'configuration', 'package'],
    targets: {}
})

Plugin Elements

A MakeMe plugin consists of two mandatory elements:

• A MakeMe file of the same name as the plugin pak.
• A Pak pak.json description file

The NAME.me MakeMe file provides the plugin's functionality. It may contain targets, settings, and may reference other MakeMe files or scripts. The Pak pak.json file describes the pak and specifies its name, version and source code repository location from which it can be downloaded.

A plugin may also include:

• Additional MakeMe files
• MakeMe targets in any MakeMe file
• Ejscript mixins referenced by the MakeMe file
• Any additional files and resources

For example:

Me.load({
    blend: [
        'extra/subsystem.me'
    ],
    modules: [
        'scripts/package.es'
    ]
    mixin: `
        function log(msg) {
            Path('/var/spool/log/build.log').append(msg)
        }
    `
    targets: {
        'time': {
            shell: `date`
        },
    },
})

Sample Plugin

For example, here are the steps to create a simple MakeMe plugin that displays the current time.

$ me time
Thu Mar 13 17:04:49 PDT 2014

Step 1 — Name the Plugin

The plugin name must be a unique name in the Pak online catalog. By convention, MakeMe plugins are named with a "me-" prefix. This makes it easy for users to find suitable MakeMe plugins. You should also set your pak.json keywords to include "me-plugin" Search the Pak Online Catalog to pick a unique name.

Step 2 — Create the MakeMe File

Make a new directory for the plugin and create the MakeMe file there using the chosen name of your plugin with a ".me" extension. Here is the MakeMe file:

Me.load({
    targets: {
        'time': {
            shell: `date`
        },
    },
})

Step 3 — Package the Plugin

Plugins are packaged and distributed using the Pak package manager tool. Pak will bundle together all the components of a plugin and then publish online for distribution via the Pak Online Catalog.

To package a MakeMe file as a Pak, first run the pak init command:

pak init 'me-time' 1.0.0

This creates a default pak.json that you should edit to describe the plugin package. To publish a pak in the catalog, you must provide at a minimum:

• Unique plugin pak name
• Plugin pak description
• Plugin pak author with contact details
• Plugin pak repository location on GitHub
• Plugin version

Here is the edited pak.json:

{
    "name": "me-time",
    "description": "MakeMe Time",
    "version": "1.0.0",
    "author": {
        "name": "Embedthis Software",
        "email": "dev@embedthis.com",
        "url": "https://www.embedthis.com"
    },
    "repository": {
        "type": "git",
        "url": "git://github.com/embedthis/me-time.git"
    },
}

Step 4 — Publish the Plugin

Plugins may be optionally published to the Pak Online Catalog using the Pak tool. This is an optional step and the pack may simply be included in the projects src/paks directory without publishing online. To publish online, use the pak tool:

pak publish

This will prompt for a password that can subsequently be used to administer the plugin in the catalog. REMEMBER this password and save it in a safe place. You will need it to modify or delete the plugin should you need to do so.

Using a Plugin

Users can download and install plugins locally using the Pak tool. For example:

pak install NAME

This will download and install the plugin into the current src/paks directory. The project main.me file should load this plugin via the plugins property. For example:

Me.load({
    plugins: [ 'time' ],
    ...

Mixins

Plugins may contribute scripts that are made available to target scripts or other MakeMe plugins. Plugin scripts are Javascript (Ejscript) definitions or functions that are injected the MakeMe Javascript engine. There are two methods of adding scripts.

• blend
• mixin

The MakeMe blend property is an array of external scripts to load. These paths may include the wild-card "*" character to match a filename portion and "**" to match any file or directory at any depth in the directory tree. If the filename is not found, "~/.paks" is searched for a matching Pak.

The mixin property is a literal Javascript string to load. These are both injected at the global scope.

Install Events

A plugin may need install libraries on its target system or otherwise may need to perform initialization tasks when first installed. The Pak pak.json file contains a "scripts.install" and property that can be set to an Ejscript file that will be executed when the pak is first installed. Similarly the "scripts.uninstall" property that can be set to an Ejscript that will be run when the script is uninstalled.

Configurable Components

A common use for plugins is to publish a component that can be configured by the user to add functionality to an existing project. The component will be expressed as a target with a configurable property set to true. See Configurable Projects for more details.