INSTALL

Quick installation:

FriCAS now tries to support standard GNU build/installation
conventions.  So if you have sources and all prerequisites
just:

configure && make && make install

should work. The above will install FriCAS files in
/usr/local/lib/fricas directory and put fricas command in
/usr/local/bin directory, you can give arguments to configure
to change those locations.

NOTE!! If you use svn (minimal version) the above will install broken
HyperDoc pages -- all graphic examples will be missing (and trying to access
them will crash hypertex).

The get working graphic examples login into X and replace 'make' above by
the following:

make MAYBE_VIEWPORT=viewports

alternatively, after 'make' finishes use:

make viewports

Important: building graphic examples accesses the X server, so it will
not work on text console.  During build drawings will temporarily
appear on the screen.  Redirecting X via ssh should work fine,
but may be slow.

It is also possible to use xvfb-run program, replacing 'make viewports'
above by:

xvfb-run --server-args="-screen 0 1024x768x24" --auto-servernum -n 0 make viewports


--------------------------------------------------------

Prerequisites:

- Lisp, one of:
    * sbcl, 1.0.7 or later
    * clisp, 2.41 or later
    * Clozure CL (former openmcl), starting from openmcl 1.1 prerelease
    070512
    * ECL, 0.9l or later (we recommend latest version)
    * cmucl
  All Lisp implementations should give essentially the same
  functionality, however performance (speed) may differ quite a lot.
  ATM CMU CL port should be considered experimental, it received only
  little testing.  Also CMU CL seem to have problems on some machines.
  By default FriCAS tries to use sbcl, since it is fast and reliable.
  On 64-bit AMD64 on average sbcl is the fastest one (9 times faster
  than clisp), Clozure CL the second (about 1.5 times slower than sbcl),
  than gcl and ECL (about 3 times slower than sbcl) and clisp is the slowest
  one.  Note: older versions of ECL were much (about 4 times) slower,
  you should use newest version if you care about speed.  FriCAS used
  to build using GCL.  However, due to incompatible changes in GCL newest
  GCL will not work for FriCAS, build will fail.  Unfortunatly failing
  versions show the same version number, namely 2.6.12 as working ones.
  So currently using GCL for building FriCAS is unsupported.

  Some computation work much faster on 64-bit machines, especially
  when using sbcl.

- X libraries and headers (including Xpm library).

  On Debian (or Ubuntu) you probably need: libx11-dev, libxt-dev, libice-dev,
  libsm-dev, libxau-dev, libxdmcp-dev, libxpm-dev.

- If using sbcl or Clozure CL the '--enable-gmp' option is available
  only if the development version of GMP is installed.  Note: using
  GMP should work on all sbcl and Clozure CL platforms except
  for Clozure CL on Power PC.

- Extra libraries needed to have LaTeXed output (ASCII output works
  fine without) in efricas.

  On Debian (or Ubuntu) you probably need: dvipng, auctex

- Extra libraries needed by gcl.  If you use Debian gcl you probably
  need libreadline5-dev, libncurses5-dev, libgmp3-dev, libxmu-dev and
  libxaw7-dev

- For ECL you probably need libffi-dev.

Known problems:

- currently on when using case insensitive filesystem (typically
  on Mac OSX and Windows) svn version can be only build in
  separate directory (in-tree build will fail).  This does not
  affect release tarball.
- by default sbcl 1.0.54 and newer limits memory use to 1GB, which
  is too small for heavy use.  To work around this one can
  pass '--dynamic-space-size' argument during _sbcl_ build
  to increase default limit.  We recommend limit slightly
  smaller than amount of available RAM (in this way FriCAS
  will be able to use almost all RAM, but limit should prevent
  thrashing).

- on some systems (notably MAC OSX) when using sbcl default
  limit of open files may be too low.  To workaround increase
  limit (experiments suggest that 512 open files is enough).
  This should be not needed in FriCAS 1.1.7.

- sbcl from 1.3.1 to 1.3.4 runs out of memory when compiling
  FriCAS.  This is fixed in newer versions of sbcl.

- using sbcl from 1.0.47 to 1.0.49 compilation is very slow
  (few hours on fast machine).  This is fixed in newer
  versions of sbcl.

- sbcl-1.0.29 has bug in 'directory' function which causes build
  failure.  This problem is fixed in 1.0.29.54.rc1.

- 1.0.29.54.rc1 has broken complex 'tanh' function -- you will get
  wrong results when applying 'tanh' to Complex DoubleFloat.

- in sbcl 1.0.35 and up Control-C handling did not work.  This
  should be fixed in current FriCAS.

- Some Linux versions, notably SuSe, by default seem to have very small
  limit on virtual memory.  This causes build failure when using sbcl
  or Clozure CL.  Also if limit on virtual memory is too small
  sbcl-based or Clozure CL-based FriCAS binary will silently fail
  at startup.  The simplest workaround is to increase limit,
  in the shell typing

    ulimit -v unlimited

  Alternatively for sbcl one can use '--dynamic-space-size' argument
  to decrease use of virtual memory.

- building FriCAS fails when using newest gcl

