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:

* GCL, 2.6.7 or 2.6.8

* 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.

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 Closure CL the '--enable-gmp' option it is available

only if the development version of GMP is installed. Note: using

GMP should work on all sbcl and Closure CL platforms except

for Closure 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

trashing).

- 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 Closure CL. Also if limit on virtual memory is too small

sbcl-based or Closure 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.

- 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

- gcl, version 2.6.8 works OK. If you want to try development

version from git note that main branch currently is very

unstable and can not build FriCAS.

In the past in case of build problems the following configure line

was helpful:

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

- 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

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.

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

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.

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

Using GMP with sbcl or Closure CL.

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). Currently there are two available GMP versions,

version 5 is much faster than version 4. Then configure FriCAS

adding '--enable-gmp' option to the 'configure' arguments.

FriCAS also has support for using GMP with Closure CL.

Currently Closure CL with GMP works on 32/64 bit Intel/AMD

processors and ARM (using Closure CL with GMP is not supported

on Power PC processors).

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

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.