Parser Library

Parser Library is an object hierarchy which contains object classes that can be used to parse and handle GRP files. You can use these objects in your program if you link it with the library.

If your system and your compiler support shared libraries, compilation of the grp2c package produces two kind of Parser Library, classical static library and a shared one.

Using static Parser Library

You can use static library in general way. After installation of the grp2c package you can find the library in the PREFIX/lib directory, where PREFIX was specified during the configuration of the package or it is /usr/local by default. This directory must be specified as -L option of the compiler when you compile your program. Note, that shared library is installed into same place as the static one and some linkers (well, most of them) prefer shared library, so if you would like to use static library, you should use -static option too. Name of the library, which is parser, must be specified in the -l option:

$ CC -static YourOptions -LPREFIX/lib -lparser

Using shared Parser Library

First you must install shared library, see notes about it in the chapter Installation. After that you can link it to your program in same way as static version, just leave -static option out of the command line:

$ CC YourOptions -LPREFIX/lib -lparser

It is enough because if the linker find both static and shared library and it supports dynamic linking, it will use shared library instead of static one. You can check the result of the linking with the ldd command, see the manual pages how to use it. If you find out that something is wrong, you can try to use -shared option with the linker/compiler.

Completing installation, executing applications

If you linked shared Parser Library to your program, you must inform dinamic loader/linker about it so it will be able to find and load shared library when it dynamically links your aplication and shared libraries during starting phase of the application. This can be done in several ways.

Most simple way is install library into a suitable directory and set up LD_LIBRARY_PATH environment variable, because you need not be root to do this. First check if the variable has been set up before:
$ echo $LD_LIBRARY_PATH
If the variable has any value, you should expand it with the name of the directory where the shared Parser Library is installed to:
$ LD_LIBRARY_PATH=$LD_LIBRARY_PATH:PREFIX/lib
otherwise just define the variable with required value:
$ export LD_LIBARAY_PATH=PREFIX/lib
If you do not use any Bourne-like shell, use the syntax of your shell. You can put this command in your startup script, such as .profile or .cshrc.
Some dynamic linker/loader does not check directories specified in the LD_LIBRARY_PATH variable if you execute you application as root, or it has setuid bit set. It has security reasons. If it causes any problem, you should do something other.
You can install shared Parser Library into a trusted directory, where the linker will look for it in every cases. Note that you must be root to do this because these directories are not writable by others than root obviously. On Linux system the trusted libraries are listed in the file /etc/ld.so.conf. You can choose any directory from the list and install library into that. Or, if you are sure that it is safe, you can insert the name of the directory where the library is installed to. Whatever you do, you must inform the dinamic linker/loader about the new situation. You must invoke the ldconfig command and it will do everything for you. After that you must be able to execute your program which has been dynamically linked with the shared Parser Library.
Note, that other systems can behave differently. For example on IRIX and Solaris names of the trusted directories are hardcoded into the dynamic linker/loader and you can not change them. On these systems you can not find ldconfig utility, you simply need to install libraries into any trusted directory (/lib, /usr/lib, and some others) or your own one and set up the LD_LIBRARY_PATH environment variable to contain the name of your directory.

Upgrading shared Parser Library

The main advantage of the usgae of the shared libraries is that it is more easy to upgrade the library, because you do not have to relink your application in every times when you change the library with a new version. Version number of the library is included into its name and the linker will search for that version which was available when the application has been linked. Let's suppose that it was libparser.so.0.64. Normally it is a symbolic link to the actual version of the library, for example

libparser.so.0.64 -> libparser.so.0.64.2

It means that you have version 0.64.2 currently. When you upgrade the library to a new version 0.64.3 you just install the new library and remake the link:

libparser.so.0.64 -> libparser.so.0.64.3

this is done by the installation procedure automatically, so you do not have to do anything else. When major or minor version number of the library is changing, for example you install 0.65.0, it can cause some problems, because linker needs 0.64 and it is no longer exists. In this case the linker can refuse using the new library, because it can not be compatible with the required version. In this case you should relink your application.

If you know that the new version is compatible with the old one and you would not relink your aplpication, you can remake the required link to point to the new library and try to use your application:

libparser.so.0.64 -> libparser.so.0.65.0

It is possible that your linker uses a different procedure when it looks for the required library. For example the IRIX's linker does not check the version number of the library. It means that it needs different links, so the installation step makes some other links too:

libparser.so -> libparser.so.0
libparser.so.0 -> libparser.so.0.64
libparser.so.0.64 -> libparser.so.0.64.3

Back to Grapnel Compiler.