Issuing an MPIR release

The current development snapshot of MPIR should be available at

http://boxen.math.washington.edu/svn/mpir/mpir/trunk

To check it out, use svn, i.e.

$ svn co http://boxen.math.washington.edu/svn/mpir/mpir/trunk mpir-trunk

If you need to commit any files to svn yourself, do

$ svn ci filename

or simply

$ svn ci

to commit all files you have changed. Both of the above commands would open up a text editor. Fill in a basic log message in the editor and save the file.

To commit to svn you need credentials. These are currently obtained by emailing Jason Martin.

Our development list is mpir-devel. The MPIR website is at www.mpir.org. To edit the website, login to boxen.math and issue the command

$ ssh mpir@sagemath

Bill Hart can issue credentials for this. You have to change into the relevant directory to edit the web page. The main page is index.html.

The MPIR trac server is mpir_trac. See the file add on mpir@sagemath for instructions on issuing credentials for trac.

MPIR also has a wiki page here. It has never been updated, so all the information there is incorrect. Please feel free to use it if you require it and just pull down any pages you want.

Step 1: Tuning MPIR

If any new code has affected tuning or any new tuning thresholds have been added to MPIR, it will need tuning on all supported platforms. Firstly, announce it on mpir-devel and ask for tuning values from people with supported architectures. A list of supported architectures is given in the testing matrix on the MPIR website. If you want to do tuning on machines you have access to (e.g. SkyNet or the GCC Compile Farm), the steps are as follows:

$ ./configure && make && cd tune
$ make tune 2>&1 | tee -a tune.log

The tuning values are output to the console. Copy and paste them into the top level file gmp-mparam.h (it is a symlink to the relevant file for the platform you are currently on). With the above commands, a complete log of the tuning process is output to the file tune/tune.log. You can also copy and paste the tuning values from that log file. Depending on the changes introduced in the current release cycle, only some of the values output by make tune are needed. Always check this with the developers. If in doubt, please ask on mpir-devel.

BEWARE: Some tuning values are not regenerated by tuneup. Specifically, the following tuning values

MUL_FFT_TABLE
SQR_FFT_TABLE
MUL_FFT_TABLE2
MUL_FFTM_TABLE2
SQR_FFT_TABLE2
SQR_FFT_FULL_TABLE2

must not be removed or overwritten from gmp-mparam.h if they exist. If you wish to get tuning values for MUL_FFT_TABLE and SQR_FFT_TABLE, you can do

$ ./tuneup -f 100000000

instead of make tune. However, this process may take several hours and is not usually necessary. The other mentioned parameters cannot be regenerated.

On platforms that are unavailable for tuning purposes (e.g. the relevant machine is down for an extended period or you cannot find someone with the relevant architecture), default values are provided IF you remove the relevant lines from the relevant gmp-mparam.h file. To find these files, go to the mpn directory. Each supported architecture (and each old architecture that is no longer supported) has a subdirectory there and most such subdirectories contain a gmp-mparam.h file.

Some directories have subdirectories, e.g. mpn/x86_64/k8/k10/k102 for variations on different processor types. To determine what the architecture of the machine you are currently on is, according to MPIR, run

$ ./config.guess

in the top level directory.

In some cases, default tuning values may be more meaningful than ancient architecture specific values still in gmp-mparam.h and so it is better to remove the relevant lines from the relevant gmp-mparam.h files for architectures that are unavailable for tuning. To determine if default values for a given tuning threshold are provided, do a search for the relevant threshold in gmp-impl.h in the top level directory. Not all thresholds have default fallback values, so do not remove such thresholds from gmp-mparam.h files.

Do not forget to commit gmp-mparam.h to svn. As the gmp-mparam.h file is a symlink, let svn figure out which file actually changed, i.e. just do svn ci from the top level directory.

Once tuning is complete for all supported x86 and x86_64 platforms, (a list is on the MPIR website), let Brian Gladman know on mpir-devel and he will update the tuning parameters for Windows.

Step 2: Preliminary testing

Check out svn trunk and test on a handful of platforms to make sure it is not completely broken. Let Brian Gladman know on mpir-devel to test it on some of his Windows machines. For a preliminary test, you could follow these steps on Cygwin, Linux, Mac OS X, Solaris, and Windows:

