pi

 Pi is a scheme interpreter.

SYNOPSIS
pi [file] [arguments]

Pi executes ordinary read-eval-print loop if invoked without any arguments. It exits when expression (exit) is evaluated.
If invoked with command line arguments, pi considers the first argument as file name unless it is "--", and loads named file before entering read-eval-print loop. Subsequent arguments may be used to give parameters to application program. To get command line arguments from program, use global variable *invocation-arg* or procedure rp:command-line-arguments. Use "--" as the first argument to give arguments to pi without loading any files. If pi is invoked with no arguments or "--" as the first argument, and if the environment variable RHIZOME_PI_RC is set, content of it is evaluated before entering read-eval-print loop.
The functionality of pi is implemented by the module rp_pi included in standard library. Specifying rp_pi: as the last argument of pisl creates scheme interpreter augmented with compiled procedures in other modules linked together. In fact, pi itself is reproduced by the command line "pisl rp_pi:". In detail, module rp_pi does the following.
  1. At the start of execution, *invocation-arg* contains command line.
  2. If the first argument is "--", delete it from *invocation-arg*. Otherwise, if there is any argument, delete zeroth argument (the command name itself) from *invocation-arg*. If there is no argument at all (aside from zeroth one,) remain *invocation-arg* intact.
    1. If there was no arguments or the first argument was "--", test the environment variable RHIZOME_PI_RC and eval its value if it was set.
    2. If there was any argument and first of them was not "--", load it.
  4. If step 2 overs and pi is still executing, break procedure (it is, the read-eval-print loop) is invoked with prompt derived from car of *invocation-arg*. This is not a facility of module rp_pi in fact and done regardless of whether module rp_pi is linked in or not.

*invocation-arg* global variable
Initially, this holds command line arguments as a list. In interpreter pi, this list begins with first argument (loaded prorgram). In compiled program, this list begins with zeroth argument (name of load module). In any case, arguments to program begins from second element, so the same logic may be applied to retrieve command line arguments regardless to whether program is run under interpreter or is compiled.
Notice that this is a usual variable and may be assigned to change value at will.

(rp:command-line-arguments) procedure
Returns command line as a vector. This is a whole command line in any situation. No method is provided to change the value of this procedure, aside from overwriting the procedure itself.

EXAMPLE 

$ cat arg.scm
(display "*invocation-arg* is               ")
(write *invocation-arg*)
(newline)
(display "rp:command-line-arguments returns ")
(write (rp:command-line-arguments))
(newline)
(exit)
$ pi arg.scm foo bar baz
*invocation-arg* is               ("arg.scm" "foo" "bar" "baz")
rp:command-line-arguments returns #("pi" "arg.scm" "foo" "bar" "baz")
$ pisc arg.scm
$ pisl arg
gcc -O2 -m486 -I/u/qfwfq/lib/rhizome -c arg.c
gcc -O2 -m486 -I/u/qfwfq/lib/rhizome -c a.c
gcc -L/u/qfwfq/lib/rhizome a.o arg.o -lrhzscm -lrhzpi -lrhizome -lm
$ ./a.out foo bar baz
*invocation-arg* is               ("./a.out" "foo" "bar" "baz")
rp:command-line-arguments returns #("./a.out" "foo" "bar" "baz")

piw

 Piw exists only in Win32 platform. This is a scheme interpreter like pi and differs only in the following points.

pisc

 Pisc is a scheme compiler that converts scheme program to program in C language.

SYNOPSYS
pisc -help
Outputs brief summary of command line syntax.
pisc [options] file
Converts file to program in C language.

OPTIONS

-module module-identifier
Gives module name module-identifier. Module name is a name you specify to pisl when creating executable. This must be a valid identifier in C language. Default is the name of source file without ".scm" suffix (if the file name had one.)
-output filename
Specifies file name of output. Defualt is module name with ".c" suffix.
-mpath dir
Add dir to search path of rp:use-macro-package. This option may be used multiple times.
-load filename
Loads named file into the environment of compiler befor reading source file. This may be used in the purpose of defining macros at compile time. This option may be used multiple times.

pisf

 Pisf converts scheme programs into (in typical cases) easy to load format. Generated file can be loaded by load procedure as for source file, but is not human readable. Typically, output file is smaller than source file, but macro expansion may result in huge outout. For large (after macro is expanded) programs, exacution of pisf may take long time. Pisf can optionally generate C programs insted of loadable file. In this case, resulting program is usually smaller than output of pisf but expressions in source are executed by interprester.

SYNOPSYS
pisf -help
Outputs brief summary of command line syntax.
pisf [options] file
Converts file.

