Plug-in Environment

Plug-in Environment

Running DLSim 3 with plug-ins

Plug-ins are archived in jar files Plugins.jar, Plugins0.jar, Plugins1.jar, ... Plugins9.jar. If these files reside in the same directory as DLSim3.jar, they will be automatically loaded when DLSim 3 is launched, either through double-clicking or by invoking the command:

java -jar DLSim3.jar
Alternatively, you can specify the directory containing the plug-in archives by binding it to the runtime property "plugins.home"; e.g.
java -Dplugins.home=plugins -jar DLSim3.jar

dlsim.prop

A plug-in archive is described in the property file dlsim.prop, which must be present either in the META-INF directory of jar files Plugins.jar, Plugins0.jar, ... Plugins9.jar, or in the DLSim launch directory. dlsim.prop must include a binding for the root plug-in directory and a description of the plugin package structure through bindings to properties as illustrated in the example below.

Defining the Library Hierarchy

Each dlsim.prop defines the plug-in library containined in a plug-in archive (Plugins*.jar) Suppose we have the following plugin packages and classes in our library:

plugins.Plugin0
plugins.Plugin1
plugins.components.Register
plugins.components.alus.ALU4
plugins.components.alus.ALU8
This hierarchy will be reflected by a corresponding set of submenus for selecting plugins in the running DLSim 3. The entries in dlsim.prop that describe this hierarchy are shown below
plugin.dir = plugins
   
plugins.submenus = components
plugins.classes = Plugin0 Plugin1
plugins.components.submenus = alus
plugins.components.classes = Register

plugins.components.alus.classes = ALU4 ALU8
Since plugins is the root directory, it is assigned as the property value to property plugin.dir. For each directory in the tree, use the suffix .submenus to list any submenus (i.e. subdirectories; package extensions) and the suffix .classes to list any plugin classes that appear at that level.

In the simplest case a "flat" package structure requires only the following 2 lines:

plugin.dir = plugins
plugins.classes = Plugin0 Plugin1 [etc.]
Associating Document and View Classes

dlsim.props is also used to associate a customized view class with its plugin class. To do so, include an entry in the dlsim.prop file of the following form:

[plugin class].view = [fully qualified plugin view class]
For example:
MUX4.view = plugins.components.mux.MUX4View
Note that the view class uses the fully qualified name. Consequently, authors may choose to package view classes together with their corresponding plugins, or group all views into one or more separate packages.

Name Clashes and Precedence

A plug-in archive containing a dlsim.prop properties file is a self-contained unit designed to be easily added to a DLSim 3 environment. However, since the XML file recording a circuit only includes the plug-in classname (and not its package), there is a need to avoid ambiguity when referring to plug-in classes.

Each plug-in archive should be able to avoid internal name clashes, such as including 2 classes from different packages with the same classname; e.g. plugins.mips.Register and plugins.mic1.Register. (In such a case, the one that appears first in dlsim.prop will be used.) The problem is solved by simply calling the first MipsRegister, and the second Mic1Register.

There is a real problem, however, when using multiple plug-in archives, possibly from different sources. DLSim 3 sorts this out by assigning the order of precedence as Plugins.jar, Plugins0.jar, ... Plugins9.jar. The best solution is to create a custom dlsim.prop for the directory containing these archives. The system will "stitch together" the property definitions contained in the archives and the default directory. In case of inconsistencies, the latter will take precedence, followed by the jar files in numerical sequence