QuickFlash Installation

Installing QuickFlash

The QuickFlash Build System

The build system is a Python script (build.py) that performs the following operations:

1. Generates a Makefile header (settings.make) that includes definitions for compiling the QuickFlash library and related programs
2. Builds the C++ library in the src_lib directory
3. (Optional) Builds the QuickFlash Python bindings in the swig directory
4. Copies the library header files and object files to the installation directories

Brief documentation about the various options for build.py can be found by issuing the command:

./build.py --help

Configuring the Build System

By default, the build.py script uses information in the machines.cfg file to construct settings.make. A setup for a given build includes specifications for the compiler and external libraries (such as HDF5). The machines.cfg file can hold multiple setup specifications (called machine contexts), each denoted by a label.

A machine context is specified by starting with the label encased in brackets, as in

[ my_context ]

Spaces between the first bracket and the start of label and those between the end of the label and the last bracket are ignored. An optional description can be added by placing a colon followed by the text after the context name, such as

[ my_context : my description ]

In general, spaces are not recommended for use within the context name string — underscores or dashes work well as substitutes — but they are welcome in the description text.

Settings for the build system follow the label, where each line begins with a keyword followed by the definition associated with that keyword. Mulitiple-line entries can be constructed by placing a "backslash" character (\) at the end of each line that is to be continued on the following line.

The line

CXX g++

assigns the value g++ to the symbol CXX. The keyword and value will be placed in the settings.make file using the same case. The definition above will yield the line

CXX = g++

in the settings.make file. (NOTE: At this time, there is no guarantee that entries in a machines.cfg context will have their order preserved when settings.make is built.) Comments can be added to machines.cfg by using the comment character #. Any text between a # and the end of the line is ignored. Blank lines are also ignored in machines.cfg.

Any desired definitions can be placed within the context, all of which will be transferred to settings.make. (However, keywords may not contain spaces or control characters.) In order to construct the QuickFlash library, the following keywords must be defined:

• MAKE — The name of the executable used for running makefiles (usually gmake or make)
• CXX — The C++ compiler
• LD — The linker (uses CXX setting by default)
• CCFLAGS — Essential compilation flags
• LDFLAGS — Essential linker flags
• CCFLAGS_SHARED — Additional compilation flags when building shared libraries
• LDFLAGS_SHARED — Additional linker flags when building shared libraries
• CCFLAGS_NOSHARED — Additional compilation flags when not building shared libraries
• LDFLAGS_NOSHARED — Additional linker flags when not building shared libraries
• SO_EXT — Default system-specific extension used for shared libraries, without the leading period (usually so or dylib)
• AR — Name of the executable used for building static archives from object files (usually ar)
• ARFLAGS — Flags used when building static archives
• RANLIB — Name of the executable used for adding indexes to static archives (usually ranlib)
• CCFLAGS_HDF5 — Additional compilation flags for the HDF5 library
• LDFLAGS_HDF5 — Additional linker flags for the HDF5 library
• LIB_INSTALL_DIR — Path to directory where the library include and lib directories will be installed (NOTE: Custom installation directories not supported at this time).

Many of these keywords have default values; for any required keywords not found in the machines.cfg file, the default will be used if it exists.

Build Settings for Python Bindings

To build the Python bindings, the following additional keywords are needed:

• SWIG — The name of the SWIG interface builder executable (usually swig); should be version 1.3.29 or later
• CCFLAGS_PYTHON — Additional compiler flags when building Python packages (usually an include search path flag indicating the location of Python.h)
• LDFLAGS_PYTHON — Additional compiler flags when building Python packages
• PYTHON_INSTALL_DIR — Path to directory where the QuickFlash Python pakcage will be installed (NOTE: Not supported at this time)

Some of these keywords also have defaults. Furthermore, the swig directory contains pre-built versions of the output from SWIG (QuickFlash.py and python_quickflash_wrap.cxx), and make will use them if they are recent enough; thus, having the SWIG executable present may not be necessary to build the Python bindings for QuickFlash.

Optional Components

The QuickFlash build system has support for optional code components for both the library and end user programs. The USE_PACKAGE keyword in machines.cfg setups allows the user to specify codes for one or more optional components. Placing the code EXAMPLE_PKG in a setup via the line

USE_PACKAGE EXAMPLE_PKG

will define the preprocessor variable USE_EXAMPLE_PKG to the C++ compiler flags. The codes for multiple components should be separated by spaces, as in

USE_PACKAGE PKG1 PKG2

Some of the supplied example applications have MPI support, which is activated with

USE_PACKAGE MPI

resulting in the preprocessor definition USE_MPI.

ImageMagick Functionality

The QuickFlash library includes optional support for image output via the ImageMagick C++ bindings (Magick++). To activate image support, add the code MAGICK to the USE_PACKAGE setting in machines.cfg.

When using ImageMagick, QuickFlash will expect the following definitions to be set in machines.cfg:

• CCFLAGS_MAGICK — Compiler flags for finding the ImageMagick header files
• LDFLAGS_MAGICK — Linker flags for binding to the ImageMagick library

Using the Build System

The build.py script performs several tasks, which are controlled by the command line flags that are provided. The most important are the following:

• --help — The complete list of options
• --machine=context_name — Specifies the name of the context in machines.cfg to be used; if this option is omitted, a new settings.make will not be generated, and the existing one will be used for building the library
• --machine-config=config_file — Use a configuration file other than machines.cfg
• --machine-help — Prints the names and descriptions of contexts defined in machines.cfg
• --screen-only — Sends the contents of the generated settings.make file to standard output; does not build the library or change any files
• --enable-python — Builds both the %QuickFlash library and the Python bindings
• --python-only — Build (or clean) only the Python bindings; the C++ library must have already been built
• --clean — Cleans the build directories; must be used with --enable-python to clean the swig directory
• --clean-first — Perform a clean operation before any specified or implide build operations
• --make-cmd=make_command — Specifies the make command to be used; overrides the MAKE setting in machines.cfg
• --makefile-only — Generates settings.make but does not build the library

Running build.py without arguments will result in an attempt to build the C++ library using an existing settings.make file. This file can be one created by previous calls to build.py, or one created by the user. (User-created settings.make files are generally only used for debugging purposes, as subsequent build.py calls using the --machines=... argument will overwrite any existing settings.make file.)

Type Ia supernova deflagration front (blue) on density field (gray).
Simulation by George Jordan / ASC Flash Center.