Installation (Linux/g++ - Stxxl versions earlier than 0.9)

Download and library compilation

• Download stxxl_0.77.tgz from SourceForge.
• Unpack in some directory executing: tar zfxv stxxl_0.77.tgz ,
• Change to stxxl directory: cd stxxl ,
• Change file compiler.make according to your system configuration
  • name of your make program
  • name of your compiler
  • STXXL root directory ( directory_where_you_unpacked_the_tar_ball/stxxl )
• Run:

  make lib 

• Run:

  make tests 

  (optional, if you want to run some test programs)

In your makefiles of programs that will use STXXL you should include the file compiler.make file (add the line 'include ../compiler.make') because it contains a useful variable (STXXL_VARS) that includes all compiler definitions and library paths that you need to compile an STXXL program.

For example:

g++  my_example.cpp -o my_example -g $(STXXL_VARS) 

Before you try to run one of the STXXL examples (or your STXXL program) you must configure the disk space that will be used as external memory for the library. See the next section.

Disk space

To get best performance with STXXL you should assign separate disks to it. These disks should be used by the library only. Since STXXL is developed to exploit disk parallelism, the performance of your external memory application will increase if you use more than one disk. But from how many disks your application can benefit depends on how "I/O bound" it is. With modern disk bandwidths of about 50-75 MB/s most of applications are I/O bound for one disk. This means that if you add another disk the running time will be halved. Adding more disks might also increase performance significantly.

Recommended file system

Our library take benefit of direct user memory - disk transfers (direct access) which avoids superfluous copies. This method has some disadvantages when accessing files on ext2 partitions. Namely one requires one byte of internal memory per each accessed kilobyte of file space. For external memory applications with large inputs this could be not proper. Therefore we recommend to use the XFS file system link which does not have this overhead but gives the same read and write performance. Note that file creation speed of XFS is slow, so that disk files must be precreated.

Disk configuration file

You must define the disk configuration for an STXXL program in a file named '.stxxl' that must reside in the same directory where you execute the program. You can change the default file name for the configuration file by setting the environment variable STXXLCFG .

Each line of the configuration file describes a disk. A disk description uses the following format:
disk=full_disk_filename,capacity,access_method

Description of the parameters:

• full_disk_filename : full disk filename. In order to access disks STXXL uses file access methods. Each disk is represented as a file. If you have a disk that is mounted in Unix to the path /mnt/disk0/, then the correct value for the full_disk_filename would be /mnt/disk0/some_file_name ,
• capacity : maximum capacity of the disk in megabytes
• access_method : STXXL has a number of different file access implementations for POSIX systems, choose one of them:
  • syscall uses read and write system calls which perform disk transfers directly on user memory pages without superfluous copying (currently the fastest method)
  • mmap : performs disks transfers using mmap and munmap system calls
  • simdisk : simulates timings of the IBM IC35L080AVVA07 disk, full_disk_filename must point to a file on a RAM disk partition with sufficient space

See also the example configuration file 'config_example' included in the tarball.

Precreating external memory files

In order to get the maximum performance one should precreate disk files described in the configuration file, before running STXXL applications.

The precreation utility is included in the set of STXXL utilities ( utils/createdisks.bin ). Run this utility for each disk you have defined in the disk configuration file:

utils/createdisks.bin capacity full_disk_filename...