Creating and Maintaining Chapters
Creating a Chapter
from the S-PLUS Command Line
-
Makefile
creation and building the
chapter DLL
-
Sourcing S-PLUS chapter code
Creating a Chapter from a DOS Shell
Creating
a Chapter using Microsoft Developer Studio Wizard
-
Sourcing S-PLUS code from
Developer Studio
-
Debugging your C++ or FORTRAN code from
Developer Studio
Chapter
Introduction
A chapter can be created
either from the S-PLUS command line or a DOS shell. Before running the chapter software, first create the folder (the
directory) that will contain the chapter.
Place all C (files with the .c extension) , C++ (.cpp, or .cxx) ,
FORTRAN (.f or .for) , and resource (.rc) files that will make up the chapter’s
DLL in the folder. Also place all files containing S-PLUS
source code (.q or .ssc) in this folder.
Alternatively, if you are
using Microsoft’s Developer Studio with the Microsoft’s Visual C++ compiler or
the DEC Visual FORTRAN compiler, a chapter wizard will be available after
installing S-PLUS.
Once a chapter is created
and debugged, the attach command (or library command) will attach the S-PLUS
database and load the DLL associated with the chapter.
Creating a Chapter
from the S-PLUS Command Line
The following S-PLUS
functions exist for creating a chapter:
logical
createChapter(where, makefile = F, undo = F, files = "", mustWork =
F)
logical makeChapter(where,
files = "")
logical
sourceChapter(where, files = "")
Here, where is the folder (directory path) for the chapter, for example
“E:\\Work\\NewRobust”. The function createChapter will ensure that the correct
database folders exist in chapter. If
the logical argument makefile value
is equal to T (true) a makefile, named Make.mak, and a make include file, named
Chapter.mif are created. The files
argument is only used if makefile=T.
See the section on Makefile
creation and building the chapter DLL for details. If the value of makefile is F (false, the default), only
the database directory structure is created.
The logical undo argument
specifies that the chapter should have the __init and __prev directories
required by the S-PLUS undo function.
Set logical argument mustWork
to T (true) if you want the S-PLUS stop
command issued if the function fails to create the chapter.
The function makeChapter,
will build a makefile and execute your make utility using the existing make.mak
makefile, whereas the sourceChapter function will source the all the S-PLUS
source code found in the chapter folder.
These functions are discussed next.
Makefile creation and building the chapter DLL
The function makeChapter
searches the specified path for any C, C++, or FORTRAN source files. If any files are found, a make include file
is created, named Chapter.mif, containing the SRC and OBJ macro definitions
used in the rules makefile that builds the target DLL. If the Chpater.mif file is replaced a backup
of the original is stored in a file with the extension .bak.
The name of the chapter
makefile must be make.mak. If this
makefile does not exist in the chapter folder, one is created by copying the
rules makefile into the chapter folder.
Within the rules makefile an include preprocessor directive must exist
that specifies the Chapter.mif file.
Once the Make.mak file exists in the chapter folder you are free to
modify any of the compiler or linker switches without any risk of the file
being changed by S-PLUS. For example,
you may wish to turn on (or off) the debugging flags for the compiler or
experiment with different optimization switches.
The name of the rules
makefile, the makefile containing all the rules for compiling and linking the
DLL, is extracted from the Splus.ini file found in $(SHOME)\cmd.
A default rules makefile
is provided for the Microsoft compiler and nmake.exe utility, Mrules.mak, and is found the cmd folder of
your SHOME.
The chapter section of the
Splus.ini file contains two keys, rules
and make, that specify the name of
the file containing the target DLL rules and the name of the make utility. For example, the chapter section below
specifies mrules.mak as the rules file and Microsoft’s nmake.exe as the make
utility.
[chapter]
rules = mrules.mak
make = nmake.exe
Sourcing S-PLUS
chapter code
The S-PLUS function
sourceChapter sources all the S-PLUS source files within the chapter, specified
by the where argument. These files
have the extension .ssc, .q, or .s. The
chapter database where is attached to
position one in your search list. On
exiting sourceChapter, the chapter database is detached or reattached to its
original position if it was not the working database when the function
started. Moreover, the current working
directory (folder) is temporarily changed to the chapter folder (for the
duration of sourcing the S-PLUS files) so that files included within a user’s
source code can have a path relative to the chapter folder.
Example
The chapter example below
is provided in samples\gausssdl that contains both C++ and S-PLUS code that
solves a linear system using Gauss-Seidel iterative method. Here, the three commands createChapter,
makeChapter, and sourceChapter create the chapter database, compiles and links
the C++ source code to produce the S.dll, and sources the chapter S-PLUS source
code. Following the createChapter
command we attach the chapter and compare the time it takes to implement the
iterative method using S-PLUS code and the SPL C++ library.
ch = paste(getenv("SHOME"),"samples\\gausssdl",sep="\\")
createChapter(ch)
makeChapter(ch)
sourceChapter(ch)
attach(ch,name="gausssdl")
A = matrix(rnorm(100),nrow=10)
#Change A to be diagonally dominant
diag(A) = seq(ncol(A),ncol(A))
b = rnorm(ncol(A))
#Gauss-Seidel implemented in pure S-PLUS code
sys.time({x1 = gaussSeidel(A,b)})
#Gauss-Seidel implemented in SPL C++ code
sys.time({x2 = .Call('gaussSeidel',A,b)})
all.equal(x1,x2)
Creating a Chapter from a DOS Shell
A chapter utility program,
chapter.exe, has also been provided that will create an S-PLUS chapter from a
DOS shell. Command arguments to the
chapter utility give the user control on what function it will perform. Below is a summary of those commands.
BOOT (-b) command
The BOOT command (or –o)
directs the chapter utility to “boot” the chapter. That is, construct the
“big file” .Data\__Objects and .Data\__Meta\__Objects. This command is run after all S-PLUS code
and data is successfully sourced into the chapter database.
BUILD (-b) command
The BUILD command (or –b)
will direct the chapter utility to verify the chapter directory structure and
make the chapter DLL (or –m) and source all the S-PLUS code use the BUILD command (or –b), i.e. chapter BUILD.
Chapter folder, -d command
The default chapter
directory will be the current working directory, the CWD. This is the folder you were residing in when
the chapter utility was started. Use
the –d command to specify a directory path for a new chapter other than the
CWD.
MAKE (-m) command
The MAKE comand (or –m)
will direct the chapter utility to construct the make include file,
chapter.mif, containing the SRC and OBJ macros defining the files containing
the compiled code for the chapter. If
Make.mak does not exist, one is copied from the rules makefile specified in the
Splus.ini file in $SHOME\cmd. Postfix to the command a list of source files if
you wish to include only a subset of the source files in the DLL. For example,
chapter –m file1.cpp
file2.for
would result in
defining the OBJ macro to be file1.obj
and file2.obj in the make include file and executing your make utility (see the
Makefile creation and building the chapter DLL section for details). This is equivalent to using the command
“nmake –f Make.mak”, assuming that you use the Microsoft nmake.
Rules file, -r
command
You can specify the make
file containing the rules for building the target S.dll using the –r command
followed by the file path. If only the
filename is given, it is assumed to be in the cmd folder of your SHOME. The rules makefile must have the include
directectve for the Chapter.mif file containing the OBJ and SRC macros. For the Microsoft nmake utility the
directive syntax is:
!include
<chapter.mif>
SHOME (-h) command
If you do not have the
environment variable SHOME set, use the SHOME (or –h) command to specify the
folder path where S-PLUS was installed.
HELP (?) command
The HELP command (or ?)
will display a menu of the available commands for the chapter program.
SOURCE (-s) command
The SOURCE command (or –s)
directs the chapter utility to source all S-PLUS files in the chapter. S-PLUS source files are recognized by the
extensions .ssc, .q, or .s.
Postfix a list of S-PLUS source code files if you wish to only source a subset of the S-PLUS source files in the chapter folder (see the Sourcing S-PLUS chapter code section for details).
Undo –u
The –u command directs the
chapter utility to add the __init and __prev directories required by the undo
S-PLUS command.
Example
The chapter example below
is the same as the previous example, except here we “boot” the chapter.
chapter -h e:\splus6 -d e:\splus6\samples\gausssdl -bo
Creating a Chapter
using Microsoft Developer Studio Wizard
A chapter wizard exists
for developers using Microsoft Visusal C++ 6.0 and the Developers Studio. After installation of S-PLUS, the chapter wizard is available in the
Projects tab of the New dialog. The New
dialog is initiated by selecting the File/New menu item.
There are two wizards
available: one for C++ and the other for FORTRAN. Select one or the other, then
enter the folder location for the project and the name of the project (the
Developer Stuido project will be the S-PLUS chapter). In the example above, we entered E:\Work for the location and
named the project NewRobust. The
complete path, E:\Work\NewRobust, was completed automatically by the wizard. On selecting the OK button, the wizard
displays a second dialog that will allow you to modify the path for the
location of the S-PLUS DLL, the Sqpe.dll.
The path to the Sqpe DLL is optional and can be left blank.
After selecting Finish, a
new project is created containing the initial code required for a chapter.
In the NewRobust example
we have the header file NewRobust.h prototyping the two new fuctions
NewRobustDotC and NewRobustDotCall, the implementation file NewRobust.cpp,
contains the source code stubs for the two functions. The content of the code is is left for the user implement and is
marked with “TODO” comments. The skeleton S-PLUS code is provided in the
NewRobust.ssc file. In the screen shot
above we see the S-PLUS .Call function for our C++ function NewRobustDotCall.
Now, wasn’t that
easy! This frees up your time to work
on the real problem: what is the New Robust method you have in mind?
Sourcing S-PLUS code from Developer Studio
Using the Microsoft
Developer Studio custom build feature, your S-PLUS source code can be sourced
into your chapter database without leaving the Developer’s Studio. First, with your mouse, right click on the
node of the Workspace tree control representing the NewRobust.ssc source
file. Select the Settings… context menu item to obtain the Project Settings dialog
displayed below.
Enter “chapter -s
$(InputPath)” into the Commands field of the Custom Build tab of the Project
Settings dialog (see the –s command of the chapter utility for details). The dialog requires that the Outputs field
have an entry. The file specified here is used by Developer Studio to establish
the dependency that determines when to “recompile” the source code. However, sourcing S-PLUS code into the
chapter database does not produce any file that is usable by Developer
Studio. As a work-around, place the
string “$(InputName)” in the Outputs
field and make sure the “Exclude file from build” checkbox is selected in the
General tab of the dialog. When
complete, select OK.
Now right click on the
node representing the NewRobust.ssc file and select the Compile NewRobust.ssc menu item.
Debugging your C++ or FORTRAN code from Developer Studio
To debug the S.dll for the
Microsoft Developer Studio, follow the
steps below:
1. Select "General" in the
"Catagory:" drop-down list of the "Debug" tab in the
Project Settings dialog.
2. Change the “Executable for debug session:"
editbox to the full path of the SPLUS.exe executable
3.
In the “Program
arguments” edit control enter S_DATA=chapter
folder, where chapter folder is
the directory path to you chapter.
4.
Now select
“Additional DLL’s” in the “Category:” drop-down list and enter the path to your
S.DLL in the “Local Name” list control.
5.
Enter OK
In step 4 we specified to
Developer’s Studio to preload the S.DLL since it is not loaded by S-PLUS
implicitly. This alows us to set break
points in the C++ code before starting S-PLUS. However, this disables the Edit
and Continue feature of the Microsoft 6.0 compiler. If you wish to use the Edit
and Continue feature of the Microsoft C++ compiler, skip step 4, but you will
have to set your break points after S-PLUS has explicty loaded the S.DLL.