Product SiteDocumentation Site

2.3.2. How to use Relaytool?

Replace -lfoo in your link line with relaytool –relay foo -lfoo, assuming libfoo is in the standard search path (/lib/, /usr/lib, /usr/local/lib). You can pass entire gcc linker lines to Relaytool, and it will interpret them accordingly. Most options will be passed through unchanged onto stdout, but -lfoo options that have a preceeding –relay foo argument will trigger stub generation and compilation.
Note that Relaytool will invoke $CC (or gcc if it's not set) to compile the stub file silently. You will not see any output.
Alternatively, you can use the –replace-all-libs option to cause Relaytool to generate a stub file for every library given in a -lfoo directive.
Because Relaytool parses linker options, you can feed the output of pkg-config and other config scripts to it:
			[earth@sun] relaytool --relay gtkspell `pkg-config --libs gtkspell-2.0`
The above produces something like this, for example:
			-Wl,--export-dynamic -L/opt/gnome26/lib libgtkspell.so.0.0.0.stub.o -laspell -lgtk-x11-2.0 -lgdk-x11-2.0 -latk-1.0
		       -lgdk_pixbuf-2.0 -lm -lpangoxft-1.0 -lpangox-1.0 -lpango-1.0 -lgobject-2.0 -lgmodule-2.0 -ldl -lglib-2.0
Note how -lgtkspell was replaced with libgtkspell.so.0.0.0.stub.o
On architectures that Relaytool does not support, the -l is passed through along with a couple of defines to provide libfoo_is_present and libfoo_symbol_is_present.

Important

Ensure CFLAGS=”-fPIC” if the library exports variables, as GOT fixup requires your program to use PIC code.
If you want to use Relaytool only for part of a shared library (for instance to make use of symbols available in newer versions only) you can use the –partial-map feature. To use this create a file with a line for each symbol, with F for function or V for variable in the first column, like so:
In file foo.relaymap:
F some_function
V some_variable
then run:
			[earth@sun] relaytool --partial-map foo.relaymap --relay whatever -lwhatever
If you want to hard link to a library but soft link to a few symbols, you can use –partial-map and –no-replace.

Note

–partial-map is currently incompatible with multiple –relay libraries on the same command line. You'll have to separate your libraries in different Relaytool calls.
If you want Relaytool to only generate the symbols required by your code and not the whole list exported by a library, you can use the –minimal-list feature. It takes as argument the list of your object files, from which it derives which symbols for each library are actually needed. For example:
			[earth@sun] relaytool --minimal-list "foo.o bar.o" --relay mylib -lmylib
This will generate a file exporting only the symbols used in foo.o and bar.o actually found in mylib instead of the complete list of symbols exported from mylib, which can mean big space savings in the final executable.