GDKLib Builder (puregdk root/plugin sdk)
PureGDK
(http://puregdk.com)
PureBasic (http://purebasic.com)
Resource
Hacker (http://angusj.com/resourcehacker)
TailBite
(http://tailbite.com)
For this tutorial I'm going to demonstrate with the
Advanced Terrain plugin from The Game Creators. You'll need the
AdvancedTerrain.dll plugin from your
..\Documents and
Settings\YourUsername\Application Data\PureGDK\plugins-licensed folder. You
will also need to create a file with the .gdt (GDK dependency template) file
extension.

Open the plugin using Resource
Hacker and copy the contents of the entire string table into your .gdt template
file. There may be more than one table in a single dll.

Here is what the template
should look like at this point. Notice that the last two commands have a
preceding semicolon. This "comments out" the commands and they are ignored by
GDKLib Builder. These commands have been commented because they do not appear in
the documentation.

Here are some examples
of how to properly setup your GDKTable:
An important difference between
DarkBasic functions and PureGDK functions is that in a PureBasic function the
optional parameters can only be at the end or the parameter list. The command
Move Camera() in DarkBasic Professional has two sets of possible
parameters:
Move Camera(Distance) and
Move Camera(CameraID,
Distance). This is not compatible with PureBasic optional parameters. To
reorder the parameters there is a second optional parameter list after the last
% sign.

PureGDK supports the Long,
Float, String, and Double data types from plugins. When using a specific type in
the parameter list it's important to identify the type (.f, .s, .d) if the type
is not of a Long. You do not need to use .l to identify a Long because this is
the default variable type.

To return a variable use an
open bracket ( [ ) before the first percent sign that separates the function
name from the parameter types string. The first type in this string will be the
type that this function returns.

If a function passes
nothing and returns nothing then use a 0 for the parameter types
string.

Another important thing you
need to know about optional parameters is how to order them properly in the
GDKTable.txt. If you have three functions
MyFunc(Param1) and two other
functions of the same name with optional parameters at the end
MyFunc(Param1, Param2) and
MyFunc(Param1, Param2, Param3). You
must identify this by listing the functions consecutively in the GDKTable.txt
and by adding a value at the end of the function name to signify that it is of
the same name but should be called only if its optional parameter is called.
Here is an example of how to set this up properly:

If the function has
parameters that need to be reordered simply add another % at the end of the
parameter list and add the reordered parameters.
Put all of that together
and this is the completed GDKTable.txt for Advanced Terrain. Notice how there is
an extra command
Set Terrain Split() at the top of the GDKTable. It's
very important that you include one command with parameters from the original
DBTable as the first line of the GDKTable. This command is used to resolve the
plugin's dependencies at compile-time. The plugin will fail without this and not
run.

To create the source
code required to compile the plugin you need to pass the .gdt
template file to GDKLib Builder.exe. It can be passed from the command line
or by simply dragging and droping the file onto GDKLib Builder.exe.
The next step is to compile the generated source from
the
Sources directory. To do this, you must first have TailBite
installed. Don't forget to restart the IDE if it was open during the TailBite
installation otherwise you may encounter problems. To compile with TailBite
after opening the source file go to Tools -> TailBite to compile. If you have
a help file that you would like to have called when a user hits F1 for help
while highlighting your command in the PureBasic IDE you can enter it in the
following window that pops up, otherwise just hit OK.

The library that's
generated by TailBite will be written to your
..\PureBasic\PureLibraries\UserLibraries folder.

If you plan to
compile a threadsafe executable using this plugin then you must compile a
threadsafe Tailbite library. You can enable this option in the TailBite manager
(TBManager.exe). After changing this setting you must restart the PureBasic IDE
for the changes to take effect. PureGDK plugins compiled as threadsafe must be
copied into the PureGDKThreadSafe subsystem. Its location
is
..\PureBasic\SubSystems\PureGDKThreadSafe\PureLibraries.With
your new library prepared, restart the PureBasic compiler to recognize that a
new library exists by going to
Compiler -> Restart Compiler from the
PureBasic IDE. If you did everything correctly then your plugin should now work!
That's all there is to it. :)

PureGDK provides a tool for quickly outputting the syntax
of a command generated by GDKLib Builder. This file is located in the
plugins-sdk directory along with GDKLib Builder. To output a syntax file simply
drag and drop your .gdt file on top of the executable or pass it from the
command line. The syntax file will output to your current working
directory.