LSB Stub Shared Libraries

The LSB development environment provides shared libraries that can be dynamically linked against an application. The functions within these libraries are stubs only (for example, contain no executable code) and are not intended to be used, except for linking against when building a dynamically linked binary.

The environment in which software is developed is often different than that in which the application is designed to be run on. For example, developers will often have a more recent version of the C library than what the LSB requires. Header files used during compilation can contain definitions that affect the runtime behavior of an application. For example, the content and size of structs can change as libraries develop, so it is important that the correct representation is used for the given version of the library.

In order to solve this problem, some libraries such as the C library use symbol versioning. Each interface within the library has a version associated with it, allowing for multiple versions of the same interface (such as open) to exist in the same shared library. The inclusion of multiple versions of a function allows older applications to continue to use the old version, while new applications use the new version.

When a binary is created, it inspects the shared library it is linking against and records the versions of those interfaces it requires. At runtime, the binary will will look for the the interfaces with the recorded version number, and fail if they do not exist. Thus, it is necessary to link against shared libraries that contain the versions of the interfaces guaranteed to exist on an LSB compliant runtime.

Where libraries supported by the LSB use symbol versioning, the specification specifies specific versions of the interfaces. The LSB stub libraries only contain the versions of the interfaces allowed by the LSB specification, and so if they are used it makes it impossible to use the wrong version when building a binary.

There are often interfaces contained in shared libraries that must not be used by an LSB compliant binary. These interfaces are often private functions, or interfaces not supported by the LSB. Since the stub libraries only contain interfaces required by the specification, an error will occur during the link stage if an application uses an unsupported interface.

LSB Header Files

The definitions contained within a header file associated with a library may change over time as the ABI of that library evolves. For example, a function in one version of the library may take one parameter, while in the next version it make take two parameters.

The LSB specification defines an ABI for each supported library, and the header files used to compile against must match exactly. In order to avoid the problem of finding the exact version of the software that contains the correct definitions, header files are supplied with the LSB build environment that are matched with the specification.

Using the Development Tools

The main tools provided by the LSB SDK are compiler wrappers fo C and C++, called lsbcc and lsbc++ correspondingly, that compile and link against compliant headers and libraries. Using these tools is an easy way to build an LSB compliant application.

Additional tools include:

• makelsbpkg - an utility to create LSB compliant RPM from a source directory of files or a cpio archive;
• qmake with accompanying utilities for Qt3 and Qt4;
• lsbrun - an utility for running LSB-compliant applications on Linux systems that do not provide a LSB runtime.

# CC=lsbcc ./configure
# CC=lsbc++ ./configure (for C++)

or

# CC=lsbcc make
# CC=lsbc++ make (for C++)

#include <stdio.h>
#include <stdlib.h>

int main(int argc, char *argv[])
{
  printf("Hello World\n");
  exit(0);
}

$ lsbcc -Wall -o hello_world hello_world.c
$ ./hello_world
Hello World
$

   $ /usr/bin/objdump -T myapplication | grep myfunction
   08048330 DF *UND* 00000032 GLIBC_2.0 myfunction

   $ /usr/bin/objdump -T /lib/i686/libc.so.6 | egrep myfunction
   000bb160 g DF .text 00000032 GLIBC_2.0 myfunction
   000bb160 w DF .text 00000032 GLIBC_2.1 myfunction

Changing Dynamic Linker

LSB compatible applications are supposed to use LSB dynamic linker instead of the default system linker. For example on x86 machines /lib/ld-lsb.so.1 should be used instead of /lib/ld-linux.so.2. By default, when built with lsbcc or lsbc++, the desurable dynamic linker is set using appropriate gcc option.

However, one may claim that at least for some applications it would be nice to be able to use the same executable on both LSB compliant platforms and on platforms that don't provide LSB dynamic linker, since even in the latter case the platform may provide all functionality required for the particular program. LSB SDK provides two ways to implement this possibility:

• Do not set dynamic linker to the LSB one. When using lsbcc, this can be achieved through the --lsb-use-default-linker option or LSBCC_USE_DEFAULT_LINKER environment variable. However, such applications are not considered as LSB-compliant at the moment.
• Use 'best effort' policy - allow application to choose the dynamic linker at runtime. If LSB linker is available, then it will be used, otherwise the default system linker will be invoced. To add this possibility to the application compiled with lsbcc, use --lsb-besteffort option. Alternatively, you may set the LSBCC_BESTEFFORT environment variable.
• Set dynamic linker to the LSB one and use the lsbrun utility to execute the program on platforms that don't have LSB dynamic linker.

makelsbpkg

LSB currently suggests to use RPM format to package the applications. However, as time goes by, RPM itself evolves and modern systems may create RPM files that cannot be installed on older systems. In order to create RPM files that match LSB requirements, one may use the makelsbpkg utility. A simple example of its usage is like the following:

   $ makelsbpkg mypackage pkgroot/mypackage

Shared libraries

When an application uses a library that is not part of the LSB specification, it can be built in one of two ways. Either the binary is statically linked against that library, or if the library is LSB compliant it may be dynamically linked with the binary. If it is dynamically linked, the shared library must be supplied with the rest of the application.

