- <chapt id="sharedlibs"><heading>Shared libraries</heading>
-
- <p>
- Packages containing shared libraries must be constructed with
- a little care to make sure that the shared library is always
- available. This is especially important for packages whose
- shared libraries are vitally important, such as the C library
- (currently <tt>libc6</tt>).
- </p>
-
- <p>
- Packages involving shared libraries should be split up into
- several binary packages. This section mostly deals with how
- this separation is to be accomplished; rules for files within
- the shared library packages are in <ref id="libraries"> instead.
- </p>
-
- <sect id="sharedlibs-runtime">
- <heading>Run-time shared libraries</heading>
-
- <p>
- The run-time shared library needs to be placed in a package called
- <package><var>libraryname</var><var>soversion</var></package>, 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>.
- 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
- <package><var>libraryname</var>-<var>soversion</var></package> and
- <package><var>libraryname</var>-<var>soversion</var>-dev</package>
- instead.
- </p>
-
- <p>
- If you have several shared libraries built from the same
- source tree you may lump them all together into a single
- shared library package, provided that you change all of
- their sonames at once (so that you don't get filename
- clashes if you try to install different versions of the
- combined shared libraries package).
- </p>
-
- <p>
- The package should install the shared libraries under
- their normal names. For example, the <package>libgdbmg1</package>
- package should install <file>libgdbm.so.1.7.3</file> as
- <file>/usr/lib/libgdbm.so.1.7.3</file>. The files should not be
- renamed or re-linked by any <prgn>prerm</prgn> or
- <prgn>postrm</prgn> scripts; <prgn>dpkg</prgn> will take care
- of renaming things safely without affecting running programs,
- and attempts to interfere with this are likely to lead to
- problems.
- </p>
-
- <p>
- Shared libraries should not be installed executable, since
- the dynamic linker does not require this and trying to
- execute a shared library usually results in a core dump.
- </p>
-
- <p>
- The run-time library package should include the symbolic link that
- <prgn>ldconfig</prgn> would create for the shared libraries.
- For example, the <package>libgdbmg1</package> package should include
- a symbolic link from <file>/usr/lib/libgdbm.so.1</file> to
- <file>libgdbm.so.1.7.3</file>. This is needed so that the dynamic
- linker (for example <prgn>ld.so</prgn> or
- <prgn>ld-linux.so.*</prgn>) can find the library between the
- time that <prgn>dpkg</prgn> installs it and the time that
- <prgn>ldconfig</prgn> is run in the <prgn>postinst</prgn>
- script.<footnote>
- <p>
- The package management system requires the library to be
- placed before the symbolic link pointing to it in the
- <file>.deb</file> file. This is so that when
- <prgn>dpkg</prgn> comes to install the symlink
- (overwriting the previous symlink pointing at an older
- version of the library), the new shared library is already
- in place. In the past, this was achieved by creating the
- library in the temporary packaging directory before
- creating the symlink. Unfortunately, this was not always
- effective, since the building of the tar file in the
- <file>.deb</file> depended on the behavior of the underlying
- file system. Some file systems (such as reiserfs) reorder
- the files so that the order of creation is forgotten.
- Since version 1.7.0, <prgn>dpkg</prgn>
- reorders the files itself as necessary when building a
- package. Thus it is no longer important to concern
- oneself with the order of file creation.
- </p>
- </footnote>
- </p>
-
- <sect1 id="ldconfig">
- <heading><tt>ldconfig</tt></heading>
-
- <p>
- Any package installing shared libraries in one of the default
- library directories of the dynamic linker (which are currently
- <file>/usr/lib</file> and <file>/lib</file>) or a directory that is
- listed in <file>/etc/ld.so.conf</file><footnote>
- <p>
- These are currently
- <list compact="compact">
- <item><p>/usr/X11R6/lib/Xaw3d</p></item>
- <item><p>/usr/local/lib</p></item>
- <item><p>/usr/lib/libc5-compat</p></item>
- <item><p>/lib/libc5-compat</p></item>
- <item><p>/usr/X11R6/lib</p></item>
- </list>
- </p>
- </footnote>
- must use <prgn>ldconfig</prgn> to update the shared library
- system.
- </p>
-
- <p>
- The package must call <prgn>ldconfig</prgn> in the
- <prgn>postinst</prgn> script if the first argument is
- <tt>configure</tt>; the <prgn>postinst</prgn> script may
- optionally invoke <prgn>ldconfig</prgn> at other times. The
- package should call <prgn>ldconfig</prgn> in the
- <prgn>postrm</prgn> script if the first argument is
- <tt>remove</tt>. The maintainer scripts must not invoke
- <prgn>ldconfig</prgn> under any circumstances other than those
- described in this paragraph.<footnote>
- <p>During install or upgrade, the preinst is called before
- the new files are installed, so calling "ldconfig" is
- pointless. The preinst of an existing package can also be
- called if an upgrade fails. However, this happens during
- the critical time when a shared libs may exist on-disk
- under a temporary name. Thus, it is dangerous and
- forbidden by current policy to call "ldconfig" at this
- time.
- </p>
- <p>When a package is installed or upgraded, "postinst
- configure" runs after the new files are safely on-disk.
- Since it is perfectly safe to invoke ldconfig
- unconditionally in a postinst, it is OK for a package to
- simply put ldconfig in its postinst without checking the
- argument. The postinst can also be called to recover from
- a failed upgrade. This happens before any new files are
- unpacked, so there is no reason to call "ldconfig" at this
- point.
- </p>
- <p>For a package that is being removed, prerm is
- called with all the files intact, so calling ldconfig is
- useless. The other calls to "prerm" happen in the case of
- upgrade at a time when all the files of the old package
- are on-disk, so again calling "ldconfig" is pointless.
- </p>
- <p>postrm, on the other hand, is called with the "remove"
- argument just after the files are removed, so this is the
- proper time to call "ldconfig" to notify the system of the
- fact shared libraries from the package are removed.
- The postrm can be called at several other times. At the
- time of "postrm purge", "postrm abort-install", or "postrm
- abort-upgrade", calling "ldconfig" is useless because the
- shared lib files are not on-disk. However, when "postrm"
- is invoked with arguments "upgrade", "failed-upgrade", or
- "disappear", a shared lib may exist on-disk under a
- temporary filename.
- </p>
- </footnote>
- </p>
- </sect1>
-
- </sect>
-
- <sect id="sharedlibs-runtime-progs">
- <heading>Run-time support programs</heading>
-
- <p>
- If your package has some run-time support programs which use
- the shared library you must not put them in the shared
- library package. If you do that then you won't be able to
- install several versions of the shared library without
- getting filename clashes.
- </p>
-
- <p>
- Instead, either create another package for the runtime binaries
- (this package might typically be named
- <package><var>libraryname</var>-runtime</package>; note the absence
- of the <var>soversion</var> in the package name), or if the
- development package is small, include them in there.
- </p>
- </sect>
-
- <sect id="sharedlibs-static">
- <heading>Static libraries</heading>
-
- <p>
- The static library (<file><var>libraryname.a</var></file>)
- is usually provided in addition to the shared version.
- It is placed into the development package (see below).
- </p>
-
- <p>
- In some cases, it is acceptable for a library to be
- available in static form only; these cases include:
- <list>
- <item>libraries for languages whose shared library support
- is immature or unstable</item>
- <item>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)</item>
- <item>libraries which are explicitly intended to be
- available only in static form by their upstream
- author(s)</item>
- </list>
- </p>
-
- <sect id="sharedlibs-dev">
- <heading>Development files</heading>
-
- <p>
- The development files associated to a shared library need to be
- placed in a package called
- <package><var>libraryname</var><var>soversion</var>-dev</package>,
- or if you prefer only to support one development version at a
- time, <package><var>libraryname</var>-dev</package>.
- </p>
-
- <p>
- In case several development versions of a library exist, 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).
- </p>
-
- <p>
- The development package should contain a symlink for the associated
- shared library without a version number. For example, the
- <package>libgdbmg1-dev</package> package should include a symlink
- from <file>/usr/lib/libgdbm.so</file> to
- <file>libgdbm.so.1.7.3</file>. This symlink is needed by the linker
- (<prgn>ld</prgn>) when compiling packages, as it will only look for
- <file>libgdbm.so</file> when compiling dynamically.
- </p>
- </sect>
-
- <sect id="sharedlibs-intradeps">
- <heading>Dependencies between the packages of the same library</heading>
-
- <p>
- Typically the development version should 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>
- </sect>
-
- <sect id="sharedlibs-shlibdeps">
- <heading>Dependencies between the library and other packages -
- the <tt>shlibs</tt> system</heading>
-
- <p>
- If a package contains a binary or library which links to a
- shared library, we must ensure that when the package is
- installed on the system, all of the libraries needed are
- also installed. This requirement led to the creation of the
- <tt>shlibs</tt> system, which is very simple in its design:
- any package which <em>provides</em> a shared library also
- provides information on the package dependencies required to
- ensure the presence of this library, and any package which
- <em>uses</em> a shared library uses this information to
- determine the dependencies it requires. The files which
- contain the mapping from shared libraries to the necessary
- dependency information are called <file>shlibs</file> files.
- </p>
-
- <p>
- Thus, when a package is built which contains any shared
- libraries, it must provide a <file>shlibs</file> file for other
- packages to use, and when a package is built which contains
- any shared libraries or compiled binaries, it must run
- <prgn>dpkg-shlibdeps</prgn> on these to determine the
- libraries used and hence the dependencies needed by this
- package.<footnote>
- <p>
- In the past, the shared libraries linked to were
- determined by calling <prgn>ldd</prgn>, but now
- <prgn>objdump</prgn> is used to do this. The only
- change this makes to package building is that
- <prgn>dpkg-shlibdeps</prgn> must also be run on shared
- libraries, whereas in the past this was unnecessary.
- The rest of this footnote explains the advantage that
- this method gives.
- </p>
-
- <p>
- We say that a binary <tt>foo</tt> <em>directly</em> uses
- a library <tt>libbar</tt> if it is explicitly linked
- with that library (that is, it uses the flag
- <tt>-lbar</tt> during the linking stage). Other
- libraries that are needed by <tt>libbar</tt> are linked
- <em>indirectly</em> to <tt>foo</tt>, and the dynamic
- linker will load them automatically when it loads
- <tt>libbar</tt>. A package should depend on
- the libraries it directly uses, and the dependencies for
- those libraries should automatically pull in the other
- libraries.
- </p>
-
- <p>
- Unfortunately, the <prgn>ldd</prgn> program shows both
- the directly and indirectly used libraries, meaning that
- the dependencies determined included both direct and
- indirect dependencies. The use of <prgn>objdump</prgn>
- avoids this problem by determining only the directly
- used libraries.
- </p>
-
- <p>
- A good example of where this helps is the following. We
- could update <tt>libimlib</tt> with a new version that
- supports a new graphics format called dgf (but retaining
- the same major version number). If we used the old
- <prgn>ldd</prgn> method, every package that uses
- <tt>libimlib</tt> would need to be recompiled so it
- would also depend on <tt>libdgf</tt> or it wouldn't run
- due to missing symbols. However with the new system,
- packages using <tt>libimlib</tt> can rely on
- <tt>libimlib</tt> itself having the dependency on
- <tt>libdgf</tt> and so they would not need rebuilding.
- </p>
- </footnote>
- </p>
-
- <p>
- In the following sections, we will first describe where the
- various <tt>shlibs</tt> files are to be found, then how to
- use <prgn>dpkg-shlibdeps</prgn>, and finally the
- <tt>shlibs</tt> file format and how to create them if your
- package contains a shared library.
- </p>
-
- <sect1>
- <heading>The <tt>shlibs</tt> files present on the system</heading>
-
- <p>
- There are several places where <tt>shlibs</tt> files are
- found. The following list gives them in the order in which
- they are read by <prgn>dpkg-shlibdeps</prgn>. (The first
- one which gives the required information is used.)
- </p>
-
- <p>
- <list>
- <item>
- <p><file>debian/shlibs.local</file></p>
- <p>
- This lists overrides for this package. Its use is
- described below (see <ref id="shlibslocal">).
- </p>
- </item>
-
- <item>
- <p><file>/etc/dpkg/shlibs.override</file></p>
- <p>
- This lists global overrides. This list is normally
- empty. It is maintained by the local system
- administrator.
- </p>
- </item>
-
- <item>
- <p><file>DEBIAN/shlibs</file> files in the "build directory"</p>
- <p>
- When packages are being built, any
- <file>debian/shlibs</file> files are copied into the
- control file area of the temporary build directory and
- given the name <file>shlibs</file>. These files give
- details of any shared libraries included in the
- package.<footnote>
- <p>
- An example may help here. Let us say that the
- source package <tt>foo</tt> generates two binary
- packages, <tt>libfoo2</tt> and
- <tt>foo-runtime</tt>. When building the binary
- packages, the two packages are created in the
- directories <file>debian/libfoo2</file> and
- <file>debian/foo-runtime</file> respectively.
- (<file>debian/tmp</file> could be used instead of one
- of these.) Since <tt>libfoo2</tt> provides the
- <tt>libfoo</tt> shared library, it will require a
- <tt>shlibs</tt> file, which will be installed in
- <file>debian/libfoo2/DEBIAN/shlibs</file>, eventually
- to become
- <file>/var/lib/dpkg/info/libfoo2.shlibs</file>. Then
- when <prgn>dpkg-shlibdeps</prgn> is run on the
- executable
- <file>debian/foo-runtime/usr/bin/foo-prog</file>, it
- will examine the
- <file>debian/libfoo2/DEBIAN/shlibs</file> file to
- determine whether <tt>foo-prog</tt>'s library
- dependencies are satisfied by any of the libraries
- provided by <tt>libfoo2</tt>. For this reason,
- <prgn>dpkg-shlibdeps</prgn> must only be run once
- all of the individual binary packages'
- <tt>shlibs</tt> files have been installed into the
- build directory.
- </p>
- </footnote>
- </p>
- </item>
-
- <item>
- <p><file>/var/lib/dpkg/info/*.shlibs</file></p>
- <p>
- These are the <file>shlibs</file> files corresponding to
- all of the packages installed on the system, and are
- maintained by the relevant package maintainers.
- </p>
- </item>
-
- <item>
- <p><file>/etc/dpkg/shlibs.default</file></p>
- <p>
- This file lists any shared libraries whose packages
- have failed to provide correct <file>shlibs</file> files.
- It was used when the <file>shlibs</file> setup was first
- introduced, but it is now normally empty. It is
- maintained by the <tt>dpkg</tt> maintainer.
- </p>
- </item>
- </list>
- </p>
- </sect1>
-
- <sect1>
- <heading>How to use <prgn>dpkg-shlibdeps</prgn> and the
- <file>shlibs</file> files</heading>
-
- <p>
- Put a call to <prgn>dpkg-shlibdeps</prgn> into your
- <file>debian/rules</file> file. If your package contains only
- compiled binaries and libraries (but no scripts), you can
- use a command such as:
- <example compact="compact">
-dpkg-shlibdeps debian/tmp/usr/bin/* debian/tmp/usr/sbin/* \
- debian/tmp/usr/lib/*
- </example>
- Otherwise, you will need to explicitly list the compiled
- binaries and libraries.<footnote>
- <p>
- If you are using <tt>debhelper</tt>, the
- <prgn>dh_shlibdeps</prgn> program will do this work for
- you. It will also correctly handle multi-binary
- packages.
- </p>
- </footnote>
- </p>
-
- <p>
- This command puts the dependency information into the
- <file>debian/substvars</file> file, which is then used by
- <prgn>dpkg-gencontrol</prgn>. You will need to place a
- <tt>${shlib:Depends}</tt> variable in the <tt>Depends</tt>
- field in the control file for this to work.
- </p>
-
- <p>
- If <prgn>dpkg-shlibdeps</prgn> doesn't complain, you're
- done. If it does complain you might need to create your own
- <file>debian/shlibs.local</file> file, as explained below (see
- <ref id="shlibslocal">).
- </p>
-
- <p>
- If you have multiple binary packages, you will need to call
- <prgn>dpkg-shlibdeps</prgn> on each one which contains
- compiled libraries or binaries. In such a case, you will
- need to use the <tt>-T</tt> option to the <tt>dpkg</tt>
- utilities to specify a different <file>substvars</file> file.
- For more details on this and other options, see <manref
- name="dpkg-shlibdeps" section="1">.
- </p>
- </sect1>
-
- <sect1 id="shlibs">
- <heading>The <file>shlibs</file> File Format</heading>
-
- <p>
- Each <file>shlibs</file> file has the same format. Lines
- beginning with <tt>#</tt> are considered to be comments and
- are ignored. Each line is of the form:
- <example compact="compact">
-<var>library-name</var> <var>soname-version-number</var> <var>dependencies ...</var>
- </example>
- </p>
-
- <p>
- We will explain this by reference to the example of the
- <tt>zlib1g</tt> package, which (at the time of writing)
- installs the shared library <file>/usr/lib/libz.so.1.1.3</file>.
- </p>
-
- <p>
- <var>library-name</var> is the name of the shared library,
- in this case <tt>libz</tt>. (This must match the name part
- of the soname, see below.)
- </p>
-
- <p>
- <var>soname-version-number</var> is the version part of the
- soname of the library. The soname is the thing that must
- exactly match for the library to be recognized by the
- dynamic linker, and is usually of the form
- <tt><var>name</var>.so.<var>major-version</var></tt>, in our
- example, <tt>libz.so.1</tt>.<footnote>
- <p>
- This can be determined using the command
- <example compact="compact">
-objdump -p /usr/lib/libz.so.1.1.3 | grep SONAME
- </example>
- </p>
- </footnote>
- The version part is the part which comes after
- <tt>.so.</tt>, so in our case, it is <tt>1</tt>.
- </p>
-
- <p>
- <var>dependencies</var> has the same syntax as a dependency
- field in a binary package control file. It should give
- details of which packages are required to satisfy a binary
- built against the version of the library contained in the
- package. See <ref id="depsyntax"> for details.
- </p>
-
- <p>
- In our example, if the first version of the <tt>zlib1g</tt>
- package which contained a minor number of at least
- <tt>1.3</tt> was <var>1:1.1.3-1</var>, then the
- <tt>shlibs</tt> entry for this library could say:
- <example compact="compact">
-libz 1 zlib1g (>= 1:1.1.3)
- </example>
- The version-specific dependency is to avoid warnings from
- the dynamic linker about using older shared libraries with
- newer binaries.
- </p>
- </sect1>
-
- <sect1>
- <heading>Providing a <file>shlibs</file> file</heading>
-
- <p>
- If your package provides a shared library, you should create
- a <file>shlibs</file> file following the format described above.
- It is usual to call this file <file>debian/shlibs</file> (but if
- you have multiple binary packages, you might want to call it
- <file>debian/shlibs.<var>package</var></file> instead). Then
- let <file>debian/rules</file> install it in the control area:
- <example compact="compact">
-install -m644 debian/shlibs debian/tmp/DEBIAN
- </example>
- or, in the case of a multi-binary package:
- <example compact="compact">
-install -m644 debian/shlibs.<var>package</var> debian/<var>package</var>/DEBIAN/shlibs
- </example>
- An alternative way of doing this is to create the
- <file>shlibs</file> file in the control area directly from
- <file>debian/rules</file> without using a <file>debian/shlibs</file>
- file at all,<footnote>
- <p>
- This is what <prgn>dh_makeshlibs</prgn> in the
- <tt>debhelper</tt> suite does.
- </p>
- </footnote>
- since the <file>debian/shlibs</file> file itself is ignored by
- <prgn>dpkg-shlibdeps</prgn>.
- </p>
-
- <p>
- As <prgn>dpkg-shlibdeps</prgn> reads the
- <file>DEBIAN/shlibs</file> files in all of the binary packages
- being built from this source package, all of the
- <file>DEBIAN/shlibs</file> files should be installed before
- <prgn>dpkg-shlibdeps</prgn> is called on any of the binary
- packages.
- </p>
- </sect1>
-
- <sect1 id="shlibslocal">
- <heading>Writing the <file>debian/shlibs.local</file> file</heading>
-
- <p>
- This file is intended only as a <em>temporary</em> fix if
- your binaries or libraries depend on a library whose package
- does not yet provide a correct <file>shlibs</file> file.
- </p>
-
- <p>
- We will assume that you are trying to package a binary
- <tt>foo</tt>. When you try running
- <prgn>dpkg-shlibdeps</prgn> you get the following error
- message (<tt>-O</tt> displays the dependency information on
- <tt>stdout</tt> instead of writing it to
- <tt>debian/substvars</tt>, and the lines have been wrapped
- for ease of reading):
- <example compact="compact">
-$ dpkg-shlibdeps -O debian/tmp/usr/bin/foo
-dpkg-shlibdeps: warning: unable to find dependency
- information for shared library libbar (soname 1,
- path /usr/lib/libbar.so.1, dependency field Depends)
-shlibs:Depends=libc6 (>= 2.2.2-2)
- </example>
- You can then run <prgn>ldd</prgn> on the binary to find the
- full location of the library concerned:
- <example compact="compact">
-$ ldd foo
-libbar.so.1 => /usr/lib/libbar.so.1 (0x4001e000)
-libc.so.6 => /lib/libc.so.6 (0x40032000)
-/lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x40000000)
- </example>
- So the <prgn>foo</prgn> binary depends on the
- <prgn>libbar</prgn> shared library, but no package seems to
- provide a <file>*.shlibs</file> file handling
- <file>libbar.so.1</file> in <file>/var/lib/dpkg/info/</file>. Let's
- determine the package responsible:
- <example compact="compact">
-$ dpkg -S /usr/lib/libbar.so.1
-bar1: /usr/lib/libbar.so.1
-$ dpkg -s bar1 | grep Version
-Version: 1.0-1
- </example>
- This tells us that the <tt>bar1</tt> package, version 1.0-1,
- is the one we are using. Now we can file a bug against the
- <tt>bar1</tt> package and create our own
- <file>debian/shlibs.local</file> to locally fix the problem.
- Including the following line into your
- <file>debian/shlibs.local</file> file:
- <example compact="compact">
-libbar 1 bar1 (>= 1.0-1)
- </example>
- should allow the package build to work.
- </p>
-
- <p>
- As soon as the maintainer of <tt>bar1</tt> provides a
- correct <file>shlibs</file> file, you should remove this line
- from your <file>debian/shlibs.local</file> file. (You should
- probably also then have a versioned <tt>Build-Depends</tt>
- on <tt>bar1</tt> to help ensure that others do not have the
- same problem building your package.)
- </p>
- </sect1>
-
- </sect>
-
- </chapt>
-
- <chapt id="opersys"><heading>The Operating System</heading>
-
- <sect>
- <heading>Filesystem hierarchy</heading>
-
-
- <sect1>
- <heading>Filesystem Structure</heading>
-
- <p>
- The location of all installed files and directories must
- comply with the Filesystem Hierarchy Standard (FHS),
- version 2.1, except where doing so would violate other
- terms of Debian Policy. The version of this document
- referred here can be found in the <tt>debian-policy</tt>
- package or on
- <url id="http://www.debian.org/doc/packaging-manuals/fhs/"
- name="FHS (Debian copy)"> alongside this manual (or, if
- you have the <package>debian-policy</package> installed,
- you can try <url
- id="file:///usr/share/doc/debian-policy/fhs/" name="FHS
- (local copy)">). The
- latest version, which may be a more recent version, may
- be found on
- <url id="http://www.pathname.com/fhs/" name="FHS (upstream)">.
- Specific questions about following the standard may be
- asked on the <tt>debian-devel</tt> mailing list, or
- referred to the FHS mailing list (see the
- <url id="http://www.pathname.com/fhs/" name="FHS web site"> for
- more information).
- </p>
- </sect1>
-
- <sect1>
- <heading>Site-specific programs</heading>
-
- <p>
- As mandated by the FHS, packages must not place any
- files in <file>/usr/local</file>, either by putting them in
- the file system archive to be unpacked by <prgn>dpkg</prgn>
- or by manipulating them in their maintainer scripts.
- </p>
-
- <p>
- However, the package may create empty directories below
- <file>/usr/local</file> so that the system administrator knows
- where to place site-specific files. These directories
- should be removed on package removal if they are
- empty.
- </p>
-
- <p>
- Note, that this applies only to directories <em>below</em>
- <file>/usr/local</file>, not <em>in</em> <file>/usr/local</file>.
- Packages must not create sub-directories in the directory
- <file>/usr/local</file> itself, except those listed in FHS,
- section 4.5. However, you may create directories below
- them as you wish. You must not remove any of the
- directories listed in 4.5, even if you created them.
- </p>
-
- <p>
- Since <file>/usr/local</file> can be mounted read-only from a
- remote server, these directories must be created and
- removed by the <prgn>postinst</prgn> and <prgn>prerm</prgn>
- maintainer scripts and not be included in the
- <file>.deb</file> archive. These scripts must not fail if
- either of these operations fail.
- </p>
-
- <p>
- For example, the <tt>emacsen-common</tt> package could
- contain something like
- <example compact="compact">
-if [ ! -e /usr/local/share/emacs ]
-then
- if mkdir /usr/local/share/emacs 2>/dev/null
- then
- chown root:staff /usr/local/share/emacs
- chmod 2775 /usr/local/share/emacs
- fi
-fi
- </example>
- in its <prgn>postinst</prgn> script, and
- <example compact="compact">
-rmdir /usr/local/share/emacs/site-lisp 2>/dev/null || true
-rmdir /usr/local/share/emacs 2>/dev/null || true
- </example>
- in the <prgn>prerm</prgn> script. (Note that this form is
- used to ensure that if the script is interrupted, the
- directory <file>/usr/local/share/emacs</file> will still be
- removed.)
- </p>
-
- <p>
- If you do create a directory in <file>/usr/local</file> for
- local additions to a package, you should ensure that
- settings in <file>/usr/local</file> take precedence over the
- equivalents in <file>/usr</file>.
- </p>
-
- <p>
- However, because <file>/usr/local</file> and its contents are
- for exclusive use of the local administrator, a package
- must not rely on the presence or absence of files or
- directories in <file>/usr/local</file> for normal operation.
- </p>
-
- <p>
- The <file>/usr/local</file> directory itself and all the
- subdirectories created by the package should (by default) have
- permissions 2775 (group-writable and set-group-id) and be
- owned by <tt>root.staff</tt>.
- </p>
- </sect1>
-
- <sect1>
- <heading>The system-wide mail directory</heading>
- <p>
- The system-wide mail directory is <file>/var/mail</file>. This
- directory is part of the base system and should not owned
- by any particular mail agents. The use of the old
- location <file>/var/spool/mail</file> is deprecated, even
- though the spool may still be physically located there.
- To maintain partial upgrade compatibility for systems
- which have <file>/var/spool/mail</file> as their physical mail
- spool, packages using <file>/var/mail</file> must depend on
- either <package>libc6</package> (>= 2.1.3-13), or on
- <package>base-files</package> (>= 2.2.0), or on later
- versions of either one of these packages.
- </p>
- </sect1>
- </sect>
-
- <sect>
- <heading>Users and groups</heading>
-
- <sect1>
- <heading>Introduction</heading>
- <p>
- The Debian system can be configured to use either plain or
- shadow passwords.
- </p>
-
- <p>
- Some user ids (UIDs) and group ids (GIDs) are reserved
- globally for use by certain packages. Because some
- packages need to include files which are owned by these
- users or groups, or need the ids compiled into binaries,
- these ids must be used on any Debian system only for the
- purpose for which they are allocated. This is a serious
- restriction, and we should avoid getting in the way of
- local administration policies. In particular, many sites
- allocate users and/or local system groups starting at 100.
- </p>
-
- <p>
- Apart from this we should have dynamically allocated ids,
- which should by default be arranged in some sensible
- order, but the behavior should be configurable.
- </p>
-
- <p>
- Packages other than <tt>base-passwd</tt> must not modify
- <file>/etc/passwd</file>, <file>/etc/shadow</file>,
- <file>/etc/group</file> or <file>/etc/gshadow</file>.
- </p>
- </sect1>
-
- <sect1>
- <heading>UID and GID classes</heading>
- <p>
- The UID and GID numbers are divided into classes as
- follows:
- <taglist>
- <tag>0-99:</tag>
- <item>
- <p>
- Globally allocated by the Debian project, the same
- on every Debian system. These ids will appear in
- the <file>passwd</file> and <file>group</file> files of all
- Debian systems, new ids in this range being added
- automatically as the <tt>base-passwd</tt> package is
- updated.
- </p>
-
- <p>
- Packages which need a single statically allocated
- uid or gid should use one of these; their
- maintainers should ask the <tt>base-passwd</tt>
- maintainer for ids.
- </p>
- </item>