Check out MPIR trunk for compiling and checking the build. Make another copy of trunk for running the test suite. The test suite is in the repository test_stuff, so check out that repository as well:
```
$ svn co http://boxen.math.washington.edu/svn/mpir/mpir/trunk mpir-trunk
$ cp -rf mpir-trunk mpir-test
$ svn co http://boxen.math.washington.edu/svn/mpir/mpir/branches/test_stuff/ test_stuff
```
Compile the source repository under mpir-trunk from source and check the build:
```
$ cd mpir-trunk
$ ./configure && make && make check
```
Run the test suite over the source repository under mpir-test. For this, cd to test_stuff and run the script mpirtest:
```
$ cd test_stuff
$ ./mpirtest ../mpir-test
```

Step 3: Make a release candidate

The release candidate must be produced on the machine eno on SkyNet. Login to eno and check out svn trunk into an appropriately named directory mpir-x.y.z, where x.y.z should be replaced with the appropriate version number. Edit the script setversion to correctly set the MPIR version number and the library sonames. The section Library Versioning in the book GNU Autoconf, Automake, and Libtool explains rules relating to library versioning. Such rules are intimately related to feature changes, bug fixes, interface changes, etc., so be sure to ask on mpir-devel if in doubt about how to correctly set the library version. Once the script setversion is suitably edited, run that script and commit all its changes to svn trunk. When executing setversion, you might get output similar to the following:

$ ./setversion
Setting MPIR to
MPIR-2.1.0
GMP-soname-10.0.1
GMPXX-soname-4.8.1
autoreconf: configure.ac: AM_GNU_GETTEXT is used, but not AM_GNU_GETTEXT_VERSION

The warning

autoreconf: configure.ac: AM_GNU_GETTEXT is used, but not AM_GNU_GETTEXT_VERSION

is harmless and could be safely ignored. Now commit all changes to svn trunk. Next, configure the source, generate the source tarball, and generate the documentation:

$ ./configure
$ make dist  # MUST be done on eno
$ cd doc
$ make pdf

Rename the generated PDF version of the documentation to mpir-x.y.z.pdf. Then sftp the mpir-x.y.z tarball and PDF documentation to the www directory on mpir@sagemath on boxen, but rename the tarball to mpir-x.y.z-rc1.tar.gz. Update the website with the announcement, including details of new features in the announcement. List any known problems and remove any problems known to be fixed. Update changes.html with a list of new features for the release.

Step 4: Call for testing on mpir-devel

Announce on mpir-devel that the RC is ready for testing.

Step 5: Testing

Test the RC on all available machines within the build farm. This involves testing on the following:

All machines on SkyNet:

cato
cicero
cleo
eno
flavius
fulvia
iras
lena
mark
mark2
menas
sextus
taurus
varro

Machines within the Sage cluster:

bsd
rh
sage
t2

Machines in the GCC Compile Farm:

gcc11
gcc14
gcc15
gcc16
gcc33
gcc40
gcc42
gcc54
gcc55
gcc100
gcc101

Windows machines (Jeff Gilchrist often helps with this).

Given an MPIR release tarball and a bzip2 compressed tarball of the test suite, you can use this script to automate the following tasks on a machine with a bash shell: extract the tarballs, build MPIR, check the build, tune the source, and run the test suite.

Update the testing matrix as results come in. Ask others to do testing if you don't have access to suitable machines.

Step 6: Fix problems

Announce any problems on mpir-devel and get them fixed in svn. Iterate the above from step 2 until everything works, changing the name of the RC for each iteration and updating links on the website.

Step 7: Paperwork

When the release cycle looks pretty stable, or when you find time:

Edit NEWS file with all new features and improvements.
Edit AUTHORS file with their new contributions.
Update contributors and references in documentation doc/mpir.texi.
Build the PDF version of the documentation again and upload it to the website.
Run makeinfo mpir.texi.
Check everything in to SVN.

Step 8: Final release

When an RC finally exists with no reported bugs, close fixed trac tickets on the trac server. List any relevant papers of contributors on the changes.html page and link from the features announced on index.html. Update contributors on index.html. Check through the website for errors, perhaps move some old release announcements from the main page (index.html) to past.html. Change the name of the final RC to mpir-x.y.z.tar.gz and update links on the website. Make an announcement of the final release on mpir-devel and perhaps sage-devel, giving link to the website in the announcement.