Products : RacerPro : Version 2.0 preview : Plugins:
On this page we present the plugin mechanism introduced with RacerPro 2.0.
Introduction
By using plugins the development of customized solutions for special purposes is becoming much easier for both the developer as well as the manufacturer of RacerPro 2.0 as it makes the partners more independent from each other. Since a certain functionality required for a customer or in a project can now be developed and deployed without synching with the release schedule of RacerPro. On the other hand, the manufacturer can provide patches for delivering small enhancements or minor bug fixes more quickly and additional functionality can also be distributed to beta testers more easily. Extending the server with self-written functions is possible also via MiniLisp, another new feature of RacerPro 2.0 that should be mentioned here. However, plugins are much faster and can access the entire memory structures of RacerPro 2.0.
If you are interested in writing your own code which shall be integrated into the RacerPro 2.0 server you have to use the same application development environment that is used for compiling the RacerPro: Allegro Common Lisp (ACL) by Franz Inc.. Even an entry-level option of ACL is sufficient for writing and compiling your program which has to be saved as a "FASL" file. That Fasl (sort of Lisp library) can be wrapped into a plugin by RacerPro 2.0. You see, you get really independent with this plugin feature.
Of course, Racer Systems GmbH & Co. KG is also offering customized development as a service. Please contact us if you have an idea for a project or a certain demand.
Demonstration
For demonstration purposes we discuss the installation and use of a very simple example plugin. In order to test the plugin, please create a directory "racerplugins" (if it doesn't exist already) in the same directory which contains your RacerPro 2.0 application folder. Download the appopriate demo plugin for your platform from the list below and copy it into that "racerplugins" folder. The next time you launch RacerPro 2.0, it will automatically load all the plugins found there.
From the RacerPorter "Shell Tab", try the command
(installed-plugins)
to verify that the plugin has been installed, and check that it is working by entering
(say-hello-to yourname)
RacerPro will respond appropriately. The new "say-hello-to" API function is supplied by the plugin. Of course, this is just a demo function.
Download demo plugin (if not in package)
|
Demo Plugin for RacerPro 2.0 preview — Windows 22.2 KB Last modified: 06/03/2009 04:22:59 PM |
| This file is a sample plugin for the preview version of RacerPro 2.0. It contains an extension to the servers functionality by providing compiled code in text-encoded format. Please do not modify the content of the file. |
|
|
Demo Plugin for RacerPro 2.0 preview — Mac OS X 21.2 KB Last modified: 06/03/2009 04:22:59 PM |
| This file is a sample plugin for the preview version of RacerPro 2.0. It contains an extension to the servers functionality by providing compiled code in text-encoded format. Please do not modify the content of the file. |
|
|
Demo Plugin for RacerPro 2.0 preview — Linux 21.1 KB Last modified: 06/03/2009 04:22:59 PM |
| This file is a sample plugin for the preview version of RacerPro 2.0. It contains an extension to the servers functionality by providing compiled code in text-encoded format. Please do not modify the content of the file. |
How to write your own plugin and convert it for RacerPro 2.0
We are describing the process for Windows here. In order to write your own RacerPro plugin, use Allegro Common Lisp as the development environment. If you don't own a license, you can download the free "Allegro CL 8.1 Free Express Edition" from Franz Inc. for your platform.
Launch Allegro Express. First you will have to create a new so-called "mlisp image" of Allegro Express. This is described in the readme file in the acl81-express directory, where it says:
To build one of the available above images, start up allegro-express.exe and evaluate one or more of the following forms in the Debug window:
;; mlisp: (progn (build-lisp-image "sys:mlisp.dxl" :case-mode :case-sensitive-lower :include-ide nil :restart-app-function nil :restart-init-function nil) (when (probe-file "sys:mlisp.exe") (delete-file "sys:mlisp.exe")) (sys:copy-file "sys:allegro-express.exe" "sys:mlisp.exe"))"
After mlisp.exe has been created, quit Allegro Express and start mlisp.exe.
Develop your plugin code using mlisp.exe. Let us assume your source code looks as follows, and is contained in the file c:/temp/project/plugin.lisp:
(in-package :cl-user)
(defun implementation-of-say-hello-to (name)
(format nil
"Hello ~A, this is ~A ~A Build ~A. How are you today? This is your first RacerPro Plugin!"
name
(get-product-name)
(get-product-version)
(get-build-version)))
(defun say-hello-to (expr)
(case (intern (first expr) :keyword)
(:say-hello-to
(apply #'implementation-of-say-hello-to (rest expr)))
(otherwise
:hook-not-found)))
(ts::server-hook 'say-hello-to)
Since the ts package and the server-hook function don't exist, you'll have to create dummy versions of them before you can compile this Lisp source code into FASL (object) code. Simply evaluate:
cl-user(1):(defpackage ts)#<The ts package> cl-user(2):(defun ts::server-hook (x) x)ts::server-hook
to create the dummies.
Then, either compile plugin.lisp using the project mechanism or use compile-file as follows:
cl-user(3): (compile-file "c:/temp/project/plugin.lisp")
;;; Compiling file c:\temp\project\plugin.lisp
;;; Writing fasl file c:\temp\project\plugin.fasl
;;; Fasl write complete
Warning: While compiling these undefined functions were referenced:
get-build-version from position 25 in
c:\temp\project\plugin.lisp
get-product-version from position 25 in
c:\temp\project\plugin.lisp
get-product-name from position 25 in
c:\temp\project\plugin.lisp
#P"c:\\temp\\project\\plugin.fasl"
nil
nil
Note that you will get some warnings about undefined functions, but this is normal and will not affect the working of your plugin (when the plugin is loaded, the functions will be there in RacerPro). These undefined functions are RacerPro API functions which are documented in the Reference Manual.
The next step is to use RacerPro and RacerPorter to create a RacerPro plugin file from that FASL which loads into RacerPro. Proceed as follows. In RacerPorter, enter the following into the Shell:
[14] ? (make-plugin-from-fasl-file "c:/temp/project/plugin"
:platform "X86 WIN32"
:plugin-name "myplugin"
:short-description "My first plugin"
:for-version :accept
:for-build :accept)
*** WRITING PLUGIN TO myplugin-3453121189.racerplugin...
[14] > NIL
Of course, RacerPro must be running in unsafe mode for this (this is the default if you let RacerPorter start the RacerPro instance). You will now find the file "myplugin-3453121189.racerplugin" in your RacerPro folder.
This plugin can be loaded automatically the next time RacerPro is started, simply by putting it into the folder "racerplugins" in the RacerPro folder, or load it manually from the Porter Shell as follows:
[15] ? (load-racer-plugin "myplugin-3453121189.racerplugin")
nRQL Warning: Attempting to load plugin myplugin-3453121189.racerplugin.
nRQL Warning: Plugin 3453121189 sucessfully installed from file myplugin-3453121189.racerplugin
[15] > ((3453121189 "My first plugin" "Plugin 3453121189"))
And then test it as follows:
[16] ? (say-hello-to "michael")
[16] > "Hello michael, this is RacerPro 2.0 Build 2009-06-03. How are you today? This is your first RacerPro Plugin!"