[ previous ] [ Contents ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ 5 ] [ 6 ] [ next ]
This section describes the additions to the Debian Policy
that
are required for CLI packages.
For packages that consist of 100% managed code, "Architecture: all" must be chosen in debian/control.
Packages containing a mix of managed and native code must be "Architecure: any" or depending on the specific package a more restricted set of architectures is valid.
The package's applications, libraries and meta-data must be installed
into /usr/lib/packagename
.
Libraries that will be installed into the GAC should be installed into
/usr/lib/cli/packagename-X.Y
(for more details about the X.Y
version see GAC versioning). The
commonly seen /usr/lib/mono/packagename
path should only
be used for Mono project packages.
Never install native "glue" libraries into /usr/lib
,
instead install them at /usr/lib/cli/packagename-X.Y
. When moving
libraries update the references to the new location using a DLL Map. See the
Mono DLL maps secion for an
example.
The only exception here is for native libraries that are of wider use; can be
used other packages. Native libraries should be packaged according to the
Library
Packaging Guide
in a Debain Policy conformant way.
Never ever install application files (.exe
) directly into
/usr/bin
. Instead create a wrapper script into
/usr/bin
to allow them to be run without the .exe
suffix.
Source code files (*.cs
, *.vb
, *.boo
,
etc.) should be non-executable.
Library files (*.dll
) should be non-executable.
Debug symbol files (*.mdb
) should be non-executable.
Assembly config files (*.config
) should be non-executable.
Application files (*.exe
) must have the executable flag
(+x) set to enable compatiblity with direct invokation as
./foo.exe
using Linux binfmt.
To ensure that the file permissions are correct, use the following at the end
of the install target in debian/rules
:
find debian/ -type f -name "*.dll" -or -name "*.mdb" -or -name "*.cs" -or -name "*.config" | xargs chmod -x find debian/ -type f -name "*.exe" | xargs chmod +x
At a minimum, CLI packages must Build-Depends on
cli-common-dev
(>= 0.4.0) and the appropriate CLI compiler(s).
Current CLI compilers in Debian:
C#: mono-mcs
(>= 1.0) | c-sharp-compiler
C# 2.0: mono-gmcs
(>= 1.1.8) | c-sharp-2.0-compiler
Nemerle: nemerle
(>= 0.9)
Boo: boo
(>= 0.5.6)
Software that uses Mono via the C interface library (libmono.so
)
or requires the /usr/lib/pkgconfig/mono.pc
file must
Build-Depends on libmono-dev (>= 1.0)
Note that there are architectures for which no CLR is available and thus you may have to restrict the Build-Depends for your package to the architectures available.
If your package is Architecture: all
, you should specify this as
Build-Depends-Indep. Never put debhelper
, cdbs
or
dpatch
into Build-Depends-Indep. See the Debian
Policy Manual
for more information on this.
Libraries that are installed into the GAC should provide decent ABI stability and be useful for other packages. Otherwise, they should remain private to the package.
Libraries that are installed into the GAC must be strong-named, i.e. signed.
Each of the libraries in the GAC has an assembly version number that consists of 4 parts (major, minor, build and revision number). When loading libraries from the GAC all 4 parts and the public signing key fingerprint must match.
It is general practice and recommended
by Microsoft
that a library is ABI compatible when only the build
and revision number change and the major and minor number stay the same.
To reflect the ABI stability and prevent breakages when a ABI-incompatible
version is released, a similar solution for native
library packages
is used. The major and minor number must
mirror the SONAME version and the resulting package name should be
libfooX.Y-cil
, where X is the major and Y the minor number.
One notable exception for this naming are assemblies that end on a number
(Mono.C5 for example). In this case the package should be named
libfoo123-X.Y-cil
(i.e. libmono-c5-0.5-cil
) to
improve the readability.
The -cil
suffix is chosen to prevent confusion with native library
package names. Never use "sharp" in the package name as it does not
represent the language, and a CLI library can
be used with all CLI implemented / enabled
languages such as C#, Boo, Nemerle, J#, ASP.NET, VB.NET (full list
).
Unnecessary package renames should be avoided. Existing package names that do not follow this policy should not be renamed until the next incompatible ABI change when the new naming scheme should be used.
If the upstream software does not use major and minor number to reflect ABI
stability or breaks ABI with a change in build or revision, the package
must be renamed to either libfooA.B.C-cil
or
libfooA.B.C.D-cil
(where A, B, C, D are the complete assembly
version numbers), depending at which point (major or minor) where the breakage
occurred. All Policy Files must be
dropped at this stage until a new major or minor version is released.
The upstream software may use wildcards in the assembly versions (1.2.* for example) which are filled by the compiler with a random value. You must replace these wildcards with 0 (1.2.0.0 in the example) to make it possible to use Policy Files and make predictable version numbers.
More than one library can be installed in one package but it is required that they must all have the same version and belong together.
As explained above a exact match of the version number is required to load a
library from the GAC. To override this
behaviour and make different versions of ABI-compatible library packages really
ABI-compatible you have to use Policy
Files
. These files have to be named policy.X.Y.foo.dll
(where X and Y are the major and minor number of the assembly it should be
compatible with), it must be signed with the same signing key as the
original assembly and it must be installed into the GAC. For information on how to create policy
files look at the previous Policy Files link or at the example below.
Overriding the GAC policy should only be done when the different library versions are really ABI-compatible. You should also raise the version in the clilibs control file to the minimum version when new interfaces/classes/methods were added.
The clilibs
control file MUST be present in all GAC library packages. It can be created with
the dh_makeclilibs helper
script and has a format similar to the shlibs
file created by
dh_makeshlibs(1)
and also has a similar use: it is used by dh_clideps helper script to find the
correct dependencies.
You should always set the minimum required version of the library in the
clilibs
file.
Many libraries deliver a .pc
file for use by the
pkg-config
helper utility, which aids other libraries and
applications to link against libraries.
All GAC library packages should have a pkg-config .pc
file located
in /usr/lib/pkgconfig
. The filename must be named:
package-X.Y.pc
including the versioning. The version
must reflect the same X.Y version as the package name. There
should also be a symlink without the version to the latest version, as
follows: from package.pc
to package-X.Y.pc
When installing libraries into the GAC
signing is required. The signing key can either be supplied by upstream or you
have to create your own one using the sn
utility. This
must be put into your source package and used for all following
versions of the library.
This includes libraries that are not ABI-stable, may be not strong-named and are usually in an early stage of development. They must not include a clilibs control file.
The package should be named libfoo-cil
(without a version in the
package name) and libraries should not be installed into the GAC but only into
/usr/lib/packagename
.
Applications using non-GAC libraries must copy the libraries they need into their own application directory. You can compare this with static linking of native libraries.
[ previous ] [ Contents ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ 5 ] [ 6 ] [ next ]
Debian CLI Policy (DRAFT)
Version 0.4.2meebey@meebey.net
brandon@smarterits.com
slomo@ubuntu.com
debian@mfgames.com