Vicare Scheme
                             =============


Topics
------

  1. Introduction
  2. License
  3. Install
  4. Testing
  A. Credits
  B. Bug reports
  C. Resources
  D. On boot images


1. Introduction
---------------

Scheme is a statically scoped and properly tail-recursive dialect of the
Lisp programming language  invented by Guy Lewis Steele  Jr.  and Gerald
Jay Sussman.  It was designed to  have an exceptionally clear and simple
semantics and few different ways to form expressions.

  The  "Revised^6 Report  on the  Algorithmic Language  Scheme"  gives a
defining description of the  programming language Scheme.  The report is
the work  of many  people in the  course of  many years; revision  6 was
edited by Michael  Sperber, R. Kent Dybvig, Matthew  Flatt and Anton Van
Straaten.

  Ikarus Scheme is an almost R6RS compliant implementation of the Scheme
programming language;  it is  the creation  of Abdulaziz  Ghuloum, which
retired from  development in 2010.   Vicare Scheme is an  R6RS compliant
fork of Ikarus Scheme, aiming to  become a native compiler for R6 Scheme
producing  single   threaded  programs  running  on   Intel  x86  32-bit
processors, with experimental support for  64-bit machines; it is tested
only on GNU+Linux, no official support for other platforms is present.

  "Vicare" is pronounced  the etruscan way.  The logo of  the project is
the greek capital letter Upsilon (U+03D2).

  Vicare offers arbitrary precision integers through GMP.  It implements
an optionally included foreign-functions interface based on Libffi.  The
last time  the maintainer updated  this paragraph, it had  tested Libffi
version 3.0.11.

  A port to R6RS of the SRFI libraries is included in the distribution.

  Current official maintainers are:

Marco Maggi <[email protected]>


2. License
----------

Copyright (c) 2011-2013 Marco Maggi <[email protected]>
Copyright (c) 2006-2010 Abdulaziz Ghuloum <[email protected]>
Modified by the Vicare contributors.

This program is free software:  you can redistribute it and/or modify it
under the  terms of the GNU  General Public License as  published by the
Free Software Foundation,  either version 3 of the  License, or (at your
option) any later version.

This program  is distributed  in the  hope that it  will be  useful, but
WITHOUT   ANY   WARRANTY;  without   even   the   implied  warranty   of
MERCHANTABILITY  or  FITNESS FOR  A  PARTICULAR  PURPOSE.   See the  GNU
General Public License for more details.

You should have received a copy  of the GNU General Public License along
with this program.  If not, see <http://www.gnu.org/licenses/>.


3. Install
----------

3.1 Install Vicare
------------------

To install Vicare  Scheme from a proper release tarball,  we must unpack
the archive then do:

   $ cd vicare-scheme-0.3d1
   $ mkdir build
   $ cd build
   $ ../configure
   $ make
   $ make check
   $ make install

notice  that  the  "configure"  script  is  prepared  to  enable  shared
libraries  and  disable static  libraries:  this  must not  be  changed,
because  the package  is  meant to  install  a C  shared  library to  be
dynamically loaded.

  If, instead,  we have checked out  a revision from the  repository, we
will have  to first build the  infrastructure by running a  Bourne shell
script from the top source directory:

   $ cd vicare-scheme
   $ sh autogen.sh

notice  that  "autogen.sh"  will   run  the  programs  "autoreconf"  and
"libtoolize"; the  latter is  selected through the  environment variable
"LIBTOOLIZE",  whose  value  can  be  customised;  for  example  to  run
"glibtoolize" rather than "libtoolize" we do:

   $ LIBTOOLIZE=glibtoolize sh autogen.sh

  After this the  procedure is the same  as the one for  building from a
proper release tarball, but we  must enable maintainer mode when running
the "configure" script:

   $ mkdir build
   $ cd build
   $ ../configure --enable-maintainer-mode
   $ make
   $ make check
   $ make install

  To make use  of the POSIX semaphore functions, we  need to include the
pthread library using the option:

   $ ../configure --with-pthread [... other options ...]

by default pthread is linked to the executable if found on the host.

  A  bare build  (without  support for  optional  features and  external
libraries) can be obtained with:

   $ ../configure \
         --disable-posix	\
	 --disable-glibc	\
	 --disable-linux	\
         --without-pthread	\
         --without-libffi	\
         --without-libiconv	\
         --without-readline	\
         --without-cre2

  To test what a rule will do use the "-n" option; example:

   $ make install -n

  The "Makefile" supports the  "DESTDIR" environment variable to install