OPTIONS

-exec interpreter
Output executable script file for unix like operating systems. Specify full pathname of executable to execute the program. First line of resulting file will have form "#!interpreter".
-module module-identifier
Genarate C program. Module-identifier has the same meaning as in pisc and resulting file can be specified as module to pisl as if it was output from pisc.
-output filename
-mpath dir
-load filename
These options has the same meaning as in pisc.

pisl

 Pisl compiles programs in C language generated by pisc and links with run time libraries to generate executable file.

SYNOPSYS
pisl -help
Outputs brief summary of command line syntax.
pisl [options] module-specifier ...
Binds modules specified by module-specifier together and generates executable file.

OPTIONS

-cc cc-command-line
Specify command line of C compiler. Default is printed in the output of `pisl -help'.
-ld ld-command-line
Specify command line of linker. Default is printed in the output of `pisl -help'.
-nold
Supress execution of linker.
-nolib
Supress linking with default run time library. Default library specification is printed in the output of `pisl -help'.
-loadable
Create shared object insted of executable. Resulting object can be loaded by the procedure rp:load-compiled-module. In some environment, this option is not supported.
-static
Make resulting executable run without specific shared object. Size of executable file becomes substantially large. In some environment, this option is always in effect.
-modlib
Create shared object which can be used as input module file at another pisl invocation. In some environment, this option is not supported.
-windows
This option has effect only in Win32 platform. When this is specified, pisl generates GUI application of Win32. Generated executable launches detatched from console and gets its own console when it accesses console first time.
-o filename
Specify the name of executable file generated. If this option is not specified, linker determines the name of executable.
-s filename
Specify the name of file that contains startup code (the code wich calls each initialization routines of linked modules.) This file will be the first modules passed to linker. Default is, if -o option is specified, the value of it prepended "s_" and appended ".c", "a.c" othewise.
-base address
Specify base address of output file. Format of address specification depends on your linker. Specifying base address is said to be useful in some environment.
-xm module
Omit specified standard module from executable. Module shall be one of the following.
expand Hygienic macro feature with syntax-case. Some syntaxes will change its behavior slightly if this is omitted, though this should not affect normal programs.
stdmacro Standard marcros. In rhizome/pi, basic syntax kyewords such as define, lambda are impremented as macros, so omitting stdmacro disables usage of them. If application has no feature to evaluate arbitrary expression specified at run time, you can safely omit this.
debugger Debugging features.
stdproc Built in procedures implemented in scheme code at rhizome/pi. Consult to the source to see what will be unusable if this is omitted :-) Expand and debugger will be omitted automatically if stdproc is omitted.
extcall Macros providing interface to functions in shared objects. If application need not to be able to define new external procedures, callbacks, buffer structures or constants at run time, you can safely omit this.
saccess Procedures used to expand macros defined trough macros which belongs to extcall. Saccess will be omitted automatically if expand is omitted and if saccess is omitted, extcall will be omitted automatically.

This option may be used multiple times.
-aux string
Add string to the command line of linker. This may be used in the purpose of specifying a module wich is already in an object file. This option may be used multiple times.
Format of module-specifier

Specify names you specified at -module option to pisc as module-specifier.
If tha name of file which contains the module is not the module name appended ".c", specify the file name after ':'. If the module is already in object file, specify null string after ':' and specify object file using -aux option.

EXAMPLE
Assume creating a executable from source files x.scm, y.scm, z-0.scm. The following is one sample of compiling process. 

pisc x.scm				# generates x.c
pisl -nold x				# generates x.o
pisc y.scm				# generates y.c
pisc -module zz -output z-0.c z-0.scm	# generates z-0.c with module name zz
pisl -aux x.o x: y zz:z-0.c		# generates executable
Running generated executable results in the same effact as loading each source files to the interpreter in the same sequence of module specification to pisl. In the above example, assuming the contents of a.scm is 
	(load "x.scm")
	(load "y.scm")
	(load "z-0.scm")
the result will be same with doing 
	pi a.scm [arguments]
If compiled program is written to accomplish (exit) after some uninteractive operation, resulting executable will be an uninteractive program. On the other hand, compiling program which only includes some definitions of procedures, resulting executable will be a scheme interpreter extended with the predefined procedures. Note, however, if you want the same behaviour with pi, namely loading its first argument, you must describe such behaviour in your program (linking with module rp_pi included in library is sufficient. In fact, pi itself can be reprodeced by "pisl -o pi rp_pi:".)
It is an error to load same module more than once. Doing so makes program to terminate abnormally.
indexes