Create a chapter

DESCRIPTION:

Create a chapter

USAGE:

createChapter(where, makefile=F, undo=F, files="", mustWork=F)

REQUIRED ARGUMENTS:

where
the directory path to the new database.

OPTIONAL ARGUMENTS:

makefile
logical variable indicating whether a makefile should be created. The name of the makefile will be make.mak. A make include file will be created named chapter.mif.
undo
logical variable indicating whether the undo directories, __init and __prev, should be created within the database directory .Data.
files
character vector containing the names of specific C, C++ and FORTRAN source code to be used in building the chapter DLL.
mustWork
logical variable indicating that if the chapter creation fails, a stop command will be issued.

VALUE:

a character vector of length 1 containing the full path to the chapter.

DETAILS:

The function createChapter will ensure that the correct database directories exist in a chapter. If the logical argument makefile is F (false, the default), only the database directory structure is created. If the value of makefile value is equal to T (true), a makefile named Make.mak and a make include file named Chapter.mif are created. In this case, the function 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 Chapter.mif file is replaced, a backup of the original is stored in a file with the extension .bak. Specific source files can be given, using the character vector files. If the argument file is not empty, a search for source files is not done.

The name of the chapter makefile must be Make.mak. If this makefile does not exist in the chapter directory, one is created by copying the rules makefile into the chapter directory. 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 directory 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 an nmake.exe utility, Mrules.mak, and is found in 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

After the makefile is created, the make utility specified in the Splus.ini file will be executed with the arguments -f make.mak . Output from the make utility will be piped to the commands window.

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.__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.

SEE ALSO:

,

EXAMPLES:

# create a subdirectory and chapter called "testChapter"
createChapter("testChapter")
createChapter(paste(getenv("SHOME"),"samples/gausssdl",sep="/"),
makefile=T, mustWork=T)