Go to the first, previous, next, last section, table of contents.

# Installation and Customization

This chapter describes the installation and customization of FFTW, the latest version of which may be downloaded from the FFTW home page.

As distributed, FFTW makes very few assumptions about your system. All you need is an ANSI C compiler (`gcc` is fine, although vendor-provided compilers often produce faster code). However, installation of FFTW is somewhat simpler if you have a Unix or a GNU system, such as Linux. In this chapter, we first describe the installation of FFTW on Unix and non-Unix systems. We then describe how you can customize FFTW to achieve better performance. Specifically, you can I) enable `gcc`/x86-specific hacks that improve performance on Pentia and PentiumPro's; II) adapt FFTW to use the high-resolution clock of your machine, if any; III) produce code (codelets) to support fast transforms of sizes that are not supported efficiently by the standard FFTW distribution.

## Installation on Unix

FFTW comes with a `configure` program in the GNU style. Installation can be as simple as:

    ./configure
    make
    make install

This will build the uniprocessor complex and real transform libraries along with the test programs. We strongly recommend that you use GNU `make` if it is available; on some systems it is called `gmake`. The "`make install`" command installs the fftw and rfftw libraries in standard places, and typically requires root privileges (unless you specify a different install directory with the `--prefix` flag to `configure`). You can also type "`make check`" to put the FFTW test programs through their paces. If you have problems during configuration or compilation, you may want to run "`make distclean`" before trying again; this ensures that you don't have any stale files left over from previous compilation attempts.

The `configure` script knows good `CFLAGS` (C compiler flags) for a few systems. If your system is not known, the `configure` script will print out a warning. (9) In this case, you can compile FFTW with the command

    make CFLAGS="<write your CFLAGS here>"

If you do find an optimal set of `CFLAGS` for your system, please let us know what they are (along with the output of `config.guess`) so that we can include them in future releases.

The `configure` program supports all the standard flags defined by the GNU Coding Standards; see the `INSTALL` file in FFTW or the GNU web page. Note especially `--help` to list all flags and `--enable-shared` to create shared, rather than static, libraries. `configure` also accepts a few FFTW-specific flags, particularly:

- `--enable-float` Produces a single-precision version of FFTW (`float`) instead of the default double-precision (`double`). See Section Installing FFTW in both single and double precision.
- `--enable-type-prefix` Adds a ``d'` or ``s'` prefix to all installed libraries and header files to indicate the floating-point precision. See Section Installing FFTW in both single and double precision. (`--enable-type-prefix=<prefix>` lets you add an arbitrary prefix.) By default, no prefix is used.
- `--enable-threads` Enables compilation and installation of the FFTW threads library (see Section Multi-threaded FFTW), which provides a simple interface to parallel transforms for SMP systems. (By default, the threads routines are not compiled.)
- `--enable-mpi` Enables compilation and installation of the FFTW MPI library (see Section MPI FFTW), which provides parallel transforms for distributed-memory systems with MPI. (By default, the MPI routines are not compiled.)
- `--disable-fortran` Disables inclusion of Fortran-callable wrapper routines (see Section Calling FFTW from Fortran) in the standard FFTW libraries. These wrapper routines increase the library size by only a negligible amount, so they are included by default as long as the `configure` script finds a Fortran compiler on your system.
- `--with-gcc` Enables the use of `gcc`. By default, FFTW uses the vendor-supplied `cc` compiler if present. Unfortunately, `gcc` produces slower code than `cc` on many systems.
- `--enable-i386-hacks` See Section `gcc` and Pentium hacks, below.
- `--enable-pentium-timer` See Section `gcc` and Pentium hacks, below.

To force `configure` to use a particular C compiler (instead of the default, usually `cc`), set the environment variable `CC` to the name of the desired compiler before running `configure`; you may also need to set the flags via the variable `CFLAGS`.

## Installation on non-Unix Systems

It is quite straightforward to install FFTW even on non-Unix systems lacking the niceties of the `configure` script. The FFTW Home Page may include some FFTW packages preconfigured for particular systems/compilers, and also contains installation notes sent in by users. All you really need to do, though, is to compile all of the `.c` files in the appropriate directories of the FFTW package. (You needn't worry about the many extraneous files lying around.)

For the complex transforms, compile all of the `.c` files in the `fftw` directory and link them into a library. Similarly, for the real transforms, compile all of the `.c` files in the `rfftw` directory into a library. Note that these sources `#include` various files in the `fftw` and `rfftw` directories, so you may need to set up the `#include` paths for your compiler appropriately. Be sure to enable the highest-possible level of optimization in your compiler.

