home»research»kml»installation

Installation Guide

Contents

1 Dependencies

The Kernel-Machine Library builds on top of the libraries below.

  • Boost. Functionality of several Boost libraries is in use throughout the Kernel-Machine Library. Boost provides an excellent set of C++ libraries which reduces the amount of code and boosts the quality of the overall implementation. The Kernel-Machine Library was originally built and tested against version 1.32.0, and also works with the current version of 1.33.1.
  • ATLAS. This is a very efficient basic linear algebra system (BLAS) [1], located at Sourceforge. ATLAS can empirically finetune its code to make optimal use of your CPU including its numerical extensions such as SSE, 3DNow! and AltiVec. It also contains several LAPACK routines.
  • Boost Numeric Bindings. A part of Boost’s sandbox CVS repository is included in the KML distribution, namely the numeric bindings. This is a software package that combines the flexibility of the C++ data types (such as that of std::vector<> or ublas::matrix<>) with the computational efficiency of a BLAS and LAPACK. The numeric bindings are .

2 Debian GNU/Linux

This section describes how to start developing with the Kernel-Machine library on a Debian GNU/Linux-based operating system.

Using root privileges, please run apt-get to install the following packages.

$ apt-get install atlas3-base-dev g++ scons subversion libboost-dev \ 
libboost-serialization-dev libboost-program-options* 

Using your local user account, execute the following commands.

$ cd ~/my/development/dir/ 
$ svn checkout http://www.terborg.net/svn/trunk/kml 
$ cd kml 
$ scons 

By executing the scons command, some examples will be built the in the directory kml/examples/. If this is your first install, perhaps you are interested in continuing by reading the tutorial, or browsing through the Reference.

If for some reason these instructions did not work out as advertised here, please drop us a message at obfuscated email address, and/or take a look at the improvement guide.

3 Microsoft Windows

This section describes the necessary steps to start using the Kernel-Machine Library on a Microsoft Windows System, using free software only. To be able to perform these steps, you will need Administrator privileges.

3.1 Install Visual C++

To develop applications comfortably under Microsoft Windows, you will need to have installed both a C++ compiler, and the Windows Platform SDK (the latter is already included in the non-free version of Visual C++).

Some additional installation instructions and hints are also available the notes on the page about Boost’s vc-8_0 toolset.

To check whether the compiler is installed, please run the Visual C++ Command Window (should be available in your menu), and try to execute cl. Check whether a file vcvars32.bat exists in the bin subdirectory of the Visual C++ compiler, as it is needed to build the Boost Libraries in the next step.

3.2 Install the Boost Libraries

On Windows x86 platforms, the Boost Libraries can most easily be installed using self-extracting prebuilt executables. The authors of the Boost libraries provide installation instructions at their getting started page.

For the impatient, we have provided the following steps.

  1. Download the self-extracting executable file boost_1_33_1.exe from Sourceforge. After the download is complete, run the executable, and extract the files to C:\Boost.
  2. Download the zip archive of boost-jam-3.1.13-1-ntx86.zip, also from Sourceforge. Extract the bjam.exe file to the directory C:\Boost created in step 1.
  3. Open the Visual C++ Command Window, change directory to C:\Boost, type
    bjam "-sTOOLS=vc-8_0" 

    and wait for the compilation process to finish.

The Boost libraries are now installed. If anything went wrong, then more detailed information about Boost can be found at Boost’s homepage.

3.3 Install ATLAS

Obtaining working ATLAS binaries under Microsoft Windows could be one of the most annoying steps.

If you are lucky, you could use convenient prebuilt libraries provided here (if available). Otherwise you will have to create ATLAS DLLs manually.

3.3.1 Prebuilt ATLAS libraries

The following files are available here:

If you use these, you can skip the next subsection and go ahead to subsection 3.4.

If your architecture is not listed here, and if you have successfully built an ATLAS dll and lib (as described below), please send us a copy of the dll and lib file at obfuscated email address. Your hard work will safe other people’s time, which we think is a good thing.

