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" – ) gforth-0.7 “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.