tar
zfxv
stxxl-x.y.z.tgz
,stxxl
directory: cd
stxxl-x.y.z
,make.settings.gnu
or make.settings.local
file according to your system configuration:STXXL
root directory STXXL_ROOT
variable ( directory_where_you_unpacked_the_tar_ball/stxxl-x.y.z
)STXXL
to use Boost libraries (you should have the Boost libraries already installed)USE_BOOST
variable to yes
BOOST_ROOT
variable according to the Boost root pathOPT
variable to -O3
or other g++ optimization level you like (default: -O3
)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)make library_g++
make tests_g++
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 applicationsSTXXL_CPPFLAGS
- add these flags to the compile commandsSTXXL_LDLIBS
- add these libraries to the link commandsAn 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.
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.
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 megabytesaccess_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 callssimdisk
: simulates timings of the IBM IC35L080AVVA07 disk, full_disk_filename must point to a file on a RAM disk partition with sufficient spaceSee also the example configuration file 'config_example'
included in the tarball.
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...