Hi Waldek,
On 1/8/24 01:15, Waldek Hebisch wrote:
I would like to do the following change to install.rst (and
consequently INSTALL). This is mostly change due to Ralf,
but I did small change to Aldor instructions. Now it is
enough to give '--enable-aldor' to make Aldor interface,
do I removed part about changing directores and 'make'
in the subdirectory.
I've added your changes to my patch and also corrected a little.
It would be ready to commit (patch attached).
I also did small change to performance comparison corresponding
to my latest measurements.
The "than" in line 73 looks a bit weird. Shouldn't it be "then"?
https://github.com/hemmecke/fricas/blob/update-doc-aldor-interface/src/doc/sphinx/source/install.rst?plain=1#L73
On 64-bit AMD64 on average SBCL is the fastest one (9 times faster than
CLISP), Clozure CL and GCL the second (about 3 times slower than SBCL),
than ECL (about 7 times slower than SBCL) and CLISP is the slowest
^^^^
one. Note: very old versions of ECL were much (about 4 times) slower,
versions from about 7-10 years ago gave best performance and
newest ECL versions are progressively slower.
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/ad46df9f-0e4a-444b-b0bf-9ac5d4c732b1%40hemmecke.org.
From 0702ea7c439371c0c4875bee07eb0cdcc611662b Mon Sep 17 00:00:00 2001
From: Ralf Hemmecke <r...@hemmecke.org>
Date: Sun, 10 Dec 2023 18:11:01 +0100
Subject: update documentation for building FriCAS Aldor interface
---
INSTALL | 89 +++++++++++++++++++++++--------
INSTALL.aldor | 55 -------------------
src/doc/sphinx/source/install.rst | 68 +++++++++++++++++------
3 files changed, 118 insertions(+), 94 deletions(-)
delete mode 100644 INSTALL.aldor
diff --git a/INSTALL b/INSTALL
index 027f8805..f8436bc5 100644
--- a/INSTALL
+++ b/INSTALL
@@ -68,10 +68,11 @@ 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: very old versions of ECL were much (about 4 times) slower, you
-should use reasonably new version if you care about speed.
+CLISP), Clozure CL and GCL the second (about 3 times slower than SBCL), than
+ECL (about 7 times slower than SBCL) and CLISP is the slowest
+one. Note: very old versions of ECL were much (about 4 times) slower,
+versions from about 7-10 years ago gave best performance and
+newest ECL versions are progressively slower.
Some computation work much faster on 64-bit machines, especially
when using SBCL.
@@ -168,17 +169,37 @@ SphinxDoc (optional)
The documentation is built via Sphinx.
sudo apt install python3 python3-pip
- pip3 install -U Sphinx==5.3.0
-
-**WARNING**: Currently, Sphinx 6 and higher will fail building the
-".html" pages.
+ pip3 install -U Sphinx
Aldor (optional)
-If you want to use Aldor to extend the FriCAS library, you must, of
-course, have Aldor installed, and add "--enable-aldor" to your
-configure options when you compile FriCAS.
+Aldor was originally invented to be the next generation compiler for
+Axiom (the system that FriCAS forked from). If you want to use
+Aldor to extend the FriCAS library, you must, of course, have Aldor_
+installed, and add "--enable-aldor" to your configure options when
+you compile FriCAS.
+
+The commands below download the Aldor git repository into
+"$ALDORDIR" and install it into "$ALDORINSTALLDIR". Adapt the
+directories to whatever you like.
+
+ ALDORDIR=$HOME/aldor
+ ALDORINSTALLDIR=$ALDORDIR/install
+ mkdir -p $ALDORDIR
+ cd $ALDORDIR
+ git clone https://github.com/aldorlang/aldor.git
+ mkdir $ALDORDIR/build
+ cd $ALDORDIR/build
+ $ALDORDIR/aldor/aldor/configure --prefix=$ALDORINSTALLDIR --disable-maintainer-mode
+ make -j8
+ make install
+
+Then make the aldor executable available in your "PATH" by adding
+the following lines to your ".bashrc".
+
+ ALDORINSTALLDIR=/absolute/path/to/aldor/install
+ export PATH=$ALDORINSTALLDIR/bin:$PATH
Extra libraries needed by ECL
@@ -480,15 +501,25 @@ You can not 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.)
+Note that building the interface temporarily needs about 2 GB extra
+disk space. Since currently, building the Aldor interface accesses the
+build files of a previous FriCAS build, you need about 3 GB disk
+space.
- configure --enable-aldor --prefix=/tmp/usr
- ( cd src/aldor && make )
- make install
+If you configured FriCAS using "--enable-aldor" option, then
+"make" will also build "libfricas.al" and "make install"
+will install it together with FriCAS.
+
+If the "aldor" binary is not reachable during build via your
+"PATH", you can add "--with-aldor-binary=/path/to/aldor" to the
+configure command line.
-After that you should be able to compile and use the program below in
-a FriCAS session via
+Note: at runtime, the Aldor binary is taken as specified by the
+"ALDOR_COMPILER" environment variable or (if not set) must be
+available through the "PATH".
+
+After installation you should be able to compile and use the program
+below in a FriCAS session via
)compile sieve.as
sieve 10
@@ -525,15 +556,25 @@ There are a couple of things to install.
#. Jupyter
#. jFriCAS
+The simplest way to install jFriCAS is via `pip` as follows
+
+ sudo apt install python3-pip
+ pip3 install jupyter
+ pip3 install jfricas
+
+You can also install jFriCAS into a python virtual environment from
+`jfricas at PyPI <https://pypi.org/project/jfricas/>`_ or from the
+git repository.
+
+Below, we describe the installation from the git repository.
+
Except for the file "$HOME/.jupyter/jupyter_notebook_config.py" that
maybe necessary to create, the following description will put most of
the things (in particular the git repositories) under the directory
"$FDIR".
We assume that FriCAS will be installed into "$FRICASINSTALL".
jFriCAS and Jupyter will go into "$JFRICASINSTALL"
-You can change any of these paths or even install without a python
-virtual environment, but there is no description (yet) for an
-installation without venv.
+You can change any of these paths.
FDIR=$HOME/fricas
GITREPOS=$FDIR
@@ -567,7 +608,7 @@ not work. If you have it installed, then uninstall it first.
python3 -m venv $JFRICASINSTALL
source $JFRICASINSTALL/bin/activate
- pip3 install wheel jupyter
+ pip3 install jupyter
cd $GITREPOS/jfricas
pip3 install .
jupyter kernelspec list
@@ -653,7 +694,7 @@ SCRIPT_EXTENSIONS = {
Make Jupytext available
"""""""""""""""""""""""
-In Ubuntu 22.04 you need not do run the commands from this section.
+In Ubuntu 22.04 you need not run the commands from this section.
It seemingly works without having to change something in the
configuration file. There were even reports that jFriCAS stopped
working if "c.NotebookApp.contents_manager_class" was set. However,
@@ -762,6 +803,7 @@ wish you can create distribution tarballs from trunk.
The binary distribution can be created as follows. First fetch and
unpack source tarball in work directory. Then in work directory
+
mkdir fr-build
../fricas-X.Y.Z/configure --enable--gmp --with-lisp=/path/to/hsbcl
make -j 7 > makelog 2>&1
@@ -952,6 +994,7 @@ Known problems
Aldor: https://github.com/aldorlang/aldor
+Axiom: http://axiom-developer.org/
CLISP: http://clisp.cons.org
Clozure CL: http://ccl.clozure.com/manual/chapter2.2.html
CMUCL: https://www.cons.org/cmucl/
diff --git a/INSTALL.aldor b/INSTALL.aldor
deleted file mode 100644
index cd4fe94f..00000000
--- a/INSTALL.aldor
+++ /dev/null
@@ -1,55 +0,0 @@
-Aldor (http://www.aldor.org) was originally invented to be the next
-generation compiler for Axiom.
-
-Since FriCAS is a fork of Axiom, Aldor programs can be run inside FriCAS.
-
-The following criteria have to be met.
-
- Aldor must be locally installed and the aldor executable must be
- available through the PATH environment variable.
- The command `aldor --print-confvar datadir` must return the path
- to the include and lib directory, i.e. $datadir/include/aldor.conf and
- $datadir/lib/libfoam.al must be available.
-
-Note that building Aldor interface uses more than 1.6 GB disc space.
-Since currently building Aldor interface requires building FriCAS
-together you need about 2.4 GB free disc space.
-
-Suggestion for building the aldor interface:
-
-1. Configure a VPATH (or out-of-source) build of FriCAS.
-
- cd /path/to/builddir
- /path/to/fricas-src/configure --prefix=/path/to/installdir --enable-aldor
-
-2. Start the build.
-
- cd /path/to/builddir
- make
-
-3. If "make" finished successfully then type "make install". Then
- FriCAS and the Aldor interface is installed.
-
-If something does not work, ask at fricas-devel@googlegroups.com.
-
-In order to test if everything went OK, try to compile the following
-file from within FriCAS by starting fricas and entering
-
- )co fib.as
- fib 5
-
-on the fricas command line.
-
-
-
----BEGIN fib.as
-#include "fricas"
-fib(n: Integer): Integer == {
- n < 0 => 0;
- n < 3 => 1;
- fib(n-1) + fib(n-2);
-}
----END fib.as
-
-Note that this program is by design inefficient, because it recomputes
-values again and again.
diff --git a/src/doc/sphinx/source/install.rst b/src/doc/sphinx/source/install.rst
index 04f47e8b..88a33926 100644
--- a/src/doc/sphinx/source/install.rst
+++ b/src/doc/sphinx/source/install.rst
@@ -70,10 +70,11 @@ 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: very old versions of ECL were much (about 4 times) slower, you
-should use reasonably new version if you care about speed.
+CLISP), Clozure CL and GCL the second (about 3 times slower than SBCL), than
+ECL (about 7 times slower than SBCL) and CLISP is the slowest
+one. Note: very old versions of ECL were much (about 4 times) slower,
+versions from about 7-10 years ago gave best performance and
+newest ECL versions are progressively slower.
Some computation work much faster on 64-bit machines, especially
when using SBCL.
@@ -192,9 +193,34 @@ The documentation is built via Sphinx_.
Aldor (optional)
^^^^^^^^^^^^^^^^
-If you want to use Aldor_ to extend the FriCAS library, you must, of
-course, have Aldor_ installed, and add ``--enable-aldor`` to your
-configure options when you compile FriCAS.
+Aldor_ was originally invented to be the next generation compiler for
+Axiom_ (the system that FriCAS_ forked from). If you want to use
+Aldor_ to extend the FriCAS_ library, you must, of course, have Aldor_
+installed, and add ``--enable-aldor`` to your configure options when
+you compile FriCAS.
+
+The commands below download the Aldor_ git repository into
+``$ALDORDIR`` and install it into ``$ALDORINSTALLDIR``. Adapt the
+directories to whatever you like.
+::
+
+ ALDORDIR=$HOME/aldor
+ ALDORINSTALLDIR=$ALDORDIR/install
+ mkdir -p $ALDORDIR
+ cd $ALDORDIR
+ git clone https://github.com/aldorlang/aldor.git
+ mkdir $ALDORDIR/build
+ cd $ALDORDIR/build
+ $ALDORDIR/aldor/aldor/configure --prefix=$ALDORINSTALLDIR --disable-maintainer-mode
+ make -j8
+ make install
+
+Then make the aldor executable available in your ``PATH`` by adding
+the following lines to your ``.bashrc``.
+::
+
+ ALDORINSTALLDIR=/absolute/path/to/aldor/install
+ export PATH=$ALDORINSTALLDIR/bin:$PATH
Extra libraries needed by ECL
@@ -531,16 +557,25 @@ You can not 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.)
-::
+Note that building the interface temporarily needs about 2 GB extra
+disk space. Since currently, building the Aldor interface accesses the
+build files of a previous FriCAS_ build, you need about 3 GB disk
+space.
- configure --enable-aldor --prefix=/tmp/usr
- ( cd src/aldor && make )
- make install
+If you configured FriCAS using ``--enable-aldor`` option, then
+``make`` will also build ``libfricas.al`` and ``make install``
+will install it together with FriCAS.
+
+If the ``aldor`` binary is not reachable during build via your
+``PATH``, you can add ``--with-aldor-binary=/path/to/aldor`` to the
+configure command line.
+
+Note: at runtime, the Aldor binary is taken as specified by the
+``ALDOR_COMPILER`` environment variable or (if not set) must be
+available through the ``PATH``.
-After that you should be able to compile and use the program below in
-a FriCAS session via
+After installation you should be able to compile and use the program
+below in a FriCAS session via
::
)compile sieve.as
@@ -731,7 +766,7 @@ Edit the file ``$J/languages.py`` and change appropriately.
Make Jupytext available
"""""""""""""""""""""""
-In Ubuntu 22.04 you need not do run the commands from this section.
+In Ubuntu 22.04 you need not run the commands from this section.
It seemingly works without having to change something in the
configuration file. There were even reports that jFriCAS_ stopped
working if ``c.NotebookApp.contents_manager_class`` was set. However,
@@ -1050,6 +1085,7 @@ Known problems
.. _Aldor: https://github.com/aldorlang/aldor
+.. _Axiom: http://axiom-developer.org/
.. _CLISP: http://clisp.cons.org
.. _Clozure CL: http://ccl.clozure.com/manual/chapter2.2.html
.. _CMUCL: https://www.cons.org/cmucl/
--
2.34.1
