Creating An Option

PV-WAVE Foundation > Programmer Guide > Creating an OPI Option > Creating An Option

Creating An Option

The Option developer must create two shared objects. The first is the Option Table, which contains information regarding the number of functions, the number of procedures, the names of the functions and the names of the procedures and the feature name and version. The second shared object contains the actual code for the routines described in the Option Table.

Option development consists of the following steps:

Create a new Option directory structure. This can be done using a template that Rogue Wave has provided.

Modify the template files for the new Option

Develop the Option code

Define the Option table

Build the new Option

Test the new Option

Step 1: Create a New Option Directory Structure

To begin, copy the option-templates directory tree in the main Rogue Wave directory (the directory to which the RW_DIR environment variable/logical points). Give the new directory a name that follows the naming convention outlined in the section "Main Directory Requirements".

For example, to create the new Option directory tree for the SAMPLE Option, enter the commands shown at the system prompt:

UNIX

% cd $RW_DIR

% cp -r option-templates sample-1_0

Windows

> cd %RW_DIR%

> xcopy option-templates sample-1_0

The new Option directory structure contains a number of files needed to build the Option. Some files must be modified for the new Option. The procedure for modifying the template files is described in the next step. Table 14-2 lists the files that were copied from the template directory tree:

Option Files
Files	Used for:
CMakeLists.txt	Controls the building of an Option.
src/CMakeLists.txt	Controls the building of Option source files.
src/option_info.h	The Option definition template.
src/option_routines.c	The Option user routines template.
src/option_routines.def	The module definition file for the Option. Windows-specific.
src/option_table.c	The Option Table definition.
src/option_table.def	The module definition file for the Option Table. Windows-specific.

Step 2: Modify the Template Files

Next, modify some of the files that were copied from the template directory. In general, this entails changing generic names given in the template files to the name of your Option. Table 14-3 lists the files that you need to modify and tell you exactly what modifications to make to each file.

Files to Modify
Files	Modification
CMakeLists.txt	Change the project() name to the name of your Option directory.
src/option_info.h	See the section "Step 4: Define the New Option Table".
src/option_routines.c	See the section "Step 3: Develop the Option Code".
src/option_routines.def	Define the EXPORTed Option routines, and the IMPORTed PV‑WAVE routines used in your Option. Windows-specific

Step 3: Develop the Option Code

The template file option_routines.c is available for developing the Option procedures in C. If you have a limited number of Option routines written in C, it is recommended that you place them in the option_routines.c file.

To split your Option routines into several separate files, modify the build file src/CMakeLists.txt.

note	Windows platforms require the DllMain function to be defined in one of the files containing the Option routine code.

If PV‑WAVE procedure files are part of your Option, they should be placed in the lib subdirectory. That is because PV‑WAVE automatically appends all option directories located in the directory pointed to by the RW_DIR environment variable/logical and that contain the subdirectory lib to the !Path system variable.

Step 4: Define the New Option Table

The Option Table needs to contain information regarding the number of functions and procedures in the Option, the names of the functions and procedures in the Option, the feature name, and version of the Option.

This information must be entered into a template file, option_info.h, located in src subdirectory. Just open this file and fill in the required information as indicated in the comments. Here is a sample of the file with some additional notes:

/* Option Feature Identifier: Place the string between the double

   quotes. Leave this string blank for unlicensed options. */

static char feature[] = ””;

/* Option Version Identifier: Replace the 0.0 with the

   option's version */

static double version = 0.0;

/* Option Functions: Enter the number of option functions and

   the option function names below. Enter one name per string

   in the ”function_names” array. Function names must be in

   upper case and listed in alphabetical order. */

static int nm_functions = 0;

static char * function_names[] = {

};

/* Option Procedures: Enter the number of option procedures

   and the option procedure names below. Enter one name per

   string in the ”procedure_names” array. Procedure names

   must be in upper case and listed in alphabetical order. */

static int nm_procedures = 0;

static char * procedure_names[] = {

};

Step 5: Build the New Option

The procedure for building an Option, as explained in this section, is platform dependent.

To build the Option shareable libraries for UNIX platforms use:

% cd $RW_DIR/<Option_Dir_Name>

% mkdir build

% cd build

% cmake -DCMAKE_BUILD_TYPE=Release -DWAVE_DIR=$RW_DIR/wave ..

% make

To build the Option shareable libraries for Windows platforms use:

> cd %RW_DIR%/<Option_Dir_Name>

> mkdir build

> cd build

> cmake -G "NMake Makefiles" -DCMAKE_BUILD_TYPE=Release -DWAVE_DIR=%RW_DIR%\wave ..

> nmake

note	The environment variable RW_DIR must be set before building the Option. Refer to the PV‑WAVE User’s Guide for more information bout these variables.

Step 6: Test the New Option

Place the tests written for the new Option in a test subdirectory.