Clisp-2.45

Installation on Unix:
---------------------
 
This file describes the standard installation procedure.
Please do read this entire file before starting
- or, if you are impatient, start with step 2 and then skip to step 12.
Special hints for some platforms can be found in file unix/PLATFORMS.
Despite this file's location, it is applicable to cygwin and mingw as well.
 
1. (Optional)
   Choose which C compiler to use for building CLISP.
   This is normally not necessary; if GNU C is available under the
   name "gcc", it will be used.
 
   For example, if you were wanting to use gcc with full warnings, then
   type, if you are using csh:
 
         setenv CC "gcc -Wall"
 
   or if you are using bash or ksh:
 
         export CC="gcc -Wall"
 
   or if you are using sh:
 
         CC="gcc -Wall"
         export CC
 
   If you want to build a 64-bit version of CLISP, you will need to set
   CC to "gcc -m64".
 
2. (Recommended)
   Install a few libraries on which CLISP relies:
   * GNU libsigsegv
      + Highly recommended: needed for generational garbage collection
        and for stack overflow detection in interpreted Lisp code.
      <ftp://ftp.gnu.org/pub/gnu/libsigsegv/>
      <http://sourceforge.net/projects/libsigsegv/>
   * GNU libffcall
      + Highly recommended: needed for the foreign function interface.
      <ftp://ftp.gnu.org/pub/gnu/libffcall/>
      <http://www.gnu.org/software/libffcall/>
   * GNU libiconv
      + Not needed on systems with glibc 2.2 or newer, or MacOS X 10.3 or
        newer, but recommended on all other systems for additional encodings.
      <ftp://ftp.gnu.org/pub/gnu/libiconv/>
      <http://sourceforge.net/projects/libiconv/>
   * GNU readline
      + Recommended: needed if you want terminal command line editing.
      <ftp://ftp.gnu.org/pub/gnu/readline/>
      <http://cnswww.cns.cwru.edu/~chet/readline/rltop.html>
   * GNU gettext
      + Not needed on systems with glibc 2.2 or newer, but recommended on all
        other systems: needed if you want CLISP with native language support.
      <ftp://ftp.gnu.org/pub/gnu/gettext/>
      <http://www.gnu.org/software/gettext/>
 
   When you install your libraries in a non-standard location, you will
   need to tell the location to the top-level configure, e.g.:
 
   ./configure --with-libreadline-prefix=/sw               \
               --with-libsigsegv-prefix=/usr/local         \
               --with-libiconv-prefix=/home/user/my/prefix \
               --with-module=libsvm --with-module=rawsock  \
               --cbc my-build-directory
 
