How to compile DFPAL?

The DFPAL Library, version 2.20 © Copyright IBM Corporation, 2007. All rights reserved.
[previous \| contents \| next]	[printer friendly]

How to compile DFPAL?

DFPAL is successfully compiled with a variety of compilers on multiple platforms. DFPAL portability is enabled by a combination of coding style and compile time switches. Build instructions (Makefile), for various environments, are included in the package. Follow instructions in the makefile carefully, especially on AIX (e.g. -qlongdouble flag must be used with XLC on AIX) and Linux on Power (e.g. -mlong-double-128 flag must be used with GCC on Linux on Power). DFPAL can be compiled as a standalone library or can be integrated into the application itself.

decNumber tuning
Beginning decNumber version 3.40, the DECENDIAN setting (in decNumberLocal.h) has been removed to improve performance; instead, you must set the DECLITEND parameter to 1 if compiling for a little-endian target (for example, AMD and Intel x86), or to 0 if compiling for a big-endian (IBM POWER processor) target.

The decNumber package included in the DFPAL package has DECLITEND value set to 0. Additionally, respective Makefiles set DECLITEND to appropriate value on compiler command line.

Compile time switches

`DFPAL_THREAD_SAFE`	Activate thread local storage for DFPAL context. This switch must be specified on all platforms to enable multi-threading support. Non multi-threaded application may get marginal performance benefit by not defining this switch. Absence of this switch bypasses a thread local storage.
`DFPAL_OS_AIX5L` `DFPAL_OS_LOP` `DFPAL_OS_WINDOWS`	Specify target platform using one of these switches. Using `DFPAL_OS_AIX5L` implies detecting and activating hardware decimal floating point with AIX on POWER6. Such code will run on any level of supported AIX operating system with any supported POWER processor. On pre-POWER6 processors, DFPAL will utilize decNumber for the decimal floating point arithmetic. Using `DFPAL_OS_LOP` implies detecting and activating hardware decimal floating point for Linux on Power platform, running on POWER6. Such code will run on any level of supported Linux on Power distribution, with any supported POWER processor. On pre-POWER6 processors, DFPAL will utilize decNumber for the decimal floating point arithmetic. Both IBM XLC and GCC compilers are supported. Use `DFPAL_OS_WINDOWS` to compile on Microsoft Windows using Microsoft compiler. Windows has a different thread local storage model than POSIX (on Unix or Linux) thread local storage model.
`DFPAL_USE_INTTYPES_H` `DFPAL_LOCAL_INTTYPES`	For C99 data types, some platform have `inttypes.h`, whereas others have stdint.h (e.g. AIX, Linux). Windows does not have either. Select appropriate switch for your platform. For Windows use `DFPAL_LOCAL_INTTYPES` switch. If your build environment does not work with any of these, create and edit a file with `stdint.h` name and define appropriate data types.
`DFPAL_INTEGER64_LITERAL_LL` `DFPAL_INTEGER64_LITERAL_L` `DFPAL_INTEGER64_LITERAL_i64`	Various platforms/compilers use different literal designator for 64-bit integers. Set any one of these switch accordingly. The default is `LL` and `ULL` for signed integer and unsigned integer, respectively. AIX/XLC do not require any switch from this list. `DFPAL_INTEGER64_LITERAL_i64` is for Windows platforms. The easiest way to determine the literal designator for particular compiler/platform is to look at system header file `limits.h`.
`DFPAL_NO_HW_DFP`	Use this switch if target platform/compiler does not support hardware DFP or `#pragma mc_func` directives for the hardware instruction inline expansion (e.g. using GCC compiler on AIX). DFPAL compiled with this switch will only use decNumber for the DFP arithmetic even if running on POWER6.
`DFPAL_USE_DECFLOAT`	decFloat is new API, part of the decNumber package, which performs arithmetic directly on densely packed decimal (DPD) encoding. Use of decFloat eliminates DPD encoding to decNumber format conversion, and vice versa, enabling faster operation in software. Use of this switch has no impact on speed of hardware arithmetic operations. Use this switch to use decFloat instead of decNumber. More information about the decFloat is available at decNumber module.
`DFPAL_STANDALONE_DLL` (only for Windows)	This switch is relevant to Windows platform only. DFPAL is using `pthread_once()` facility on Unix platforms with POSIX thread support. Windows does not have equivalent facility. Alternatively, DFPAL is using `DllMain()` facility on Windows platform. Compile with this switch if DFPAL is being compiled as standalone library (Dynamic Link Library or DLL). If DFPAL is integrated into some container module such as EXE or another DLL, use that container module's `DllMain()` equivalent facility. The container module's `DllMain()` equivalent facility must call `dfpalInitProcessContext()` for `DLL_PROCESS_ATTACH` event. No other actions are necessary for the remaining events. A sample export symbol definition file `dfpalsymexp.def` is included for convenience.
`DFPAL_USE_COMPILER_DFP`	In future when application build environment is migrated to XLC version 9, this switch allows compiler native decimal floating point usage, bypassing DFPAL. Applications can take advantage of the fastest decimal floating point arithmetic using compile native decimal floating (as compared to the compiler native decimal floating point, all arithmetic operations have function call overhead with DFPAL). To be able to use this switch, application must use `decNN...()` macros rather than `decimalNN...()` functions (`decNN...()` directly map to either `decimalNN...()` function call or equivalent compiler native decimal floating point operation).

