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:

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:

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 package.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:

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 package.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 package.json that you should edit to describe the plugin package. To publish a pak in the catalog, you must provide at a minimum:

Here is the edited package.json:

{
    "name": "me-time",
    "description": "MakeMe Time",
    "version": "1.0.0",
    "author": {
        "name": "Embedthis Software",
        "email": "dev@embedthis.com",
        "url": "https://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.

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 package.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.

© Embedthis Software, 2003-2015. All rights reserved.