3. Choose the name of a directory in which to build CLISP.
   (This allows you to build CLISP with different compilers on the same
   machine or for different architectures in the same filesystem, sharing
   the same source.)
   For example, depending on the chosen compiler, let's use build-with-gcc.
   Then execute
 
         ./configure build-with-gcc
 
   This will prepare a directory build-with-gcc/ and figure out many
   system and compiler dependent parameters needed by CLISP.
 
   (Note: Some `make's - for example the HP-UX make - have problems
   with symbolic links. You may avoid these by calling
 
         ./configure
 
   without argument. Then CLISP will be built in the src/ directory
   itself.)
 
   Note that the argument to configure can be an absolute pathname.
   For example, the following command will also work.
 
         ./configure /tmp/with-gcc-wall
 
   Note that you should not use a directory name with spaces in it.
   This is especially relevant to woe32-based systems, such as mingw and cygwin.
   Specifically, if your source distribution is in
     "C:\Documents and Settings\username\...\clisp\"
   then your best bet is "./configure /tmp/build-clisp",
   not "./configure build".
 
4. The previous step printed a recommendation how to continue.
   Follow the recommendation: go to this directory
 
         cd build-with-gcc
 
   For platform specific adjustment of the makefile, take a look at the
   PLATFORMS file.
 
5. If you wish to build CLISP with add-on modules (see the main INSTALL file
   for a list), edit Makefile and change the line defining the MODULES variable.
   The list of modules included with the distribution is available via
 
         ./configure --help-modules
 
   This can be automated by adding --with-module= arguments to the ./configure
   invocation in step 2.
 
6. Edit the contents of config.lisp appropriately for your site,
   especially the definitions of short-site-name and long-site-name.
 
7. Type
 
         make
 
   to build CLISP.
   If you are an expert in building CLISP, you may alternatively do this
   in eight steps:
         make init                prepares all symbolic links and utilities
         make allc                makes all *.c files
         make lisp.run            makes the executable
           (cygwin & mingw: use "make lisp.exe" instead)
         make interpreted.mem     a memory image with everything uncompiled
         make halfcompiled.mem    a memory image with compiler.fas and
                                  the rest uncompiled
         make lispinit.mem        makes all *.fas files and
                                  a memory image with everything compiled
         make manual              makes the documentation
         make modular             makes the base module set
 
   If something goes wrong, check and optionally modify the contents of
   the file config.h and retry this step. Yes, there are many warnings,
   we know. Most of them are harmless.
 
   If you need to switch to a different compiler, execute a
         make distclean
         cd ..
   and go back to step 1.
 
8. (Optionally)
   Three more tests for CLISP. Let the compiler (now compiled!) recompile
   itself:
 
         make check-recompile
 
   Check whether CLISP passes the XCL/CLISP test suite:
 
         make check-tests
 
   Check whether CLISP passes the Minejima/SACLA test suite:
 
         make check-sacla-tests
 
   Check whether CLISP passes the Dietz/GCL test suite:
 
         make check-ansi-tests
 
   Or run all four tests with one shot:
 
         make check
 
   If you build with some modules, you can test those of them that come
   with a test suite with:
 
         make mod-check
 
   Note that the modules may use external libraries, and test failures
   may indicate bugs in those libraries rather than in CLISP.
   See the specific test suite for detail.
 
9. Edit the `prefix' variable in the makefile (you could also have specified
   it as command line option --prefix=... to `configure' in step 3), then type
 
         make install
 
   If `prefix' is /usr/local, then this will install the CLISP binaries
   into /usr/local/bin and /usr/local/lib (creating a directory
   /usr/local/lib/clisp) and the manual page into /usr/local/man/man1.
   You may need superuser privileges for this step when installing into
   public directories.
   If you built with modules (e.g., ./configure --with-module=rawsock)
   there will be two "linking sets" in /usr/local/lib/clisp/ - "base"
   and "full" (see <http://clisp.cons.org/impnotes.html#modules>).
   You can chose which linking set to run by using "-K" option of clisp
   (see <http://clisp.cons.org/clisp.html#opt-link-set>)
   Note that some modules (i18n, regexp, syscalls and readline at this time)
   are included in the "base" linking set by default,
   see BASE_MODULES in build-dir/Makefile.
 
10. If you want other people to benefit from your work, you can make a binary
   distribution of CLISP for your platform which we will distribute.
   To do this, make sure you have executed step 7 above,
   adjust the definition of ROFF_MAN in the makefile,
   then type
 
         make distrib
 
   to create a binary distribution in a clisp-*.tar.gz file.
   Tell us about your success, and make that file available to us.
 
   If you want to distribute the binaries, recall that you have to accompany
   them with full source; see the files COPYING and GNU-GPL.
 
11. The last thing to do:
 
         cd ..
 
12. If you are lazy and have too few spare neurons to remember this long
    process, just use the shortcut, like I do:
 
         ./configure --with-module=rawsock --cbc build-dir
 
    this covers the build process through step 8 (except mod-check).
    If you want to instal too, do
 
         ./configure --with-module=rawsock --install build-dir
 
    su(1) will prompt you for the root password if the installation
    destination is not writable by you.
 
 
Additional Information for Maintainers of Binary Packages:
----------------------------------------------------------
 
1. CLISP build process respects the CFLAGS environment variable,
   and, when GCC is used and CFLAGS is unset, "-g -O2" is used, see
   <http://www.gnu.org/software/autoconf/manual/html_node/C-Compiler.html>.
   This means that if your distribution's policy is to minimize executables'
   size at the expense of debuggability you should configure CLISP like this:
        CFLAGS="-O" ./configure ...
   The often used alternative - to strip the executables before packaging -
   breaks DISASSEMBLE on functions written in C: (DISASSEMBLE #'CAR) prints
   the disassembly of the whole executable instead of just a few lines
   that constitute the function CAR.
   Note that makemake (the script run by configure and "make Makefile")
   will set the appropriate optimization level,
   so it does not matter if you set CFLAGS to "-O", "-O2" or just "".
   See <https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=199887>.
 
2. Despite whatever ldd may say to the contrary, CLISP is linked
   _statically_ against libsigsegv, so whenever you upgrade libsigsegv,
   you MUST recompile CLISP.
   See <https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=199525>.
 
3. Module selection: it is up to you which modules to distribute.
   The trade off is offering extra functionality while increasing dependency
   on other packages, the executable size, and the distribution size.
   Another issue is offering a uniform experience to all CLISP users
   regardless of platform or distribution.
   We recommend keeping the base linking set (i18n, regexp, syscalls, readline)
   intact and adding at least rawsock and libsvm to the full linking set.
   See <http://clisp.cons.org/impnotes/modules.html#base-modules>
   and "./configure --help-modules".
 
Authors:
--------
 
        Bruno Haible
        Michael Stoll
        Sam Steingold
 
Email: clisp-list@lists.sourceforge.net

Installation on Win32 (WinNT, Win95) using the MSVC6.0 or MSVC7.0
=================================================================
development environment, using native system calls
==================================================
 
** Note! Binaries created with MSVC 7.0 with MFLAGS=-MD should not be
   distributed: They depend on a closed-source library 'msvcr70.dll' which is
   not normally part of a Woe32 installation. You cannot distribute
   'msvcr70.dll' with the binaries - this would be a violation of the GPL and
   of the Microsoft EULA. You can distribute the binaries without including
   'msvcr70.dll', but this will cause problems for users that don't have this
   library on their system. Therefore it is not recommended. This problem does
   not occur with MSVC 6.0 and earlier.
 
** Note! The easiest way to get a native win32 version of CLISP is to use
   -- cygwin <http://cywgin.com> or
   -- mingw/msys <http://www.mingw.org/>.
   Either way, read ../unix/INSTALL, get libsigsegv, and do
   $ ./configure --with-mingw --cbc build-mingw --with-module=...
   $ cd build-mingw
   $ make distrib
   unzip the distribution in your preferred location, and run install.bat.
   The GCC builds should be faster than the MSVC builds
   because CLISP uses some GCC-specific assembly code.
 
If you still want to use the MS C compiler, here are the steps:
 
1. Build a few recommended libraries: libiconv and libsigsegv.
   - GNU libsigsegv (highly recommended for C stack overflow detection
     and high-performance Generational GC),
   - GNU libiconv (for more character set conversions).
 
2. Unpack the source, start a console with a shell.
   Make sure that the MSVC utilities ("cl" etc.) are found in PATH.
   For example, I use the following settings:
 
        set MSDEVDIR=C:\Program Files\Microsoft Visual Studio
        set MSVCDIR=%MSDEVDIR%\VC98
        set Include=%MSDEVDIR%\VC98\include
        set Lib=%MSDEVDIR%\VC98\lib
        set PATH=%MSDEVDIR%\VC98\bin;%MSDEVDIR%\Common\MSDev98\Bin;%PATH%
 
   Alternatively you can use a file vcvars32.bat supplied with MSVC. Copy
   it to some location in the PATH and add the following line to its end:
 
        %1 %2 %3 %4 %5 %6 %7 %8 %9
 
   Now you can call VC command line utilities in the proper environment
   prepending it with vcvars32. For example
 
        vcvars32 nmake
 
3. Ensure unix-like command-line utilities used in the build: sed, grep,
   touch, rm (more the better) are in the PATH.
   There are quite a few such packages available, for example
   - UnxUtils <http://unxutils.sourceforge.net/>,
   - GnuWin32 <http://gnuwin32.sourceforge.net/> or
   - cygwin <http://cywgin.com> (overkill for this particular case).
 
4. Then build a few tools and libraries:
 
        cd ffcall
        nmake -f Makefile.msvc check
        cd ..
 
   Copy the appropriate makefile from win32msvc to src\makefile:
 
   Check that environment variable MSVCDIR points to VC98 directory
   or uncomment and modify the value of MSVCDIR in src\makefile to
   match your site.
 
   Now that the libraries recommended in 1. are not distributed with
   CLISP anymore, the makefiles do not make use of them. For
   actually using libsigsegv with CLISP, here is a way to go:
        a) Compile the library as per libsigsegv\README.woe32
        b) Copy sigsegv.lib and sigsegv.h to src
        c) Remove -DNO_SIGSEGV from CFLAGS in src\makefile
        d) Add sigsegv.lib to LIBS in src\makefile
 
        cd src
        nmake
 
5. (optional) Using cygwin:
 
        cd src
        make distrib