ranlib command. STMicroelectronics PGI

Chapter 9. Creating and Using Libraries

Where:

• The first argument must be a command line switch, and the leading dash on the first option is optional.

• The single character options, such as

–d

and

–v

, may be combined into a single option, as

–dv

.

Thus, ar dv

, ar -dv, and ar -d -v

all mean the same thing.

• The first non-switch argument must be the library name.

• One (and only one) of

–d

,

–r

,

–t

, or

–x

must appear on the command line.

Options

The options available for the ar

command are these:

–c

This switch is for compatibility; it is ignored.

–d

Deletes the named object files from the library.

–r

Replaces in or adds the named object files to the library.

–t

Writes a table of contents of the library to standard out.

–v

Writes a verbose file-by-file description of the making of the new library to standard out.

–x

Extracts the named files by copying them into the current directory.

ranlib command

The ranlib

command is a wrapper that allows use of legacy scripts and makefiles that use the ranlib command. The command actually does nothing; it merely exists for compatibility.

Syntax:

The syntax for the ranlib

command is this: ranlib [options] [archive]

Options

The options available for the ranlib

command are these:

–help

Short help information is printed out.

–V

Version information is printed out.

121

Creating and Using Dynamic-Link Libraries on Windows

Creating and Using Dynamic-Link Libraries on Windows

There are several differences between static and dynamic-link libraries on Windows. Libraries of either type are used when resolving external references for linking an executable, but the process differs for each type of library. When linking with a static library, the code needed from the library is incorporated into the executable.

When linking with a DLL, external references are resolved using the DLL's import library, not the DLL itself. The code in the DLL associated with the external references does not become a part of the executable. The DLL is loaded when the executable that needs it is run. For the DLL to be loaded in this manner, the DLL must be in your path.

Static libraries and DLLs also handle global data differently. Global data in static libraries is automatically accessible to other objects linked into an executable. Global data in a DLL can only be accessed from outside the DLL if the DLL exports the data and the image that uses the data imports it.

To access global data, the C compilers support the Microsoft storage class extensions:

__declspec

( dllimport

) and

__declspec

( dllexport

). These extensions may appear as storage class modifiers and enable functions and data to be imported and exported: extern int __declspec(dllimport) intfunc(); float __declspec(dllexport) fdata;

The PGI Fortran compilers support the DEC$ ATTRIBUTES extensions

DLLIMPORT

and

DLLEXPORT

: cDEC$ ATTRIBUTES DLLEXPORT :: object [,object] ...

cDEC$ ATTRIBUTES DLLIMPORT :: object [,object] ...

Here

c

is one of C, c, !, or *. object

is the name of the subprogram or common block that is exported or imported. Further, common block names are enclosed within slashes (/), as shown here: cDEC$ ATTRIBUTES DLLIMPORT :: intfunc

!DEC$ ATTRIBUTES DLLEXPORT :: /fdata/

For more information on these extensions, refer to “!DEC$ Directives,” on page 113

.

The examples in this section further illustrate the use of these extensions.

To create a DLL from the command line, use the

–Mmakedll

option.

The following switches apply to making and using DLLs with the PGI compilers:

–Bdynamic

Compile for and link to the DLL version of the PGI runtime libraries. This flag is required when linking with any DLL built by the PGI compilers. This flag corresponds to the

/MD

flag used by Microsoft’s cl compilers.

When you use the PGI compiler flag

–Bdynamic

to create an executable that links to the DLL form of the runtime, the executable built is smaller than one built without

–Bdynamic

. The PGI runtime DLLs, however, must be available on the system where the executable is run. You must use the

–Bdynamic

flag when linking an executable against a DLL built by the PGI compilers.

–Bstatic

Compile for and link to the static version of the PGI runtime libraries. This flag corresponds to the

/MT flag used by Microsoft’s cl

compilers.

122

Chapter 9. Creating and Using Libraries

On Windows, you must use

–Bstatic

for both compiling and linking.

–Mmakedll

Generate a dynamic-link library or DLL. Implies

–Bdynamic

.

–Mmakeimplib

Generate an import library without generating a DLL. Use this flag when you want to generate an import library for a DLL but are not yet ready to build the DLL itself. This situation might arise, for example, when

building DLLs with mutual imports, as shown in Example 9.4, “Build DLLs Containing Mutual Imports:

Fortran,” on page 127

.

–o <file>

Passed to the linker. Name the DLL or import library <file>.

