[Plplot-cvs] SF.net SVN: plplot:[10672] trunk/bindings

[<arj...@us...>]

Revision: 10672
          http://plplot.svn.sourceforge.net/plplot/?rev=10672&view=rev
Author:   arjenmarkus
Date:     2009-12-03 12:50:44 +0000 (Thu, 03 Dec 2009)

Log Message:
-----------
Description of the linker definition files added

Modified Paths:
--------------
    trunk/bindings/f77/README.f77API
    trunk/bindings/f95/readme_f95.txt

Modified: trunk/bindings/f77/README.f77API
===================================================================
--- trunk/bindings/f77/README.f77API	2009-12-02 20:38:28 UTC (rev 10671)
+++ trunk/bindings/f77/README.f77API	2009-12-03 12:50:44 UTC (rev 10672)
@@ -1,5 +1,5 @@
 The following files work together to define the fortran API for PLplot.
-The general rule is 
+The general rule is
 
 * use sfstubs.fm4 for routines that have character strings;
 
@@ -55,3 +55,36 @@
 
 * scstubs.c contains all the simple (non-3D, non-cont, non-shade) API plus
 some 7-suffix routines that have a special wrapper in sfstubs.f(m4).
+
+
+Linking DLLs on Windows
+-----------------------
+On Windows it is necessary to specify which routines and functions in
+a DLL should be exported, i.e. made visible to external programs. While
+there compiler-specific ways to do that within the source code we prefer
+to do it via so-called linker definition files (.def).
+
+Basically, these files contain a list of all the subroutines and functions
+that need to be exported, one name per line. The difficulty is, however,
+that these names are the names as constructed by the compiler. Each compiler
+is free to use its own scheme for turning the name found in the Fortran code
+into a "linker" name".
+
+For the Compaq Visual Fortran the scheme is this:
+
+subroutine/function Name( a, b ) ==> _NAME@8
+
+where the @8 represents the number of bytes in the argument list (the
+hidden argument representing the length of string arguments must be
+included in that count)
+
+For the MinGW gfortran compiler the scheme is somewhat simpler:
+
+subroutine/function Name( a, b ) ==> name_
+subroutine/function My_Name( a, b ) ==> my_name__
+
+For the Cygwin gfortran compiler all symbols are automatically exported. There
+is no need for a linker definition file.
+
+One way to find out what the internally produced names are is to examine the
+object file (.obj) that is produced by the compiler.

Modified: trunk/bindings/f95/readme_f95.txt
===================================================================
--- trunk/bindings/f95/readme_f95.txt	2009-12-02 20:38:28 UTC (rev 10671)
+++ trunk/bindings/f95/readme_f95.txt	2009-12-03 12:50:44 UTC (rev 10672)
@@ -116,3 +116,77 @@
 
 Method 2 is preferred, as it is most "Fortran 95" in character.
 
+
+
+Linking DLLs on Windows
+-----------------------
+On Windows it is necessary to specify which routines and functions in
+a DLL should be exported, i.e. made visible to external programs. While
+there compiler-specific ways to do that within the source code we prefer
+to do it via so-called linker definition files (.def).
+
+Basically, these files contain a list of all the subroutines and functions
+that need to be exported, one name per line. The difficulty is, however,
+that these names are the names as constructed by the compiler. Each compiler
+is free to use its own scheme for turning the name found in the Fortran code
+into a "linker" name".
+
+For the Compaq Visual Fortran the scheme is this:
+
+subroutine/function Name( a, b ) ==> _NAME@8
+
+   module plplotp
+   contains
+   subroutine/function Name( a, b ) ==> _PLPLOTP_mp_NAME@8
+   end module
+
+where the @8 represents the number of bytes in the argument list (the
+hidden argument representing the length of string arguments must be
+included in that count)
+
+For the MinGW gfortran compiler the scheme is somewhat simpler:
+
+   subroutine/function Name( a, b ) ==> name_
+   subroutine/function My_Name( a, b ) ==> my_name__
+
+   module plplotp
+   contains
+   subroutine/function Name( a, b ) ==> __plplotp_MOD_name
+   subroutine/function My_Name( a, b ) ==> __plplotp_MOD_my_name
+   end module
+
+For the Cygwin gfortran compiler all symbols are automatically exported. There
+is no need for a linker definition file.
+
+One way to find out what the internally produced names are is to examine the
+object file (.obj) that is produced by the compiler.
+
+Notes:
+- The compiler adds the name of the module to the name of the routine
+- The MinGW compiler does not append underscores for routines living
+  in a module, but it does for routines outside a module
+- All routines that are mentioned in an interface block must be exported:
+
+  The four routines in this fragment must all be exported via the
+  linker definition file, even though only the interface name is useable
+  in the Fortran code (the routines themselves are not visible to a
+  Fortran program because of the private clause):
+
+     interface plvect
+        module procedure plvectors_0
+        module procedure plvectors_1
+        module procedure plvectors_2
+        module procedure plvectors_tr
+     end interface
+     private :: plvectors_0, plvectors_1, plvectors_2, plvectors_tr
+
+  So the definition file has these lines:
+
+     __plplotp_MOD_plvectors_0
+     __plplotp_MOD_plvectors_1
+     __plplotp_MOD_plvectors_2
+     __plplotp_MOD_plvectors_tr
+
+  (but no line for the interface name as that is stored in the
+  module intermediate file used by the compiler)
+


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.