LSB Build Environment
=====================

This purpose of this package is to make it easier to build LSB
compliant applications. It is not meant to necessarily provide an LSB
runtime environment and is possible/easy to build a binary in the
build environment which will not actually run in it. Use the LSB
sample implementation to test the binaries and packages.

See the INSTALL file for instructions on how to install the build
environment.

Quickstart
----------
Configuration file: /etc/lsbdev/lsbdev.conf

Starting:
# /etc/init.d/lsbdev start

Stopping:
# /etc/init.d/lsbdev stop

Using the environment
---------------------
Ensure that you understand how bind-mounts work before removing files
in the build environment. Depending on which version of the kernel you
are using read-only bind mounts may not in fact be read only, so it is
possible to accidentally remove important files outside of the chroot
area from within it.  The purpose of the chroot area is not for
reasons of security, but instead to make it easier to build
applications without accidentally polluting binaries with information
from non-compliant header files and libraries (as can easily happen
with configure scripts).

A developer can build an application within this build environment by
first chrooting into the directory structure constructed by the setup
scripts. This environment by default provides tools installed in /bin
and /usr/bin and the core runtime libraries needed to compile and link
a binary. System (/usr/include) header files are used if the package
is not configured to use lsb header files. Although a complete set of
development tools will not be available through just /bin and /usr/bin
more may be included by individually bind mounting them into the
chroot area.

If the package is configured to use sshd, an sshd running inside the
chroot area will be started listening on a high port (5436 by
default). This allows non root privileged users to enter the
environment (without using chroot).

It is possible to configure the package such that extra installation
specific directories and files are included in the chroot area. See
the INSTALL file for more details. This mechanism in general should
only be used for importing programs into the chroot area and not
include files or shared libraries as this may allow for the generation
of non compliant binaries.

The package contains the following:

  - LSB stub libraries (stub_libs). 
    These libraries contain the versioned symbols as required by
    the LSB specification. Linking against these libraries will ensure
    that the application attempts to use the correct versions 
    at runtime. They do not contain the code necessary for
    a program to operate during runtime.

  - gcc spec file
    A modified version for gcc (2.95.4). This will ensure that the programs
    are linked against ld-lsb.so.1 instead of ls-linux.so.2. It also
    adds the lsb stub library directory to the link search path. 

  - setup scripts
    scripts to setup the chroot build environment

  - LSB Header files

It will also be useful to have a version of rpm installed which is
capable of creating V3 format RPM packages. To work properly inside
the development environment it may be necessary to have a statically
linked version of the rpm binaries. A suitable version (lsb-rpm) is
available from ftp://ftp.freestandards.org/pub/lsb/lsbdev. This should
not be used for general package management.

Partial Static Linking
----------------------

If your application uses an interface in libc which is not part of the
LSB specification it may be necessary to statically link parts of the
program against libc. You can do this by editing the libc.so in the
chroot environment from:

GROUP ( /usr/lib/lsb-stub/libc.real.so  /usr/lib/lsb-stub/libc_nonshared.a )

to:

GROUP ( /usr/lib/lsb-stub/libc.real.so  /usr/lib/lsb-stub/libc_nonshared.a /usr/lib/lsb-stub/libc_static.a )

and bind mounting /usr/lib/libc.a into the chroot environment as
/usr/lib/libc_static.a. A couple of things to note with this approach:

- Be aware of the potential compatability problems (syscalls) with
  statically linking against libc

- Depending on how your program is licenced you may not be permitted
  to distribute binaries statically linked against libc (LGPL)

lsbdev now supports automatically setting up fallback static linking
on a per library basis. See the FALLBACK_STATIC_LINK_LIBRARIES option
in the lsbdev.conf file for more details.

Kernel Requirements
-------------------

A kernel of version 2.4.6 or greater which supports bind mounting of
symlinks is required to use this program.

Known Bugs
----------

- The header files included by with lsbdev are not yet
  used by default. To enable the use of these header files
  uncomment the LSB_INCLUDE option in lsbdev.conf. If you encounter
  compilation problems when using the supplied LSB header files 
  please also try using the system include files before reporting
  a bug. 

- We don't link against the proper runtime linker, but the 'real'
  one within that environment

Variations from LSB specification
---------------------------------

The following symbols are not in the LSB specification, but are
included in the C stub library because they are needed for the correct
compilation of some binaries by gcc. It expected that they will be
added in the near future.

  _IO_stdin_used
  __cxa_finalize

Licence
-------

lsbdev is Copyright 2001 The Free Standards Group Inc, and distributed
under the terms of the GNU Lesser General Public License (LGPL). See
the License file for details.


Feedback
--------
Please send any comments you may have to lsb-impl@linuxbase.org

Chris Yeoh <cyeoh@samba.org>
Last updated 2002/04/10

