cannam@95: @node Installation and Customization, Acknowledgments, Upgrading from FFTW version 2, Top cannam@95: @chapter Installation and Customization cannam@95: @cindex installation cannam@95: cannam@95: This chapter describes the installation and customization of FFTW, the cannam@95: latest version of which may be downloaded from cannam@95: @uref{http://www.fftw.org, the FFTW home page}. cannam@95: cannam@95: In principle, FFTW should work on any system with an ANSI C compiler cannam@95: (@code{gcc} is fine). However, planner time is drastically reduced if cannam@95: FFTW can exploit a hardware cycle counter; FFTW comes with cycle-counter cannam@95: support for all modern general-purpose CPUs, but you may need to add a cannam@95: couple of lines of code if your compiler is not yet supported cannam@95: (@pxref{Cycle Counters}). (On Unix, there will be a warning at the end cannam@95: of the @code{configure} output if no cycle counter is found.) cannam@95: @cindex cycle counter cannam@95: @cindex compiler cannam@95: @cindex portability cannam@95: cannam@95: cannam@95: Installation of FFTW is simplest if you have a Unix or a GNU system, cannam@95: such as GNU/Linux, and we describe this case in the first section below, cannam@95: including the use of special configuration options to e.g. install cannam@95: different precisions or exploit optimizations for particular cannam@95: architectures (e.g. SIMD). Compilation on non-Unix systems is a more cannam@95: manual process, but we outline the procedure in the second section. It cannam@95: is also likely that pre-compiled binaries will be available for popular cannam@95: systems. cannam@95: cannam@95: Finally, we describe how you can customize FFTW for particular needs by cannam@95: generating @emph{codelets} for fast transforms of sizes not supported cannam@95: efficiently by the standard FFTW distribution. cannam@95: @cindex codelet cannam@95: cannam@95: @menu cannam@95: * Installation on Unix:: cannam@95: * Installation on non-Unix systems:: cannam@95: * Cycle Counters:: cannam@95: * Generating your own code:: cannam@95: @end menu cannam@95: cannam@95: @c ------------------------------------------------------------ cannam@95: cannam@95: @node Installation on Unix, Installation on non-Unix systems, Installation and Customization, Installation and Customization cannam@95: @section Installation on Unix cannam@95: cannam@95: FFTW comes with a @code{configure} program in the GNU style. cannam@95: Installation can be as simple as: cannam@95: @fpindex configure cannam@95: cannam@95: @example cannam@95: ./configure cannam@95: make cannam@95: make install cannam@95: @end example cannam@95: cannam@95: This will build the uniprocessor complex and real transform libraries cannam@95: along with the test programs. (We recommend that you use GNU cannam@95: @code{make} if it is available; on some systems it is called cannam@95: @code{gmake}.) The ``@code{make install}'' command installs the fftw cannam@95: and rfftw libraries in standard places, and typically requires root cannam@95: privileges (unless you specify a different install directory with the cannam@95: @code{--prefix} flag to @code{configure}). You can also type cannam@95: ``@code{make check}'' to put the FFTW test programs through their paces. cannam@95: If you have problems during configuration or compilation, you may want cannam@95: to run ``@code{make distclean}'' before trying again; this ensures that cannam@95: you don't have any stale files left over from previous compilation cannam@95: attempts. cannam@95: cannam@95: The @code{configure} script chooses the @code{gcc} compiler by default, cannam@95: if it is available; you can select some other compiler with: cannam@95: @example cannam@95: ./configure CC="@r{@i{}}" cannam@95: @end example cannam@95: cannam@95: The @code{configure} script knows good @code{CFLAGS} (C compiler flags) cannam@95: @cindex compiler flags cannam@95: for a few systems. If your system is not known, the @code{configure} cannam@95: script will print out a warning. In this case, you should re-configure cannam@95: FFTW with the command cannam@95: @example cannam@95: ./configure CFLAGS="@r{@i{}}" cannam@95: @end example cannam@95: and then compile as usual. If you do find an optimal set of cannam@95: @code{CFLAGS} for your system, please let us know what they are (along cannam@95: with the output of @code{config.guess}) so that we can include them in cannam@95: future releases. cannam@95: cannam@95: @code{configure} supports all the standard flags defined by the GNU cannam@95: Coding Standards; see the @code{INSTALL} file in FFTW or cannam@95: @uref{http://www.gnu.org/prep/standards/html_node/index.html, the GNU web page}. cannam@95: Note especially @code{--help} to list all flags and cannam@95: @code{--enable-shared} to create shared, rather than static, libraries. cannam@95: @code{configure} also accepts a few FFTW-specific flags, particularly: cannam@95: cannam@95: @itemize @bullet cannam@95: cannam@95: @item cannam@95: @cindex precision cannam@95: @code{--enable-float}: Produces a single-precision version of FFTW cannam@95: (@code{float}) instead of the default double-precision (@code{double}). cannam@95: @xref{Precision}. cannam@95: cannam@95: @item cannam@95: @cindex precision cannam@95: @code{--enable-long-double}: Produces a long-double precision version of cannam@95: FFTW (@code{long double}) instead of the default double-precision cannam@95: (@code{double}). The @code{configure} script will halt with an error cannam@95: message if @code{long double} is the same size as @code{double} on your cannam@95: machine/compiler. @xref{Precision}. cannam@95: cannam@95: @item cannam@95: @cindex precision cannam@95: @code{--enable-quad-precision}: Produces a quadruple-precision version cannam@95: of FFTW using the nonstandard @code{__float128} type provided by cannam@95: @code{gcc} 4.6 or later on x86, x86-64, and Itanium architectures, cannam@95: instead of the default double-precision (@code{double}). The cannam@95: @code{configure} script will halt with an error message if the cannam@95: compiler is not @code{gcc} version 4.6 or later or if @code{gcc}'s cannam@95: @code{libquadmath} library is not installed. @xref{Precision}. cannam@95: cannam@95: @item cannam@95: @cindex threads cannam@95: @code{--enable-threads}: Enables compilation and installation of the cannam@95: FFTW threads library (@pxref{Multi-threaded FFTW}), which provides a cannam@95: simple interface to parallel transforms for SMP systems. By default, cannam@95: the threads routines are not compiled. cannam@95: cannam@95: @item cannam@95: @code{--enable-openmp}: Like @code{--enable-threads}, but using OpenMP cannam@95: compiler directives in order to induce parallelism rather than cannam@95: spawning its own threads directly, and installing an @samp{fftw3_omp} library cannam@95: rather than an @samp{fftw3_threads} library (@pxref{Multi-threaded cannam@95: FFTW}). You can use both @code{--enable-openmp} and @code{--enable-threads} cannam@95: since they compile/install libraries with different names. By default, cannam@95: the OpenMP routines are not compiled. cannam@95: cannam@95: @item cannam@95: @code{--with-combined-threads}: By default, if @code{--enable-threads} cannam@95: is used, the threads support is compiled into a separate library that cannam@95: must be linked in addition to the main FFTW library. This is so that cannam@95: users of the serial library do not need to link the system threads cannam@95: libraries. If @code{--with-combined-threads} is specified, however, cannam@95: then no separate threads library is created, and threads are included cannam@95: in the main FFTW library. This is mainly useful under Windows, where cannam@95: no system threads library is required and inter-library dependencies cannam@95: are problematic. cannam@95: cannam@95: @item cannam@95: @cindex MPI cannam@95: @code{--enable-mpi}: Enables compilation and installation of the FFTW cannam@95: MPI library (@pxref{Distributed-memory FFTW with MPI}), which provides cannam@95: parallel transforms for distributed-memory systems with MPI. (By cannam@95: default, the MPI routines are not compiled.) @xref{FFTW MPI cannam@95: Installation}. cannam@95: cannam@95: @item cannam@95: @cindex Fortran-callable wrappers cannam@95: @code{--disable-fortran}: Disables inclusion of legacy-Fortran cannam@95: wrapper routines (@pxref{Calling FFTW from Legacy Fortran}) in the standard cannam@95: FFTW libraries. These wrapper routines increase the library size by cannam@95: only a negligible amount, so they are included by default as long as cannam@95: the @code{configure} script finds a Fortran compiler on your system. cannam@95: (To specify a particular Fortran compiler @i{foo}, pass cannam@95: @code{F77=}@i{foo} to @code{configure}.) cannam@95: cannam@95: @item cannam@95: @code{--with-g77-wrappers}: By default, when Fortran wrappers are cannam@95: included, the wrappers employ the linking conventions of the Fortran cannam@95: compiler detected by the @code{configure} script. If this compiler is cannam@95: GNU @code{g77}, however, then @emph{two} versions of the wrappers are cannam@95: included: one with @code{g77}'s idiosyncratic convention of appending cannam@95: two underscores to identifiers, and one with the more common cannam@95: convention of appending only a single underscore. This way, the same cannam@95: FFTW library will work with both @code{g77} and other Fortran cannam@95: compilers, such as GNU @code{gfortran}. However, the converse is not cannam@95: true: if you configure with a different compiler, then the cannam@95: @code{g77}-compatible wrappers are not included. By specifying cannam@95: @code{--with-g77-wrappers}, the @code{g77}-compatible wrappers are cannam@95: included in addition to wrappers for whatever Fortran compiler cannam@95: @code{configure} finds. cannam@95: @fpindex g77 cannam@95: cannam@95: @item cannam@95: @code{--with-slow-timer}: Disables the use of hardware cycle counters, cannam@95: and falls back on @code{gettimeofday} or @code{clock}. This greatly cannam@95: worsens performance, and should generally not be used (unless you don't cannam@95: have a cycle counter but still really want an optimized plan regardless cannam@95: of the time). @xref{Cycle Counters}. cannam@95: cannam@95: @item cannam@95: @code{--enable-sse}, @code{--enable-sse2}, @code{--enable-avx}, cannam@95: @code{--enable-altivec}, @code{--enable-neon}: Enable the compilation of cannam@95: SIMD code for SSE (Pentium III+), SSE2 (Pentium IV+), AVX (Sandy Bridge, cannam@95: Interlagos), AltiVec (PowerPC G4+), NEON (some ARM processors). SSE, cannam@95: AltiVec, and NEON only work with @code{--enable-float} (above). SSE2 cannam@95: works in both single and double precision (and is simply SSE in single cannam@95: precision). The resulting code will @emph{still work} on earlier CPUs cannam@95: lacking the SIMD extensions (SIMD is automatically disabled, although cannam@95: the FFTW library is still larger). cannam@95: @itemize @minus cannam@95: @item cannam@95: These options require a compiler supporting SIMD extensions, and cannam@95: compiler support is always a bit flaky: see the FFTW FAQ for a list of cannam@95: compiler versions that have problems compiling FFTW. cannam@95: @item cannam@95: With AltiVec and @code{gcc}, you may have to use the cannam@95: @code{-mabi=altivec} option when compiling any code that links to FFTW, cannam@95: in order to properly align the stack; otherwise, FFTW could crash when cannam@95: it tries to use an AltiVec feature. (This is not necessary on MacOS X.) cannam@95: @item cannam@95: With SSE/SSE2 and @code{gcc}, you should use a version of gcc that cannam@95: properly aligns the stack when compiling any code that links to FFTW. cannam@95: By default, @code{gcc} 2.95 and later versions align the stack as cannam@95: needed, but you should not compile FFTW with the @code{-Os} option or the cannam@95: @code{-mpreferred-stack-boundary} option with an argument less than 4. cannam@95: @item cannam@95: Because of the large variety of ARM processors and ABIs, FFTW cannam@95: does not attempt to guess the correct @code{gcc} flags for generating cannam@95: NEON code. In general, you will have to provide them on the command line. cannam@95: This command line is known to have worked at least once: cannam@95: @example cannam@95: ./configure --with-slow-timer --host=arm-linux-gnueabi \ cannam@95: --enable-single --enable-neon \ cannam@95: "CC=arm-linux-gnueabi-gcc -march=armv7-a -mfloat-abi=softfp" cannam@95: @end example cannam@95: @end itemize cannam@95: cannam@95: @end itemize cannam@95: cannam@95: @cindex compiler cannam@95: To force @code{configure} to use a particular C compiler @i{foo} cannam@95: (instead of the default, usually @code{gcc}), pass @code{CC=}@i{foo} to the cannam@95: @code{configure} script; you may also need to set the flags via the variable cannam@95: @code{CFLAGS} as described above. cannam@95: @cindex compiler flags cannam@95: cannam@95: @c ------------------------------------------------------------ cannam@95: @node Installation on non-Unix systems, Cycle Counters, Installation on Unix, Installation and Customization cannam@95: @section Installation on non-Unix systems cannam@95: cannam@95: It should be relatively straightforward to compile FFTW even on non-Unix cannam@95: systems lacking the niceties of a @code{configure} script. Basically, cannam@95: you need to edit the @code{config.h} header (copy it from cannam@95: @code{config.h.in}) to @code{#define} the various options and compiler cannam@95: characteristics, and then compile all the @samp{.c} files in the cannam@95: relevant directories. cannam@95: cannam@95: The @code{config.h} header contains about 100 options to set, each one cannam@95: initially an @code{#undef}, each documented with a comment, and most of cannam@95: them fairly obvious. For most of the options, you should simply cannam@95: @code{#define} them to @code{1} if they are applicable, although a few cannam@95: options require a particular value (e.g. @code{SIZEOF_LONG_LONG} should cannam@95: be defined to the size of the @code{long long} type, in bytes, or zero cannam@95: if it is not supported). We will likely post some sample cannam@95: @code{config.h} files for various operating systems and compilers for cannam@95: you to use (at least as a starting point). Please let us know if you cannam@95: have to hand-create a configuration file (and/or a pre-compiled binary) cannam@95: that you want to share. cannam@95: cannam@95: To create the FFTW library, you will then need to compile all of the cannam@95: @samp{.c} files in the @code{kernel}, @code{dft}, @code{dft/scalar}, cannam@95: @code{dft/scalar/codelets}, @code{rdft}, @code{rdft/scalar}, cannam@95: @code{rdft/scalar/r2cf}, @code{rdft/scalar/r2cb}, cannam@95: @code{rdft/scalar/r2r}, @code{reodft}, and @code{api} directories. cannam@95: If you are compiling with SIMD support (e.g. you defined cannam@95: @code{HAVE_SSE2} in @code{config.h}), then you also need to compile cannam@95: the @code{.c} files in the @code{simd-support}, cannam@95: @code{@{dft,rdft@}/simd}, @code{@{dft,rdft@}/simd/*} directories. cannam@95: cannam@95: Once these files are all compiled, link them into a library, or a shared cannam@95: library, or directly into your program. cannam@95: cannam@95: To compile the FFTW test program, additionally compile the code in the cannam@95: @code{libbench2/} directory, and link it into a library. Then compile cannam@95: the code in the @code{tests/} directory and link it to the cannam@95: @code{libbench2} and FFTW libraries. To compile the @code{fftw-wisdom} cannam@95: (command-line) tool (@pxref{Wisdom Utilities}), compile cannam@95: @code{tools/fftw-wisdom.c} and link it to the @code{libbench2} and FFTW cannam@95: libraries cannam@95: cannam@95: @c ------------------------------------------------------------ cannam@95: @node Cycle Counters, Generating your own code, Installation on non-Unix systems, Installation and Customization cannam@95: @section Cycle Counters cannam@95: @cindex cycle counter cannam@95: cannam@95: FFTW's planner actually executes and times different possible FFT cannam@95: algorithms in order to pick the fastest plan for a given @math{n}. In cannam@95: order to do this in as short a time as possible, however, the timer must cannam@95: have a very high resolution, and to accomplish this we employ the cannam@95: hardware @dfn{cycle counters} that are available on most CPUs. cannam@95: Currently, FFTW supports the cycle counters on x86, PowerPC/POWER, Alpha, cannam@95: UltraSPARC (SPARC v9), IA64, PA-RISC, and MIPS processors. cannam@95: cannam@95: @cindex compiler cannam@95: Access to the cycle counters, unfortunately, is a compiler and/or cannam@95: operating-system dependent task, often requiring inline assembly cannam@95: language, and it may be that your compiler is not supported. If you are cannam@95: @emph{not} supported, FFTW will by default fall back on its estimator cannam@95: (effectively using @code{FFTW_ESTIMATE} for all plans). cannam@95: @ctindex FFTW_ESTIMATE cannam@95: cannam@95: You can add support by editing the file @code{kernel/cycle.h}; normally, cannam@95: this will involve adapting one of the examples already present in order cannam@95: to use the inline-assembler syntax for your C compiler, and will only cannam@95: require a couple of lines of code. Anyone adding support for a new cannam@95: system to @code{cycle.h} is encouraged to email us at @email{fftw@@fftw.org}. cannam@95: cannam@95: If a cycle counter is not available on your system (e.g. some embedded cannam@95: processor), and you don't want to use estimated plans, as a last resort cannam@95: you can use the @code{--with-slow-timer} option to @code{configure} (on cannam@95: Unix) or @code{#define WITH_SLOW_TIMER} in @code{config.h} (elsewhere). cannam@95: This will use the much lower-resolution @code{gettimeofday} function, or even cannam@95: @code{clock} if the former is unavailable, and planning will be cannam@95: extremely slow. cannam@95: cannam@95: @c ------------------------------------------------------------ cannam@95: @node Generating your own code, , Cycle Counters, Installation and Customization cannam@95: @section Generating your own code cannam@95: @cindex code generator cannam@95: cannam@95: The directory @code{genfft} contains the programs that were used to cannam@95: generate FFTW's ``codelets,'' which are hard-coded transforms of small cannam@95: sizes. cannam@95: @cindex codelet cannam@95: We do not expect casual users to employ the generator, which is a rather cannam@95: sophisticated program that generates directed acyclic graphs of FFT cannam@95: algorithms and performs algebraic simplifications on them. It was cannam@95: written in Objective Caml, a dialect of ML, which is available at cannam@95: @uref{http://caml.inria.fr/ocaml/index.en.html}. cannam@95: @cindex Caml cannam@95: cannam@95: cannam@95: If you have Objective Caml installed (along with recent versions of cannam@95: GNU @code{autoconf}, @code{automake}, and @code{libtool}), then you cannam@95: can change the set of codelets that are generated or play with the cannam@95: generation options. The set of generated codelets is specified by the cannam@95: @code{@{dft,rdft@}/@{codelets,simd@}/*/Makefile.am} files. For example, you can add cannam@95: efficient REDFT codelets of small sizes by modifying cannam@95: @code{rdft/codelets/r2r/Makefile.am}. cannam@95: @cindex REDFT cannam@95: After you modify any @code{Makefile.am} files, you can type @code{sh cannam@95: bootstrap.sh} in the top-level directory followed by @code{make} to cannam@95: re-generate the files. cannam@95: cannam@95: We do not provide more details about the code-generation process, since cannam@95: we do not expect that most users will need to generate their own code. cannam@95: However, feel free to contact us at @email{fftw@@fftw.org} if cannam@95: you are interested in the subject. cannam@95: cannam@95: @cindex monadic programming cannam@95: You might find it interesting to learn Caml and/or some modern cannam@95: programming techniques that we used in the generator (including monadic cannam@95: programming), especially if you heard the rumor that Java and cannam@95: object-oriented programming are the latest advancement in the field. cannam@95: The internal operation of the codelet generator is described in the cannam@95: paper, ``A Fast Fourier Transform Compiler,'' by M. Frigo, which is cannam@95: available from the @uref{http://www.fftw.org,FFTW home page} and also cannam@95: appeared in the @cite{Proceedings of the 1999 ACM SIGPLAN Conference on cannam@95: Programming Language Design and Implementation (PLDI)}. cannam@95: