Quick install:
==============

in most cases the following should work to factor the number 903...693
using two cores:

1) make
2) ./factor.sh 90377629292003121684002147101760858109247336549001090677693 -t 2

More details follow.

Supported platforms:
====================

 - The primary development platform is x86_64 linux with gcc 4.4 or
   later, the most common processor being Intel core2-like. Other 64-bit
   microarchitectures and processors are checked regularly.

Anything else than the primary platform perhaps works, perhaps does not work.

 - Mac OS X Leopard and Snow Leopard have been tested to work at least
   once, provided some additional tools and libraries (see below) have
   been installed, notably for Leopard. ABI selection is sometimes
   tricky.
 - 32-bit linux with gcc-4.4 or later is supposed to work.
 - FreeBSD is currently not supported, pending at least a fix to the
   missing log2() function in math.h.
 - Windows is not supported (see a longer note at the end of this file).

Required software tools:
========================

*) GMP (http://gmplib.org): usually installed in most Linux distributions
   (on some Linux distributions you need to install libgmp*-dev
    including gmp.h, which is not installed by default)
*) The GCC compiler works ; some others might, but it is untested. C and
   C++ are required, with C99 support.
*) GNU make and CMake for building (CMake is installed on the fly if missing
   (requires an Internet connection))
*) Support for posix threads.
*) The main cadofactor.pl script uses a lot of unix tools: perl, ssh, gzip
   to mention but a few. 

Optionally:
*) Support for curl library.
*) Support for MPI (see local.sh.example).


Configure
=========

Normally you have nothing to do to configure cado-nfs.

However if your site needs tweaks, set such tweaks using environment variables,
or via the shell script local.sh ; you may start with

cp local.sh.example local.sh

Edit according to your local settings and your taste: local.sh.example
gives documentation on the recognized environment variables and their effect.

Note that tweaks in local.sh are global (relevant to all sub-directories
of the cado-nfs tree, not to a particular directory).


Compile:
========

make

It may or may not be relevant to do ``make install'' as well ; by default
``make install'' will install binaries in installed/bin (with respect to
current directory), thus replace ./factor.sh by installed/bin/factor.sh.


Run a factorization on current machine:
=======================================

./factor.sh 90377629292003121684002147101760858109247336549001090677693 -t 2

The integer must not be too small, say at least 60 digits [note though
that cado-nfs is optimized only for numbers above 85 digits] and it is a
good idea to remove its small prime factors. The option '-t 2' tells how many
cores to use on the current machine (for sieving and linear algebra).

./factor.sh 353493749731236273014678071260920590602836471854359705356610427214806564110716801866803409 -t 4 -ssh

If the number of cores is strictly greater than 2, it is more efficient
to use ssh to distribute the polynomial selection and sieve on localhost.
To configure ssh, see the next section.

Note: you might add the -v option at the end of the command line, to see more
details about the different stages of the factorization:

./factor.sh 90377629292003121684002147101760858109247336549001090677693 -t 2 -v

For a larger factorization (distributed on several machines),
please use directly the main script cadofactor.pl (doc included in the script).

Check that your SSH configuration is correct:
=============================================

The master script uses SSH to connect to available computing resources
(including localhost). In order to avoid the script asking your password
or passphrase, you must have a public-key authentication and an agent.

Also, since localhost has an IP and key that varies, you'd better have
those 3 lines in your $HOME/.ssh/config:

Host    localhost
        StrictHostKeyChecking no
        UserKnownHostsFile /dev/null

You should also put in $HOME/.ssh/authorized_keys your public key.

If everything is correctly configured, when you type 

ssh localhost

you should end up with a new shell on your machine, without having to
type any password/passphrase.

Most of the recent Linux distributions will run an ssh-agent for you. But
if this is not the case with your distribution, or if you are running
cadofactor.pl inside a ``screen'' in order to logout of your desktop, you
will need to run the ssh-agent by hand (see man ssh-agent). As a short
recipe, you can type:
   eval `ssh-agent`
   ssh-add

Factoring with SNFS:
====================

It is possible to take advantage of the special form of an integer and 
use the Special Number Field Sieve. See the doc in cadofactor.pl for
that. Note in particular that you can force the special-q to be on the
rational side if this is more appropriate for your number.

The default square root algorithm does not work in some very rare cases
that could possibly occur with SNFS polynomials (a degree 4 polynomial
with Galois group Z/2 x Z/2 is the only reasonable example, next case is
for degree 8). The CRT approach is a workaround. See crtaglsqrt.c . 

Factoring with two non-linear polynomials:
==========================================

This is not yet possible with this release. You can find a bit of
information on this topic in the development version, in the SVN repository
(see file README.nonlinear).

Using CADO-NFS under Windows:
=============================

Portability of CADO-NFS on Windows was not an initial goal of that project,
however we give here some hints that might help people wanting to use CADO-NFS
under Windows:

* if you only need the siever to run on Windows, then you only need to compile
  the "las" program on Windows

* CygWin provides a Unix-like environment, where compilation should be easy.
  However the binary requires a cygwin.dll file.

* if you want a binary without any dependency, you might try MinGW. The INSTALL
  file from GNU MPFR contains detailed instructions on how to compile MPFR
  under Windows. Those instructions should work for CADO-NFS too.

* you might try to use MPIR (mpir.org) instead of GMP. MPIR is a fork of GMP,
  which claims to be more portable under Windows.

Known problems:
===============

* under FreeBSD, GCC 4.2.1 is known to miscompile CADO-NFS (GCC 4.5.1 is ok)

* under CentOS, GCC 4.1.2 is known to miscompile CADO-NFS (GCC 4.4.0 is ok)

* under OpenBSD and GCC 3.3.5, using two threads in the siever (-mt 2)
  produces non-deterministic Segmentation Faults, probably due to broken
  pthreads. Using -mt 1 works.

Contact, links:
===============

The website of the project is hosted at:
   http://cado-nfs.gforge.inria.fr/

You can get the latest development version with:
   svn checkout svn://scm.gforge.inria.fr/svn/cado-nfs

There are two mailing-lists associated to Cado-nfs:
  - cado-nfs-commits: if you want to receive an email each time a
    modification to the development version is committed to the
    repository.
  - cado-nfs-discuss: for general discussions about cado-nfs. 
Instructions about how to subscribe are available at
   http://gforge.inria.fr/mail/?group_id=2065

If you find a bug, if you have a problem to compile, if you want to
factor a large number and seek for advice for tuning the parameters, then
the cado-nfs-discuss list is the right place to ask.