The requirements for a shared library to be considered to be LSB compliant are essentially the same as those required for a directly executable program. That is, it must only use dynamic interfaces supported by the specification, or alternatively supplied in an another LSB compliant shared library that is packaged with the rest of the application.

Much like an ordinary binary, a shared library that is to be supplied with an LSB compliant application should be built against the LSB headers and stub libraries. Rather than building a shared library with ld:

	# ld -r -shared -o libtest.so obj1.o obj2.o

This may lead to the use of symbol versions that are not part of the LSB specification. If you are using the lsbcc technique of building an application, then shared libraries must also be built using lsbcc.

	# lsbcc -shared -o libtest.so obj1.o obj2.o

When it comes to linking an application, if you use lsbcc, by default only the LSB specified libraries will be linked dynamically, even if both static and shared libraries are available in the search path. This behaviour can be modified by setting the environment variable LSBCC_SHAREDLIBS. This is a colon separated list of library names and specifies which extra libraries should be dynamically linked.

Case Study: rsync

The rsync application is one of the programs in the LSB Application Battery. We use this program as an example of the types of problems that developers may encounter, and how to work around them when attempting to build an LSB compliant binary.

We use the lsbcc build tool with rsync version 3.0.0. The source for rsync can be downloaded from the rsync Web site.

$ tar xfz rsync-3.0.0.tar.gz
$ cd rsync-3.0.0/
$ CC=lsbcc ./configure
configure: Configuring rsync 3.0.0
checking build system type... i686-pc-linux-gnu
checking host system type... i686-pc-linux-gnu
checking target system type... i686-pc-linux-gnu
checking for gcc... lsbcc
checking for C compiler default output... a.out
checking whether the C compiler works... yes
...
checking for mallinfo... no
checking for getgroups... yes
checking for setgroups... yes
...
checking whether to support ACLs... running tests:
checking for acl_get_file in -lacl... no
checking for ACL support... no
checking ACL test results... No ACL support found
checking whether to support extended attributes... no
...
config.status: creating popt/dummy
config.status: creating shconfig
config.status: creating config.h

   rsync 3.0.0 configuration successful

$ make
...
lsbcc -std=gnu99 -g -O2 -DHAVE_CONFIG_H -Wall -W -I./popt -Wno-unused-parameter -o rsync 
 flist.o rsync.o generator.o receiver.o cleanup.o sender.o exclude.o util.o main.o 
 checksum.o match.o syscall.o log.o backup.o options.o io.o compat.o hlink.o token.o 
 uidlist.o socket.o hashtable.o fileio.o batch.o clientname.o chmod.o acls.o xattrs.o 
 progress.o pipe.o params.o loadparm.o clientserver.o access.o connection.o authenticate.o 
 lib/wildmatch.o lib/compat.o lib/snprintf.o lib/mdfour.o lib/md5.o lib/permstring.o lib/
 pool_alloc.o lib/sysacls.o lib/sysxattrs.o  zlib/deflate.o zlib/inffast.o zlib/inflate.o 
 zlib/inftrees.o zlib/trees.o zlib/zutil.o zlib/adler32.o zlib/compress.o zlib/crc32.o 
 popt/findme.o  popt/popt.o  popt/poptconfig.o popt/popthelp.o popt/poptparse.o
authenticate.o(.text+0x83d): In function `auth_client':
/home/cyeoh/src/rsync-3.0.0/authenticate.c:317: undefined reference to `getpass'
collect2: ld returned 1 exit status
make: *** [rsync] Error 1

$ lsbappchk rsync
 LSB version is not specified, using 4.0 by default.               
 BIN: rsync
$

$ LSBCC_LSBVERSION=3.1 CC=lsbcc ./configure
...
$ LSBCC_LSBVERSION=3.1 make
...

--- rsync-3.0.0/rsync.h.lsbcc	2008-03-01 15:12:04.000000000 -0500
+++ rsync-3.0.0/rsync.h	2008-03-18 10:35:35.000000000 -0400
@@ -29,7 +29,7 @@
 /* RSYNCD_SYSCONF is now set in config.h */
 #define RSYNCD_USERCONF "rsyncd.conf"

-#define DEFAULT_LOCK_FILE "/var/run/rsyncd.lock"
+#define DEFAULT_LOCK_FILE "/var/run/lsb-rsyncd.lock"
 #define URL_PREFIX "rsync://"

 #define SYMLINK_PREFIX "/rsyncd-munged/"

Building the LSB Development Environment

Most of the source code for the LSB SDK packages is auto generated from the LSB Specification database. This has the benefit that the header files and stub libraries are synchronized with the specification. Normally it should not be necessary for people to build the source code from the database, though all of the scripts and the contents of the database are publically available in the LSB Bazaar repository.

Source tarballs and source rpm packages for the LSB SDK are available from the LSB FTP Archive. The tarballs contains a README that describes how to build the package and the source rpm packages can be built in the usual manner with the rpm tool. For example:

# rpm --rebuild lsb-build-base-4.0.0-2.src.rpm

Expanding the LSB Development Environment

Downloading the LSB Development Environment

To obtain the LSB Development Environment go to the LSB download Web page. The packages that form the LSB SDK are listed in the Table 1.

Sources of all packages are available in the LSB Bazaar repository.