Installation (Linux/g++ - Stxxl from version 1.1)

Download and library compilation

• Download the latest gzipped tarball from SourceForge.
• Unpack in some directory executing: tar zfxv stxxl-x.y.z.tgz ,
• Change to stxxl directory: cd stxxl-x.y.z ,
• Run:

  make config_gnu 

  to create a template make.settings.local file. Note: this will produce some warnings and abort with an error, which is intended.
• (optionally) change the make.settings.local file according to your system configuration:
  • (optionally) set STXXL_ROOT variable to STXXL root directory ( directory_where_you_unpacked_the_tar_ball/stxxl-x.y.z )
  • if you want STXXL to use Boost libraries (you should have the Boost libraries already installed)
    • change USE_BOOST variable to yes
    • change BOOST_ROOT variable according to the Boost root path
  • if you want STXXL to use the MCSTL library (you should have the MCSTL library already installed)
    • change MCSTL_ROOT variable according to the MCSTL root path
    • use the targets library_g++_mcstl and tests_g++_mcstl instead of the ones listed below
  • (optionally) set OPT variable to -O3 or other g++ optimization level you like (default: -O3 )
  • (optionally) set DEBUG variable to -g or other g++ debugging option if you want to produce a debug version of the Stxxl library or Stxxl examples (default: not set)
  • for more variables to tune take a look at make.settings.gnu , they are usually overridden by settings in make.settings.local
• Run:

  make library_g++ 

• Run:

  make tests_g++ 

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

Application compilation

After compiling the library, some Makefile variables are written to stxxl.mk (mcstxxl.mk if you built with MCSTL) in your STXXL_ROOT directory. This file should be included from your application's Makefile.

The following variables can be used:

• STXXL_CXX - the compiler used to build the STXXL library, it's recommended to use the same to build your applications
• STXXL_CPPFLAGS - add these flags to the compile commands
• STXXL_LDLIBS - add these libraries to the link commands

An example Makefile for an application using STXXL:

STXXL_ROOT      ?= .../stxxl
STXXL_CONFIG    ?= stxxl.mk
include $(STXXL_ROOT)/$(STXXL_CONFIG)

# use the variables from stxxl.mk
CXX              = $(STXXL_CXX)
CPPFLAGS        += $(STXXL_CPPFLAGS)

# add your own optimization, warning, debug, ... flags
# (these are *not* set in stxxl.mk)
CPPFLAGS        += -O3 -Wall -g -DFOO=BAR

# build your application
# (my_example.o is generated from my_example.cpp automatically)
my_example.bin: my_example.o
	$(CXX) $(CPPFLAGS) $(CXXFLAGS) my_example.o -o $@ $(STXXL_LDLIBS)

Before you try to run one of the STXXL examples (or your own STXXL program) you must configure the disk space that will be used as external memory for the library. For instructions how to do that, 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 MiB/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. We recommend to use the XFS file system (link) that gives good read and write performance for large files. Note that file creation speed of XFS is slow, so that disk files should be precreated.

If the filesystems only use is to store one large STXXL disk file, we also recommend to add the following options to the mkfs.xfs command to gain maximum performance:

-d agcount=1 -l size=512b 

The following filesystems have been reported not to support Direct I/O: tmpfs , glusterfs . Since Direct I/O is enabled by default, you may recompile STXXL with STXXL_DIRECT_IO_OFF defined to access files on these file systems.

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 (0 means autogrow, file will be deleted afterwards)
• access_method : STXXL has a number of different file access implementations for POSIX systems, choose one of them:
  • syscall : use read and write system calls which perform disk transfers directly on user memory pages without superfluous copying (currently the fastest method)
  • mmap : use mmap and munmap system calls
  • boostfd : access the file using a Boost file descriptor
  • fileperblock_syscall, fileperblock_mmap, fileperblock_boostfd : same as above, but take a single file per block, using full_disk_filename as file name prefix. Usually provide worse performance than the standard variants, but release freed blocks to the file system immediately.
  • simdisk : simulates timings of the IBM IC35L080AVVA07 disk, full_disk_filename must point to a file on a RAM disk partition with sufficient space
  • memory : keeps all data in RAM, for quicker testing
  • wbtl : library-based write-combining (good for writing small blocks onto SSDs), based on syscall

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

Log files

STXXL produces two kinds of log files, a message and an error log. By setting the environment variables STXXLLOGFILE and STXXLERRLOGFILE, you can configure the location of these files. The default values are stxxl.log and stxxl.errlog, respectively.

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...