<< " border=0>

> " border=0>

8 Libraries

• 8.1 Libraries and Startup Routines
• 8.2 Using builtin Math Functions in C/C++
• 8.3 Creating and Using Shared Object Files on UNIX
• 8.4 Creating and Using DLLs on Win32
• 8.5 Using LIB3F on Win32
• 8.6 LAPACK, the BLAS and FFTs
• 8.7 The C++ Standard Template Library

This chapter discusses issues related to PGI-supplied compiler libraries, objects, and startup routines. It also addresses the use of C/C++ builtin functions in place of the corresponding libc routines, and creation of dynamically linked libraries (also known as shared objects or shared libraries on UNIX systems), and math libraries.

8.1 Libraries and Startup Routines

The following startup routines, function libraries, object files and source files are provided with the PGI compilers:

crt1.o

Startup routine for the compilation environment.

crti.o

Startup routine for the compilation environment.

crtn.o

Startup routine for the compilation environment.

f90alt.o

Fortran 90 alternate logical support routine - linked in when -Munixlogical is specified on the command line

f90main.o

Fortran 90 startup routine

init_pgpf.o

Profiler initialization routine.

initmp.o

Parallel execution environment startup routine.

libblas.a

The public domain BLAS math library.

libC.a

C++ runtime library.

liblapack.a

The public domain LAPACK math library.

libpgc.a

C support library.

libpgf90.a

Fortran 90 support library

libpgf902.a

Fortran 90 support library

libpgf90_prof.a

Fortran 90 profiling support library

libpgf90_rpm.a

Fortran 90 runtime library

libpgf90_rpm1.a

Fortran 90 runtime library

libpgf90_rpm1_p.a

Fortran 90 runtime library

libpgf90rtl.a

Fortran 90 runtime library

libpgftnrtl.a

FORTRAN 77 support library

libpgmp.a

Parallel support library

libpgnod_prof.a

Profiling support library

libpgthread.a

Parallel threads library (Linux only)

libstd.a

C++ Standard library

libstrm.a

C++ Streams library

pgfalt.o

FORTRAN 77 alternate logical support routine - linked in when -Munixlogical is specified on the command line

pgfi8st.o

Support routine for I*8 storage option

pgfmain.o

FORTRAN 77 startup routine

subchk.o

Object file containing routines that handle bounds checking

8.2 Using builtin Math Functions in C/C++

The name of the math header file is math.h. Include the math header file in all of your source files that use a math library routine as in the following example, which calculates the inverse cosine of [pi]/3.

#include <math.h>
#define PI 3.1415926535
main()
{
   double x, y;
   x = PI/3.0;
   y = acos(x);
}

Including math.h will cause PGCC C and C++ to use builtin functions, which are much more efficient than library calls. In particular, the following intrinsics calls will be processed using builtins if you include math.h:

8.3 Creating and Using Shared Object Files on UNIX

All of the PGI Fortran, C, and C++ compilers support creation of shared object files. Unlike statically linked object and library files, shared object files link and resolve references with an executable at runtime via a dynamic linker supplied with your operating system. The PGI compilers must generate position independent code to support creation of shared objects by the linker. This is not the default, so you must use the steps that follow to create object files with position independent code and shared object files which are to include them. The paragraphs that follow describe how to create and use a shared object file.

To create an object file with position independent code, compile it with the appropriate PGI compiler using the -fpic option (the -fPIC, -Kpic, and -KPIC options are supported for compatibility with other systems you may have used, and are equivalent to-fpic). For example, use the following command to create an object file with position independent code using pgf90:

% pgf90 -c -fpic tobeshared.f

To produce a shared object file, use the appropriate PGI compiler to invoke the linker supplied with your system. It is customary to name such files using a .so filename extension. On Linux, this is done by passing the -shared option to the linker:

% pgf90 -shared -o tobeshared.so tobeshared.o

while on Solaris86 it's done by passing the -G option to the linker:

% pgf90 -G -o tobeshared.so tobeshared.o

Note that compilation and generation of the shared object can be performed in one step using both the -fpic option and the appropriate option for generation of a shared object file.

To use a shared object file, compile and link the program which will reference functions or subroutines in the shared object file using the appropriate PGI compiler and listing the shared object on the link line:

% pgf90 -o myprog myprof.f tobeshared.so

You now have an executable myprog which does not include any code from functions or subroutines in tobeshared.so, but which can be executed and dynamically linked to that code. By default, when the program is linked to produce myprog, no assumptions are made on the location of tobeshared.so. In order for myprog to execute correctly, you must initialize the environment variable LD_LIBRARY_PATH to include the directory containing tobeshared.so. If LD_LIBRARY_PATH is already initialized, it is important not to overwrite its contents. Assuming you have placed tobeshared.so in a directory /home/myusername/bin, you can initialize LD_LIBRARY_PATH to include that directory and preserve its existing contents as follows:

% setenv LD_LIBRARY_PATH "$LD_LIBRARY_PATH":/home/myusername/bin

If you know that tobeshared.so will always reside in a specific directory, you can create the executable myprog in a form that assumes this using the -R link-time option. For example, you can link as follows:

% pgf90 -o myprog myprof.f tobeshared.so -R/home/myusername/bin