- older gcl had serious problems on Macs and Windows.

- released gcl-2.6.9 has a bug which causes failure of FriCAS
  build.  This problem is fixed in 2.6.10 and later but but there
  is a different one.  Namely, FriCAS builds but apparently
  on some machines is miscompiled using released 2.6.10 or 2.6.11
  or 2.6.12.

- On Gentoo system installed gcl probably will not work, one need to
  build own one.

- Older version of gcl are incompatible with Fedora "exec-shield" and
  strong address space randomization (setting randomize_va_space to 2).
  Newest CVS version of 2.6.8 branch of gcl fixes this problem.

- gcl needs bfd library.  Many Linux systems include version of bfd
  library which is incompatible with gcl.  In the past we advised to
  use in such case the following configure line:

    ./configure --disable-xgcl --disable-dynsysbfd --disable-statsysbfd --enable-locbfd

- Boehm garbage collector included in old ECL (version 6.8) is incompatible
  with Fedora strong address space randomization (setting randomize_va_space
  to 2).  Using newer version of Boehm garbage collector (7.0 or 7.1) or
  newer ECL should solve this problem.

- Striping FriCAS binaries is likely to break them.  In particular Clisp
  based FriCAS may crash with message:

    module 'syscalls' requires package OS.

  while sbcl will show only loader prompt.

- On Mac OSX Tiger some users reported problems with pseudoterminals,
  build stopped with message:

    fork_Axiom: Failed to reopen server: No such file or directory

  This problem is believed to be fixed in FriCAS-1.0.5 (and later).

- ECL 9.6.2 (and probably also 9.6.1 and 9.6.0) has a bug with
  handling string constants which causes build based on this version
  to fail.  This bugs is fixed in newer versions.
  ECL 9.7.1 generates wrong C code, so that build fails.  This
  is fixed in newer versions.

- Unicode-enabled ECL before 9.8.4 is unable to build FriCAS.

- ECL up to version 0.9l may segfault at exit.  This is usually harmless,
  but may cause build to hang (for example when generating ug13.pht).

- In general, any error when generating documentation will cause build to hang.

- Clozure CL 1.10 apparently miscompiles some operations on U32Matrix.
  Version 1.11 works OK.

- Clozure CL 1.7 and 1.6 apparently miscompiles FriCAS.  Versions 1.8 and
  newer and 1.5 and earlier work OK.

- Clozure CL earlier than release 1.2 (former Openmcl) has a bug in Lisp
  printer.  This bug causes incorrect printing of FriCAS types.  Also,
  Clozure CL earlier than release 1.2 has bug in complex
  cosine function.  Those bugs are fixed in release 1.2.  If you want to
  use earlier version you can work around the bugs applying
  the 'contib/omcl.diff' patch and recompiling the compiler (see the patch
  or Clozure CL documentation for instructions).

- Older versions of Clisp may fail to build FriCAS complaining
  about opening already opened file -- this is error is
  spurious, the file in question in fact is closed, but
  for some reason Clisp got confused.

- On new Linux kernel build using Clisp may take very long time.  This
  is caused by frequent calls to 'fsync' performed without need by Clisp.

--------------------------------------------------------

Getting Lisp.

To build FriCAS you need to install Lisp first.  You need
_one_ of the following:

- sbcl

  http://sbcl.sourceforge.net/platform-table.html

- Clozure CL

  http://ccl.clozure.com/manual/chapter2.2.html#id357702
  ftp://ftp.clozure.com/pub/release/

- ECL

  http://ecls.sourceforge.net

- clisp

  http://clisp.cons.org

- cmucl

--------------------------------------------------------

Step by step instructions for first time users:

Latest (development) version of FriCAS is available only
via svn, so you need svn client (see http://subversion.tigris.org/).

You also need Lisp -- see links in section "Getting Lisp" and
follow instructions.

0) Change to a directory with enough (0.8 GB) free space

1) Fetch sources:

svn co svn://svn.code.sf.net/p/fricas/code/trunk fricas

Aternatively, there is git mirror at github.  To fetch it is
the following command (remove the "--depth 1" option for access
to the change history):

git clone --depth 1 https://github.com/fricas/fricas

2) Create build directory and change to it:

mkdir ax-build
cd ax-build

3) Configure.  Assuming that you want fricas files to be installed in
/tmp/usr

../fricas/configure --with-lisp=/path/to/your/lisp --prefix=/tmp/usr

where /path/to/your/lisp is name of your Lisp (for example sbcl)

4) Build and install:

make
make install

If you want graphic examples read the note before.

-------------------------------------------------------

Arguments for the configure script

To choose the installation location, use the '--prefix' option and specify a
path.

Selecting a Lisp compiler:

Currently --with-lisp option accepts all supported lisp variants, namely
sbcl, clisp, ecl and Clozure CL (openmcl).  Note: the argument
is just command to invoke chosen Lisp.  Build machinery will
automatically detect which Lisp is in use and adjust as needed.

Optimization settings for Lisp compilation: see "Algebra optimization".

GMP (for faster arbitrary precision arithmetic): search for "Using GMP" in this
document.

