[ previous ] [ Contents ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ 5 ] [ 6 ] [ next ]

Debian CLI Policy
Chapter 6 - Appendix

6.1 Helper Scripts: cli-common-dev

When using cli-common-dev and the included dh_* scripts packages must Build-Depends on cli-common-dev (>= 0.7) (this version may change later, when cli-common-dev has changes which are required to be used by all CLI packages, the CLI Policy version will represent such changes).

6.1.1 dh_makeclilibs

dh_makeclilibs is used to create the clilibs control files which are used later by dh_clideps for this or other packages. It must only be used when your package contains libraries that other packages may link against.

It has the same use (and very similar parameters) to dh_makeshlibs. You should always use the most minimal version necessary.

This program must be called before dh_clideps.

See dh_makeclilibs(1) for details.

6.1.2 dh_clideps

dh_clideps is used to discover the native and managed dependencies of the packages. It uses the clilibs control files, the .config of assemblies and the shlibs files created by dh_makeshlibs. The discovered dependencies are written into the ${cli:Depends} variable.

dh_shlibdeps must be run before dh_clideps. dh_makeshlibs and dh_makeclilibs must be run before dh_clideps. If not, when two binary packages from the same source package depend on one another, dh_clideps will not be able to determine the dependencies.

dh_clideps can remove duplicate dependencies created by running dh_clideps and dh_shlibsdeps when run given the -d parameter.

See dh_clideps(1) for details.

6.1.3 dh_installcligac

dh_installcligac is used to facilitate the installation of strong-named assemblies into the various caches installed on the user's machine. Its primary purpose is to install the assemblies at the point of installation instead of pre-packing them inside the Debian package; this is also known as late-GAC install.

To identify which assemblies need to be installed into the GAC, dh_installcligac uses the debian/installcligac or the debian/packagename.installcligac to list the assemblies to install or uninstall at installation or removal respectivly.

The file format of the installcligac is simple: the full installed path of every assembly to install into the GAC. For example, the liblog4net1.2-cil package would have this in the debian/installcligac file:

     /usr/lib/cli/log4net-1.2/log4net.dll

dh_installcligac needs to be called after dh_install and before dh_clideps. See dh_installcligac(1) for details.

6.2 Examples

6.2.1 debhelper 5/6 Example

For binary-arch packages:

     binary-arch: build install
     	...
     	dh_shlibdeps -a
     	dh_makeclilibs -a -V
     	dh_installcligac -a
     	dh_clideps -a
     	...

For binary-indep packages:

     binary-indep: build install
     	...
     	dh_makeclilibs -i -V
     	dh_installcligac -i
     	dh_clideps -i
     	...

6.2.2 debhelper 7 Example

With debhelper's 7 /usr/bin/dh you don't need to add any extra commands to debian/rules yourself as debhelper has an API that allows to extend it. cli-common-dev as of version 0.5.7 can extend debhelper 7 with all commands that are needed. You can enable this by passing "cli" to dh in debian/rules like this:

     %:
         dh $@ --with cli

That's it, you are done! :-)

6.2.3 cdbs Example

     common-binary-predeb-arch common-binary-predeb-indep::
     	dh_shlibdeps
     	dh_makeclilibs -V
     	dh_installcligac
     	dh_clideps

6.2.4 Executable Wrapper Script Example

     #!/bin/sh
     exec /usr/bin/cli /usr/lib/package/package.exe "$@"

6.2.5 API Compatibility Check Example

You need to install following packages for this example: mono-devel libmono-sharpzip0.6-cil libmono-sharpzip0.84-cil

     mono-api-check /usr/lib/mono/gac/ICSharpCode.SharpZipLib/0.6.0.0__1b03e6acf1164f73/ICSharpCode.SharpZipLib.dll \
        /usr/lib/mono/gac/ICSharpCode.SharpZipLib/0.84.0.0__1b03e6acf1164f73/ICSharpCode.SharpZipLib.dll
     CLI API Check
     Assembly Name:          ICSharpCode.SharpZipLib
     Missing Interfaces:     44
     Additional Interfaces:  79
     
     The two assemblies you compared are not API compatible!
     You must use a new package name!
     
     The new assembly has additional interfaces. You must raise
     the minimal version in clilibs!

The mono-api-check wrapper script checks whether there are new public/protected interfaces (where interface in this context means namespace, class, method, interface, delegate, etc) or any missing ones. When an interface is changed it will show up as missing and additional. You should follow the instructions, in this case you must create a new versioned package for the library and raise the minimal version number for the dh_makeclilibs call.

6.2.6 GAC Policy File Example

     <configuration>
        <runtime>
           <assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1">
            <dependentAssembly>
              <assemblyIdentity name="foo" publicKeyToken="35e10195dab3c99f" />
              <bindingRedirect oldVersion="1.2.0.0-1.2.10.0" newVersion="1.3.0.0"/>
            </dependentAssembly>
           </assemblyBinding>
        </runtime>
     </configuration>

The above example would be used for a policy file for the "foo" assembly and would tell the GAC that version 1.3.0.0 is compatible with versions 1.2.0.0 to 1.2.10.0. You have to compile and install it with

     al -link:policy.1.2.foo.config -out:policy.1.2.foo.dll -keyfile:path/to/keyfile
     gacutil /i policy.1.2.foo.dll

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.

6.3 Migrating Existing Packages

Many CLI packages already exist in Debian, or are in ITP, and conform to the deprecated Mono Conventions.

Any debian/rules hacks or patches that exist to redirect files to /usr/share/dotnet should be removed, and adjusted according to upstream file locations (/usr/lib). See Mono Debian Plan for the rationale behind this change.

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 mono-jit, mono-mint, mono-utils (this one had the dh_* helper scripts which are now in cli-common-dev) and libmono-dev (use this one only if the package really links against mono or requires the mono.pc file).