This manual is free software; you may redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version.
This is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose. See the GNU General Public License for more details.
A copy of the GNU General Public License is available as /usr/share/common-licenses/GPL in the Debian GNU/Linux distribution or on the World Wide Web at the GNU General Public Licence. You can also obtain it by writing to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
Here are the changes to the Debian CLI Policy document.
Changes from 0.5.1 to 0.7:
Changes from 0.5.0 to 0.5.1:
Changes from 0.4.4 to 0.5.0:
Changes from 0.4.2 to 0.4.3:
Changes from 0.4.1 to 0.4.2:
Changes from 0.4.0 to 0.4.1:
Changes from 0.3.0 to 0.4.0:
Changes from 0.2.1 to 0.3.0:
Changes from 0.2.0 to 0.2.1:
Changes from 0.1.1 to 0.2.0:
The ".NET" area uses its own set of abbreviations, which can look confusing to other people. This chapter lists some of the terms along with their explanations:
This is what most people mean when they say ".NET".
The CLI defines mainly the virtual machine, the bytecode and how everything
works together. It is both an
The CLR is an implementation of the
The CIL is the format of the bytecode for binaries and libraries
used by the
The ".NET" word is a Microsoft marketing phrase and mostly is a CLR with added Microsoft technologies like: ASP.NET, VB.NET, System.Windows.Forms, Passport plus a lot of other things.
We highly discourage from using any form of the word ".NET", it is
burdened by copyright and marketing. We advice to use the correct
term instead, which is usually
If you really want to use the ".NET" term in a correct form please refer to the
The GAC contains and manages the libraries for the
Mono stores the GAC at
DotGNU Portable.NET stores the GAC at
There are different set of package names we refer in this policy to.
Here a list of examples for the different names:
This section describes the additions to the
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
Libraries that will be installed into the GAC must be installed into
Example path for the
Never install native "glue" libraries into
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
You must not install application files (
Source code files (
Library files (
Debug symbol files (
Assembly config files (
Application files (
To ensure that all files have correct permissions, you should use Debhelper's
At a minimum, CLI packages should Build-Depends on
Current CLI compilers in Debian:
Current CLI SDKs in Debian:
Software that uses Mono via the C interface library
(
Note that there are architectures for which no
If your package is
Libraries that are installed into the
Libraries that are installed into the
Libraries must to be installed into the GAC at package install
time (postinst) which is provided by the
Each of the libraries in the
It is general practice and
The library package name must be prefixed with
To reflect the ABI stability and prevent breakages when a
ABI-incompatible version is released, a similar solution for
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
The
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, at which point 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
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
More than one library can be installed in one package but it is required that they must all have the same assembly version and belong together.
As explained above a exact match of the version number is required
to load a library from the
Overriding the
The
You should always set the minimum required version of the library in the
Many libraries deliver a
All GAC library packages should have a pkg-config
When installing libraries into the
Unnecessary ABI breakages should be avoided. Existing keys shipped by the source package should not be replaced (with mono.snk) until the next incompatible ABI change.
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
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.
This section offers help with common problems encountered when packaging Mono-specific applications for Debian.
The official name of the Mono Project is: Mono, mono:: or mono. To keep this consistent for users, it should always be called "Mono" (not MONO, mono, mono:: or mixed with the .NET name). The explanation of what Mono is, should be in the package long description.
Often times, upstream software developers are not packagers, and vice versa. Developers do not necessarily test their software with packaging issues in mind. The most common problem we see from this are missing DLL exceptions.
When Mono code invokes an external library, it usually calls something like [DllImport("foo")] which expands "foo" to a shared library name such as "libfoo.so" which is then searched for in the library search path.
In Debian and some other binary Linux distributions, packages are split into runtime and developer (-dev) packages. Since the versioned library libfoo.so.X is usually used at runtime, and libfoo.so is a symlink only used when building against the library, the libfoo.so symlink is in the libfoo-dev package.
When packaging an application which uses libfoo.so normal users should not need the -dev packages installed just to run the application. However, Mono defaults to looking for the unversioned libfoo.so, which is unavailable in the runtime package.
When the DLL map is missing or upstream forgets to install
the DLL map, it will result in a
This can be fixed by creating a DLL map for the application exe or for the library DLL that is trying to invoke libfoo.so. If libfoo.so is invoked by the DLL bar.dll, create an xml file, bar.dll.config to tell Mono which .so should be loaded at runtime. bar.dll.config should be installed to the same directory as bar.dll.
A config file can contain as many dllmap directives as are needed. If the upstream developer already ships a config file, but it is incomplete, you should create a patch against it in your package.
Most Mono software developers are very helpful people, and will readily accept patches to solve this type of bug if you bring it to their attention. Please be sure to inform them of all these changes.
The Mono runtime uses a shared directory, by default
There are 2 problems with this:
In these cases, the package building will fail, applications will hang, die with strange Mono runtime errors or segfault. This includes dh_clideps or dh_makeclilibs, since they run monodis.
The solution is to include
This section offers help to common problems encountered when packaging DotGNU Portable.NET-specific applications for Debian.
The official name of the DotGNU Portable.NET project is exactly that. To keep this consistent for users, it should be always called "DotGNU Portable.NET" (not pnet or Portable.NET). The explanation of what DotGNU Portable.NET is, should be in the package long description.
When using cli-common-dev and the included dh_* scripts packages must
Build-Depends on
dh_makeclilibs is used to create the
It has the same use (and very similar parameters) to
This program must be called before
See
See
To identify which assemblies need to be installed into the
GAC,
The file format of the
For binary-arch packages:
With debhelper's 7
You need to install following packages for this example: mono-devel libmono-sharpzip0.6-cil libmono-sharpzip0.84-cil
Keep in mind that the filenames must be policy.X.Y.foo.config and policy.X.Y.foo.dll where foo is the assembly name and X.Y is the major and minor version number you want to be compatible with.
Many CLI packages already exist in Debian, or are in ITP, and conform to
the deprecated
Any
Also, be sure to replace references to dh_netdepends, dh_makenetlibs, and ${net:Depends} with the newer names described in the policy above.
Please remove any build-deps on
NF^.m6p/ MHֱ/F_I.d/^d%F+=QТY_z{ is9~ \@9O cli-common-0.10+nmu1/policy-install 0000755 0000000 0000000 00000001752 13441477100 014130 0 ustar #!/bin/bash # This file is actually used to create and to remove entries from a # policy. It automatically removes old versions, and if there is a new # one, it installs it. This allows the system to remove the "best" one # and have it pick the second-best, if installed. # Variables ASSEMBLY=$1 VERSION=$2 COMBINED="$VERSION.$ASSEMBLY" POLICY="policy.$VERSION.$ASSEMBLY" # Remove the old policy, if we have one installed if [ -f /usr/share/cli-common/packages.d/$POLICY.installcligac ]; then /usr/share/cli-common/policy-remove $ASSEMBLY $VERSION > /dev/null fi # Choose the correct one for file in $(ls /usr/share/cli-common/policies.d/???-$COMBINED \ 2>/dev/null | sort -rn) do # Copy this one as a installcligac cp $file /usr/share/cli-common/packages.d/$POLICY.installcligac #echo "Installing GAC policy file ($POLICY) into available GACs" /usr/share/cli-common/gac-package-install $POLICY > /dev/null || exit 1 # We just deal with the one exit done cli-common-0.10+nmu1/policy-remove 0000755 0000000 0000000 00000000554 13441477100 013756 0 ustar #!/bin/sh set -e # This file is actually used to remove entries from a policy. # Variables ASSEMBLY=$1 VERSION=$2 COMBINED="$VERSION.$ASSEMBLY" POLICY="policy.$VERSION.$ASSEMBLY" #echo "Removing GAC policy file ($POLICY) from available GACs" /usr/share/cli-common/gac-package-remove $POLICY > /dev/null rm /usr/share/cli-common/packages.d/$POLICY.installcligac cli-common-0.10+nmu1/postinst-cliframework 0000644 0000000 0000000 00000000230 13441477100 015516 0 ustar if [ "$1" = "configure" ] && [ -x /usr/share/cli-common/framework-package-install ]; then /usr/share/cli-common/framework-package-install #PACKAGE# fi cli-common-0.10+nmu1/postinst-cligac 0000644 0000000 0000000 00000000214 13441477100 014255 0 ustar if [ "$1" = "configure" ] && [ -x /usr/share/cli-common/gac-package-install ]; then /usr/share/cli-common/gac-package-install #PACKAGE# fi cli-common-0.10+nmu1/postinst-cligacpolicy 0000644 0000000 0000000 00000000215 13441477100 015476 0 ustar if [ "$1" = "configure" ] && [ -x /usr/share/cli-common/policy-install ]; then /usr/share/cli-common/policy-install #ASSEMBLY# #VERSION# fi cli-common-0.10+nmu1/postrm-cligacpolicy 0000644 0000000 0000000 00000000241 13441477100 015136 0 ustar if [ "$1" = "remove" ] || [ "$1" = "upgrade" ] && [ -x /usr/share/cli-common/policy-remove ]; then /usr/share/cli-common/policy-remove #ASSEMBLY# #VERSION# fi cli-common-0.10+nmu1/prerm-cliframework 0000644 0000000 0000000 00000000253 13441477100 014765 0 ustar if [ "$1" = "remove" ] || [ "$1" = "upgrade" ] && [ -x /usr/share/cli-common/framework-package-remove ]; then /usr/share/cli-common/framework-package-remove #PACKAGE# fi cli-common-0.10+nmu1/prerm-cligac 0000644 0000000 0000000 00000000237 13441477100 013524 0 ustar if [ "$1" = "remove" ] || [ "$1" = "upgrade" ] && [ -x /usr/share/cli-common/gac-package-remove ]; then /usr/share/cli-common/gac-package-remove #PACKAGE# fi