> Yes, that and |git repository| (we should have actual URL in
> the file).
We can discuss this. The |...| stuff is actually defined in conf.py.
And conf.py takes input from environment variables during "make".
This was done on purpose, since I want the web address not be hardcoded.
It should also work when I present a website at my github fork.
It would be super simple to replace |...| by an awk script.
In fact, since the markup in install.rst is soooo simple, it would be
quite easy to produce a awk script that removes |...|.
> Problem is with quantity, that is actualy more
> than is some other markup formats.
What else is TOO MUCH? Name it!
BTW, in Emacs, there is a special rstdoc mode that brings me
highlighting. Vim has probably a similar mode. It is not only YOU that
reads the install file. In fact, the younger generation is for whom we
all do this, no? What is the intended user base of FriCAS? Researchers
with age over 65?
>> What you basically say is, that my conversion was work-done-for-nothing.
> If you want to view it in this way. Not all things work as
> expected/hoped for...
Yes. But do you think that increases the amount of people working on FriCAS?
>> Are you afraid of writing .rst stuff or do you think that my
>> install.rst is not nicely readable as plain text?
> Mainly the second, INSTALL should be readable as plain text.
> It is OK to have marked up version as master source. Some
> markup formats can produce decent looking plain text versions
> (IIUC sphinx is supposed to produce text version, but ATM
> this does not work for me so in particular I can not see
> if this is good enough). Another issue is dependency. .rst
> is claimend to be ligtweight, but supporting programs are
> rather large...
>
>> I definitely want
>> install.rst on the web and showing a plain text file on an otherwise
>> sphinx-generated site would look very unprofessional.
>
> .rst pretending to be plain text is at least as unprofessional.
I never said .rst is plain text (actually it is pure ASCII). But it *is*
easily readable.
Anyway. Offer for compromise. I write a script that computes (without
sphinx) the INSTALL file from the install.rst file.
Thank you, Kurt. I attach the output of
pandoc --from rst --to plain install.rst > INSTALL
Replacing the |...| stuff before giving install.rst to pandoc would be
simple, but was not done for the attachment.
Waldek, would you be satisfied with having both
src/doc/sphinc/source/install.rst and INSTALL (generated from
install.rst)? Both committed to the git repo?
May I ask you whether you really find the attached INSTALL file easier
to read than install.rst.
Ralf
--
You received this message because you are subscribed to the Google Groups
"FriCAS - computer algebra system" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to fricas-devel+unsubscr...@googlegroups.com.
To view this discussion on the web visit
https://groups.google.com/d/msgid/fricas-devel/54a0f2e9-4b2b-0d35-757b-25314fdcee83%40hemmecke.org.
INSTALLATION GUIDE
Table of Contents
Quick installation
FriCAS now tries to support standard GNU build/installation conventions.
So if you have sources and all prerequisites, then :
configure && make && sudo make install
should work. The above will install FriCAS files into
/usr/local/lib/fricas/ and put the fricas command into /usr/local/bin/.
You can give arguments to configure to change those locations.
Prerequisites
Lisp
To _build_ FriCAS you need _one_ of the following Lisp variants:
- SBCL 1.0.7 or later (preferred)
- Clozure CL (former openmcl), starting from openmcl 1.1 prerelease
070512
- ECL 0.9l or later
- CLISP 2.41 or later
- CMUCL
- GCL version 2.6.8 works OK.
If you want to try development version of GCL 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
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 (optional, but needed for graphics and HyperDoc)
On Debian (or Ubuntu) install the following packages. :
sudo apt install libx11-dev libxt-dev libice-dev \
libsm-dev libxau-dev libxdmcp-dev libxpm-dev
xvfb (optional, but highly recommended)
If you compile FriCAS from the , and configure does not detect the
xvfb-run program, then graphic examples will not be built. See Section
HyperDoc and graphics for more detail. :
sudo apt install xvfb
GMP (optional)
You you use SBCL or Clozure CL the --enable-gmp configure 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. :
sudo apt install libgmp3-dev
LaTeX (optional)
If you run FriCAS in Emacs (efricas) you can enable :
)set output tex on
to show rendered TeX output. For that to work, you need the following. :
sudo apt install texlive auctex dvipng
In order to build the , you also need the following LaTeX packages
(available from CTAN). :
amsmath
breqn
tensor
mleftright
epsf
verbatim
hyperref
color
listings
makeidx
xparse
tikz
SphinxDoc (optional)
The documentation is built via Sphinx. :
sudo apt install python3 python3-pip
pip3 install -U Sphinx
Aldor (optional)
If you want to use Aldor to extend the FriCAS library, you must, of
course, hava Aldor installed, and add --enable-aldor to your configure
options when you compile FriCAS.
Extra libraries needed by GCL
This only applies if you use Debian GCL. :
sudo apt install libreadline5-dev libncurses5-dev libgmp3-dev \
libxmu-dev and libxaw7-dev
Extra libraries needed by ECL
This only applies if you use Debian ECL. :
sudo apt install libffi-dev
Detailed installations instructions
We assume that you have installed all necessary prerequisittes.
1. Change to a directory with enough (0.8 GB) free space
2. Fetch sources :
git clone https://github.com/fricas/fricas
cd fricas
3. Configure. Assuming that you want fricas files to be installed in
//tmp/usr. :
./configure --with-lisp=/path/to/your/lisp --prefix=/tmp/usr
where /path/to/your/lisp is name of your Lisp. For example, type :
./configure --with-lisp="sbcl --dynamic-space-size 4096"
--prefix=/tmp/usr --enable-gmp --enable-aldor
to build with SBCL and 4 GiB dynamic space, use GMP, and enable the
build of the Aldor library libfricas.al.
4. Build and install :
make
make install
Type :
configure --help
to see all possible options.
Extra information
The preferred way to build FriCAS is to use an already installed Lisp.
Also, it is preferable to use a separate build directory. Assuming that
the source tree is in $HOME/fricas, you build in $HOME/fricas-build
subdirectory and your Lisp is called sbcl the following should just
work. :
cd $HOME/fricas-build
$HOME/fricas/configure --with-lisp=sbcl && make && sudo make install
Alternatively, if you use GCL you can just put GCL sources as a
subdirectory (called gcl) of the 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 a command to invoke the respective Lisp variant. Build machinery
will automatically detect which Lisp is in use and adjust as needed.
HyperDoc and graphics
If you compile FriCAS from the , and configure does not detect the
xvfb-run program, then graphic examples will not be built. This results
in 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 preferrable to use the xvfb-run program, replacing make viewports
above by :
xvfb-run -a -n 0 -s '-screen 0 1024x768x24' make viewports
Algebra optimization
When writing/compiling programs there is always tradeoff between speed
and safety. Programs 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 a program may just blindly goes 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 programmers, but another possibility is
to have a compiler which automatically inserts various checks. FriCAS is
compiled by a 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 Clozure 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 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 :
configure`--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.
Building documentation
After a build of FriCAS, (suppose your build directory is under $BUILD),
the can be built via :
cd $BUILD/src/doc
make doc
This builds the full content of the including the (also known as the
FriCAS User Guide) into the directory src/doc/html from which it can be
committed to the gh-pages branch of the official .
Most links also work fine if you start :
firefox src/doc/html/index.html
but some links point to the web. If you want the links referring only to
the data on your computer, you call the compilation like this :
cd $BUILD/src/doc
make localdoc
This will have broken references to the FriCAS Demos and Tutorials as
they live in a separate repository. Do the following to get a local copy
and thus have working references. :
cd $BUILD/src/doc/html
git clone -b gh-pages https://github.com/fricas/fricas-notebooks
For more control on the generation of the FriCAS website content, you
can set various variables (see src/doc/Makefile.in) in the . For
example, if you like to push to your forked FriCAS repository and refer
to branch foo instead of master then do as follows (replace hemmecke by
your account name). :
make PACKAGE_SOURCE=https://github.com/hemmecke/fricas \
BRANCH=foo \
PACKAGE_URL=https://hemmecke.github.io/fricas \
doc
If you want to change the version information provided by default
through configure.ac, you can add a variable assignment like this to the
above command. :
PACKAGE_VERSION=$(git log -1 --pretty=%H)
PACKAGE_VERSION="1.3.6+ `date +'%Y-%m-%d %H:%M'`"
Then, checkout the gh-pages branch and put the data from
$BUILD?src/doc/html into your gh-pages branch. :
git clone g...@github.com:hemmecke/fricas.git
git checkout gh-pages
git rm -rf .
rm '.gitignore'
echo 'https://help.github.com/articles/using-jekyll-with-pages' > .nojekyll
cp -a $BUILD/src/doc/html/* .
rm -r _sources/api/
git add .
git commit -m "$PACKAGE_VERSION"
git push origin gh-pages
Of course, leave out the --orphan switch, if you already have an
appropriate gh-pages branch.
Optional: If you add :
text/x-spad spad
to /etc/mime.types and in firefox associate text/x-spad with your
editor, then clicking on a .spad file opens the .spad file in in this
editor.
Aldor library libfricas.al
You cannot only extend the FriCAS library by .spad files (SPAD
programs), but also by .as files (Aldor programs). For the latter to
work FriCAS needs a library libfricas.al.
This library can be build as follows. (An Aldor compiler is of course a
prerequisite.) :
configure --enable-aldor --prefix=/tmp/usr
( cd src/aldor && make )
make install
After that you should be able to compile and use the program below in a
FriCAS session via :
)compile sieve.as
sieve 10
The program sieve.as is:
--
-- sieve.as: A prime number sieve to count primes <= n.
--
#include "fricas"
N ==> NonNegativeInteger;
import from Boolean, N, Integer;
sieve(n: N): N == {
isprime: PrimitiveArray Boolean := new(n+1, true);
np: N := 0;
two: N := 2;
for p in two..n | isprime(p::Integer) repeat {
np := np + 1;
for i in two*p..n by p::Integer repeat {
isprime(i::Integer) := false;
}
}
np
}
Known problems
- currently on when using case insensitive filesystem (typically on
Mac OSX and Windows), the git version can be only build in a
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 not be 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 a bug in the 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.
- 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 the 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.
