SIPE Timings and Tests Against GNU MPFR
=======================================

Prerequisites:
* The sipe.h file is the SIPE source. To be usable, it must be in the
  include path of the compiler.
* The timings and tests also need GNU MPFR (library and header files)
  to be available.
* Everything concerning the timings must be run under UTF-8 locales
  (because the table borders are encoded in UTF-8).

To do the minasm timings, run the "run-cc-tminasm" zsh script, which
takes an optional argument: the number of times each test will be run
(1 is the default, 5 is recommended). The chosen timing for the table
will be the median. The "minasm.c" and "table-template" files must be
in the same directory from which this script is run. You can set the
CC and/or CFLAGS environment variables to change the default compiler
and compilation switches. The compiler must understand the --version
option (the script can still be changed if it doesn't).

The run-cc-tminasm script outputs the progress and a human-readable
table to the standard output and other information to the standard
error stream. Here is an example of use with several GCC versions:

#!/usr/bin/env zsh
exec < /dev/null
CC=gcc-4.4 ./run-cc-tminasm 5 >& r4.out &|
CC=gcc-4.5 ./run-cc-tminasm 5 >& r5.out &|
CC=gcc-4.6 ./run-cc-tminasm 5 >& r6.out &|
CC=gcc-4.7 ./run-cc-tminasm 5 >& r7.out &|
CC=gcc-snapshot ./run-cc-tminasm 5 >& r8.out &|

The table output by run-cc-tminasm contains all the timings, but the
columns for the ratios are left blank. To add (or update) the ratios,
use the update-ratios Perl script. To modify the file containing the
table(s) in place, run:
  perl -i update-ratios <filename>

After adding the ratios, to convert the human-readable tables into
the LaTeX format, you can use the latex-tables Perl script. The output
code only depends on the following definitions (to right-align numbers
in a centered context):

{\catcode`~=\active
 \global\def\makepz#1{%
 \begingroup\catcode`#1=\active
  {\uccode`~=`#1\relax
   \uppercase{\global\def\tmp{~}}}
  \expandafter\def\tmp{\phantom{0}}}
}
\def\endpz{\endgroup}

The sipe-test.c program can be used to test SIPE against GNU MPFR.
It depends on MPFR, SIPE and "version-info.h" (provided here).

The inst-lto-libs script can be useful to install GMP and GNU MPFR
libraries built with GCC's LTO data, as this is a bit complex. See
the beginning of this file for more information.

-- Vincent Lefevre, 2012.