Example configure command:

../fricas/configure --prefix=/home/nsajko/usr \
        '--with-lisp=sbcl --control-stack-size 512 --dynamic-space-size 6000' \
        --enable-gmp

This configures make to

* install to /home/nsajko/usr

* build lisp with SBCL and increased stack and heap memory limits

* make FriCAS use GMP which is installed in /usr

-------------------------------------------------------

Algebra optimization

When writing/compiling programs there is always tradeoff
between speed and safety.  Program may include many
checks to detect errors early (and allow recovery),
such programs are safe but checks take time so the program
is slower.  Or program may just blindly go forward hoping
that everything goes well.  Typically the second program
will be faster, but in case of problems it may crash
without any hint why and take user data with it.

Safety checks may be written by programmer, but another
possibility is to have compiler which automatically inserts
various checks.  FriCAS is compiled by Lisp compiler and
Lisp compilers may insert safety checks.  How many checks
are inserted may be controlled by the user.  By default
FriCAS tries to strike good balance between speed and
safety.  However, some FriCAS users want different
tradeoff.  The '--enable-algebra-optimization=S' option
to configure allows changing this setting: S is a Lisp
expression specifying speed/safety tradeoff used by
Lisp compiler.  For example:

--enable-algebra-optimization="((speed 3) (safety 0))"

chooses fastest (but unsafe) variant, while

--enable-algebra-optimization="((speed 2) (safety 3))"

should be very safe (but possibly slow).

Note: this setting affects only algebra (that is mathematical
code).  The rest of FriCAS always uses default setting.
Rationale for this is that mathematical code is unlikely to
contain errors which can crash the whole system.

--------------------------------------------------------

Linux: get better performance when really necessary

The Linux operating system kernel usually uses methods to mitigate some CPU
security bugs, and these mitigations can take a great toll on code execution
speed. This is mainly a problem for Intel machines.

As the mitigations are required for security on affected harware platforms when
executing untrusted code (like in Web browsers, for example); the typical
scenario where one would disable the kernel mitigations while using FriCAS is
when it is known that the computations will be resource and time (e.g., many
hours) demanding, or when one has a machine dedicated to trusted code (so no
browsing the Web).

If one wants to execute untrusted code while running FriCAS; even if the
untrusted code is behind a hypervisor, virtual machine, JavaScript engine,
etc.; DO NOT DISABLE THE MITIGATIONS.

If one is sure that it is safe for one's system to do so, one may disable some
of these mitigations by adding mitigations=off to the kernel's boot parameters.
This will probably be accomplished by configuring the bootloader, so read the
bootloader's documentation for details. The following may also be useful:
https://wiki.archlinux.org/index.php/Kernel_parameters
https://www.kernel.org/doc/html/latest/admin-guide/kernel-parameters.html
https://www.kernel.org/doc/html/latest/admin-guide/hw-vuln/

--------------------------------------------------------

Using GMP with sbcl or Clozure CL.

See https://gmplib.org for more information on the GNU Multiple Precision
Arithmetic Library.

Currently on average FriCAS is fastest when compiled using sbcl.
However, sbcl normally uses its own routines for computations
with large numbers and those routines are slower than GMP.
FriCAS now has special support to replace sbcl arithmetic
routines by GMP.  To use this support install GMP including
header files (development package if you install via a package
manager).  Then configure FriCAS adding '--enable-gmp' option
to the 'configure' arguments.

FriCAS also has support for using GMP with Clozure CL.
Currently Clozure CL with GMP works on 32/64 bit Intel/AMD
processors and ARM (using Clozure CL with GMP is not supported
on Power PC processors).

When you have GMP installed in a non-standard location (this usually
means anything other than /usr or /usr/local) then you can specify
the location with the 'configure' argument '--with-gmp=PATH'. This
supposes that the include file is in 'PATH/include' and libgmp is in
'PATH/lib'. If you have a different setup, then you can specify
'--with-gmp-include=INCLUDEPATH --with-gmp-lib=LIBPATH' (specify the
directories where the include files and libgmp are found,
respectively).

These options also implicitly set --enable-gmp.  However,
if --enable-gmp=no is given, then '--with-gmp=...',
'--with-gmp-include=...' and '--with-gmp-lib=...' is ignored.

--------------------------------------------------------

Extra information about installation:

The preferred way to build FriCAS is to use already installed
Lisp.  Also, it is preferable to use a separate build
directory.  Assuming that source tree is in fricas subdirectory,
you build in ax-build subdirectory and your Lisp is called sbcl
the following should just work:

cd ax-build
../fricas/configure --with-lisp=sbcl && make && make install

Alternatively, if you use gcl you can just put gcl sources as a
subdirectory (called gcl) of fricas directory -- in this case the build
process should automatically build gcl and later use the freshly
build gcl.

Currently --with-lisp option accepts all supported lisp variants, namely
sbcl, clisp, ecl, gcl and Clozure CL (openmcl).  Note: the argument
is just command to invoke chosen Lisp.  Build machinery will
automatically detect which Lisp is in use and adjust as needed.