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 OptionDevelop 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 of these files must be modified for the new Option. The procedure for modifying the template files is described in the next step. The following tables list the files that were copied from the template directory tree:
Files | Used for: |
|---|---|
Makefile | Controls the building of an Option. |
buildmachine | Defines a build machine for a given UNIX platform. |
init.mkinc | Common macros, variables for Makefile. |
src/Makefile | Controls the building of the source files. |
src/option_info.h | The Option definition template. |
src/option_table.c | The Option Table definition. |
src/option_routines.c | The Option user routines template. |
src/option_rs6000.exp | The exported symbols for the Option Table (AIX only). |
src/option_rs6000.imp | The imported symbols for the Option (AIX only). |
src/depend.mkinc | Dependencies target for make. |
src/flags.mkinc | Defines cc, ld flags based on platform. |
src/axposf.mkcfg | specific make flags. |
src/hps700.mkcfg | HP-UX specific make flags. |
src/rs6000.mkcfg | RS6000/AIX specific make flags. |
src/sgi.mkcfg | SGI/IRIX specific make flags. |
src/solaris.mkcfg | SPARC/Solaris specific make flags. |
src/linux.mkcfg | Linux specific make flags. |
bin/Makefile | Controls the building of the Option shareable libraries. |
lib/Makefile | Controls the compilation of the PV‑WAVE procedures. |
Files | Used for: |
|---|---|
makefile.nt | Controls the building of an Option. |
src\makefile.nt | Controls the building of the source files. |
src\option_info.h | The Option definition template. |
src\option_table.c | The Option Table definition. |
src\option_routines.c | The Option user routines template. |
src\option_table.def | The module definition file for the Option Table. |
src\option_routines.def | The module definition file for the Option. |
Step 2: Modify the Template Files
Next you need to modify some of the files that were copied from the template directory. In general, you will change generic names given in the template files to the name of your Option. The following tables list the files that you need to modify and tell you exactly what modifications to make to each file.
Files | Modification |
|---|---|
Makefile | Change the ROOTNAME variable to the name of your Option directory. |
buildmachine | Define a build machine for the supported platform(s). |
init.mkinc | Change the ROOTNAME variable to the name of your Option directory. |
src/Makefile | Change the ROOTNAME variable 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_rs6000.imp | Add (or delete) the IMPORTed PV‑WAVE routines used in your Option (AIX only). |
bin/Makefile | Change the ROOTNAME variable to the name of your Option directory. |
lib/Makefile | Change the ROOTNAME variable to the name of your Option directory. |
Files | Modification |
|---|---|
makefile.nt | Change the ROOTNAME variable to the name of your Option directory. |
src\makefile.nt | Change the ROOTNAME variable 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. |
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.
If you want to split your Option routines into several separate files, you have to modify the appropriate build files:
(UNIX) src/Makefile
(WIN) src\makefile.nt
note | Windows platforms require the LibMain function to be defined in one of the files containing the Option routine code. AIX/RS6000 platforms require a list of the Option procedures and/or functions to be defined in the set_sys_table function defined in the option_routines.c file (for details, refer directly to the file src/option_routines.c). |
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. The template Makefile is available in the lib subdirectory to create PV‑WAVE compiled files (.cpr) from PV‑WAVE procedure files.
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>% gmake all TARGARCH = '<platform name>'
The log file BuildLog.<platform> contains the results of the build.
note | The UNIX Makefiles are written for gmake, the FSF GNU version of make. |
To build the Option shareable libraries for Windows platforms use:
Z:\VNI> cd <Option_Dir_Name>$ nmake all -f makefile.nt
note | The environment variables/logicals RW_DIR and WAVE_DIR must be set before building the Option. Refer to the PV‑WAVE User’s Guide if you any questions about these variables. |
Step 6: Test the New Option
Place the tests written for the new Option in a test subdirectory.