AIX build instruction

On AIX, the XLC compiler is required to activate hardware decimal floating point. The following guidelines will ensure a successful compile process. A working sample Makefile is also included in the DFPAL package.

XLC front-end xlc_r is recommended when building DFPAL for multi-threaded environment.
Must use –qlongdouble flag to direct 128-bit word length for long double datatype, internally used by DFPAL.
Remaining application code can be compiled with a different XLC front-end driver and does not have to use –qlongdouble flag. There shall be no linking or runtime problems mixing such object codes.
DFPAL is not tested with compiler optimization level higher than -O2 on AIX, with XLC compiler.
Must use -qflttrap flag to enable floating point exception traps if application is using floating point exception traps (not a common practice). This flag is not recommended if application does not rely on the floating point exception traps.

Following is sample XLC command line on AIX (assumes application does not use floating point exception traps; add -qflttrap flag to following command, otherwise).

xlc_r -c –q64 -O2 -DDFPAL_THREAD_SAFE -DDFPAL_OS_AIX5L -q64 -qlongdouble qflttrap -qlanglvl=stdc99 -I ../decNumber  -I . dfpal.c

Linux on Power build instruction

On Linux on Power, either IBM XLC or GCC compiler can be used to activate and enable hardware decimal floating point support. The following guidelines will ensure a successful compile process. Working sample Makefiles (for use with IBM XLC and GCC) are also included in the DFPAL package.

Must use -mlong-double-128 flag to direct 128-bit word length for long double datatype, internally used by DFPAL.
DFPAL is not tested with compiler optimization level higher than -O3 for GCC and -O for IBM XLC on Linux on Power.

Following is sample GCC command line on Linux on Power.

gcc -c -m64 -mlong-double-128 -O3 -DDFPAL_THREAD_SAFE -DDFPAL_OS_LOP -DDFPAL_INTEGER64_LITERAL_LL -I ../decNumber  -I . dfpal.c

Unix build instruction

Following is an example of typical command line for other Unix platforms (assumes literal designator is L).

cc -c -DDFPAL_THREAD_SAFE -DDFPAL_NO_HW_DFP -DDFPAL_INTEGER64_LITERAL_L -I ../decNumber -I . dfpal.c

Windows build instructions

Following is typical command line using Microsoft compiler. A working sample Makefile is also included in the DFPAL package.

cl -c -DDFPAL_THREAD_SAFE -DDFPAL_NO_HW_DFP -DDFPAL_LOCAL_INTTYPES -DDFPAL_INTEGER64_LITERAL_i64 -DDFPAL_STANDALONE_DLL -I ../decNumber -I . dfpal.c

[previous | contents | next]

DFPAL is authored by Punit Shah (punit@us.ibm.com).
Please send any corrections, comments or questions to dfpal-l@austin.ibm.com.

This page was updated on 21 Dec 2007.