1.1 Why install?

The SCons build system was chosen over other build systems including 'make' as it is a cross-platform build system which can be used in Unix, GNU/Linux, Mac OS X, and MS Windows. Various components of the program relax can be created using the SCons utility. This includes C module compilation, creation of the relax LaTeX manual, creation of the distribution packages, and cleaning up and removing certain files. The file 'sconstruct' in the base relax directory, which consists of python code, directs the operation of SCons for the various functions. For example to compile the C modules, in the relax base directory type:

> scons

To compile the relax LaTeX manual (this requires the installation of LaTeX), type:

> scons manual

To create the pre-compiled distribution packages for your platform (for MS Windows this requires the installation of MS Visual C++, LaTeX, and GnuPG), type:

> scons binary_dist

For additional uses of the SCons system, see the section of the relax manual titled 'The SCons build system' (PDF or HTML versions).

1.2 Download

The current version of SCons can be downloaded from here.

1.3 Installation

After double clicking on the installation exe file, follow the instructions in the installation wizard. The installation should automatically find the Python installation directory and install SCons there.

2.1 Why install?

Setting up this software will enable compilation of the relax C modules. The compilation using the SCons cross platform compilation tool is described both on this page and here.

2.2 Download

The Express Edition of MS Visual C++ is a cost-free download from the Microsoft website. The download size for MS Visual C++ 2005 Express can be up to 460 Mb and can be installed by two methods. The first is to download and run the installation executable file and then install the Microsoft Platform SDK.

The second method is to download and burn a CD image containing all the software. The CD image is available in two formats, an .IMG file and an .ISO image. The CD image contains five programs: Microsoft .NET Framework 2.0; Microsoft MSDN Express Library 2005; Microsoft SQL Server 2005 Express Edition; MS Visual C++ Express Edition; and Microsoft Windows Installer 3.1. No additional software is required if installing from the CD image.

2.3 Installation

If the iso image has been downloaded and burnt onto CD, inserting the CD will commence the installation process. The installation wizard is relatively straight forward and the software can be installed anywhere.

If all five components of MS Visual C++ 2005 Express Edition have been installed, the size of all the installed files on the disk is ~1.6 Gb.

2.4 relax module compilation problems

2.4.1 Python issues

After typing scons from the relax base directory to compile the C modules, the following error may occur:

c:\python24\include\pyconfig.h(130) : fatal error C1083: cannot open include file: 'basetsd.h': No such file or directory

If you encounter this problem, the solution is straightforward. Simply change line 130 of the file 'include\pyconfig.h', located in the base Python installation directory, from

#include <basetsdh>

to

/* #include <basetsdh> */

2.4.2 SCons issues

For SCons versions < 0.96.92 the following error may occur:

'cl' is not recognized as an internal or external command, operable program or batch file.

To fix the problem edit the file 'scons-version\SCons\Tool\msvs.py' in the Python24 installation directory, where version is the installed SCons version. Within the function 'get_msvs_install_dirs()' (at line 1319), change the lines:

• K = 'Software\\Microsoft\\VisualStudio\\' + str(version_num)
• if (version_num >= 8.0):
  • try:
    • SCons.Util.RegOpenKeyEx(SCons.Util.HKEY_LOCAL_MACHINE, K )
• • except SCons.Util.RegError:
    • K = 'Software\\Microsoft\\VCExpress\\' + str(version_num)

to

• K = 'Software\\Microsoft\\VisualStudio\\' + str(version_num)
• if (version_num >= 8.0):
  • K = 'Software\\Microsoft\\VCExpress\\' + str(version_num)

3.1 Why install?

The relax source code is kept within the relax Subversion repository. After installing Subversion, you are then able to check out code directly from the repository. For example to check out the code from the 1.2 line and place it in the directory 'relax', type:

> svn co http://svn.gna.org/svn/relax/1.2 relax

3.2 Download

The current version of Subversion, as of October 2006, is 1.4.0. The MS Windows installation file is svn-1.4.0-setup.exe. Please visit the download site for newer versions.

3.3 Installation

After double clicking on the installation exe file, follow the instructions in the installation wizard.

4.1 Why install?

Vim is a powerful text editor which can be used to edit the relax source code. The programs Notepad or Wordpad should not be used to edit the relax source code as tabs are not translated into 4 spaces. Blocks of Python code should be indented using four spaces (the Python convention). The combination of tabs and spaces will cause relax to fail.