By default, FFTW is compiled for double-precision transforms. To work in single precision rather than double precision, `#define` the symbol `FFTW_ENABLE_FLOAT` in `fftw.h` (in the `fftw` directory) and (re)compile FFTW.

These libraries should be linked with any program that uses the corresponding transforms. The required header files, `fftw.h` and `rfftw.h`, are located in the `fftw` and `rfftw` directories respectively; you may want to put them with the libraries, or wherever header files normally go on your system.

FFTW includes test programs, `fftw_test` and `rfftw_test`, in the `tests` directory. These are compiled and linked like any program using FFTW, except that they use additional header files located in the `fftw` and `rfftw` directories, so you will need to set your compiler `#include` paths appropriately. `fftw_test` is compiled from `fftw_test.c` and `test_main.c`, while `rfftw_test` is compiled from `rfftw_test.c` and `test_main.c`. When you run these programs, you will be prompted interactively for various possible tests to perform; see also `tests/README` for more information.

## Installing FFTW in both single and double precision

It is often useful to install both single- and double-precision versions of the FFTW libraries on the same machine, and we provide a convenient mechanism for achieving this on Unix systems.

When the `--enable-type-prefix` option of configure is used, the FFTW libraries and header files are installed with a prefix of ``d'` or ``s'`, depending upon whether you compiled in double or single precision. Then, instead of linking your program with `-lrfftw -lfftw`, for example, you would link with `-ldrfftw -ldfftw` to use the double-precision version or with `-lsrfftw -lsfftw` to use the single-precision version. Also, you would `#include` `<drfftw.h>` or `<srfftw.h>` instead of `<rfftw.h>`, and so on.

The names of FFTW functions, data types, and constants remain unchanged! You still call, for instance, `fftw_one` and not `dfftw_one`. Only the names of header files and libraries are modified. One consequence of this is that you cannot use both the single- and double-precision FFTW libraries in the same program, simultaneously, as the function names would conflict.

So, to install both the single- and double-precision libraries on the same machine, you would do:

    ./configure --enable-type-prefix [ other options ]
    make
    make install
    make clean
    ./configure --enable-float --enable-type-prefix [ other options ]
    make
    make install

## `gcc` and Pentium hacks

The `configure` option `--enable-i386-hacks` enables specific optimizations for the Pentium and later x86 CPUs under gcc, which can significantly improve performance of double-precision transforms. Specifically, we have tested these hacks on Linux with `gcc` 2.[789] and versions of `egcs` since 1.0.3. These optimizations affect only the performance and not the correctness of FFTW (i.e. it is always safe to try them out).

These hacks provide a workaround to the incorrect alignment of local `double` variables in `gcc`. The compiler aligns these variables to multiples of 4 bytes, but execution is much faster (on Pentium and PentiumPro) if `double`s are aligned to a multiple of 8 bytes. By carefully counting the number of variables allocated by the compiler in performance-critical regions of the code, we have been able to introduce dummy allocations (using `alloca`) that align the stack properly. The hack depends crucially on the compiler flags that are used. For example, it won't work without `-fomit-frame-pointer`.

In principle, these hacks are no longer required under `gcc` versions 2.95 and later, which automatically align the stack correctly (see `-mpreferred-stack-boundary` in the `gcc` manual). However, we have encountered a bug in the stack alignment of versions 2.95.[012] that causes FFTW's stack to be misaligned under some circumstances. The `configure` script automatically detects this bug and disables `gcc`'s stack alignment in favor of our own hacks when `--enable-i386-hacks` is used.

The `fftw_test` program outputs speed measurements that you can use to see if these hacks are beneficial.

