\documentclass[onecolumn, 12pt, twoside, openright, dvipdfm]{book} \usepackage{fontspec} \defaultfontfeatures{Scale=MatchLowercase} %\setmainfont[Mapping=tex-text]{Cochin} %\setmainfont[Mapping=tex-text]{Palatino} %\setmainfont[Mapping=tex-text]{Baskerville} \setmainfont[Mapping=tex-text]{Perpetua} \setsansfont[Mapping=tex-text]{Geneva} \setmonofont{Monaco} \usepackage{fancyhdr} \usepackage{makeidx} \usepackage{fancyvrb} \makeindex \usepackage[dvipdfm,CJKbookmarks,bookmarks=true,bookmarksopen=true]{hyperref} \hypersetup{ pdftitle={}, pdfauthor={Abdulaziz Ghuloum}, pdfkeywords={}, bookmarksnumbered=true, %pagebackref=true, breaklinks=true, % pdfview=FitH, % Or try pdfstartview={FitV}, This lead to uncorrect bookmarks urlcolor=cyan, colorlinks=true, citecolor=blue, %citeref's color linkcolor=blue, } \usepackage{rotating} \usepackage{multicol,ragged2e} \renewcommand{\sectionmark}[1]{\markright{\thesection\ #1}} \fancyhf{} \fancyhead[LE,RO]{\bfseries\thepage} \fancyhead[LO]{\bfseries\rightmark} \fancyhead[RE]{\bfseries\leftmark} \renewcommand{\headrulewidth}{0pt} \renewcommand{\footrulewidth}{0pt} \renewcommand{\headheight}{15pt} \newcommand{\coderefpage}[1]{figure~\ref{#1}, p.~\pageref{#1}} \newcommand{\figrefpage}[1]{figure~\ref{#1}, p.~\pageref{#1}} \newcommand{\coderef}[1]{figure~\ref{#1}} \newcommand{\figref}[1]{figure~\ref{#1}} \newcommand{\secref}[1]{section~\ref{#1}} \newcommand{\rnrs}[1]{R$^{\mathrm{#1}}$RS} \newcommand{\BoxedText}[2]{ \vspace{.05in} \begin{center} \begin{tabular}{|p{4.6in}|} {\large \emph{#1}} #2 \end{tabular} \end{center} \vspace{.05in} } \newcommand{\testfile}[2]{\texttt{tests-{\ref{#1}}-{#2}.ss}} \newcommand{\idxtt}[1]{\index{#1 @ \texttt{#1}}\texttt{#1}} \newenvironment{Language} { \begin{center} \begin{tabular}{|p{4.5in}|} {\large \emph{Input Language:}} \begin{center} \begin{tabular}{@{}r@{ }c@{ }l@{}} }{ \end{tabular} \end{center} \end{tabular} \end{center} } \DefineVerbatimEnvironment{CodeInline}{Verbatim} {gobble=0, xleftmargin=2em, xrightmargin=0em, %numbers=left, numbersep=2mm, frame=lines ,framerule=1pt} \DefineVerbatimEnvironment{CodeInlineIdx}{Verbatim} {gobble=0, xleftmargin=3em, xrightmargin=0em, numbers=left, numbersep=1ex, frame=lines ,framerule=1pt} \begin{document} \frontmatter \title{Ikarus Scheme User's Guide} \author{Abdulaziz Ghuloum} \pagestyle{empty} \mbox{} \vspace{3in} { \fontsize{66}{66} \fontspec{Hoefler Text Italic} \begin{center} Ikarus Scheme User's Guide \end{center} } \noindent \rule{\textwidth}{6pt} {\fontsize{18}{18} \fontspec{Hoefler Text Italic} \hfill{} % Quick Start\\ % \rnrs{6} Crash Course\\ % Ikarus (Preliminary Document) } \vfill { \fontsize{24}{24} \fontspec{Hoefler Text Italic} \hfill{} Abdulaziz Ghuloum } { \fontsize{18}{18} \fontspec{Hoefler Text Italic} \hfill{} \today } \newpage \mbox{} \vfill{} \noindent Ikarus Scheme User's Guide\\ %Volume 1: Quick Start (Preliminary Document)\\ Copyright \copyright{} 2007, Abdulaziz Ghuloum\\ \noindent Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 published by the Free Software Foundation; with no Invariant Sections, the Front-Cover Texts being \emph{``Ikarus Scheme User's Guide''}, and no Back-Cover Texts. A copy of the license is included in the section entitled ``GNU Free Documentation License''. \newpage \pagestyle{fancy} \tableofcontents \newpage % \chapter{Preface} % % Here\index{Preface, Great One} % % % \begin{verbatim} % (library (foo) % (export x) % (import (rnrs)) % (define y 13) % (define-syntax x % (syntax-rules () % [(_ n) (+ n y)])) % \end{verbatim} \mainmatter \setlength{\parindent}{0pt} \setlength{\parskip}{2.0ex plus 0ex minus 0ex} \chapter{Getting Started} \section{Introduction} Ikarus Scheme is an implementation of the Scheme programming language\cite{steele:scheme}. The prerelease version of Ikarus implements the majority of the features found in the current standard, the Revised$^6$ report on the algorithmic language Scheme\cite{r6rs}. Subsequent revisions will proceed towards completing the set of \rnrs{6} features. The main purpose behind releasing Ikarus early is to give Scheme programmers the opportunity to experiment with the various new features that were newly introduced in \rnrs{6}. The most important of such features is the ability to structure large programs into libraries; where each library extends the language through procedural and syntactic abstractions. Many useful libraries can be written using the currently supported set of \rnrs{6} features including text processing tools, symbolic logic systems, interpreters and compilers, and many mathematical and scientific packages. It is our hope that this release will encourage the Scheme community to write and to share their most useful \rnrs{6} libraries. \newpage \section{Technology Overview} Ikarus Scheme provides the programmer with many advantages: \textbf{Optimizing code generator:} The compiler's backend employs state of the art technologies in code generation that produce fast efficient machine code. When developing computationally intensive programs, one is not constrained by using a slow interpreter. \textbf{Fast incremental compilation:} Every library and script is quickly compiled to native machine code. When developing large software, one is not constrained by how slow the batch compiler runs. \textbf{Robust and fine-tuned standard libraries:} The standard libraries are written such that they perform as much error checking as required to provide a safe and fast runtime environment. \textbf{Multi-generational garbage collector:} The BiBOP\cite{dybvig:sm} based garbage collector used in Ikarus allows the runtime system to expand its memory footprint as needed. Up to four gigabytes of data can be used and unneeded memory is released back to the operating system. \textbf{Supports many operating systems:} Ikarus runs on the most popular and widely used operating systems for servers and personal computers. The supported systems include Mac~OS~X, GNU/Linux, and Microsoft Windows. \section{System Requirements} \subsection{Hardware} Ikarus Scheme runs on the IA-32 (\emph{x86}) architecture supporting SSE2 extensions. This includes the Athlon 64, Sempron 64, and Turion 64 processors from AMD and the Pentium 4, Xeon, Celeron, Pentium M, Core, and Core2 processors from Intel. The system does not run on Intel Pentium III or earlier processors. \subsection{Operating Systems} Ikarus is tested under the following operating systems: \begin{itemize} \item Mac OS X version 10.4. \item Linux 2.6.18 (Debian, Fedora, Gentoo, and Ubuntu). \item Microsoft Windows XP (using Cygwin 1.5.24). \end{itemize} \subsection{Additional Software} \begin{itemize} \item\textbf{GMP:} Ikarus uses the GNU Multiple Precision Arithmetic Library (GMP) for some bignum arithmetic operations. To build ikarus from scratch, GMP version 4.2 or better must be installed along with the required header files. Pre-built GMP packages es are available for most operating systems. Alternatively, GMP can be downloaded from \url{http://gmplib.org/}. \item\textbf{GCC:} The GNU C Compiler is required to build the ikarus executable (e.g. the garbage collector, loader, and OS-related runtime). GCC versions 4.1 and 4.2 were used successfully to build ikarus. \item\textbf{Autoconf and Automake:} The GNU Autoconf (version 2.59) and GNU Automake (version 1.9) tools are required if one wishes to modify the ikarus source base. They are not required to build the official release of ikarus. \item\textbf{XeLaTeX:} The XeLaTeX typesetting system is required for building the documentation. XeLaTeX (and XeTeX) is an implementation of the LaTeX (and TeX) typesetting system. \end{itemize} \newpage \section{Installation} If you are familiar with installing Unix software on your system, then all you need to know is that Ikarus uses the standard installation method found in most other Unix software. Simply run the following commands from the shell: \begin{verbatim} $ tar -zxf ikarus-pre-0-nnn.tar.gz $ cd ikarus-pre-0-nnn $ ./configure [--prefix=path] [CFLAGS=-I/dir] [LDFLAGS=-L/dir] $ make $ make install $ \end{verbatim} The rest of this section describes the build process in more details. It is targetted to users who are unfamiliar with steps mentioned above. \subsection{Installation Details} \begin{enumerate} \item Download the Ikarus source distribution. The source is distributed as a \texttt{gzip}-compressed \texttt{tar} file (\texttt{ikarus-pre-0-nnn.tar.gz} where \texttt{nnn} is a 3-digit number indicating the current revision). The latest revision can be downloaded from the following URL:\\ \url{http://www.cs.indiana.edu/~aghuloum/ikarus/} \item Unpack the source distribution package. From your shell command, type: \begin{verbatim} $ tar -zxf ikarus-pre-0-nnn.tar.gz \end{verbatim} This creates the base directory \texttt{ikarus-pre-0-nnn}. \item Configure the build system by running the \texttt{configure} script located in the base directory. To do this, type the following commands: \begin{verbatim} $ cd ikarus-pre-0-nnn $ ./configure checking build system type... i386-apple-darwin8.10.1 checking host system type... i386-apple-darwin8.10.1 ... configure: creating ./config.status config.status: creating Makefile config.status: creating src/Makefile config.status: creating scheme/Makefile config.status: creating doc/Makefile config.status: executing depfiles commands $ \end{verbatim} This configures the system to be built then installed in the system-wide location (binaries are installed in \texttt{/usr/local/bin}) . If you wish to install it in another location (e.g. in your home directory), you can supply a \texttt{--prefix} location to the \texttt{configure} script as follows: \begin{verbatim} $ ./configure --prefix=/path/to/installation/location \end{verbatim} The \texttt{configure} script will fail if it cannot locate the location where GMP is installed. If running \texttt{configure} fails to locate GMP, you should supply the location in which the GMP header file, \texttt{gmp.h}, and the GMP library file, \texttt{libgmp.so}, are installed. This is done by supplying the two paths in the \texttt{CFLAGS} and \texttt{LDFLAGS} arguments: \begin{verbatim} $ ./configure CFLAGS=-I/path/to/include LDFLAGS=-L/path/to/lib \end{verbatim} \item Build the system by running: \begin{verbatim} $ make \end{verbatim} This performs two tasks. First, it builds the \texttt{ikarus} executable from the C files located in the \texttt{src} directory. It then uses the \texttt{ikarus} executable and the pre-built \texttt{ikarus.boot.orig} boot file to rebuild the Scheme boot image file \texttt{ikarus.boot} from the Scheme sources located in the \texttt{scheme} directory. \item Install Ikarus by typing: \begin{verbatim} $ make install \end{verbatim} If you are installing Ikarus in a system-wide location, you might need to have administrator privileges (use the \texttt{sudo} or \texttt{su} commands). \item Test that Ikarus runs from the command line. \begin{verbatim} $ ikarus Ikarus Scheme (Build 2007-10-20) Copyright (c) 2006-2007 Abdulaziz Ghuloum > \end{verbatim} If you get the prompt, then Ikarus was successfully installed on your system. You may need to update the \texttt{PATH} variable in your environment to contain the directory in which the \texttt{ikarus} executable was installed. Do not delete the \texttt{ikarus-pre-0-nnn} directory from which you configured, built, and installed Ikarus. It will be needed if you decide at a later time to uninstall Ikarus. \end{enumerate} \subsection{Uninstalling Ikarus} To uninstall Ikarus, use the following steps: \begin{verbatim} $ cd path/to/ikarus-pre-0-nnn $ make uninstall \end{verbatim} \newpage \section{\index{Command-line switches}Command-line Switches} The \texttt{ikarus} executable recognizes a few command-line switches that influence how Ikarus starts. \begin{itemize} \item \texttt{ikarus -h} The presence of the \texttt{-h} flag causes \texttt{ikarus} to display a help message then exits. The help message summarises the command-line switches. No further action is performed. \item \texttt{ikarus -b path/to/boot/file.boot} The \texttt{-b} flag (which requires an extra argument) directs \texttt{ikarus} to use the specified boot file as the initial system boot file. \index{Boot files} The boot file is a binary file that contains all the code and data of the Scheme system. In the absence of \texttt{-b} flag, the executable attempts to guess the location of the boot file using the following strategy: \begin{enumerate} \item If \texttt{ikarus} was started by supplying an explicit location such as \texttt{/usr/local/bin/ikarus} or \texttt{./ikarus}, then the name of the boot file is the concatenation of a \texttt{.boot} prefix to the executable file name (e.g. \texttt{/usr/local/bin/ikarus.boot} or \texttt{./ikarus.boot}). \item Otherwise, \texttt{ikarus} assumes that it was started from a location in the \texttt{PATH} environment variable. In that case, it searches for the location of \texttt{ikarus} in the \texttt{PATH}. If \texttt{ikarus} is found in \texttt{/path/to/ikarus}, then the name of the boot file becomes \texttt{/path/to/ikarus.boot}. \item Failing both guesses, \texttt{ikarus} prints an error message and exits. \end{enumerate} The motivation for this strategy was to allow one to (1) rename the \texttt{ikarus} executable and the corresponding boot file to some new names (e.g. \texttt{my-ikarus} and \texttt{my-ikarus.boot}) without conflicting with other installed versions of Ikarus, and (2) override the location of the boot file for testing and building purposes (e.g. the installation process using one boot file to build another). The rest of the command-line arguments are recognized by the standard Scheme run time system. They are processed after the boot file is loaded. \item \texttt{ikarus --r6rs-script script-file-name [arguments ...]} \index{R6RS Script@\rnrs{6} Script} The \texttt{--r6rs-script} argument instructs Ikarus that the supplied file is an \rnrs{6} script. See Section~\ref{sec:scripts} for a short introduction to writing \rnrs{6} scripts. The script file name and any additional optional \texttt{arguments} can be obtained by calling the \idxtt{command-line} procedure. \begin{verbatim} $ cat test.ss (import (rnrs)) (write (command-line)) (newline) $ ikarus --r6rs-script test.ss hi there ("test.ss" "hi" "there") $ \end{verbatim} \item \texttt{ikarus files ... [-- arguments ...]} The lack of an \texttt{--r6rs-script} argument causes Ikarus to start in interactive mode. Each of the \texttt{files} is first loaded, in the interaction environment. The interaction environment initially containes all the bindings exported from the \texttt{(ikarus)} library (see Section~\ref{lib:ikarus}). The optional \texttt{arguments} following the \texttt{--} marker can be obtained by calling the \texttt{command-line} procedure. \BoxedText{Note:}{The interactive mode is intended for quickly experimenting with the built-in features. It is intended neither for developing applications nor for writing any substantial pieces of code. The main reason for this is that the innteraction between \rnrs{6} libraries and the interactive environment is not well understood. We hope to achieve better interaction between the two subsystems in the future.} \end{itemize} \section{Executable Scripts} FIXME \subsection{Mac OS X} FIXME \subsection{GNU/Linux} FIXME \subsection{Windows/Cygwin} FIXME \chapter{\rnrs{6} Crash Course} The major difference between \rnrs{5} and \rnrs{6} is the way in which programs are loaded and evaluated. In \rnrs{5}, Scheme implementations typically start as an interactive session (often referred to as the REPL, or read-eval-print-loop). Inside the interactive session, the user enters definitions and expressions one at a time using the keyboard. Files, which also contain definitions and expressions, can be loaded and reloaded by calling the \texttt{load} procedure. The environment in which the interactive session starts often contains implementation-specific bindings that are not found \rnrs{5} and users may redefine any of the initial bindings. The semantics of a loading a file depends on the state of the environment at the time the file contents are evaluated. \index{R6RS Script@\rnrs{6} Script!Import} \rnrs{6} differs from \rnrs{5} in that it specifies how \emph{whole programs}, or scripts, are compiled and evaluated. An \rnrs{6} script is closed in the sense that all the identifiers found in the body of the script must either be defined in the script or imported from a library. \rnrs{6} also specifies how \emph{libraries} can be defined and used. While files in \rnrs{5} are \emph{loaded} imperatively into the top-level environments, \rnrs{6} libraries can be \emph{imported} declaratively in scripts and in other \rnrs{6} libraries. \section{\label{sec:scripts}Writing a simple script} An \rnrs{6} script is a set of definitions and expressions preceeded by an \texttt{import} form. The \texttt{import} form specifies the language (i.e. the variable and keyword bindings) in which the library body is written. A very simple example of an \rnrs{6} script is listed below. \index{Examples!Hello World@\textit{Hello World}} \begin{CodeInline} (import (rnrs)) (display "Hello World!\n") \end{CodeInline} The first line imports the \texttt{(rnrs)} library. All the bindings exported from the \texttt{(rnrs)} library are made available to be used within the body of the library. The exports of the \texttt{(rnrs)} library include variables (e.g. \texttt{cons}, \texttt{car}, \texttt{display}, etc.) and keywords (e.g. \texttt{define}, \texttt{lambda}, \texttt{quote}, etc.). The second line displays the string \texttt{Hello World!} followed by a new line character. In addition to expressions, such as the call to \texttt{display} in the previous example, a script may define some variables. The script below defines the variable \texttt{greeting} and calls the procedure bound to it. \begin{CodeInline} (import (rnrs)) (define greeting (lambda () (display "Hello World!\n"))) (greeting) \end{CodeInline} Additional keywords may be defined within a script. In the example below, we define the \texttt{(do-times n exprs ...)} macro that evaluates the expressions \texttt{exprs} \texttt{n} times. Running the script displays \texttt{Hello World} 3 times. \newpage \begin{CodeInline} (import (rnrs)) (define greeting (lambda () (display "Hello World!\n"))) (define-syntax do-times (syntax-rules () [(_ n exprs ...) (let f ([i n]) (unless (zero? i) exprs ... (f (- i 1))))])) (do-times 3 (greeting)) \end{CodeInline} \section{Writing simple libraries} A script is intended to be a small piece of the program---useful abstractions belong to libraries. The \texttt{do-times} macro that was defined in the previous section may be useful in places other than printing greeting messages. So, we can create a small library, \texttt{(iterations)} that contains common iteration forms. An \rnrs{6} library form is made of four essential parts: (1) the library name, (2) the set of identifiers that the library exports, (3) the set of libraries that the library imports, and (4) the body of the library. The library name can be any non-empty list of identifiers. \rnrs{6}-defined libraries includes \texttt{(rnrs)}, \texttt{(rnrs~unicode)}, \texttt{(rnrs~bytevectors)}, and so on. The library exports are a set of identifiers that are made available to importing libraries. Every exported identifier must be bound: it may either be defined in the libraries or imported from another library. %\emph{re-exported} identifiers}. Library exports include variables, keywords, record names, condition names. Library imports are similar to script imports: they specify the set of libraries whose exports are made visible within the body of the library. \index{Invoke} The body of a library contains definitions (variable, keyword, record, condition, etc.) followed by an optional set of expressions. The expressions are evaluated for side effect when needed. The \texttt{(iteration)} library may be written as follows: \begin{CodeInline} (library (iteration) (export do-times) (import (rnrs)) (define-syntax do-times (syntax-rules () [(_ n exprs ...) (let f ([i n]) (unless (zero? i) exprs ... (f (- i 1))))]))) \end{CodeInline} To use the \texttt{(iteration)} library in our script, we add the name of the library to the script's \texttt{import} form. This makes all of \texttt{(iteration)}'s exported identifiers, e.g. \texttt{do-times}, visible in the body of the script. \begin{CodeInline} (import (rnrs) (iteration)) (define greeting (lambda () (display "Hello World!\n"))) (do-times 3 (greeting)) \end{CodeInline} % \begin{CodeInline} % (library (iteration) % (export do-times) % (import (rnrs)) % (define-syntax do-times % (syntax-rules () % [(_ n exprs ...) % (do-times-proc n (lambda () exprs ...))])) % (define do-times-proc % (lambda (n proc) % (unless (zero? n) % (proc) % (do-times-proc (- n 1) proc))))) % \end{CodeInline} \chapter{\rnrs{6} Standard Libraries} \newpage \section{\texttt{(rnrs)}} \newpage \section{\texttt{(rnrs base)}} \newpage \section{\texttt{(rnrs arithmetic bitwise)}} \newpage \section{\texttt{(rnrs arithmetic fixnums)}} \newpage \section{\texttt{(rnrs arithmetic flonums)}} \newpage \section{\texttt{(rnrs bytevectors)}} \newpage \section{\texttt{(rnrs conditions)}} \newpage \section{\texttt{(rnrs control)}} \newpage \section{\texttt{(rnrs enums)}} \newpage \section{\texttt{(rnrs exceptions)}} \newpage \section{\texttt{(rnrs files)}} \newpage \section{\texttt{(rnrs hashtables)}} \cite{ghuloum07hashtables} \newpage \section{\texttt{(rnrs io ports)}} \newpage \section{\texttt{(rnrs io simple)}} \newpage \section{\texttt{(rnrs lists)}} \newpage \section{\texttt{(rnrs mutable-pairs)}} \newpage \section{\texttt{(rnrs mutable-strings)}} \newpage \section{\texttt{(rnrs programs)}} \newpage \section{\texttt{(rnrs r5rs)}} \newpage \section{\texttt{(rnrs records inspection)}} \newpage \section{\texttt{(rnrs records procedural)}} \newpage \section{\texttt{(rnrs records syntactic)}} \newpage \section{\texttt{(rnrs sorting)}} \newpage \section{\texttt{(rnrs syntax-case)}} \newpage \section{\texttt{(rnrs unicode)}} \newpage \chapter{Ikarus Library Collection} * list all ikarus libraries. * explain each of the exports. \newpage \section{\label{lib:ikarus}\texttt{(ikarus)}} \newpage \section{\texttt{(ikarus files)}} \newpage \section{\texttt{(ikarus parameters)}} \newpage \section{\texttt{(ikarus posix)}} \newpage \section{\texttt{(ikarus printing)}} \newpage \section{\texttt{(ikarus symbols)}} \newpage \section{\texttt{(ikarus timers)}} \newpage \section{\texttt{(ikarus tracing)}} \newpage \section{\texttt{(ikarus unicode)}} \newpage \section{\texttt{(ikarus guardians)}} \cite{dybvig93guardians} \newpage \section{\texttt{(ikarus weak-pairs)}} \newpage \section{\texttt{(ikarus modules)}} \newpage \section{\texttt{(ikarus library-manager)}} \newpage % \chapter{Using \rnrs{6} Libraries Effectively} % \chapter{Additional Libraries} % % \section{\texttt{(iu match)}} % \chapter{The Programming Environment} % % \section{Working with Unicode} % % \section{Working} % % \section{Some Section Here} % % %\index{cheese!gouda!brie} % %\index{cheese!gouda!none} % \section{Additional Stuff} % \subsection{And some sub stuff} \appendix \bibliographystyle{plain} \bibliography{ikarus-users-guide} \printindex \backmatter \end{document}