6.29.4 Defining library interfaces

You can give a name to a bunch of C function declarations (a library interface), as follows:

c-library lseek-lib
\c #define _FILE_OFFSET_BITS 64
...
end-c-library

The effect of giving such a name to the interface is that the names of the generated files will contain that name, and when you use the interface a second time, it will use the existing files instead of generating and compiling them again, saving you time. The generated file contains a 128 bit hash (not cryptographically safe, but good enough for that purpose) of the source code, so changing the declarations will cause a new compilation. Normally these files are cached in $HOME/.gforth/architecture/libcc-named, so if you experience problems or have other reasons to force a recompilation, you can delete the files there.

Note that you should use c-library before everything else having anything to do with that library, as it resets some setup stuff. The idea is that the typical use is to put each c-library...end-c-library unit in its own file, and to be able to include these files in any order. All other words dealing with the C interface are hidden in the vocabulary c-lib, which is put on top o the search stack by c-library and removed by end-c-library.

Note that the library name is not allocated in the dictionary and therefore does not shadow dictionary names. It is used in the file system, so you have to use naming conventions appropriate for file systems. The name is also used as part of the C symbols, but characters outside the legal C symbol names are replaced with underscores. Also, you shall not call a function you declare after c-library before you perform end-c-library.

A major benefit of these named library interfaces is that, once they are generated, the tools used to generated them (in particular, the C compiler and libtool) are no longer needed, so the interface can be used even on machines that do not have the tools installed. The build system of Gforth can even cross-compile these libraries, so that the libraries are available for plattforms on which build tools aren’t installed.

c-library-name ( c-addr u –  ) gforth-0.7 “c-library-name”

Start a C library interface with name c-addr u.

c++-library-name ( c-addr u –  ) gforth-1.0 “c++-library-name”

Start a C++ library interface with name c-addr u.

c-library ( "name" –  ) gforth-0.7 “c-library”

Parsing version of c-library-name

c++-library ( "name" –  ) gforth-1.0 “c++-library”

Parsing version of c++-library-name

end-c-library ( ) gforth-0.7 “end-c-library”

Finish and (if necessary) build the latest C library interface.