Wiki Navigation

Quick DDL Tutorial

This quick tutorial is intended to allow developers to hit the ground running with DDL. As there are many points not covered in this tutorial, it is strongly recommended that the reader review the other tutorials and documentation when/if time permits. -Pragma

In this tutorial you will see examples on how to:

Create a simple plugin
Prep a simple program for using DDL
Load a plugin
Execute a method located within a plugin

Things not covered in this tutorial:

How DDL actually works
How to handle external plugin dependencies
How to recover from runtime linking problems

Source Listing for this tutorial

1. Create a Plugin

We're going to use a single D module as our plugin in this example. Do do that, simply create a .d file with a single method like so:

module plugin;

char[] helloWorld(){
    return "hello world";
}

You're only going to need the object file that the compiler creates, so just compile it:

dmd -c examples/quick/plugin.d

Note that the code above doesn't reference DDL at all. It doesn't need to since it's not performing any linking of it's own.

2. Create a Host Program

The host program is going to need to include DDL. This is where the dynamic loading and linking of the plugin is going to take place.

module quick;

import ddl.DefaultRegistry;
import ddl.Linker;

import tango.io.Stdout;

void main(){
    auto linker = new Linker(new DefaultRegistry());
    linker.loadAndRegister("quick.map");

    auto plugin = linker.load("plugin.obj");
    linker.register(plugin);
    linker.link(plugin);

    auto helloWorld = plugin.getDExport!(char[] function(),"plugin.helloWorld")();

    Stdout(helloWorld());
    Stdout.newline;
}

Then build the program using Bu[il]d. Be sure to not use the -clean option, as we'll need the .map file (DMD creates one by default) later.

build examples/quick/quick -L/map

Note that this example doesn't load the D platform library (tango-base-dmd.lib) or the compiler's library (snn.lib). Larger examples may need to link these as some DDL's may require support that your host program doesn't already have compiled in. This is covered more fully in the tutorial section.

2b. Create a Host Program using Rebuild

Building the host application with Rebuild is similar to using Bu[il]d, yet this time -clean may be included, since Rebuild doesn't remove the .map with this switch.

rebuild -I../.. -clean -L/map quick.d

3. Prep and Execute

Your project directory should now contain quick.exe, quick.map. plugin.obj will be two directories higher (unless it was compiled from the examples/quick directory), so should be moved where quick.exe resides.

Now run your host program.

quick

This should output the message from your helloWorld() function.

hello world

4. Done

That's it. This is the most straightforward, and simple way to use DDL in your application. More advanced techniques, based on this and other modes of use, are covered in the tutorial section.

ddl