- <p>
- Although binaries in the build tree should be compiled with
- debugging information by default, it can often be difficult
- to debug programs if they are also subjected to compiler
- optimization. For this reason, it is recommended to support
- the standardized environment
- variable <tt>DEB_BUILD_OPTIONS</tt>. This variable can
- contain several flags to change how a package is compiled
- and built.
- </p>
- <p>
- <taglist>
- <tag>noopt</tag>
- <item>
- <p>
- The presence of this string means that the package
- should be complied with a minimum of optimization.
- For C programs, it is best to add <tt>-O0</tt>
- to <tt>CFLAGS</tt> (although this is usually the
- default). Some programs might fail to build or run at
- this level of optimization; it may be necessary to
- use <tt>-O1</tt>, for example.
- </p>
- </item>
- <tag>nostrip</tag>
- <item>
- <p>
- This string means that the debugging symbols should
- not be stripped from the binary during installation,
- so that debugging information may be included in the package.
- </p>
- </item>
- </taglist>
- </p>
- <p>
- The following makefile snippet is an example of how one may
- implement the build options; you will probably have to
- massage this example in order to make it work for your
- package.
- <example compact="compact">
-CFLAGS = -Wall -g
-INSTALL = install
-INSTALL_FILE = $(INSTALL) -p -o root -g root -m 644
-INSTALL_PROGRAM = $(INSTALL) -p -o root -g root -m 755
-INSTALL_SCRIPT = $(INSTALL) -p -o root -g root -m 755
-INSTALL_DIR = $(INSTALL) -p -d -o root -g root -m 755
-
-ifneq (,$(findstring noopt,$(DEB_BUILD_OPTIONS)))
-CFLAGS += -O0
-else
-CFLAGS += -O2
-endif
-ifeq (,$(findstring nostrip,$(DEB_BUILD_OPTIONS)))
-INSTALL_PROGRAM += -s
-endif
- </example>
- </p>
-
- <p>
- It is up to the package maintainer to decide what
- compilation options are best for the package. Certain
- binaries (such as computationally-intensive programs) will
- function better with certain flags (<tt>-O3</tt>, for
- example); feel free to use them. Please use good judgment
- here. Don't use flags for the sake of it; only use them
- if there is good reason to do so. Feel free to override
- the upstream author's ideas about which compilation
- options are best: they are often inappropriate for our
- environment.
- </p>
- </sect>
-
-
- <sect>
- <heading>Libraries</heading>
- <p>
- In general, libraries must have a shared version in the
- library package and a static version in the development
- package. The shared version must be compiled with
- <tt>-fPIC</tt>, and the static version must not be. In
- other words, each source unit ( <tt>*.c</tt>, for example,
- for C files) will need to be compiled twice.
- </p>
- <p>
- In some cases, it is acceptable for a library to be
- available in static form only; these cases include:
- <list>
- <item>
- <p>libraries for languages whose shared library support
- is immature or unstable</p>
- </item>
- <item>
- <p>
- libraries whose interfaces are in flux or under
- development (commonly the case when the library's
- major version number is zero, or where the ABI breaks
- across patchlevels)
- </p>
- </item>
- <item>
- <p>
- libraries which are explicitly intended to be
- available only in static form by their upstream
- author(s)</p>
- </item>
- </list>
- If a library is available only in static form, then it must follow
- the conventions for a development package.
- </p>
- <p>
- All libraries must have a shared version in the
- <tt>lib*</tt> package and a static version in the
- <tt>lib*-dev</tt> package. The shared version must be
- compiled with <tt>-fPIC</tt>, and the static version must
- not be. In other words, each <tt>*.c</tt> file will need to
- be compiled twice.</p>
-
- <p>
- You must specify the gcc option <tt>-D_REENTRANT</tt>
- when building a library (either static or shared) to make
- the library compatible with LinuxThreads.</p>
-
- <p>
- Note that all installed shared libraries should be
- stripped with
- <example compact="compact">
-strip --strip-unneeded <var>your-lib</var>
- </example>
- (The option <tt>--strip-unneeded</tt> makes
- <prgn>strip</prgn> remove only the symbols which aren't
- needed for relocation processing.) Shared libraries can
- function perfectly well when stripped, since the symbols for
- dynamic linking are in a separate part of the ELF object
- file.<footnote>
- <p>
- You might also want to use the options
- <tt>--remove-section=.comment</tt> and
- <tt>--remove-section=.note</tt> on both shared libraries
- and executables, and <tt>--strip-debug</tt> on static
- libraries.
- </p>
- </footnote>
- </p>
-
- <p>
- Note that under some circumstances it may be useful to
- install a shared library unstripped, for example when
- building a separate package to support debugging.
- </p>
-
- <p>
- Shared object files (often <file>.so</file> files) that are not
- public libraries, that is, they are not meant to be linked
- to by third party executables (binaries of other packages),
- should be installed in subdirectories of the
- <file>/usr/lib</file> directory. Such files are exempt from the
- rules that govern ordinary shared libraries, except that
- they must not be installed executable and should be
- stripped.<footnote>
- <p>
- A common example are the so-called ``plug-ins'',
- internal shared objects that are dynamically loaded by
- programs using <manref name="dlopen" section="3">.
- </p>
- </footnote>
- </p>
-
- <p>
- Packages containing shared libraries that may be linked to
- by other packages' binaries, but which for some
- <em>compelling</em> reason can not be installed in
- <file>/usr/lib</file> directory, may install the shared library
- files in subdirectories of the <file>/usr/lib</file> directory,
- in which case they should arrange to add that directory in
- <file>/etc/ld.so.conf</file> in the package's post-installation
- script, and remove it in the package's post-removal script.
- </p>
-
- <p>
- An ever increasing number of packages are using
- <prgn>libtool</prgn> to do their linking. The latest GNU
- libtools (>= 1.3a) can take advantage of the metadata in the
- installed <prgn>libtool</prgn> archive files (<file>*.la</file>
- files). The main advantage of <prgn>libtool</prgn>'s
- <file>.la</file> files is that it allows <prgn>libtool</prgn> to
- store and subsequently access metadata with respect to the
- libraries it builds. <prgn>libtool</prgn> will search for
- those files, which contain a lot of useful information about
- a library (such as library dependency information for static
- linking). Also, they're <em>essential</em> for programs
- using <tt>libltdl</tt>.<footnote>
- <p>
- Although <prgn>libtool</prgn> is fully capable of
- linking against shared libraries which don't have
- <tt>.la</tt> files, as it is a mere shell script it can
- add considerably to the build time of a
- <prgn>libtool</prgn>-using package if that shell script
- has to derive all this information from first principles
- for each library every time it is linked. With the
- advent of <prgn>libtool</prgn> version 1.4 (and to a
- lesser extent <prgn>libtool</prgn> version 1.3), the
- <file>.la</file> files also store information about
- inter-library dependencies which cannot necessarily be
- derived after the <file>.la</file> file is deleted.
- </p>
- </footnote>
- </p>
-
- <p>
- Packages that use <prgn>libtool</prgn> to create shared
- libraries should include the <file>.la</file> files in the
- <tt>-dev</tt> package, unless the package relies on
- <tt>libtool</tt>'s <tt>libltdl</tt> library, in which case
- the <tt>.la</tt> files must go in the run-time library
- package.
- </p>
-
- <p>
- You must make sure that you use only released versions of
- shared libraries to build your packages; otherwise other
- users will not be able to run your binaries
- properly. Producing source packages that depend on
- unreleased compilers is also usually a bad
- idea.
- </p>
- </sect>
-
- <sect>
- <heading>Shared libraries</heading>
-
- <p>
- Packages involving shared libraries should be split up
- into several binary packages.</p>
-
- <p>
- For a straightforward library which has a development
- environment and a runtime kit including just shared
- libraries you need to create two packages:
- <file><var>libraryname</var><var>soversion</var></file>, where
- <file><var>soversion</var></file> is the version number in the
- soname of the shared library<footnote>
- <p>
- The soname is the shared object name: it's the thing
- that has to match exactly between building an executable
- and running it for the dynamic linker to be able run the
- program. For example, if the soname of the library is
- <file>libfoo.so.6</file>, the library package would be
- called <file>libfoo6</file>.
- </p>
- </footnote>
- and <tt><var>libraryname</var><var>soversion</var>-dev</tt>.
- Alternatively, if it would be confusing to directly append
- <var>soversion</var> to <var>libraryname</var> (e.g. because
- <var>libraryname</var> itself ends in a number), you may use
- <tt><var>libraryname</var>-<var>soversion</var></tt> and
- <tt><var>libraryname</var>-<var>soversion</var>-dev</tt>
- instead.
- </p>
-
- <p>
- If you prefer only to support one development version at a
- time you may name the development package
- <file><var>libraryname</var>-dev</file>; otherwise you may need
- to use <prgn>dpkg</prgn>'s Conflicts mechanism (see <ref
- id="conflicts">) to ensure that the user only installs one
- development version at a time (as different development
- versions are likely to have the same header files in them,
- which would cause a filename clash if both were installed).
- Typically the development version should also have an exact
- version dependency on the runtime library, to make sure that
- compilation and linking happens correctly. The
- <tt>${Source-Version}</tt> substitution variable can be
- useful for this purpose.
- </p>
-
- <p>
- Packages which use the shared library should have a
- dependency on the name of the shared library package,
- <file><var>libraryname</var><var>soversion</var></file>. When
- the soname changes you can have both versions of the library
- installed while migrating from the old library to the new.
- </p>