* Added the user guide to the repository.
This commit is contained in:
Abdulaziz Ghuloum
parent
63ddb1b479
commit
3cca074ca2
|
|
@ -0,0 +1,18 @@
|
||||||
|
|
||||||
|
|
||||||
|
#dist_doc_DATA=doc/ikarus-users-guide.pdf
|
||||||
|
EXTRA_DIST = ikarus-users-guide.tex ikarus-users-guide.bib ikarus-users-guide.pdf
|
||||||
|
|
||||||
|
TEX=xelatex -output-driver="xdvipdfmx -q -E"
|
||||||
|
|
||||||
|
ikarus-users-guide.pdf: ikarus-users-guide.tex ikarus-users-guide.bib
|
||||||
|
$(TEX) ikarus-users-guide
|
||||||
|
makeindex ikarus-users-guide
|
||||||
|
bibtex ikarus-users-guide
|
||||||
|
$(TEX) ikarus-users-guide
|
||||||
|
$(TEX) ikarus-users-guide
|
||||||
|
|
||||||
|
all: ikarus-users-guide.pdf
|
||||||
|
|
||||||
|
clean:
|
||||||
|
rm -f *.aux *.log *.toc *.out *.idx *.ind *.ilg
|
||||||
|
|
@ -0,0 +1,41 @@
|
||||||
|
|
||||||
|
@article{ r6rs,
|
||||||
|
author = "Michael Sperber and R. Kent Dybvig and Matthew Flatt
|
||||||
|
and Anton Van Straaten {(Editors)}",
|
||||||
|
title = "Revised$^{6}$ Report on the Algorithmic Language {Scheme}",
|
||||||
|
year = "2007"
|
||||||
|
}
|
||||||
|
|
||||||
|
|
||||||
|
@inproceedings{dybvig93guardians,
|
||||||
|
author = {R. Kent Dybvig and Carl Bruggeman and David Eby},
|
||||||
|
title = {Guardians in a generation-based garbage collector},
|
||||||
|
booktitle = "PLDI '93",
|
||||||
|
pages = "207-216",
|
||||||
|
month = jun,
|
||||||
|
year = 1993,
|
||||||
|
annote = {Introduces guardians and describes the implementation of
|
||||||
|
guardians and weak pairs in Chez Scheme.}
|
||||||
|
}
|
||||||
|
|
||||||
|
@techreport{dybvig:sm,
|
||||||
|
author = {R. Kent Dybvig and David Eby and Carl Bruggeman},
|
||||||
|
title = {Don't stop the {BiBOP}: Flexible and efficient storage
|
||||||
|
management for dynamically-typed languages},
|
||||||
|
institution = "Indiana University",
|
||||||
|
number = 400,
|
||||||
|
month = "March",
|
||||||
|
year = 1994,
|
||||||
|
annote = {Describes Chez Scheme's storage management system.}
|
||||||
|
}
|
||||||
|
|
||||||
|
@inproceedings{ghuloum07hashtables,
|
||||||
|
author = {Abdulaziz Ghuloum and R. Kent Dybvig},
|
||||||
|
title = {Generation Friendly Eq Hash Tables},
|
||||||
|
booktitle = "Workshop on Scheme and Functional Programming",
|
||||||
|
pages = "207-216",
|
||||||
|
month = sep,
|
||||||
|
year = 2007
|
||||||
|
}
|
||||||
|
|
||||||
|
|
||||||
|
|
@ -0,0 +1,616 @@
|
||||||
|
|
||||||
|
\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}
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
Loading…
Reference in New Issue