| POOMA: A C++ Toolkit for High-Performance Parallel Scientific Computing | ||
|---|---|---|
| Prev | Chapter 1. Getting Started with POOMA | Next |
Most of the POOMA Toolkit source code is available in header files containing template class definitions. A few files are compiled and collected together into the POOMA library.
Before the POOMA toolkit may be compiled, it must be configured. Configuration creates files used during compilation that are specific to the particular operating system, compiler, and available libraries that are to be used. The configuration files in the config/arch/ directory correspond to supported operating systems and compilers. For example, LINUXgcc.conf supports compiling under a Linux operating system with gcc (really g++). SGI64KCC.conf supports compiling under a 64-bit SGI Irix operating system with KCC.
To configure the source code, use a command like
./configure - -arch LINUXgcc - -opt - -suite LINUXgcc-optThe architecture argument to the - -arch option is the name of the corresponding configuration file, omitting its .conf suffix. The - -opt indicates the POOMA Toolkit will contain optimized source code, which makes the code run more quickly but may impede debugging. Alternatively, use the - -debug option which supports debugging. The suite name can be any arbitrary string. We chose LINUXgcc-opt to remind us of the architecture and optimization choice. configure creates subdirectories named "LINUXgcc-opt" for use when compiling the source files. Comments at the beginning of lib/suiteName/PoomaConfiguration.h record the configuration arguments.
To create the POOMA library, the toolkit source files need to be compiled. Specify the desired suite by setting the POOMASUITE environment variable to the appropriate value. For example, if using the bash shell, use
export POOMASUITE=suiteNamesubstituting the suite name's suiteName. If using the csh shell, use
setenv POOMASUITE suiteNameIn the previous paragraph, the suite name is LINUXgcc-opt so we would issue the statement
setenv POOMASUITE LINUXgcc-opt
Issuing the make command compiles the POOMA source code files to create the POOMA library. The POOMA makefiles assume the GNU™ Make is available so substitute the proper command to run GNU™ Make if necessary. As each source file is compiled, a line is printed. If the compilation succeeds, the POOMA library can be found in, e.g., lib/LINUXgcc-opt/libpooma-gcc.a. If it fails, the makefiles will print a line indicating which file failed to compile. Reading the corresponding .info file may indicate what failed.
The same POOMA source code can support multiple suites as long as different names are used. For example, we could have LINUXgcc-opt and LINUXgcc-debug suites. Both of these might specify use of the Linux operating system and gcc, but one could have optimized code corresponding to the configuration option - -opt and the other could have debuggable code corresponding to the configuration option - -debug. When compiling both the library and user code, the POOMASUITE environment variable indicates which suite to use.
(Are you sure you should be reading this section? The DANGER in the title is meant to warn you about material that ought to be skipped on the first reading. And maybe also on the second reading. The reader-beware paragraphs sometimes refer to concepts that aren't explained until later chapters. (Thanks to Donald E. Knuth for the concept of DANGER sections and for the preceding text.))
The configuration script supports many more command-line options than the two used above, but few POOMA users need use them except those using distributed POOMA, which are described below. ./configure -h yields a complete list. We also describe them here.
Table 1-1. Configuration Options
| option | description |
|---|---|
| Architecture and Installation Choices | |
| - -arch architecture | specify the desired operating system and compiler. architecture should correspond to a file in config/arch/ omitting the .conf suffix. |
| - -suite suite | specify a name for the this particular configuration. The environment variable POOMASUITE's value should equal suite when compiling the library. suite can be any string that can serve as a filename. If this option is omitted, the - -arch architecture is used. |
| - -prefix directory | indicates the directory where files are installed. make install should be invoked after compiling the library. |
| Debugging and Optimization Choices | |
| - -opt | causes an optimized library to be built. Optimized code typically runs faster than unoptimized code, but debugging can be inhibited. |
| - -debug | causes an debuggable library to be built. That is, a debugger will be able to traverse library code. |
| Compiler Choices | |
| - -cpp compiler | specifies the C++ compiler to use. The default value is specified by the architecture configuration file. |
| - -c compiler | specifies the C compiler to use when compiling C executables. Such executables usually are example programs. The default value is specified by the architecture configuration file. |
| - -f77 compiler | specifies the Fortran77 compiler to use. The default value is specified by the architecture configuration file. |
| - -ar archiver | specifies the library archiver to use when creating a static library. The default value is specified by the architecture configuration file. |
| - -link linker | specifies the linker to use when creating POOMA executables. The default value, usually the same as the C++ compiler, is specified by the architecture configuration file. |
| Compiler Options | |
| - -static | creates a static library that will be directly linked into executables, rather than loaded dynamically. Compare with the - -shared option. This option is a default. |
| - -shared | creates a library that will be dynamically loaded when a POOMA executable starts. It is the executable user's responsibility to configure the operating system so the library will be found, e.g., by setting the LD_LIBRARY_PATH environment variable. |
| - -v | enables verbose output from the compiler and linker. |
| - -q | disables verbose output from the compiler and linker. |
| - -strict | enables ANSI C++ conformance checking by the compiler. |
| - -inc directory | causes -Idirectory options to be passed to the compiler. These indicate directories where header files are located. This option may be specified repeatedly. |
| - -def definition | causes -Ddefinition options to be passed to the compiler. These define preprocessor symbols. This option may be specified repeatedly. |
| - -cpparg arguments | specifies C++ compiler options. This option may be specified repeatedly. |
| - -carg arguments | specifies C compiler options. This option may be specified repeatedly. |
| - -f77arg arguments | specifies Fortran77 compiler options. This option may be specified repeatedly. |
| - -ararg arguments | specifies archiver options. This option may be specified repeatedly. |
| - -linkarg arguments | specifies linker options. This option may be specified repeatedly. |
| - -oneper | enables the one-per-template-instantiation compiler option. The KCC compiler requires this option to avoid problems from instantiating the same template class repeatedly. |
| - -noonper | disables the one-per-template-instantiation compiler option. See - -oneper description. |
| Code Checking | |
| - -bounds | turns on bound checking for indexing operations. That is, indexes into a C (a(3,4)) are checked to be in the domain. This option is not the default because it slows each access but is useful when checking program correctness. |
| - -insure | enables Insure++ code checking. |
| - -purify | enables Purify code checking. |
| Language Choices | |
| - -ex | enables use of exceptions if available. Only one of this xor the - -noex option should be specified. |
| - -noex | disables use of exceptions. Only one of this xor the - -ex option should be specified. |
| - -arch-specific-functions | enables the use of architecture-specific initialization functions. |
| Library Options | |
| - -preinst | causes preinstantiated versions of several templated classes to be included in the library. This may reduce the time to compile executables. |
| DANGER: Option for Distributed Computation | |
| - -messaging | enables creation of distributed POOMA executables by enabling use of the Cheetah communications package. |
| Configure Options | |
| -v | turns on verbose output during configuration, showing which options are chosen and which are not. |
| -i | prevents overwriting existing files during configuration without first querying the user. |
| -f | forces overwriting existing files during configuration without querying the user. This is the default. |
| -h | prints the list of configuration options. |
| -? | prints the list of configuration options. This is the same as -h. |