Note that there is no space between -R and the directory name. As with the -L option, no space can be present. If the -R option is used, it is not necessary to initialize LD_LIBRARY_PATH. In the example above, the dynamic linker will always look in /home/myusername/bin to resolve references to tobeshared.so. By default, if the LD_LIBRARY_PATH environment variable is not set, the linker will only search /usr/lib for shared objects.

The UNIX command ldd is a useful tool when working with shared object files and executables which reference them. When applied to an executable as follows:

% ldd myprog 

ldd lists all shared object files referenced in the executable along with the pathname of the directory from which they will be extracted. If the pathname is not hard-coded using the -R option, and if LD_LIBRARY_PATH is not initialized, the pathname is listed as "not found". See the online man page for ldd for more information on options and usage.

NOTE: The PGCC C and C++ compilers for Solaris86 do not automatically pass the -z text or -z { defs | nodefs} options to ld. If needed, those options must be passed explicitly. You can see the options passed to ld by the pgcc and pgCC drivers by invoking either with the -v or -dryrun options.

8.4 Creating and Using DLLs on Win32

To create dynamically linked libraries (DLLs) using the PGI compilers for Win32, you must use the utilities dlltool and dllwrap which are included as part of the PGI Workstation for Win32 command environment. Here are the steps in the process.

Step 1 - Use dlltool to create a .def file from the object file(s) you wish to have included in the DLL. Th .def file includes entry points and intermediate code for all of the functions/subroutines in the DLL. This intermediate code replaces the actual objects in an executable that references the DLL, and causes the objects to be loaded from the static .a library file at runtime. Only the objects that are to be included in the DLL are entered here.

To create a DLL from the object code in files object1.o and object2.o, create a file obj12.def as follows:

    % dlltool --export-all --output-def obj12.def \
    object1.o object2.o

Step 2 - Create the intermediate DLL file using dllwrap. This step requires a complete linking of the objects declared previously, ensuring that any DLL entries referenced in the target DLLs have all of their symbols resolved by the linker (the resolved symbols can also be DLLs).

Assuming the objects object1.o and object2.o are compiled by PGF90, do the following to create obj12.dll from the objects and the required PGF90 libraries:

    % dllwrap  --def obj12.def  -o obj12.dll \
    --driver-name pgcc  object1.o object2.o \
    -L. -dll -cyglibs -lpgf90 -lpgf90_rpm1 -lpgf902 \
    -lpgf90rtl -lpgftnrtl

If the objects are compiled using PGF77, you need only include the reference to -lpgftnrtl (i.e. you can omit the references to -lpgf90, -lpgf90_rpm1, -lpgf902 and -lpgf90rtl. If the objects are compiled using PGCC, you need not include any of the PGI Fortran runtime library references.

The dllwrap command creates a series of commands to send to the linker, among which is -nostartfiles, which directs pgcc to not load various startup files into the list of object files sent to the linker.

Step 3 - Use dlltool again to create the libobj12dll.a library file from obj12.dll and obj12.def.

% dlltool --dllname obj12.dll --def obj12.def  \
    --output-lib libobj12dll.a

As an example, consider the following source files, object1.f:

      subroutine subf1 (n)
      integer n
      n=1
      print *,"n=",n
      return
      end

and object2.f:

      function funf2 ()
      real funf2
      funf2 = 2.0
      return
      end

and prog.f:

      program test
      external subf1
      real funf2, val
      integer n
      call subf1(n)
      val = funf2()
      write (*,*) 'val = ', val
      stop
      end

Create the DLL libobj12dll.a using the steps above. To create the test program using libobj12dll.a, do the following:

    % pgf90 -o test prog.f -L. -lobj12dll

should you wish to change libobj12dll.a without changing the subroutine or function interfaces, no rebuilding of test is necessary. Just recreate libobj12dll.a, and it will be loaded at runtime.

8.5 Using LIB3F on Win32

Previous releases of the PGI Fortran compilers on Win32 required special compiler options or include statements for program units using LIB3F routines. LIB3F is now supported on Win32 by default, without the need for specific steps taken by the programmer. See the PGF77 Workstation Reference Manual for further information on the contents of LIB3F.

8.6 LAPACK, the BLAS and FFTs

Pre-compiled versions of the public domain LAPACK and BLAS libraries are included with the PGI compilers on UNIX and Win32 systems in the files $PGI/<target>/lib/lapack.a and $PGI/<target>/lib/blas.a respectively, where <target> is replaced with the appropriate target name (linux86, solaris86, or nt86).

To use these libraries, simply link them in using the -l option when linking your main program:

% pgf90 myprog.f -lblas -llapack

Highly optimized assembly-coded versions of the BLAS and certain FFT routines may be available for your platform. In some cases these are shipped with the PGI compilers. See the current release notes for the PGI compilers you are using to determine if these optimized libraries exist, from where they can be downloaded (if necessary), and how to incorporate them into your installation as the default.

8.7 The C++ Standard Template Library

The PGCC C++ compiler includes a bundled copy of the Standard C++ Library from Rogue Wave Software. See the online Standard C++ Library tutorial and reference manual from Rogue Wave Software for further details. The version of the Rogue Wave Standard Template Library included with PGCC C++ requires that the header files be encrypted, so you won't be able to read them.

<< " border=0>

> " border=0>