–def <file>

When used with

–Mmakedll

, this flag is passed to the linker and a

.def

file named <file> is generated for the DLL. The

.def

file contains the symbols exported by the DLL. Generating a

.def

file is not required when building a DLL but can be a useful debugging tool if the DLL does not contain the symbols that you expect it to contain.

When used with

–Mmakeimplib

, this flag is passed to lib

which requires a

.def

file to create an import library. The

.def

file can be empty if the list of symbols to export are passed to lib

on the command line or explicitly marked as

DLLEXPORT

in the source code.

–implib <file>

Passed to the colinker. Generate an import library named <file> for the DLL. A DLL’s import library is the interface used when linking an executable that depends on routines in a DLL.

To use the PGI compilers to create an executable that links to the DLL form of the runtime, use the compiler flag

–Bdynamic

. The executable built will be smaller than one built without

–Bdynamic

; the PGI runtime

DLLs, however, must be available on the system where the executable is run. The

–Bdynamic

flag must be used when an executable is linked against a DLL built by the PGI compilers.

The following examples outline how to use

–Bdynamic

,

–Mmakedll

and

–Mmakeimplib

to build and use

DLLs with the PGI compilers.

Example 9.1. Build a DLL: Fortran

This example builds a DLL from a single source file,

object1.f

, which exports data and a subroutine using

DLLEXPORT

. The source file, prog1.f

, uses

DLLIMPORT

to import the data and subroutine from the DLL.

object1.f

subroutine sub1(i)

!DEC$ ATTRIBUTES DLLEXPORT :: sub1

integer i

common /acommon/ adata

integer adata

!DEC$ ATTRIBUTES DLLEXPORT :: /acommon/

print *, "sub1 adata", adata

print *, "sub1 i ", i

adata = i

end

123

Creating and Using Dynamic-Link Libraries on Windows

124 prog1.f

program prog1

common /acommon/ adata

integer adata

external sub1

!DEC$ ATTRIBUTES DLLIMPORT:: sub1, /acommon/

adata = 11

call sub1(12)

print *, "main adata", adata

end

Step 1: Create the DLL obj1.dll

and its import library obj1.lib

using the following series of commands:

% pgf95 -Bdynamic -c object1.f

% pgf95 -Mmakedll object1.obj -o obj1.dll

Step 2: Compile the main program:

% pgf95 -Bdynamic -o prog1 prog1.f -defaultlib:obj1

The

–Bdynamic

and

–Mmakedll

switches cause the compiler to link against the PGI runtime DLLs instead of the PGI runtime static libraries. The

–Bdynamic

switch is required when linking against any PGI-compiled

DLL, such as obj1.dll

. The -defaultlib: switch specifies that obj1.lib

, the DLL’s import library, should be used to resolve imports.

Step 3: Ensure that obj1.dll

is in your path, then run the executable prog1

to determine if the DLL was successfully created and linked:

% prog1 sub1 adata 11 sub1 i 12 main adata 12

Should you wish to change obj1.dll

without changing the subroutine or function interfaces, no rebuilding of prog1

is necessary. Just recreate obj1.dll

and the new obj1.dll

is loaded at runtime.

Example 9.2. Build a DLL: C

In this example, we build a DLL out of a single source file, object2.c

, which exports data and a subroutine using

__declspec

( dllexport

). The main source file, prog2.c

, uses

__declspec

( dllimport

) to import the data and subroutine from the DLL.

object2.c

int __declspec(dllexport) data; void __declspec(dllexport) func2(int i)

{

printf("func2: data == %d\n", data);

printf("func2: i == %d\n", i);

data = i;

} prog2.c

int __declspec(dllimport) data;

Chapter 9. Creating and Using Libraries void __declspec(dllimport) func2(int); int main()

{

data = 11;

func2(12);

printf("main: data == %d\n",data);

return 0;

}

Step 1: Create the DLL obj2.dll

and its import library obj2.lib

using the following series of commands:

% pgcc -Bdynamic -c object2.c

% pgcc -Mmakedll object2.obj -o obj2.dll

Step 2: Compile the main program:

% pgcc -Bdynamic -o prog2 prog2.c -defaultlib:obj2

The

–Bdynamic

switch causes the compiler to link against the PGI runtime DLLs instead of the PGI runtime static libraries. The

–Bdynamic

switch is required when linking against any PGI-compiled DLL such as obj2.dll

. The

#defaultlib:

switch specifies that obj2.lib

, the DLL’s import library, should be used to resolve the imported data and subroutine in prog2.c

.

Step 3: Ensure that obj2.dll

is in your path, then run the executable prog2

to determine if the DLL was successfully created and linked:

% prog2 func2: data == 11 func2: i == 12 main: data == 12

Should you wish to change obj2.dll

without changing the subroutine or function interfaces, no rebuilding of prog2

is necessary. Just recreate obj2.dll

and the new obj2.dll

is loaded at runtime.

Example 9.3. Build DLLs Containing Circular Mutual Imports: C

In this example we build two DLLs, obj3.dll

and obj4.dll

, each of which imports a routine that is exported by the other. To link the first DLL, the import library for the second DLL must be available. Usually an import library is created when a DLL is linked. In this case, however, the second DLL cannot be linked without the import library for the first DLL. When such circular imports exist, an import library for one of the DLLs must be created in a separate step without creating the DLL. The PGI drivers call the Microsoft lib

tool to create import libraries in this situation. Once the DLLs are built, we can use them to build the main program.

/* object3.c */

void __declspec(dllimport) func_4b(void);

void __declspec(dllexport)

func_3a(void)

{

printf("func_3a, calling a routine in obj4.dll\n");

func_4b();

}

void __declspec(dllexport)

func_3b(void)

{

printf("func_3b\n");

}

125

Creating and Using Dynamic-Link Libraries on Windows

126

/* object4.c */

void __declspec(dllimport) func_3b(void);

void __declspec(dllexport)

func_4a(void)

{

printf("func_4a, calling a routine in obj3.dll\n");

func_3b();

}

void __declspec(dllexport)

func_4b(void)

{

printf("func_4b\n");

}

/* prog3.c */

void __declspec(dllimport) func_3a(void);

void __declspec(dllimport) func_4a(void);

int

main()

{

func_3a();

func_4a();

return 0;

}

Step 1: Use

–Mmakeimplib

with the PGI compilers to build an import library for the first DLL without building the DLL itself.

% pgcc -Bdynamic -c object3.c

% pgcc -Mmakeimplib -o obj3.lib object3.obj

Tip

The

–def=<deffile>

option can also be used with

–Mmakeimplib

. Use a

.def

file when you need to export additional symbols from the DLL. A

.def

file is not needed in this example because all symbols are exported using

__declspec

( dllexport

).

Step 2: Use the import library, obj3.lib

, created in Step 1, to link the second DLL.

% pgcc -Bdynamic -c object4.c

% pgcc -Mmakedll -o obj4.dll object4.obj -defaultlib:obj3

Step 3: Use the import library, obj4.lib

, created in Step 2, to link the first DLL.

% pgcc -Mmakedll -o obj3.dll object3.obj -defaultlib:obj4

Step 4: Compile the main program and link against the import libraries for the two DLLs.

% pgcc -Bdynamic prog3.c -o prog3 -defaultlib:obj3 -defaultlib:obj4

Step 5: Execute prog3.exe

to ensure that the DLLs were create properly.

% prog3 func_3a, calling a routine in obj4.dll

func_4b func_4a, calling a routine in obj3.dll

func_3b

Chapter 9. Creating and Using Libraries

Example 9.4. Build DLLs Containing Mutual Imports: Fortran

In this example we build two DLLs when each DLL is dependent on the other, and use them to build the main program.

In the following source files, object2.f95

makes calls to routines defined in object3.f95

, and vice versa. This situation of mutual imports requires two steps to build each DLL.

To link the first DLL, the import library for the second DLL must be available. Usually an import library is created when a DLL is linked. In this case, however, the second DLL cannot be linked without the import library for the first DLL. When such circular imports exist, an import library for one of the DLLs must be created in a separate step without creating the DLL. The PGI drivers call the Microsoft lib

tool to create import libraries in this situation.

Once the DLLs are built, we can use them to build the main program.

object2.f95

subroutine func_2a

external func_3b

!DEC$ ATTRIBUTES DLLEXPORT :: func_2a

!DEC$ ATTRIBUTES DLLIMPORT :: func_3b

print*,"func_2a, calling a routine in obj3.dll"

call func_3b()

end subroutine

subroutine func_2b

!DEC$ ATTRIBUTES DLLEXPORT :: func_2b

print*,"func_2b"

end subroutine object3.f95

subroutine func_3a

external func_2b

