ikarus/doc/ikarus-users-guide.tex

\documentclass[onecolumn, 12pt, twoside, openright, dvipdfm]{book}
\usepackage{fontspec}

\defaultfontfeatures{Scale=MatchLowercase} 
\setmainfont[Mapping=tex-text]{Cochin} 
%\setmainfont[Mapping=tex-text]{Palatino}
\setsansfont[Mapping=tex-text]{Geneva} 
\setmonofont{Monaco} 

\usepackage{fancyhdr}
\usepackage{makeidx}
\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}

%\pagestyle{fancy}

\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}}

\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}
}

\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{}
Volume 1: Quick Start (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 (2.59 or better)
and GNU Automakei (1.6.3 or better) 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 (e.g. \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{/some/location/ikarus}, then the name of the boot file
becomes \texttt{/some/location/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{\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
\index{\texttt{command-line}}\texttt{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}



\newpage


\chapter{\rnrs{6} Crash Course}

* Describe major differences between r6 and r5

* Explain what a top-level program is

* Explain what a library is

* Explain what the standard R6RS libraries are

\section{\label{sec:scripts}Writing a simple script}

* Hello World example

* Definitions (procedures)

* Simple macros.

\section{Writing simple libraries}

\section{\rnrs{6} Standard Libraries}

\subsection{\texttt{(rnrs (6))}}
a
\subsection{\texttt{(rnrs arithmetic bitwise (6))}}
a
\subsection{\texttt{(rnrs arithmetic fixnums (6))}}
a
\subsection{\texttt{(rnrs arithmetic flonums (6))}}
a
\subsection{\texttt{(rnrs bytevectors (6))}}
a
\subsection{\texttt{(rnrs conditions (6))}}
a
\subsection{\texttt{(rnrs control (6))}}
a
\subsection{\texttt{(rnrs enums (6))}}
a
\subsection{\texttt{(rnrs exceptions (6))}}
a
\subsection{\texttt{(rnrs files (6))}}
a
\subsection{\texttt{(rnrs hashtables (6))}}
\cite{ghuloum07hashtables}

\subsection{\texttt{(rnrs io ports (6))}}
a
\subsection{\texttt{(rnrs io simple (6))}}
a
\subsection{\texttt{(rnrs lists (6))}}
a
\subsection{\texttt{(rnrs mutable-pairs (6))}}
a
\subsection{\texttt{(rnrs mutable-strings (6))}}
a
\subsection{\texttt{(rnrs programs (6))}}
a
\subsection{\texttt{(rnrs r5rs (6))}}
a
\subsection{\texttt{(rnrs records inspection (6))}}
a
\subsection{\texttt{(rnrs records procedural (6))}}
a
\subsection{\texttt{(rnrs records syntactic (6))}}
a
\subsection{\texttt{(rnrs sorting (6))}}
a
\subsection{\texttt{(rnrs syntax-case (6))}}
a
\subsection{\texttt{(rnrs unicode (6))}}
a




\chapter{Ikarus's Built-in Libraries} 

* list all ikarus libraries.

* explain each of the exports.

\section{\label{lib:ikarus}\texttt{(ikarus)}}
\section{\texttt{(ikarus files)}}
\section{\texttt{(ikarus parameters)}}
\section{\texttt{(ikarus posix)}}
\section{\texttt{(ikarus printing)}}
\section{\texttt{(ikarus symbols)}}
\section{\texttt{(ikarus timers)}}
\section{\texttt{(ikarus tracing)}}
\section{\texttt{(ikarus unicode)}}
\section{\texttt{(ikarus guardians)}}
\cite{dybvig93guardians}
\section{\texttt{(ikarus weak-pairs)}}
\section{\texttt{(ikarus modules)}}
\section{\texttt{(ikarus library-manager)}}

% \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}