| 1 | This is the README for dynamic extension support for GNU awk 3.1.2 under Windows32
|
|---|
| 2 | This part of the README is directed to the gawk maintainers.
|
|---|
| 3 |
|
|---|
| 4 | The implementation consists of
|
|---|
| 5 |
|
|---|
| 6 | pc/dlfcn.h
|
|---|
| 7 | pc/dlfcn.c
|
|---|
| 8 | An implementation of the POSIX dynamic loading functions for Windows32.
|
|---|
| 9 | Bugs and limitations:
|
|---|
| 10 | the RTLD_* flags are ignored
|
|---|
| 11 | passing NULL as the module name is not really supported.
|
|---|
| 12 | dlerror() doesn't always generate useful output.
|
|---|
| 13 |
|
|---|
| 14 | pc/w32dynamic.patch
|
|---|
| 15 | A patch to pc/Makefile. This adds macros to allow dynamic loading
|
|---|
| 16 | to be compiled in. The macros (DYN_EXP, DYN_OBJ, DYN_FLAGS, and
|
|---|
| 17 | DYN_MAKEXP) are commented-out by default (which is the default on
|
|---|
| 18 | Unix as well). I've added definitions only for MS VC and MinGW.
|
|---|
| 19 | I also added support for pgawk under MS VC and MinGW.
|
|---|
| 20 |
|
|---|
| 21 | pc/gawkw32.def
|
|---|
| 22 | A list of functions to export from gawk.exe. Every function used
|
|---|
| 23 | in an extension DLL needs to be in this file. I've added the ones
|
|---|
| 24 | required by the provided examples, but some thought should go into
|
|---|
| 25 | determining a useful set of API functions. From a maintenance
|
|---|
| 26 | perspective, it's important that the ordinals (the number following @)
|
|---|
| 27 | never change. You can use an existing DLL with a gawk.exe which has
|
|---|
| 28 | new exported functions, but if you change the ordinal of an existing
|
|---|
| 29 | function, you have to recompile all the extensions that use it.
|
|---|
| 30 |
|
|---|
| 31 | extension/Makefile.pc
|
|---|
| 32 | A make file which compiles a few of the extension examples.
|
|---|
| 33 | Only readfile, ordchr, and arrayparm are built, since the
|
|---|
| 34 | other functions didn't compile without sizeable modifications.
|
|---|
| 35 |
|
|---|
| 36 | extension/pcext.def
|
|---|
| 37 | A module definition file which exports dlload.
|
|---|
| 38 |
|
|---|
| 39 | extension/w32dynamic.patch
|
|---|
| 40 | A patch to readfile.c to have it open files in binary mode. Without
|
|---|
| 41 | this, the bytes read doesn't always match the file size.
|
|---|
| 42 |
|
|---|
| 43 | w32dynamic.patch
|
|---|
| 44 | A patch to awk.h. This makes the temporary variable _t static and
|
|---|
| 45 | adds an attribute to some data declarations when WIN32_EXTENSION is
|
|---|
| 46 | defined. The issue is that data imported from a separate module has
|
|---|
| 47 | a different level of indirection from the same data in the
|
|---|
| 48 | original module. The difference can be made transparent by adding
|
|---|
| 49 | __declspec(dllimport)) to the declarations used in the importing module.
|
|---|
| 50 | Since _t doesn't actually have to be shared, I've just made it
|
|---|
| 51 | static to the extension module and avoided the problem.
|
|---|
| 52 |
|
|---|
| 53 | README_d/README.pcdynamic
|
|---|
| 54 | This file.
|
|---|
| 55 |
|
|---|
| 56 | The remainder of the file is intended for people installing and using gawk
|
|---|
| 57 | and probably ought to be added to README.pc
|
|---|
| 58 | ---
|
|---|
| 59 | To compile gawk with dynamic extension support, uncomment the
|
|---|
| 60 | definitions of DYN_FLAGS, DYN_EXP, DYN_OBJ, and DYN_MAKEXP in the
|
|---|
| 61 | configuration section of Makefile. There are two definitions for
|
|---|
| 62 | DYN_MAKEXP -- pick the one that matches your target.
|
|---|
| 63 |
|
|---|
| 64 | To build some of the example extension libraries, cd to the extension
|
|---|
| 65 | directory and copy Makefile.pc to Makefile. You can then build using the same
|
|---|
| 66 | two targets. To run the example awk scripts, you'll need to either change the
|
|---|
| 67 | call to the `extension' function to match the name of the library (for
|
|---|
| 68 | instance, change "./ordchr.so" to "ordchr.dll" or simply "ordchr"), or rename
|
|---|
| 69 | the library to match the call (for instance, rename ordchr.dll to ordchr.so).
|
|---|
| 70 |
|
|---|
| 71 | If you build gawk.exe with one compiler but want to build an extension library
|
|---|
| 72 | with the other, you need to copy the import library. Visual C uses a library
|
|---|
| 73 | called gawk.lib, while MinGW uses a library called libgawk.a. These files
|
|---|
| 74 | are equivalent and will interoperate if you give them the correct name.
|
|---|
| 75 | The resulting shared libraries are also interoperable.
|
|---|
| 76 |
|
|---|
| 77 | To create your own extension library, you can use the examples as models, but
|
|---|
| 78 | you're essentially on your own. Post to comp.lang.awk or send e-mail to
|
|---|
| 79 | ptjm@interlog.com if you have problems getting started. If you need to access
|
|---|
| 80 | functions or variables which are not exported by gawk.exe, add them to
|
|---|
| 81 | gawkw32.def and rebuild. You should also add ATTRIBUTE_EXPORTED to the
|
|---|
| 82 | declaration in awk.h of any variables you add to gawkw32.def.
|
|---|
| 83 |
|
|---|
| 84 | Note that extension libraries have the name of the awk executable embedded in
|
|---|
| 85 | them at link time, so they will work only with gawk.exe. In particular, they won't
|
|---|
| 86 | work if you rename gawk.exe to awk.exe or if you try to use pgawk.exe. You can
|
|---|
| 87 | perform profiling by temporarily renaming pgawk.exe to gawk.exe. You can resolve
|
|---|
| 88 | this problem by changing the program name in the definition of DYN_MAKEXP for
|
|---|
| 89 | your compiler.
|
|---|
| 90 |
|
|---|
| 91 | On Windows32, libraries are sought first in the current directory, then in the
|
|---|
| 92 | directory containing gawk.exe, and finally through the PATH environment
|
|---|
| 93 | variable.
|
|---|