!DEC$ ATTRIBUTES DLLEXPORT :: func_3a

!DEC$ ATTRIBUTES DLLIMPORT :: func_2b

print*,"func_3a, calling a routine in obj2.dll"

call func_2b()

end subroutine

subroutine func_3b

!DEC$ ATTRIBUTES DLLEXPORT :: func_3b

print*,"func_3b"

end subroutine prog2.f95

program prog2

external func_2a

external func_3a

!DEC$ ATTRIBUTES DLLIMPORT :: func_2a

!DEC$ ATTRIBUTES DLLIMPORT :: func_3a

call func_2a()

call func_3a()

end program

Step 1: Use

–Mmakeimplib

with the PGI compilers to build an import library for the first DLL without building the DLL itself.

127

Creating and Using Dynamic-Link Libraries on Windows

128

% pgf95 -Bdynamic -c object2.f95

% pgf95 -Mmakeimplib -o obj2.lib object2.obj

Tip

The

-def=<deffile>

option can also be used with

–Mmakeimplib

. Use a

.def

file when you need to export additional symbols from the DLL. A

.def

file is not needed in this example because all symbols are exported using

DLLEXPORT

.

Step 2: Use the import library, obj2.lib

, created in Step 1, to link the second DLL.

% pgf95 -Bdynamic -c object3.f95

% pgf95 -Mmakedll -o obj3.dll object3.obj -defaultlib:obj2

Step 3: Use the import library, obj3.lib

, created in Step 2, to link the first DLL.

% pgf95 -Mmakedll -o obj2.dll object2.obj -defaultlib:obj3

Step 4: Compile the main program and link against the import libraries for the two DLLs.

% pgf95 -Bdynamic prog2.f95 -o prog2 -defaultlib:obj2 -defaultlib:obj3

Step 5: Execute prog2

to ensure that the DLLs were created properly:

% prog2 func_2a, calling a routine in obj3.dll

func_3b func_3a, calling a routine in obj2.dll

func_2b

Example 9.5. Import a Fortran module from a DLL

In this example we import a Fortran module from a DLL. We use the source file defmod.f90

to create a DLL containing a Fortran module. We then use the source file use_mod.f90

to build a program that imports and uses the Fortran module from defmod.f90

.

defmod.f90

module testm

type a_type

integer :: an_int

end type a_type

type(a_type) :: a, b

!DEC$ ATTRIBUTES DLLEXPORT :: a,b

contains

subroutine print_a

!DEC$ ATTRIBUTES DLLEXPORT :: print_a

write(*,*) a%an_int

end subroutine

subroutine print_b

!DEC$ ATTRIBUTES DLLEXPORT :: print_b

write(*,*) b%an_int

end subroutine end module usemod.f90

use testm

a%an_int = 1

b%an_int = 2

Chapter 9. Creating and Using Libraries

call print_a

call print_b end

Step 1: Create the DLL.

% pgf90 -Mmakedll -o defmod.dll defmod.f90

Creating library defmod.lib and object defmod.exp

Step 2: Create the exe

and link against the import library for the imported DLL.

% pgf90 -Bdynamic -o usemod usemod.f90 -defaultlib:defmod.lib

Step 3: Run the exe

to ensure that the module was imported from the DLL properly.

% usemod

1

2

Using LIB3F

The PGI Fortran compilers include complete support for the de facto standard LIB3F library routines on both

Linux and Windows operating systems. See the PGI Fortran Reference manual for a complete list of available routines in the PGI implementation of LIB3F.

LAPACK, BLAS and FFTs

Pre-compiled versions of the public domain LAPACK and BLAS libraries are included with the PGI compilers.

The LAPACK library is called liblapack.a

or on Windows, liblapack.lib

. The BLAS library is called libblas.a

or on Windows, libblas.lib

. These libraries are installed to

$PGI/<target>/lib

, where

<target> is replaced with the appropriate target name (linux86, linux86-64, osx86, osx86-64, win32, win64, sfu32, sua32, or sua64).

To use these libraries, simply link them in using the

–l

option when linking your main program:

% pgf95 myprog.f -llapack -lblas

Highly optimized assembly-coded versions of 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, where they can be downloaded (if necessary), and how to incorporate them into your installation as the default.

The C++ Standard Template Library

The PGC++ compiler includes a bundled copy of the STLPort Standard C++ Library. See the online Standard C

++ Library tutorial and reference manual at

www.stlport.com

for further details and licensing.

129

130