To compile a source program, use one of the xlf90, xlf90_r, f90, xlf95, xlf95_r, f95, xlf2003, xlf2003_r, f2003, xlf, xlf_r, f77, or fort77 commands, which have the form:
.----------------------------------. V | >>-+-xlf90-----+----+--------------+----input_file---+--------->< +-xlf90_r---+ '-cmd_line_opt-' +-f90-------+ +-xlf95-----+ +-xlf95_r---+ +-f95-------+ +-xlf2003---+ +-xlf2003_r-+ +-f2003-----+ +-xlf-------+ +-xlf_r-----+ +-f77-------+ '-fort77----'
These commands all accept essentially the same Fortran language. The main difference is that they use different default options (which you can see by reading the file /etc/opt/ibmcmp/xlf/11.1/xlf.cfg).
The invocation command performs the necessary steps to compile the Fortran source files, assemble any .s files, and link the object files and libraries into an executable program. In particular, the xlf_r, xlf90_r, xlf95_r, and xlf2003_r, commands use the thread-safe components (libraries, and so on) to link and bind object files.
The following table summarizes the invocation commands that you can use:
| Driver Invocation | Path or Location | Chief Functionality | Linked Libraries |
|---|---|---|---|
| xlf90, f90 | /opt/ibmcmp/xlf/11.1/bin | Fortran 90 | libxlf90.so |
| f90 | /opt/ibmcmp/xlf/11.1/bin | Fortran 90 | libxlf90.so |
| xlf90_r | /opt/ibmcmp/xlf/11.1/bin | Threadsafe Fortran 90 | libxlf90_r.so |
| xlf95, f95 | /opt/ibmcmp/xlf/11.1/bin | Fortran 95 | libxlf90.so |
| f95 | /opt/ibmcmp/xlf/11.1/bin | Fortran 95 | libxlf90.so |
| xlf95_r | /opt/ibmcmp/xlf/11.1/bin | Threadsafe Fortran 95 | libxlf90_r.so |
| xlf2003 | /opt/ibmcmp/xlf/11.1/bin | Fortran 2003 | libxlf90.so |
| xlf2003_r | /opt/ibmcmp/xlf/11.1/bin | Threadsafe Fortran 2003 | libxlf90.so |
| f2003 | /opt/ibmcmp/xlf/11.1/bin | Fortran 2003 | libxlf90.so |
| xlf | /opt/ibmcmp/xlf/11.1/bin | FORTRAN 77 | libxlf90.so |
| xlf_r | /opt/ibmcmp/xlf/11.1/bin | Threadsafe FORTRAN 77 | libxlf90_r.so |
| f77 or fort77 | /opt/ibmcmp/xlf/11.1/bin | FORTRAN 77 | libxlf90.so |
The invocation commands have the following implications for directive triggers:
If you specify the -qsmp compiler option, the following occurs:
XL Fortran provides the library libxlf90_t.so, in addition to libxlf90_r.so. The library libxlf90_r.so is a superset of libxlf90_t.so. The file xlf.cfg is set up to link to libxlf90_r.so automatically when you use the xlf90_r, xlf95_r, and xlf_r commands.libxlf90_t.so is a partial thread-support runtime library. It will be installed as /opt/ibmcmp/lib/libxlf90_t.so with one restriction on its use: because routines in the library are not thread-reentrant, only one Fortran thread at a time can perform I/O operations or invoke Fortran intrinsics in a multithreaded application that uses the library. To avoid the thread synchronization overhead in libxlf90_r.so when an application is threaded, you can use libxlf90_t.so in multithreaded applications where there is only one Fortran thread.
When you bind a multithreaded executable with multiple Fortran threads, libxlf90_r.so should be used. Note that using the xlf_r , xlf90_r, xlf95_r, or xlf2003_r invocation command ensures the proper linking.
The f90, xlf90, and xlf90_r commands make your programs conform more closely to the Fortran 90 standard than do the xlf, xlf_r, and f77/fort77 commands. The f95, xlf95, and xlf95_r commands make your programs conform more closely to the Fortran 95 standard than do the xlf, xlf_r, and f77/fort77 commands. f90, xlf90, xlf90_r, f95, xlf95, and xlf95_r are the preferred commands for compiling any new programs. They all accept Fortran 90 free source form by default; to use them for fixed source form, you must use the -qfixed option. I/O formats are slightly different between these commands and the other commands. I/O formats also differ between the set of f90, xlf90 and xlf90_r commands and the set of f95, xlf95 and xlf95_r commands. We recommend that you switch to the Fortran 95 formats for data files whenever possible.
By default, the f90, xlf90 and xlf90_r commands do not conform completely to the Fortran 90 standard. Also, by default, the f95, xlf95 and xlf95_r commands do not conform completely to the Fortran 95 standard. If you need full Fortran 90 or Fortran 95 compliance, compile with any of the following additional compiler options (and suboptions):
-qnodirective -qnoescape -qextname -qfloat=nomaf:nofold -qnoswapomp
-qlanglvl=90std
-qlanglvl=95stdAlso, specify the following runtime options before running the program, with a command similar to one of the following:
export XLFRTEOPTS="err_recovery=no:langlvl=90std" export XLFRTEOPTS="err_recovery=no:langlvl=95std"
The default settings are intended to provide the best combination of performance and usability. Therefore, it is usually a good idea to change them only when required. Some of the options above are only required for compliance in very specific situations. For example, you only need to specify -qextname when an external symbol, such as a common block or subprogram, is named main.
The f2003, xlf2003, and xlf2003_r commands make your programs conform more closely to the Fortran 2003 Standard than do the xlf or xlf_r commands. The Fortran 2003 commands accept free source form by default. I/O formats for the Fortran 2003 commands are the same as for the f95, xlf95, and xlf95_r commands. The Fortran 2003 commands format infinity and NaN floating-point values differently from previous commands.
By default, the f2003, xlf2003, and xlf2003_r commands do not conform completely to the Fortran 2003 standard. If you need full compliance, compile with the following additional compiler suboptions:
-qlanglvl=2003std -qnodirective -qnoescape -qextname -qfloat=nomaf:rndsngl:nofold -qnoswapomp -qstrictieeemod
Also specify the following runtime options:
XLFRTEOPTS="err_recovery=no:langlvl=2003std:iostat_end=2003std:internal_nldelim=2003std"
You can use the xlf_r, xlf90_r, xlf95_r, or xlf2003_r command to compile XL Fortran SMP programs. The xlf_r command is similar to the xlf command; the xlf90_r command is similar to the xlf90 command; the xlf95_r command is similar to the xlf95 command; the xlf2003_r command is similar to the xlf2003 command. The main difference is that the thread-safe components are used to link and bind the object files if you specify the xlf_r, xlf90_r, xlf95_r, or xlf2003_r command.
Note that using any of these commands alone does not imply parallelization. For the compiler to recognize the SMP directives and activate parallelization, you must also specify -qsmp. In turn, you can only specify the -qsmp option in conjunction with one of these six invocation commands. When you specify -qsmp, the driver links in the libraries specified on the smplibraries line in the active stanza of the configuration file.
XL Fortran supports thread programming with the IEEE 1003.1-2001 (POSIX) standard pthreads API.
To compile and then link your program with the standard interface libraries, use the xlf_r, xlf90_r, xlf95_r, or xlf2003_r command. For example, you could specify:
xlf95_r test.f
If you have a program unit, subprogram, or interface body that uses a module, you must first compile the module. If the module and the code that uses the module are in separate files, you must first compile the file that contains the module. If they are in the same file, the module must come before the code that uses it in the file. If you change any entity in a module, you must recompile any files that use that module.
To stop the compiler before it finishes compiling, press Ctrl+C in interactive mode, or use the kill command.
The input files to the compiler are:
Include files also contain source and often have different suffixes from .f.
The fsuffix and cppsuffix attributes in Editing the default configuration file and the -qsuffix let you select a different suffix.
The osuffix attribute, which is described in Editing the default configuration file and the -qsuffix, lets you select a different suffix.
The default configuration file is /etc/opt/ibmcmp/xlf/11.1/xlf.cfg.
The -qpdf1 option produces runtime profile information for use in subsequent compilations. This information is stored in one or more hidden files with names that match the pattern ".*pdf*".
The output files that XL Fortran produces are:
You can specify compiler options in any of three locations. Their scope and precedence are defined by the location you use. (XL Fortran also has comment directives, such as SOURCEFORM, that can specify option settings. There is no general rule about the scope and precedence of such directives.)
| Location | Scope | Precedence |
|---|---|---|
| In a stanza of the configuration file. | All compilation units in all files compiled with that stanza in effect. | Lowest |
| On the command line. | All compilation units in all files compiled with that command. | Medium |
|
In an @PROCESS directive. (XL Fortran also has comment directives, such as SOURCEFORM, that can specify option settings. There is no general rule about the scope and precedence of such directives.) |
The following compilation unit. | Highest |
If you specify an option more than once with different settings, the last setting generally takes effect. Any exceptions are noted in the individual descriptions in the Detailed descriptions of the XL Fortran compiler options and are indexed under "conflicting options".
XL Fortran supports the traditional UNIX® method of specifying command-line options, with one or more letters (known as flags) following a minus sign:
xlf95 -c file.f
You can often concatenate multiple flags or specify them individually:
xlf95 -cv file.f # These forms xlf95 -c -v file.f # are equivalent
(There are some exceptions, such as -pg, which is a single option and not the same as -p -g.)
Some of the flags require additional argument strings. Again, XL Fortran is flexible in interpreting them; you can concatenate multiple flags as long as the flag with an argument appears at the end. The following example shows how you can specify flags:
# All of these commands are equivalent. xlf95 -g -v -o montecarlo -p montecarlo.f xlf95 montecarlo.f -g -v -o montecarlo -p xlf95 -g -v montecarlo.f -o montecarlo -p xlf95 -g -v -omontecarlo -p montecarlo.f # Because -o takes a blank-delimited argument, # the -p cannot be concatenated. xlf95 -gvomontecarlo -p montecarlo.f # Unless we switch the order. xlf95 -gvpomontecarlo montecarlo.f
If you are familiar with other compilers, particularly those in the XL family of compilers, you may already be familiar with many of these flags.
You can also specify many command-line options in a form that is intended to be easy to remember and make compilation scripts and makefiles relatively self-explanatory:
This format is more restrictive about the placement of blanks; you must separate individual -q options by blanks, and there must be no blank between a -q option and a following argument string. Unlike the names of flag options, -q option names are not case-sensitive except that the q must be lowercase. Use an equal sign to separate a -q option from any arguments it requires, and use colons to separate suboptions within the argument string.
For example:
xlf95 -qddim -qXREF=full -qfloat=nomaf:rsqrt -O3 -qcache=type=c:level=1 file.f
By putting the @PROCESS compiler directive in the source file, you can specify compiler options to affect an individual compilation unit. The @PROCESS compiler directive can override options specified in the configuration file, in the default settings, or on the command line.
In fixed source form, @PROCESS can start in column 1 or after column 6. In free source form, the @PROCESS compiler directive can start in any column.
You cannot place a statement label or inline comment on the same line as an @PROCESS compiler directive.
By default, option settings you designate with the @PROCESS compiler directive are effective only for the compilation unit in which the statement appears. If the file has more than one compilation unit, the option setting is reset to its original state before the next unit is compiled. Trigger constants specified by the DIRECTIVE option are in effect until the end of the file (or until NODIRECTIVE is processed).
The @PROCESS compiler directive must usually appear before the first statement of a compilation unit. The only exceptions are when specifying SOURCE and NOSOURCE; you can put them in @PROCESS directives anywhere in the compilation unit.
Because the compiler automatically executes other commands, such as ld and as, as needed during compilation, you usually do not need to concern yourself with the options of those commands. If you want to choose options for these individual commands, you can do one of the following:
xlf95 --print-map file.f # --print-map is passed to ld
xlf95 -Wl,--print-map file.f # --print-map is passed to ldIn this example, the ld option --print-map is passed to the linker (which is denoted by the l in the -Wl option) when the linker is executed.
This form is more general than the previous one because it works for the as command and any other commands called during compilation, by using different letters after the -W option.
For example, if you include these lines in the xlf95 stanza of /etc/opt/ibmcmp/xlf/11.1/xlf.cfg:
asopt = "W" ldopt = "M"
and issue this command:
xlf95 -Wa,-Z -Wl,-s -w produces_warnings.s uses_many_symbols.fthe file produces_warnings.s is assembled with the options -W and -Z (issue warnings and produce an object file even if there are compilation errors), and the linker is invoked with the options -s and -M (strip final executable file and produce a load map).
The strings command reads information encoded into some binary files, as follows:
For example to see the information embedded in /opt/ibmcmp/xlf/11.1/exe/xlfentry, issue the following command:
strings /opt/ibmcmp/xlf/11.1/exe/xlfentry | grep "@(#)"
You can use -qarch and -qtune to target your program to instruct the compiler to generate code specific to a particular architecture. This allows the compiler to take advantage of machine-specific instructions that can improve performance. The -qarch option determines the architectures on which the resulting programs can run. The -qtune and -qcache options refine the degree of platform-specific optimization performed.
By default, the -qarch setting produces code using only instructions common to all supported architectures, with resultant settings of -qtune and -qcache that are relatively general. To tune performance for a particular processor set or architecture, you may need to specify different settings for one or more of these options. The natural progression to try is to use -qarch, and then add -qtune, and then add -qcache. Because the defaults for -qarch also affect the defaults for -qtune and -qcache, the -qarch option is often all that is needed.
If the compiling machine is also the target architecture, -qarch=auto will automatically detect the setting for the compiling machine. For more information on this compiler option setting, see -qarch and also -O4 and -O5 under the -O.
If your programs are intended for execution mostly on particular architectures, you may want to add one or more of these options to the configuration file so that they become the default for all compilations.
A common programming practice is to pass files through the C preprocessor (cpp). cpp can include or omit lines from the output file based on user-specified conditions ("conditional compilation"). It can also perform string substitution ("macro expansion").
XL Fortran can use cpp to preprocess a file before compiling it.
To call cpp for a particular file, use a file suffix of .F, .F77, .F90, .F95, or .F03. If you specify the -d option, each .F* file filename.F* is preprocessed into an intermediate file Ffilename.f, which is then compiled. If you do not specify the -d option, the intermediate file name is /tmpdir/F8xxxxxx, where x is an alphanumeric character and tmpdir is the contents of the TMPDIR environment variable or, if you have not specified a value for TMPDIR, /tmp. You can save the intermediate file by specifying the -d compiler option; otherwise, the file is deleted. If you only want to preprocess and do not want to produce object or executable files, specify the -qnoobject option also.
When XL Fortran uses cpp for a file, the preprocessor will emit #line directives unless you also specify the -d option. The #line directive associates code that is created by cpp or any other Fortran source code generator with input code that you create. The preprocessor may cause lines of code to be inserted or deleted. Therefore, the #line directives that it emits can be useful in error reporting and debugging, because they identify the source statements found in the preprocessed code by listing the line numbers that were used in the original source.
The _OPENMP C preprocessor macro can be used to conditionally include code. This macro is defined when the C preprocessor is invoked and when you specify the -qsmp=omp compiler option. An example of using this macro follows:
program par_mat_mul
implicit none
integer(kind=8) ::i,j,nthreads
integer(kind=8),parameter ::N=60
integer(kind=8),dimension(N,N) ::Ai,Bi,Ci
integer(kind=8) ::Sumi
#ifdef _OPENMP
integer omp_get_num_threads
#endif
common/data/ Ai,Bi,Ci
!$OMP threadprivate (/data/)
!$omp parallel
forall(i=1:N,j=1:N) Ai(i,j) = (i-N/2)**2+(j+N/2)
forall(i=1:N,j=1:N) Bi(i,j) = 3-((i/2)+(j-N/2)**2)
!$omp master
#ifdef _OPENMP
nthreads=omp_get_num_threads()
#else
nthreads=8
#endif
!$omp end master
!$omp end parallel
!$OMP parallel default(private),copyin(Ai,Bi),shared(nthreads)
!$omp do
do i=1,nthreads
call imat_mul(Sumi)
enddo
!$omp end do
!$omp end parallel
endSee Conditional Compilation in the Language Elements section for more information on conditional compilation.
To customize cpp preprocessing, the configuration file accepts the attributes cpp, cppsuffix, and cppoptions.
The letter F denotes the C preprocessor with the -t and -W options.
Macro expansion can have unexpected consequences that are difficult to debug, such as modifying a FORMAT statement or making a line longer than 72 characters in fixed source form. Therefore, we recommend using cpp primarily for conditional compilation of Fortran programs. The cpp directives that are most often used for conditional compilation are #if, #ifdef, #ifndef, #elif, #else, and #endif.
Because the compiler does not recognize cpp options other than -I directly on the command line, you must pass them through the -W option. For example, if a program contains #ifdef directives that test the existence of a symbol named LNXV1, you can define that symbol to cpp by compiling with a command like:
xlf95 conditional.F -WF,-DLNXV1
Because Fortran and C differ in their treatment of some sequences of characters, be careful when using /* or */. These might be interpreted as C comment delimiters, possibly causing problems even if they occur inside Fortran comments. Also be careful when using three-character sequences that begin with ?? (which might be interpreted as C trigraphs).
Consider the following example:
program testcase
character a
character*4 word
a = '?'
word(1:2) = '??'
print *, word(1:2)
end program testcase
If the preprocessor matches your character combination with the corresponding trigraph sequence, your output may not be what you expected.
If your code does not require the use of the XL Fortran compiler option -qnoescape, a possible solution is to replace the character string with an escape sequence word(1:2) = '\?\?'. However, if you are using the -qnoescape compiler option, this solution will not work. In this case, you require a cpp that will ignore the trigraph sequence. XL Fortran uses the cpp that is found in /opt/ibmcmp/xlf/11.1/exe/cpp. It is ISO C compliant and therefore recognizes trigraph sequences.