The `configure` option `--enable-pentium-timer` enables the use of the Pentium and PentiumPro cycle counter for timing purposes. In order to get correct results, you must define `FFTW_CYCLES_PER_SEC` in `fftw/config.h` to be the clock speed of your processor; the resulting FFTW library will be nonportable. The use of this option is deprecated. On serious operating systems (such as Linux), FFTW uses `gettimeofday()`, which has enough resolution and is portable. (Note that Win32 has its own high-resolution timing routines as well. FFTW contains unsupported code to use these routines.)

## Customizing the timer

FFTW needs a reasonably-precise clock in order to find the optimal way to compute a transform. On Unix systems, `configure` looks for `gettimeofday` and other system-specific timers. If it does not find any high resolution clock, it defaults to using the `clock()` function, which is very portable, but forces FFTW to run for a long time in order to get reliable measurements.

If your machine supports a high-resolution clock not recognized by FFTW, it is therefore advisable to use it. You must edit `fftw/fftw-int.h`. There are a few macros you must redefine. The code is documented and should be self-explanatory. (By the way, `fftw-int` stands for `fftw-internal`, but for some inexplicable reason people are still using primitive systems with 8.3 filenames.)

Even if you don't install high-resolution timing code, we still recommend that you look at the `FFTW_TIME_MIN` constant in `fftw/fftw-int.h`. This constant holds the minimum time interval (in seconds) required to get accurate timing measurements, and should be (at least) several hundred times the resolution of your clock. The default constants are on the conservative side, and may cause FFTW to take longer than necessary when you create a plan. Set `FFTW_TIME_MIN` to whatever is appropriate on your system (be sure to set the right `FFTW_TIME_MIN`...there are several definitions in `fftw-int.h`, corresponding to different platforms and timers).

As an aid in checking the resolution of your clock, you can use the `tests/fftw_test` program with the `-t` option (c.f. `tests/README`). Remember, the mere fact that your clock reports times in, say, picoseconds, does not mean that it is actually accurate to that resolution.

## Generating your own code

If you know that you will only use transforms of a certain size (say, powers of 2) and want to reduce the size of the library, you can reconfigure FFTW to support only those sizes you are interested in. You may even generate code to enable efficient transforms of a size not supported by the default distribution. The default distribution supports transforms of any size, but not all sizes are equally fast. The default installation of FFTW is best at handling sizes of the form 2a 3b 5c 7d 11e 13f, where e+f is either 0 or 1, and the other exponents are arbitrary. Other sizes are computed by means of a slow, general-purpose routine. However, if you have an application that requires fast transforms of size, say, `17`, there is a way to generate specialized code to handle that.

The directory `gensrc` contains all the programs and scripts that were used to generate FFTW. In particular, the program `gensrc/genfft.ml` was used to generate the code that FFTW uses to compute the transforms. We do not expect casual users to use it. `genfft` is a rather sophisticated program that generates directed acyclic graphs of FFT algorithms and performs algebraic simplifications on them. `genfft` is written in Objective Caml, a dialect of ML. Objective Caml is described at http://pauillac.inria.fr/ocaml/ and can be downloaded from from ftp://ftp.inria.fr/lang/caml-light.

If you have Objective Caml installed, you can type `sh bootstrap.sh` in the top-level directory to re-generate the files. If you change the `gensrc/config` file, you can optimize FFTW for sizes that are not currently supported efficiently (say, 17 or 19).

We do not provide more details about the code-generation process, since we do not expect that users will need to generate their own code. However, feel free to contact us at fftw@fftw.org if you are interested in the subject.

You might find it interesting to learn Caml and/or some modern programming techniques that we used in the generator (including monadic programming), especially if you heard the rumor that Java and object-oriented programming are the latest advancement in the field. The internal operation of the codelet generator is described in the paper, "A Fast Fourier Transform Compiler," by M. Frigo, which is available from the FFTW home page and will appear in the Proceedings of the 1999 ACM SIGPLAN Conference on Programming Language Design and Implementation (PLDI).

Go to the first, previous, next, last section, table of contents.