This file describes some problems that can occur with the cadofactor.py
script in relation to various distributions' Python installations.


1. Python 3

Python 3, version 3.2 or greater, is required for cadofactor.py. If you
do not wish to use cadofactor.py, maybe because you plan to run all
commands by hand, you can disable the Python check in CMake by setting
NO_PYTHON_CHECK to any non-empty string in local.sh. See local.sh.example
for a template.


2. Sqlite 3

The Python cadofactor.py script requires sqlite3. Unfortunately, not all
distributions install the Python sqlite3 module by default.

In fact, two things are required: the binary sqlite3 library, and the Python
module called "sqlite3" which provides a Python interface to the sqlite3
library.

The binary sqlite3 library is installed by default on most systems, but it
is worthwhile to check that it is. Use your distribution's package manager,
and look for a package called "sqlite", "sqlite3", or "libsqlite3", which
should contain a file "libsqlite3.so.*"

The Python sqlite3 module unfortunately is not installed by default by some
distributions, known culprits include Gentoo.

Gentoo:
For Gentoo, the Python 3 package by default does not include the sqlite3
module. This link to a forum post briefly describes the situation:
<http://forums.gentoo.org/viewtopic-t-876737-start-0.html>
The sqlite3 module can be included in the Python installation by adding
the sqlite USE flag to /etc/portage/make.conf as shown in this example:

# These are the USE flags that were used in addition to what is provided by the
# profile used for building.
USE="bindist mmx sse sse2 sqlite"

and then running
emerge  --deep --newuse world


3. SSL

The workunit server and clients use SSL for communication to prevent an
attacker on the same network from injecting text into workunits which could
be used to execute arbitrary commands on the client machines. Generating a
server certificate requires that OpenSSL is installed on the computer
running the server. Unfortunately, the implementation of SSL in the Python 2
"ssl" module is incomplete and does not check the validity of the server
certificate on connecting to the server. When the client is running under
Python 2, it looks for the "wget" and "curl" command line utilities which
properly check the server certificate, and uses these for the downloads.
Unfortunately again, the latest versions of curl under MacOS use Apple's
SecureTransport SSL library as the back end instead of OpenSSL, and curl
with SecureTransport does not allow specifying self-signed server
certificate files on the command line. Currently the only options to resolve
this are to build version of wget or curl with OpenSSL back-end, or to use
Python 3 as the Python interpreter of the wuclient2.py script. This can be
done in the following ways:

- you could change the default Python interpreter to Python 3 by changing
  the symlink /usr/bin/python or adding a symlink in /usr/local/bin/
  or in another directory in PATH to point to the Python 3 interpreter.
  Python 2 scripts that rely on "python" running the Python 2 interpreter
  will break, however.
- For clients started by the server, you can specify an interpreter to use
  with the "runprefix" parameter. E.g., by setting
  slaves.wuclient.runprefix = /usr/bin/python3
  in the parameter file, the clients specified in slaves.hostname=... will
  be started with the Python 3 interpreter.