The best way to fit your own application-specific code into Darwin2K is to create a self-contained dynamic library called a 'plugin'. The plugins that are used by Darwin2K programs at runtime are determined at runtime: you can specify one or more plugins in a p-file, and they'll be loaded and an initialization routine will be called, which can do things like add your own classes to the Darwin2K runtime database. This in turn will let you use your own modules, d2kComponents, and d2kSimulators (among other things) in the same manner as the core Darwin2K classes.The main advantage of plug-ins is that all of your changes (in most cases) can be confined to your own files, in a separate directory. Thus, if you want to upgrade Darwin2K, you can do so without having to worry about what happens to all the changes you made, and multiple users can have their own specialized code while sharing the same core Darwin2K installation.
In some cases, you might just want to tweak the internals of an existing Darwin2K class. This may well be easier done in the core Darwin2K distribution; however, if you decide to upgrade to get added functionality or a bug fix, you'll have to deal with making sure that change gets preserved. It's worth thinking about just making a subclass of the particular class you want to change, overriding the specific methods you're interested in, and putting that in a plugin. Or, for example, if you just need to perform some small modification at initialization time, you can create a new d2kComponent, load and initialize it via a p-file, and have it do its job.
You probably get my point: use plugins whenever possible, even if it's a little extra work. It's not too hard to do; there's even a program called darwin2k-makeplugin that'll set up all the files you need to compile a plugin, so you can just fill in the guts without worrying about stuff like Makefiles.
You'll need reasonably up-to-date versions of libtool, autoconf, and automake to use darwin2k-makeplugin. As of 1/25/02, the versions used by Darwin2K 0.90 are:
- GNU autoconf 2.52
- GNU automake 1.5
- GNU libtool 1.4
Using darwin2k-makeplugin is easy: create a directory for the plugin and cd into it, then run darwin2k-makeplugin. This will generate a bunch of files, including a Makefile.am, installation instructions, and sample source files. Then, run './build.sh' to compile and build things.
A sample evaluator class is included; you can fill in the methods as needed. (You can add other class types beside evaluators; just make sure you include them in the initializeUserEvalDB() and initializeUserPMDB() functions, which get called at startup by the simulation or PM programs, respectively.)
To use your plugin in an existing Darwin2K binary, add a line to the #libraries section for your plugin. Darwin2K will keep trying to read variables named 'libraryName0', 'libraryName1', etc., until it fails to read one. For example, the top of your p-file for a simulation (e.g. using evStandaloneGL or evaluator) might look like this:
char simType[80] = "myEvaluator"; char componentDBFilename[200] = "software/src/myEval/componentDB"; ...
#libraries int numLibs = 2; char libraryName0[80] = "libsynEvalRover.so"; char libraryName1[80] = "libMyEval.so";
...
#myEvaluator int foo = 1; double bar = 2.0;
...
In case you're wondering how you can actually access the classes defined in your plugin, the answer is that the functions 'initializeUserEvalDB' and/or 'initializeUserPMDB' get called after the library is loaded, depending on whether it's a simulator or the PM that's doing the loading. These functions, in turn, add your classes to the global runtime database of classes so that they can be instantiated at runtime based on classname. So, you should edit the 'initializeUserEvalDB' and 'initializeUserPMDB' functions to add your d2kSimulators / evaluators / d2kComponents / modules to the database. Examples are provided, so it's pretty easy.
There's a disp.p file created by darwin2k-makeplugin, which shows how to load your plugin. After you build your plugin using the build.sh script, you should be able to run:
and have a display come up showing a simple configuration. (displayCfgGL automatically looks for disp.p in the current directory, so it'll pick up your plugin from there.) If you don't get a display, then something didn't work with the plugin--look through the output of displayCfgGL for a message starting with 'ERROR', and try the darwin2k-users list if you can't figure it out.displayCfgGL testCfg.l
So, that's basically it. Run darwin2k-makeplugin, stick your own code in, and add your library and initialization function to the #libraries section of the p-file.
See the FAQ for troubleshooting info if you run into problems, and send email to darwin2k-users@lists.sourceforge.net if your problem isn't covered. You might also check out src/d2k/apl/demos/ for a sample plugin that's used in the hex demo.
Alphabetic index Hierarchy of classes