the files under a temporary location; example:

   $ make install DESTDIR=/tmp/vicare

  After   installation,  the   makefile   rule  "vfasl-installed"   will
precompile the libraries  installed in the hierarchies  (vicare ---) and
(srfi ---).   By default, the  Scheme libraries are installed  under the
directory:

			$(libdir)/vicare-scheme

  The variable VFLAGS is available  to the user when running "configure"
and "make" to add command line options to the execution of "vicare" when
compiling libraries and running tests; for example:

   $ make VFLAGS="-g -O2 --print-loaded-libraries"


3.2 Install CRE2
----------------

CRE2 is a  C language wrapper for the RE2  library, which is implemented
in  C++.    RE2  is  a   fast,  safe,  thread-friendly   alternative  to
backtracking regular  expression engines from Google like  those used in
PCRE, Perl, and Python.

  Vicare  implements an  optional  built  in interface  to  CRE2; it  is
disabled by default, to enable it  we must give the "--with-cre2" option
to the "configure" script.

  At present (Jan 6, 2012), to install  RE2 we must check out a revision
from  the  repository  (see  Resources);   then  we  should  follow  the
installation instructions in the README file.  To install CRE2: download
the  latest tarball,  build  and  install it;  CRE2  relies  on the  GNU
Autotools.


3.3 Special make rules
----------------------

There are  special makefile rules  to rebuild source code  files, mostly
lexer and parser tables:

ip-address-tables	- rebuild the tables for the net libraries
silex-test		- rebuild the tests for the SILex lexer
lalr-test		- rebuild the tests for the LALR parser

and the  following DANGEROUS  rule, use  only if you  know what  you are
doing:

silex-internals - rebuild the internal tables of SILex itself


4. Testing
----------

Test  files  are  located  in  the "tests"  directory;  the  files  with
extension  ".sps" are  Scheme  programs.  They  are  partitioned in  two
families: the files whose name  start with "long-test" need some time to
be executed  by a  powerless computer; the  files whose name  start with
"test" can  be run in  reasonable time on  any system.  The  files whose
name contains "r6rs" are R6RS compliance tests by Matthew Flatt.

  The  "make  vfasl"  command  will  precompile  the  libraries  in  the
hierarchies (vicare ---) and (srfi ---) to be used by the test suite.

  The "make check",  "make test" and "make tests" commands  run the same
set of  "quick" tests; the "check"  makefile rule uses the  GNU Automake
infrastructure (parallel test harness,  see Automake's documentation for
details).   After the  installation: we  can run  these tests  using the
"make installcheck" rule.

  The "make long-test"  and "make long-tests" commands run  the same set
of time-consuming tests.

  It  is possible  to select  a  single test  file by  using the  "file"
variable on the command line of "make"; for example:

   $ make test file=equal-hash

will run the  "test-issue-001-equal-hash.sps" file.  The "file" variable
is used to expand a file name with wildcards as in "test-*$(file)*.sps".

  It  is possible to  run "vicare"  from the  build directory  with user
selected command line arguments doing:

   $ make test-run user_flags='...'

where the contents  of the "user_flags" variable are  placed directly on
the command line.

  Some  test  files need  a  usable  directory  pathname in  the  TMPDIR
environment variable.

  The file  "test-vicare-posix.sps" contains  tests for  network sockets
which are  normally disabled because  the firewall rules on  the hosting
machine  must  allow  TCP  and UDP  connections  on  127.0.0.1:8080  and
127.0.0.1:8081; to  enable these tests  run "make" with  the environment
variable RUN_INET_TESTS set to something:

   $ make test file=vicare-posix RUN_INET_TESTS=1

  When included, it is possible to run tests for the bindings to foreign
libraries (like CRE2) with:

   $ make foreign-test


A. Credits
----------

The  original Ikarus  Scheme  code  is the  work  of Abdulaziz  Ghuloum.
Vicare Scheme  is a fork  driven by  Marco Maggi.  See  the CONTRIBUTORS
file for the list of contributors to Ikarus Scheme and Vicare Scheme.

  IrRegex is adapted  from the original distribution by  Alex Shinn, see
the file "LICENSE.irregex".

  Pregexp is adapted from the original library by Dorai Sitaram, see the