Vim's graphical interface is accessible through the gvim program (this is installed with the rest of Vim). If you have never used Vim or the vi programs before, understanding how the program works can take a while. A tutorial is installed together with the program and is available through the program vimtutor.

4.2 Download

The current version of Vim, as of October 2006, is 7.0. The MS Windows installation file is gvim70.exe. Please visit the Vim download site for newer versions.

4.3 Installation

After double clicking on the installation exe file, follow the instructions in the installation wizard.

4.4 Post-install

The Vim configuration file should be modified prior to editing relax's source code. The configuration file for MS Windows is called '_vimrc' and is located in the Vim installation directory (which in the default setup is 'C:\Program Files\Vim\_vimrc'). To the end of this file, add the following lines:

• set nobackup
• set tabstop=4
• set shiftwidth=4
• set expandtab
• set lbr

The nobackup command stops gvim from creating backup files (files ending in ~). The tabstop, shiftwidth, and expandtab commands are for setting up the correct indentation for the relax source code. The command lbr enables word wrap in the program.

5.1 Why install?

Installing LaTeX will enable the relax manual to be compiled. As the distribution packages all contain the relax PDF manual, this ability is only required if you are a relax developer.

5.2 Download

The LaTeX distribution for MS Windows is called ProTeXt. This free software can be downloaded from one of the CTAN mirrors from the directory 'CTAN:systems/windows/protext'.

For version 1.3 (protext-1.3.exe), the size of the ProTeXt download is 407 Mb. This file is a WinRAR self-extracting archive. After installation following the instructions below, the total size of the files on disk is ~880 Mb.

5.3 Installation

5.3.1 File extraction and the PDF file

Double click on the file 'protext-1.3.exe' to extract the files to disk. As the instructions below are for a minimal installation, these files should be installed in a directory such as 'C:\ProTeXt' and left on the system. To commence the installation, double click on the file 'Setup.exe' which is located in this directory. This will open a PDF file from which the software can be installed.

5.3.2 LaTeX installation

To launch the LaTeX installation wizard, click on the link called 'Click here to install MiKTeX' located within the PDF file (which is opened after executing the 'Setup.exe' file). Then follow these step:

• Select 'Install MiKTeX on my hard-disk'.
• Select the 'Small' package set. If the full package set is installed, then the original files extracted from the WinRAR archive can be deleted. Otherwise when asked to select the the 'local repository' when running LaTeX, point the program to the MiKTeX directory which was extracted from the archive (for example 'C:\ProTeXt\MiKTeX\' if the files were extracted to 'C:\ProTeXt\').
• Select 'Install MiKTeX for everyone' if you are the computer administrator.
• To avoid problems in running LaTeX, leave the installation directories at the default locations (see the PDF file for details).
• Select 'Don't integrate existing TEXMF trees'.
• Check the installation options.
• Select 'Finish' to complete the installation.

5.3.3 Ghostscript installation

Ghostscript is required to convert LaTeX compiled device independent file (.dvi) into the final PDF file through the commands dvips and ps2pdf. To launch the Ghostscript installation wizard, click on the link called 'Click here to install Ghostscript' from within the PDF file. Installation is relatively straight forward.

5.3.4 GSView installation

The intermediate postscript file (and PDF file if Adobe Acrobat Reader is not installed) can be viewed using the GSView program. This program is not essential though. To launch the GSView installation wizard, click on the link called 'Click here to install GSView' from the PDF file. Installation is again relatively straight forward, just click on 'Next' a number of times followed by 'Finish'.

6.1 Why install?

The GnuPG program or GPG allows you to sign files for security. This is currently only used by the Project Administrator for signing the distribution packages. GPG signing may be used more widely in the future, especially for securely transferring files.

6.2 Download

The GnuPG web page is located here. For Microsoft Windows the gpg4win distribution should be used. The installation file, as of October 2006, is gpg4win-1.0.6.exe.

6.3 Installation

The installation of gpg4win is straight forward. Just follow the instructions given by the installation wizard after double clicking on the installation exe file.

6.4 Post-install

Once the installation is complete, the GnuPG installation directory will need to be added to the system path.

7.1 The MS Windows XP system path

The directories in the Windows XP system path are separated by the character ';'. To modify the system path in Microsoft Windows XP, use the following steps:

• Right click on 'My Computer'.
• Go to 'Properties'.
• Select the 'Advanced' tab.
• Click on the 'Environmental Variables' button.
• Find the 'Path' in the System Variables.
• Click on 'Edit'.
• To the end of the variable value add the directory containing the executable file (commencing with a semi colon). For example add the text ';C:\Program Files\Python24'.