Version 3 (modified by aydan, 11 years ago)

--

You can use the sample driver template to get started on writing a new Orca driver. The driver template consists of 3 projects:

  • core
    • specifies the API for all drivers of the given family, e.g., drivers for creating virtual machines
    • provides ANT tasks that invoke the driver API
  • specific device driver implementation
    • contains the implementation of a specific driver from the device family, e.g, a driver that creates Xen virtual machines
  • tests
    • contains tests for the driver and its ant taske

To use the template to generate a working skeleton for your driver do the following:

1. Make a work directory

mkdir scratch

2. Download the template

cd scratch
svn export https://geni-orca.renci.org/svn/orca/drivers/template/trunk template
mv template/convert.sh .

3. Edit the conversion script.

The following variables must be changed:

DEST=test
DEVICE_FAMILY=test
DEVICE_FAMILY_PREFIX=Test
VERSION=1.0-SNAPSHOT
FAMILY_NAME='Orca Test Device'
DEVICE_INSTANCE=testdevice
DEVICE_INSTANCE_PREFIX=TestDevice
DEVICE_INSTANCE_GUID=4d739173-8588-42b3-b301-b744e978de25
INSTANCE_NAME='Orca Test Device Driver'
TESTS_NAME='Orca Test Device Driver Tests'
  • DEST - top level directory for your driver, e.g., mydriver
  • DEVICE_FAMILY - package name for the driver family. The full package name will become: orca.drivers.${DEVICE_FAMILY}, e.g, mydriver
  • DEVICE_FAMILY_PREFIX - prefix to use for class file names for the driver family, e.g., MyDriver?
  • VERSION - you can leave it as it is
  • FAMILY_NAME - name you want to use in the pom for the driver family
  • DEVICE_INSTANCE - package name for the specific device. The full package name will become: orca.drivers.${DEVICE_FAMILY}.${DEVICE_INSTANCE}, e.g, mydevice
  • DEVICE_INSTANCE_PREFIX - prefix to use for class file names for the specific device, e.g., MyDevice?
  • DEVICE_INSTANCE_GUID - guid for your device driver. NOTE: you must generate a new one.
  • INSTANCE_NAME - name you want to use in the pom for the specific device
  • TESTS_NAME - name you want to use in the pom for the device family tests

4. After you modify the template settings, invoke the script

bash convert.sh

5. The script will generate a new directory ($DEST). You can compile the generate code by doing:

cd ${DEST}
mvn install

To test the driver you need to install it on in a node-agent service. Orca provides two helper projects to simplify this process:

  • orca/tools/config/trunk - contains tools to install and configure a node agent service
  • orca/tools/drivers/trunk - contains tools to simplify the installation of drivers

You will need to check out orca/tools/config/trunk and follow the instructions listed on this page. Once you have installed your node agent, you will need to check out orca/tools/drivers/trunk and add a link to the runtime directory from the config project, e.g.:

cd ORCA_TOOLS_DRIVERS_DIR
ln -s -f ORCA_TOOLS_CONFIG_DIR/runtime

Finally, you will need to add a link to the driver tools project in the top-level directory of your newly generated driver:

cd ${DEST}
ln -s -f ORCA_TOOLS_DRIVERS_DIR tools

The template assumes that your node agent is running on the localhost on port 6. If this is not the case with your setup you will need to do the following:

cd ${DEST}/$DEVICE_INSTANCE/ant
cp tests.properties user.properties

Edit user.properties and specify the location and port of your node agent service. Place a copy of the resulting file in ${DEST}/tests/ant

Once you have successfully run mvn install in ${DEST}. You can install the driver by:

cd $DEVICE_INSTANCE
ant install

To run the unit tests for the driver:

cd tests
ant copy.local   (do this to make sure log4j will log to a file)
ant tests.device

To test the ant tasks:

cd tests
ant -f test.xml clean
ant -f test.xml greet