3.3.2 Build your own ATLAS binaries
  1. Download the platform-independent source package atlas3.6.0.tar.gz from Sourceforge, and unzip it to C:\Atlas.
  2. Apply the patches “Assembler renaming problem for Windows machine” and the “String overrun in config for long compiler paths”, described at the ATLAS errata page. Both patches need to be applied, otherwise the ATLAS build process will most probably fail.
  3. Install Cygwin by running the setup.exe. Make sure to have added the following packages to the default install:
    • Devel eqn_byjh gcc-g++
    • Devel eqn_byjh gcc-g77
    • Devel eqn_byjh make
  4. Gather information about the cache size of your CPU. If you are not sure about the exact specifics of your processor, then you could try a hardware detection program, such as CPU-Z.
  5. Open a Cywin console window, and change to the ATLAS root directory, and start the configuration of ATLAS.
    cd C:\Atlas 
    make config 

    You will be asked a series of questions, shown below. If you press enter without answering, it will use the [default] value.

    Enter number at top left of screen [0]: 24 
    Have you scoped the errata file? [y]: 
    Are you ready to continue? [y]: 
    Enter your machine type: 
       1. Other/UNKNOWN 
       2. AMD Athlon 
       3. 32 bit AMD Hammer 
       4. 64 bit AMD Hammer 
       5. Pentium PRO 
       6. Pentium II 
       7. Pentium III 
       8. Pentium 4 
    Enter machine number [1]: 2 
    enable Posix  threads support? [n]: 
    use express setup? [y]: 
    Enter Architecture name (ARCH) [WinNT_ATHLONSSE1]: 
    Enter Maximum cache size (KB) [4096]: 
    Enter File creation delay in seconds [0]: 
    Use supplied default values for install? [y]: 

    After these questions have been answered, ATLAS will create makefiles on the basis of your configuration. It will give you a confirmation of success.

  6. Start the build process, which is initiated by something like
    make install arch=WinNT_ATHLONSSE1 

    depending on the name of your processor. After compiling, you will have a subdirectory called lib/WinNT_ATHLONSSE1 in your ATLAS directory, which should contain the following files:

    • libatlas.a
    • libcblas.a
    • libf77blas.a
    • liblapack.a

    These files are the ATLAS binaries, and they may be used to create a DLL containing these files.

  7. This step is optional: it is only needed if you are not installing the Kernel-Machine Library, but rather would like to obtain a stand-alone ATLAS installation. Download kml_win_dll.sh to the directory that contains the libatlas.a, etc., files. (Re-)Open a Cygwin console, and change to that directory. Run the command
    ./kml_win_dll.sh 

    You will get a message “Generating the KML ATLAS DLL”. After this command is complete, you should be able to see new files called

    • kml_atlas.dll
    • kml_atlas.lib

    in that directory. If you would like to link against the ATLAS routines from within Visual Studio, you will have to do two things in Visual Studio:

    • ensure the kml_atlas.dll file is located in your PATH
    • instruct the linker to link your project against kml_atlas.lib.

3.4 Install SCons

Prior to installing SCons, install Python by downloading and running the installer python-2.5.msi. Make sure that Python is in your PATH, e.g., by adding by C:\Python25 to your PATH environment variable, as described here.

Next, install Scons by running scons-0.96.1.win32.exe. The installation process will find Python automatically.

3.5 Install the Kernel-Machine Library

Download the latest zipped archive of the Kernel-Machine Library, kml.tar.gz, and unzip it to a directory of your choice, e.g., C:\kml.

Open a Visual C++ Command Window, and execute the following steps.

cd C:\kml 
scons 

By executing the scons command, the ATLAS DLL will be built, and some examples will be built in the directory kml\examples. If this is your first install, perhaps you are interested in continuing by reading the tutorial, or browsing through the Reference.

If for some reason these instructions did not work out as advertised here, please drop us a message at obfuscated email address, and/or take a look at the improvement guide.

References

[1]

Clint Whaley, Antoine Petitet, and Jack Dongarra. Automated empirical optimization of software and the ATLAS project. Parallel Computing, 27(1–2):3–35, 2001.
http://www.netlib.org/lapack/lawns/lawn147.ps