file "LICENSE.pregexp".

  The libraries  in the  hierarchy (vicare  containers strings  ---) are
derived from the reference implementation of SRFI 13 by Olin Shivers.

  The libraries  in the  hierarchy (vicare  containers vectors  ---) are
derived from the reference implementation of SRFI 13 by Olin Shivers.

  The library (vicare containers knuth-morris-pratt) is derived from the
reference implementation of SRFI 13 by Olin Shivers.

  The library (vicare containers strings rabin-karp) is derived from the
implementation at:

    <http://algs4.cs.princeton.edu/53substring/RabinKarp.java.html>

  The library  (vicare containers levenshtein)  is derived from  code by
Neil Van Dyke.

  The library (vicare language-extensions  streams) is derived from code
by Philip L. Bewig.

  The library (vicare language-extensions loops) is derived from code by
Sebastian Egner.

  The library  (vicare language-extensions comparisons) is  derived from
code by Sebastian Egner and Jens Axel Soegaard.

  The libraries in the hierarchy (vicare crypto randomisations ---) have
many authors, please see the headers of the individual files.

  Some libraries  in the  hierarchy (vicare containers  bytevectors ---)
are derived from the SRFI 13 reference implementation by Olin Shivers.

  The library  (vicare formations) is derived  from: "format.scm" Common
LISP  text  output  formatter  for  SLIB.   Written  1992-1994  by  Dirk
Lutzebaeck.  Authors of the original  version (<1.4) were Ken Dickey and
Aubrey Jaffer.  Assimilated into Guile  May 1999.  Ported to R6RS Scheme
and Vicare by Marco Maggi.

  The SILex libraries are a port to  R6RS Scheme of SILex version 1.0 by
Danny Dube'.  Copyright (C) 2001, 2009 Danny Dube'.

  The LALR libraries are a port  to R6RS Scheme of Lalr-scm by Dominique
Boucher.  Copyright (c) 2005-2008 Dominique Boucher.


B. Bug reports
--------------

Bug reports  are appreciated, register  them using the issue  tracker at
Vicare's GitHub site:

	      <http://github.com/marcomaggi/vicare/issues>


C. Resources
------------

The latest version of this package can be downloaded from Google Code:

	 <http://sourceforge.net/projects/vicare-scheme/files/>

the home page of the Vicare project is at:

               <http://marcomaggi.github.com/vicare.html>

development takes place at:

                 <http://github.com/marcomaggi/vicare/>

and as backup at:

		     <http://gitorious.org/vicare>

and at:

	    <http://sourceforge.net/projects/vicare-scheme/>

this project has a mailing list:

	     <http://groups.google.com/group/vicare-users>

  The library Libffi can be found at:

		    <http://sourceware.org/libffi/>

  The GMP library is available at:

			  <http://gmplib.org/>

  The library RE2 is available at:

		    <http://code.google.com/p/re2/>

the library CRE2 is available from:

		  <http://github.com/marcomaggi/cre2/>

  The home page of the R6RS standard is at:

			 <http://www.r6rs.org>


D. On boot images
-----------------

Vicare comes with 2 prebuilt boot images:

    $(top_srcdir)/scheme/vicare.boot.4.prebuilt
    $(top_srcdir)/scheme/vicare.boot.8.prebuilt

one for 32-bit systems (4) and one for 64-bit systems (8).  The prebuilt
images do not contain the latest version of the code.

  When executing "make all" a new boot image is built:

    $(builddir)/scheme/vicare.boot

and this image is then installed  on the system by "make install".  This
new boot image is the one containing the latest version of the code.

  On a 32-bit system, when the maintainer feels it is time to rotate the
boot images, he just replaces by hand:

    $(top_srcdir)/scheme/vicare.boot.4.prebuilt

with:

    $(builddir)/scheme/vicare.boot

then he does:

    $ make boot-image-64-bit

to (blindly) generate:

    $(builddir)/scheme/vicare.boot.8.prebuilt

and make it become the new:

    $(top_srcdir)/scheme/vicare.boot.8.prebuilt

  When building the 64-bit image, the file:

    $(builddir)/scheme/ikarus.config.ss

is filled with values that are invalid on a 32-bit system, so we have to
remove it to return to building 32-bit images.


### end of file
# Local Variables:
# mode: text
# fill-column: 72
# paragraph-start: "*"
# End: