[Pkg-mono-svn-commits] rev 2359 - cli-common/trunk
Sebastian Dröge
slomo-guest at costa.debian.org
Fri Mar 24 13:15:13 UTC 2006
Author: slomo-guest
Date: 2006-03-24 13:14:20 +0000 (Fri, 24 Mar 2006)
New Revision: 2359
Modified:
cli-common/trunk/cli-policy.sgml
Log:
* fix indendation
Modified: cli-common/trunk/cli-policy.sgml
===================================================================
--- cli-common/trunk/cli-policy.sgml 2006-03-24 06:19:26 UTC (rev 2358)
+++ cli-common/trunk/cli-policy.sgml 2006-03-24 13:14:20 UTC (rev 2359)
@@ -27,7 +27,7 @@
<copyright>
<copyrightsummary>
- Copyright © 2005-2006 Mirco Bauer, Brandon Hale and Sebastian Dröge.
+ Copyright © 2005-2006 Mirco Bauer, Brandon Hale and Sebastian Dröge.
</copyrightsummary>
<p>This manual is free software; you may redistribute it and/or modify it
@@ -57,11 +57,11 @@
<p>
Changes from 0.3.0 to 0.4.0:
<list>
- <item><ref id="build-deps">: Added nemerle to the compilers.</item>
- <item><ref id="packaging">: Added a packaging chapter that includes some of the old chapter and some new.</item>
- <item><ref id="gac-library-packaging">: Added informations about signing and policy files.</item>
- <item><ref id="dh_installcligac">: Added stub for the new dh_installcligac script. Must be filled with content soon.</item>
- <item><ref id="file-locations">: Require that files are installed into <file>/usr/lib/package</file> now.</item>
+ <item><ref id="build-deps">: Added nemerle to the compilers.</item>
+ <item><ref id="packaging">: Added a packaging chapter that includes some of the old chapter and some new.</item>
+ <item><ref id="gac-library-packaging">: Added informations about signing and policy files.</item>
+ <item><ref id="dh_installcligac">: Added stub for the new dh_installcligac script. Must be filled with content soon.</item>
+ <item><ref id="file-locations">: Require that files are installed into <file>/usr/lib/package</file> now.</item>
</list>
</p>
<p>
@@ -101,260 +101,362 @@
<chapt>
<heading>Used Terms</heading>
- <p>The ".NET" area uses an own set of abbreviations, which can
- look confusing to other people.
- Here a short list with their explanations:</p>
+ <p>
+ The ".NET" area uses an own set of abbreviations, which can
+ look confusing to other people.
+ Here a short list with their explanations:
+ </p>
<sect id="CLI">
<heading>CLI - Common Language Infrastructure</heading>
- <p>This is what most people mean when they say ".NET".
- The CLI defines mainly the virtual machine, bytecode and how everything
- works together and is an <url id="http://www.iso.org/iso/en/CatalogueDetailPage.CatalogueDetail?CSNUMBER=36769" name="ISO"> and <url id="http://www.ecma-international.org/publications/standards/Ecma-335.htm" name="ECMA"> standard.</p>
+ <p>
+ This is what most people mean when they say ".NET".
+ The CLI defines mainly the virtual machine, bytecode and how everything
+ works together and is an <url
+ id="http://www.iso.org/iso/en/CatalogueDetailPage.CatalogueDetail?CSNUMBER=36769" name="ISO">
+ and <url id="http://www.ecma-international.org/publications/standards/Ecma-335.htm" name="ECMA">
+ standard.
+ </p>
</sect>
<sect id="CLR">
<heading>CLR - Common Language Runtime</heading>
- <p>The CLR is an implementation of the <qref id="CLI">CLI</qref> (often with a lot of addons/tools
- for developers), like Mono or Microsoft .NET Framework is.</p>
+ <p>
+ The CLR is an implementation of the <qref id="CLI">CLI</qref> (often with a lot of addons/tools
+ for developers), like Mono or Microsoft .NET Framework is.
+ </p>
</sect>
<sect id="CIL">
<heading>CIL - Common Intermediate Language</heading>
- <p>CIL is the format of the bytecode (for binaries and libraries)
- used by <qref id="CLI">CLI</qref>.</p>
+ <p>
+ CIL is the format of the bytecode (for binaries and libraries)
+ used by <qref id="CLI">CLI</qref>.
+ </p>
</sect>
<sect id=".NET">
<heading>".NET" or long "Microsoft .NET Framework"</heading>
- <p>The word .NET is a marketing word by Microsoft, which is basically a
- CLR with added Microsoft technologies like: ASP.NET, VB.NET,
- System.Windows.Forms, Passport and a lot of other things.<p>
+ <p>
+ The word .NET is a marketing word by Microsoft, which is basically a
+ CLR with added Microsoft technologies like: ASP.NET, VB.NET,
+ System.Windows.Forms, Passport and a lot of other things.
+ <p>
- <p><strong>We highly discourage from using any form of the word ".NET", it is
- burdened by copyright and marketing.</strong> We advice to use the correct
- term instead, which is usually <qref id="CLI">CLI</qref>.</p>
+ <p>
+ <strong>We highly discourage from using any form of the word ".NET", it is
+ burdened by copyright and marketing.</strong> We advice to use the correct
+ term instead, which is usually <qref id="CLI">CLI</qref>.
+ </p>
- <p>If you really want to use the ".NET" term in a correct form please refer to the
- <url id="http://www.microsoft.com/mscorp/ip/trademarks/netguide.asp" name="Microsoft .NET Guidelines"></p>
+ <p>
+ If you really want to use the ".NET" term in a correct form please refer to the
+ <url id="http://www.microsoft.com/mscorp/ip/trademarks/netguide.asp" name="Microsoft .NET Guidelines">.
+ </p>
</sect>
<sect id="GAC">
<heading>GAC - Global Assembly Cache</heading>
- <p>The GAC contains and manages the libraries for the <qref id="CLR">CLR</qref>.
- It allows users to install multiple versions of the same library and load
- the right version when an application is executed.</p>
- <p>Mono stores the GAC at <file>/usr/lib/mono/gac</file></p>
- <p>Portable.NET stores the GAC at <file>/usr/lib/cscc/lib</file></p>
+ <p>
+ The GAC contains and manages the libraries for the <qref id="CLR">CLR</qref>.
+ It allows users to install multiple versions of the same library and load
+ the right version when an application is executed.
+ </p>
+ <p>
+ Mono stores the GAC at <file>/usr/lib/mono/gac</file>
+ </p>
+ <p>
+ Portable.NET stores the GAC at <file>/usr/lib/cscc/lib</file>
+ </p>
</sect>
</chapt>
<chapt id="packaging">
<heading>Packaging Policy</heading>
- <p>This section describes which additions to the
- <url id="http://www.debian.org/doc/debian-policy/" name="Debian Policy">
- are required for <qref id="CLI">CLI</qref> packages.</p>
+ <p>
+ This section describes which additions to the
+ <url id="http://www.debian.org/doc/debian-policy/" name="Debian Policy">
+ are required for <qref id="CLI">CLI</qref> packages.
+ </p>
<sect id="general-packaging">
<heading>General Packaging</heading>
<sect1 id="architecture">
<heading>Architecture</heading>
- <p>For packages that consist of 100% managed code "Architecure: all" must be chosen.</p>
- <p>Packages containing a mix of managed and native code must be "Architecure: any" or
- depending on the specific package also a restricted set of architectures is valid.</p>
+
+ <p>
+ For packages that consist of 100% managed code "Architecure: all" must be chosen.
+ </p>
+ <p>
+ Packages containing a mix of managed and native code must be "Architecure: any" or
+ depending on the specific package also a restricted set of architectures is valid.
+ </p>
</sect1>
<sect1 id="file-locations">
<heading>File Locations</heading>
- <p>The package's libraries and executables must be installed in
- <file>/usr/lib/packagename</file>. The often seen
- <file>/usr/lib/mono/packagename</file> is wrong and should only be used for packages
- by the Mono project.</p>
- <p>The only exception here are obviously native libraries that are of any use for
- other packages. They should be packaged according to the <url
- id="http://www.netfort.gr.jp/~dancer/column/libpkg-guide/libpkg-guide.html"
- name="Library Packaging Guide"> or any other policy conform way.</p>
- <p>Never put "glue" libraries into <file>/usr/lib</file> but move them to
- <file>/usr/lib/packagename</file>, too. When moving them you in general have to specify
- the new location (see the <qref id="dll-maps-intro"> Mono dllmaps</qref> for an example).</p>
- <p>For <file>.exe</file> files a <qref id="wrapper-script-example">wrapper script</qref>
- should be installed into <file>/usr/bin</file> to allow normal execution.
- Never ever install <file>.exe</file> files directly into <file>/usr/bin</file>.</p>
+
+ <p>The package's libraries and executables must be installed in
+ <file>/usr/lib/packagename</file>. The often seen
+ <file>/usr/lib/mono/packagename</file> is wrong and should only be used for packages
+ by the Mono project.
+ </p>
+
+ <p>
+ The only exception here are obviously native libraries that are of any use for
+ other packages. They should be packaged according to the <url
+ id="http://www.netfort.gr.jp/~dancer/column/libpkg-guide/libpkg-guide.html"
+ name="Library Packaging Guide"> or any other policy conform way.
+ </p>
+
+ <p>
+ Never put "glue" libraries into <file>/usr/lib</file> but move them to
+ <file>/usr/lib/packagename</file>, too. When moving them you in general have to specify
+ the new location (see the <qref id="dll-maps-intro"> Mono dllmaps</qref> for an example).
+ </p>
+
+ <p>
+ For <file>.exe</file> files a <qref id="wrapper-script-example">wrapper script</qref>
+ should be installed into <file>/usr/bin</file> to allow normal execution.
+ Never ever install <file>.exe</file> files directly into <file>/usr/bin</file>.
+ </p>
</sect1>
<sect1 id="file-perms">
- <heading>File Permissions</heading>
-
- <p>Source code files (*.cs, *.vb, *.boo, etc) should be non-executable.</p>
- <p>Library files (*.dll) should be non-executable.<p>
- <p>Debug symbol files (*.mdb) should be non-executable.<p>
- <p>Assembly config files (*.config) should be non-executable.<p>
-
- <p>Application files (*.exe) must have the executable flag (+x) set to be
- compatibile with binfmt (direct invokation like ./foo.exe).</p>
-
- <p>To insure that the file permissions are right, you should call the
- following at the end of your install target in debian/rules:
- <example>
- 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
- </example>
- </p>
+ <heading>File Permissions</heading>
+
+ <p>
+ Source code files (*.cs, *.vb, *.boo, etc) should be non-executable.
+ </p>
+ <p>
+ Library files (*.dll) should be non-executable.
+ </p>
+ <p>
+ Debug symbol files (*.mdb) should be non-executable.
+ </p>
+ <p>
+ Assembly config files (*.config) should be non-executable.
+ </p>
+
+ <p>
+ Application files (*.exe) must have the executable flag (+x) set to be
+ compatibile with binfmt (direct invokation like ./foo.exe).
+ </p>
+
+ <p>
+ To insure that the file permissions are right, you should call the
+ following at the end of your install target in debian/rules:
+ <example>
+ 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
+ </example>
+ </p>
</sect1>
<sect1 id="build-deps">
<heading>Build Dependencies</heading>
- <p>At a minimum, CLI packages must build-depend on
- <package>cli-common</package> (>= 0.2.0) and the compiler.</p>
-
- <p>Current CLI compilers in Debian:
- <list>
- <item>
- C#: <package>mono-mcs</package> (>= 1.0) | c-sharp-compiler
- </item>
- <item>
- C# 2.0: <package>mono-gmcs</package> (>= 1.1.8) | c-sharp-2.0-compiler
- </item>
- <item>
- Nemerle: <package>nemerle</package> (>= 0.9)
- </item>
- <item>
- Boo: <package>boo</package> (>= 0.5.6)
- </item>
- </list>
- </p>
-
- <p>Software that access Mono via the C interface (libmono.so) or requires
- the mono.pc file must build-depend also on: libmono-dev (>= 1.0)</p>
+
+ <p>
+ At a minimum, CLI packages must build-depend on
+ <package>cli-common</package> (>= 0.2.0) and the compiler.
+ </p>
+
+ <p>
+ Current CLI compilers in Debian:
+ <list>
+ <item>
+ C#: <package>mono-mcs</package> (>= 1.0) | c-sharp-compiler
+ </item>
+ <item>
+ C# 2.0: <package>mono-gmcs</package> (>= 1.1.8) | c-sharp-2.0-compiler
+ </item>
+ <item>
+ Nemerle: <package>nemerle</package> (>= 0.9)
+ </item>
+ <item>
+ Boo: <package>boo</package> (>= 0.5.6)
+ </item>
+ </list>
+ </p>
+
+ <p>
+ Software that access Mono via the C interface (libmono.so) or requires
+ the mono.pc file must build-depend also on: libmono-dev (>= 1.0)
+ </p>
+
+ <p>
+ Keep in mind that there are architectures for which no <qref id="CLR">CLR</qref> is
+ available. You may have to restrict the Build-Depends to some architectures when your
+ package is required on that architectures, too.
+ </p>
- <p>Keep in mind that there are architectures for which no <qref id="CLR">CLR</qref> is
- available. You may have to restrict the Build-Depends to some architectures when your
- package is required on that architectures, too.</p>
-
- <p>If your package is Arch: all, you should specify this as Build-Depends-Indep.
- Never put <package>debhelper</package>, <package>cdbs</package> or <package>dpatch</package>
- into Build-Depends-Indep (See the <url
- id="http://www.debian.org/doc/debian-policy/ch-relationships.html#s-sourcebinarydeps"
- name="Debian Policy Manual"> for more informations on this).</p>
+ <p>
+ If your package is Arch: all, you should specify this as Build-Depends-Indep.
+ Never put <package>debhelper</package>, <package>cdbs</package> or <package>dpatch</package>
+ into Build-Depends-Indep (See the <url
+ id="http://www.debian.org/doc/debian-policy/ch-relationships.html#s-sourcebinarydeps"
+ name="Debian Policy Manual"> for more informations on this).
+ </p>
</sect1>
</sect>
<sect id="gac-library-packaging">
<heading>GAC Library Packaging</heading>
- <p>These are libraries that are installed into the <qref id="GAC">GAC</qref>.
- They should provide at least provide decent ABI stability and should be
- useful for other packages too.</p>
+ <p>
+ These are libraries that are installed into the <qref id="GAC">GAC</qref>.
+ They should provide at least provide decent ABI stability and should be
+ useful for other packages too.
+ </p>
<sect1 id="gac-naming-versioning">
<heading>Naming & Versioning</heading>
- <p>Libraries that are installed into the <qref id="GAC">GAC</qref> must be
- strong-named, i.e. <qref id="signing">signed</qref>.</p>
+ <p>
+ Libraries that are installed into the <qref id="GAC">GAC</qref> must be
+ strong-named, i.e. <qref id="signing">signed</qref>.
+ </p>
+
+ <p>
+ Each of this library in the <qref id="GAC">GAC</qref> has
+ a assembly version number that consists of 4 parts (major, minor, build
+ and revision number). When loading libraries from the
+ <qref id="GAC">GAC</qref> it is required that all 4 parts and the public
+ signing key fingerprint are exactly the same.
+ </p>
+
+ <p>
+ It's general practice and <url
+ id="http://msdn.microsoft.com/netframework/programming/deployment/default.aspx?pull=/library/en-us/dndotnet/html/dplywithnet.asp#dplywithnet_version"
+ name="recommended"> by Microsoft that a library has to stay ABI compatible when only the
+ build and revision number change and the major and minor number stay the same.
+ </p>
+
+ <p>
+ To reflect the ABI stability and prevent
+ breakages when a ABI incompatible version is release a similar solution as
+ for <url
+ id="http://www.netfort.gr.jp/~dancer/column/libpkg-guide/libpkg-guide.html#naminglibpkg"
+ name="native library packages"> is chosen. The major and minor number mirror
+ the SONAME and the resulting package name is libfooX.Y-cil, where X is the
+ major and Y the minor number.
+ </p>
+
+ <p>
+ The -cil suffix is chosen to prevent confusion
+ with native library packages. You should never use "sharp" in the package
+ name as it doesn't represent the language and a <qref id="CLI">CLI</qref>
+ library can be used with all <qref id="CLI">CLI</qref> implemented/enabled
+ languages like C#, Boo, Nemerle, J#, ASP.NET, VB.NET (<url
+ id="http://www.mono-project.com/Languages" name="full list">).
+ </p>
- <p>Each of this library in the <qref id="GAC">GAC</qref> has
- a assembly version number that consists of 4 parts (major, minor, build
- and revision number). When loading libraries from the
- <qref id="GAC">GAC</qref> it is required that all 4 parts and the public
- signing key fingerprint are exactly the same.</p>
-
- <p>It's general practice and <url
- id="http://msdn.microsoft.com/netframework/programming/deployment/default.aspx?pull=/library/en-us/dndotnet/html/dplywithnet.asp#dplywithnet_version"
- name="recommended"> by Microsoft that a library has to stay ABI compatible when only the
- build and revision number change and the major and minor number stay the same.</p>
- <p>
- To reflect the ABI stability and prevent
- breakages when a ABI incompatible version is release a similar solution as
- for <url
- id="http://www.netfort.gr.jp/~dancer/column/libpkg-guide/libpkg-guide.html#naminglibpkg"
- name="native library packages"> is chosen. The major and minor number mirror
- the SONAME and the resulting package name is libfooX.Y-cil, where X is the
- major and Y the minor number.</p>
-
- <p>The -cil suffix is chosen to prevent confusion
- with native library packages. You should never use "sharp" in the package
- name as it doesn't represent the language and a <qref id="CLI">CLI</qref>
- library can be used with all <qref id="CLI">CLI</qref> implemented/enabled
- languages like C#, Boo, Nemerle, J#, ASP.NET, VB.NET (<url
- id="http://www.mono-project.com/Languages" name="full list">).</p>
-
- <p>To avoid un-necessary renamings, existing package names will not be changed but when the ABI changes,
- the new naming scheme must be used.</p>
-
- <p>When upstream doesn't use the major and minor number to reflect ABI stability
- or breaks ABI with a change in build or revision the package must be renamed
- to libfooA.B.C.D-cil (where A, B, C, D is the complete assembly version) and all
- <qref id="policy-files">Policy Files </qref> must be dropped until a new major or minor
- version is released.</p>
-
- <p>Upstream could 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
- <qref id="policy-files">Policy Files</qref> and make predictable version numbers</p>
-
- <p>It is allowed to put more than one library into one package. But in that case it is required
- that they all have the same version and belong together.</p>
+ <p>
+ To avoid un-necessary renamings, existing package names will not be changed but when the ABI changes,
+ the new naming scheme must be used.
+ </p>
+
+ <p>
+ When upstream doesn't use the major and minor number to reflect ABI stability
+ or breaks ABI with a change in build or revision the package must be renamed
+ to libfooA.B.C.D-cil (where A, B, C, D is the complete assembly version) and all
+ <qref id="policy-files">Policy Files </qref> must be dropped until a new major or minor
+ version is released.
+ </p>
+
+ <p>
+ Upstream could 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
+ <qref id="policy-files">Policy Files</qref> and make predictable version numbers.
+ </p>
+
+ <p>
+ It is allowed to put more than one library into one package. But in that case it is required
+ that they all have the same version and belong together.
+ </p>
</sect1>
<sect1 id="gac-installation">
<heading>Installation into the GAC</heading>
- <p>For the actual installing into the <qref id="GAC">GAC</qref> see
- <qref id="dh_installcligac">dh_installcligac</qref> and <manref name="gacutil" section="1">.</p>
- <p>You should never (except in rare corner cases) install files directly into the <qref id="GAC">GAC</qref>
- but leave it to the postinst and prerm scripts to install the libraries into all available
- <qref id="GAC">GAC</qref>.</p>
+ <p>For the actual installing into the <qref id="GAC">GAC</qref> see
+ <qref id="dh_installcligac">dh_installcligac</qref> and <manref name="gacutil" section="1">.
+ </p>
+
+ <p>
+ You should never (except in rare corner cases) install files directly into the <qref id="GAC">GAC</qref>
+ but leave it to the postinst and prerm scripts to install the libraries into all available
+ <qref id="GAC">GAC</qref>.
+ </p>
</sect1>
<sect1 id="policy-files">
<heading>Policy Files</heading>
- <p>As explained above a exact match of the version number is required
- to load from the <qref id="GAC">GAC</qref>. To override this behaviour
- and make different versions of ABI compatible library packages really
- ABI compatible you have to use <url
- id="http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpguide/html/cpconcreatingpublisherpolicyfile.asp"
- name="Policy Files">. They have to be called policy.X.Y.foo.dll (where X and Y
- are the major and minor number of the assembly it should be compatible with),
- must be signed with the same signing key as the original assembly and installed
- into the <qref id="GAC">GAC</qref>. For informations how to create them
- look at the site linked above or look at the <qref id="policy-file-example">example</qref>
- below.</p>
-
- <p>You should only override the <qref id="GAC">GAC</qref> policy when the
- different versions are really ABI compatible. Also you should raise the minimal version
- in the <qref id="clilibs-control-file">clilibs control file</qref> when there were
- new interfaces/classes/methods added.</p>
-
+ <p>
+ As explained above a exact match of the version number is required
+ to load from the <qref id="GAC">GAC</qref>. To override this behaviour
+ and make different versions of ABI compatible library packages really
+ ABI compatible you have to use <url
+ id="http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpguide/html/cpconcreatingpublisherpolicyfile.asp"
+ name="Policy Files">. They have to be called policy.X.Y.foo.dll (where X and Y
+ are the major and minor number of the assembly it should be compatible with),
+ must be signed with the same signing key as the original assembly and installed
+ into the <qref id="GAC">GAC</qref>. For informations how to create them
+ look at the site linked above or look at the <qref id="policy-file-example">example</qref>
+ below.
+ </p>
+
+ <p>
+ You should only override the <qref id="GAC">GAC</qref> policy when the
+ different versions are really ABI compatible. Also you should raise the minimal version
+ in the <qref id="clilibs-control-file">clilibs control file</qref> when there were
+ new interfaces/classes/methods added.
+ </p>
+
</sect1>
<sect1 id="clilibs-control-file">
<heading>clilibs Control File</heading>
- <p>The clilibs control file must be present in all <qref id="GAC">GAC</qref> library
- packages. It can be created with the <qref id="dh_makeclilibs">dh_makeclilibs</qref>
- helper script and has a format similar to the shlibs file created by <manref name="dh_makeshlibs"
- section="1"> and also a similar use: it is used by <qref id="dh_clideps">dh_clideps</qref>
- to find the correct dependencies.</p>
- <p>You should always set the least required version of the library here.</p>
+ <p>
+ The clilibs control file must be present in all <qref id="GAC">GAC</qref> library
+ packages. It can be created with the <qref id="dh_makeclilibs">dh_makeclilibs</qref>
+ helper script and has a format similar to the shlibs file created by <manref name="dh_makeshlibs"
+ section="1"> and also a similar use: it is used by <qref id="dh_clideps">dh_clideps</qref>
+ to find the correct dependencies.
+ </p>
+
+ <p>
+ You should always set the least required version of the library here.
+ </p>
</sect1>
<sect1 id="signing">
<heading>Signing</heading>
- <p>When installing libraries into the <qref id="GAC">GAC</qref> 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 package and used for all following versions of the library.</p>
+ <p>
+ When installing libraries into the <qref id="GAC">GAC</qref> 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 package and used for all following versions of the library.
+ </p>
</sect1>
</sect>
<sect id="non-gac-library-packaging">
<heading>non-GAC Library Packaging</heading>
- <p>This includes libraries that are in no way ABI stable, may be not strong-named
- and are usually in an early stage of development. They must not include a clilibs
- control file!</p>
+ <p>
+ This includes libraries that are in no way ABI stable, may be not strong-named
+ and are usually in an early stage of development. They must not include a clilibs
+ control file!
+ </p>
<sect1 id="non-gac-naming">
<heading>Naming</heading>
- <p>The package should be named libfoo-cil (without a version in the package name)
- and should not be installed into the <qref id="GAC">GAC</qref> but only
- into <file>/usr/lib/packagename</file>.
- <p>Applications using them must copy the libraries they need into their own package
- library directory. You can compare this with static linking of native libraries</p>
+ <p>
+ The package should be named libfoo-cil (without a version in the package name)
+ and should not be installed into the <qref id="GAC">GAC</qref> but only
+ into <file>/usr/lib/packagename</file>.
+ <p>
+ Applications using them must copy the libraries they need into their own package
+ library directory. You can compare this with static linking of native libraries
+ </p>
</sect1>
</sect>
</chapt>
@@ -362,18 +464,24 @@
<chapt id="migrating">
<heading>Migrating Existing Packages</heading>
- <p>Many CLI packages already exist in Debian, or are in ITP, and conform to
- the deprecated <url id="http://wiki.debian.net/?MonoConventions"
- name="Mono Conventions">.</p>
+ <p>
+ Many CLI packages already exist in Debian, or are in ITP, and conform to
+ the deprecated <url id="http://wiki.debian.net/?MonoConventions"
+ name="Mono Conventions">.
+ </p>
- <p>Any <file>debian/rules</file> hacks or patches that exist to redirect
- files to <file>/usr/share/dotnet</file> should be removed, and adjusted
- according to upstream file locations (<file>/usr/lib</file>). See
- <url id="http://wiki.debian.net/?MonoDebianPlan" name="Mono Debian Plan">
- for the rationale behind this change.</p>
+ <p>
+ Any <file>debian/rules</file> hacks or patches that exist to redirect
+ files to <file>/usr/share/dotnet</file> should be removed, and adjusted
+ according to upstream file locations (<file>/usr/lib</file>). See
+ <url id="http://wiki.debian.net/?MonoDebianPlan" name="Mono Debian Plan">
+ for the rationale behind this change.
+ </p>
- <p>Also, be sure to replace references to dh_netdepends, dh_makenetlibs, and
- ${net:Depends} with the CLI functions detailed above.</p>
+ <p>
+ Also, be sure to replace references to dh_netdepends, dh_makenetlibs, and
+ ${net:Depends} with the CLI functions detailed above.
+ </p>
<p>
Please remove any build-deps on <package>mono-jit</package>,
@@ -384,93 +492,117 @@
file).
</p>
- <p>Do not use the cli-wrapper (<file>/usr/bin/cli-wrapper</file>) anymore.
- It is deprecated and will be removed soon! Either use the upstream shell
- script to invoke the application or write one, which calls
- <file>/usr/bin/mono</file> or <file>/usr/bin/cli</file> (if it runs also
- on other CLRs like <url id="http://www.southern-storm.com.au/portable_net.html"
- name="Portable.NET">).</p>
+ <p>
+ Do not use the cli-wrapper (<file>/usr/bin/cli-wrapper</file>) anymore.
+ It is deprecated and will be removed soon! Either use the upstream shell
+ script to invoke the application or write one, which calls
+ <file>/usr/bin/mono</file> or <file>/usr/bin/cli</file> (if it runs also
+ on other CLRs like <url id="http://www.southern-storm.com.au/portable_net.html"
+ name="Portable.NET">).
+ </p>
</chapt>
<chapt id="mono">
<heading>Mono Specifics</heading>
- <p>This section will offer workarounds to common problems encountered when
- packaging Mono-specific applications for Debian.</p>
+ <p>
+ This section will offer workarounds to common problems encountered when
+ packaging Mono-specific applications for Debian.
+ </p>
<sect>
<heading>Naming</heading>
- <p>The official name of the Mono Project is: Mono, mono:: or mono.
- To keep it unified (more transparent to the user) it should be <em>always
- </em> called "Mono", not MONO, not mono, not mono:: even no
- mixing with .NET in it. The explanation of Mono goes into the package
- <em>long</em> description.</p>
+ <p>
+ The official name of the Mono Project is: Mono, mono:: or mono.
+ To keep it unified (more transparent to the user) it should be <em>always
+ </em> called "Mono", not MONO, not mono, not mono:: even no
+ mixing with .NET in it. The explanation of Mono goes into the package
+ <em>long</em> description.
+ </p>
</sect>
<sect>
<heading>DLL Maps</heading>
- <p>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.</p>
+ <p>
+ 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.
+ </p>
<sect1 id="dll-maps-intro">
<heading>Introduction</heading>
- <p>When Mono code invokes an external library, it usually calls
- something like [DllImport("foo")]. "foo" is expanded to libfoo.so, and
- searched for in your library path.</p>
+ <p>
+ When Mono code invokes an external library, it usually calls
+ something like [DllImport("foo")]. "foo" is expanded to libfoo.so, and
+ searched for in your library path.
+ </p>
- <p>In Debian and some other binary Linux distributions, packages are
- split into runtime and -dev packages. Since the versioned library
- libfoo.so.X is usually used at runtime, and .so is a symlink only used
- at build time, .so is moved to the -dev package.</p>
+ <p>
+ In Debian and some other binary Linux distributions, packages are
+ split into runtime and -dev packages. Since the versioned library
+ libfoo.so.X is usually used at runtime, and .so is a symlink only used
+ at build time, .so is moved to the -dev package.
+ </p>
- <p>When packaging an application which uses libfoo, we don't want
- normal users to need to need the -dev packages just to run the
- application. As you saw above, however, Mono defaults to looking for
- the unversioned .so, which is unavailable in the runtime packages.</p>
+ <p>
+ When packaging an application which uses libfoo, we don't want
+ normal users to need to need the -dev packages just to run the
+ application. As you saw above, however, Mono defaults to looking for
+ the unversioned .so, which is unavailable in the runtime packages.
+ </p>
- <p>When the dll map is missing or upstream forgot the dllmap, it will
- result in a <url id="http://www.mono-project.com/DllNotFoundException"
- name="DllNotFoundException">. This will stop the execution of the
- program.</p>
+ <p>
+ When the dll map is missing or upstream forgot the dllmap, it will
+ result in a <url id="http://www.mono-project.com/DllNotFoundException"
+ name="DllNotFoundException">. This will stop the execution of the
+ program.
+ </p>
</sect1>
<sect1>
- <heading>Solution</heading>
-
- <p>We can fix this by creating a dll map to the exe or dll that is
- trying to invoke libfoo.
- If libfoo is invoked by the dll bar.dll, we will create an xml file,
- bar.dll.config to tell Mono which .so we really want to load at runtime.
- bar.dll.config should be installed to the same directory as bar.dll.</p>
+ <heading>Solution</heading>
+
+ <p>
+ We can fix this by creating a dll map to the exe or dll that is
+ trying to invoke libfoo.
+ If libfoo is invoked by the dll bar.dll, we will create an xml file,
+ bar.dll.config to tell Mono which .so we really want to load at runtime.
+ bar.dll.config should be installed to the same directory as bar.dll.
+ </p>
<p>
<example>
- <configuration>
- <dllmap dll="foo" target="libfoo.so.0"/>
- </configuration>
+ <configuration>
+ <dllmap dll="foo" target="libfoo.so.0"/>
+ </configuration>
</example>
</p>
- <p>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.</p>
+ <p>
+ 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.
+ </p>
- <p>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.</p>
+ <p>
+ 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.
+ </p>
</sect1>
</sect>
<sect>
<heading>MONO_SHARED_DIR</heading>
- <p>The Mono runtime uses a shared directory, by default
- <file>~/.wapi</file>. This directory will be created/used when any CLI
- application is executed (like the C# compiler mcs).</p>
+ <p>
+ The Mono runtime uses a shared directory, by default
+ <file>~/.wapi</file>. This directory will be created/used when any CLI
+ application is executed (like the C# compiler mcs).
+ </p>
<p>
Here comes 2 problems with it:
@@ -483,34 +615,42 @@
</list>
</p>
- <p>Means when you don't set MONO_SHARED_DIR explicitly, the package
- building will fail! Applications will either hang, die with strange Mono
- runtime errors or segfault (for instance dh_clideps or dh_makeclideps,
- they use monodis).
- So change the MONO_SHARED_DIR by calling
- <example>
- export MONO_SHARED_DIR=$(CURDIR)
- </example>
- in the debian/rules file.</p>
- <p>The clean target should later remove $(MONO_SHARED_DIR)/.wapi.
- For more information what this .wapi directory is used for, please take
- a look at <manref name="mono" section="1">.</p>
+ <p>
+ Means when you don't set MONO_SHARED_DIR explicitly, the package
+ building will fail! Applications will either hang, die with strange Mono
+ runtime errors or segfault (for instance dh_clideps or dh_makeclideps,
+ they use monodis).
+ So change the MONO_SHARED_DIR by calling
+ <example>
+ export MONO_SHARED_DIR=$(CURDIR)
+ </example>
+ in the debian/rules file.
+ </p>
+ <p>
+ The clean target should later remove $(MONO_SHARED_DIR)/.wapi.
+ For more information what this .wapi directory is used for, please take
+ a look at <manref name="mono" section="1">.
+ </p>
</sect>
</chapt>
<chapt id="pnet">
<heading>DotGNU Portable.NET Specifics</heading>
- <p>This section will offer workarounds to common problems encountered when
- packaging DotGNU Portable.NET-specific applications for Debian.</p>
+ <p>
+ This section will offer workarounds to common problems encountered when
+ packaging DotGNU Portable.NET-specific applications for Debian.
+ </p>
<sect>
<heading>Naming</heading>
- <p>The official name of the DotGNU Portable.NET project is exactly that.
- To keep it unified (more transparent to the user) it should be <em>always
- </em> called "DotGNU Portable.NET", not pnet, not Portable.NET.
- The explanation of DotGNU Portable.NET goes into the package
- <em>long</em> description.</p>
+ <p>
+ The official name of the DotGNU Portable.NET project is exactly that.
+ To keep it unified (more transparent to the user) it should be <em>always
+ </em> called "DotGNU Portable.NET", not pnet, not Portable.NET.
+ The explanation of DotGNU Portable.NET goes into the package
+ <em>long</em> description.
+ </p>
</sect>
</chapt>
@@ -518,100 +658,117 @@
<heading>Appendix</heading>
<sect id="cli-common">
<heading>Helper Scripts: cli-common</heading>
- <p>When using cli-common and the included dh_* scripts packages must
- build-depend on <package>cli-common</package> (>= 0.4.0)
- (this version may change later, when cli-common has changes which
- are required to be used by all CLI packages, the CLI Policy version will
- represent such change).</p>
+ <p>
+ When using cli-common and the included dh_* scripts packages must
+ build-depend on <package>cli-common</package> (>= 0.4.0)
+ (this version may change later, when cli-common has changes which
+ are required to be used by all CLI packages, the CLI Policy version will
+ represent such change).
+ </p>
<sect1 id="dh_makeclilibs">
<heading>dh_makeclilibs</heading>
- <p>dh_makeclilibs is used to create the <qref id="clilibs-control-file">clilibs
- control files</qref> 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.</p>
- <p>It has the same use (and very similar) parameters as dh_makeshlibs. You
- should always use a as loose minimal version as possible and a as strict
- minimal version as necessary.</p>
- <p>It must be called before dh_clideps.</p>
-
- <p>See <manref name="dh_makeclilibs" section="1"> for details</p>
+ <p>
+ dh_makeclilibs is used to create the <qref id="clilibs-control-file">clilibs
+ control files</qref> 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.
+ </p>
+ <p>
+ It has the same use (and very similar) parameters as dh_makeshlibs. You
+ should always use a as loose minimal version as possible and a as strict
+ minimal version as necessary.
+ </p>
+ <p>
+ It must be called before dh_clideps.
+ </p>
+
+ <p>
+ See <manref name="dh_makeclilibs" section="1"> for details
+ </p>
</sect1>
<sect1 id="dh_clideps">
<heading>dh_clideps</heading>
- <p>dh_clideps is used to get the native and managed dependencies
- of the packages. It uses the <qref id="clilibs-control-file">clilibs
- control files</qref>, the .config of the assemblies and the shlibs
- files created by dh_makeshlibs. The dependencies are put into ${cli:Depends}.</p>
+ <p>
+ dh_clideps is used to get the native and managed dependencies
+ of the packages. It uses the <qref id="clilibs-control-file">clilibs
+ control files</qref>, the .config of the assemblies and the shlibs
+ files created by dh_makeshlibs. The dependencies are put into ${cli:Depends}.
+ </p>
- <p><em>Be sure to run dh_shlibdeps before dh_clideps is called. Also run dh_makeshlibs
- and dh_makeclilibs before dh_clideps!</em> Otherwise, if two binary packages from
- the same source package depend on one another, dh_clideps will not be able to
- determine depedencies.</p>
-
- <p>dh_clideps can remove duplicates created by running dh_clideps and dh_shlibsdeps
- by using the -d parameter.</p>
-
- <p>See <manref name="dh_clideps" section="1"> for details</p>
+ <p>
+ <em>Be sure to run dh_shlibdeps before dh_clideps is called. Also run dh_makeshlibs
+ and dh_makeclilibs before dh_clideps!</em> Otherwise, if two binary packages from
+ the same source package depend on one another, dh_clideps will not be able to
+ determine depedencies.
+ </p>
+
+ <p>
+ dh_clideps can remove duplicates created by running dh_clideps and dh_shlibsdeps
+ by using the -d parameter.
+ </p>
+
+ <p>
+ See <manref name="dh_clideps" section="1"> for details
+ </p>
</sect1>
<sect1 id="dh_installcligac">
<heading>dh_installcligac</heading>
- <p>TODO</p>
+ <p>TODO</p>
</sect1>
-
</sect>
<sect id="examples">
<heading>Examples</heading>
<sect1 id="debhelper-example">
<heading>debhelper Example</heading>
- <p>
- For binary-arch packages:
- <example>
- binary-arch: build install
- ...
- dh_shlibdeps -a
- dh_makeclilibs -V
- dh_clideps -a -d
- dh_installgac -a
- ...
- </example>
- For binary-indep packages:
- <example>
- binary-indep: build install
- dh_makeclilibs -V
- dh_clideps -i
- dh_installcligac -i
- </example>
- </p>
+ <p>
+ For binary-arch packages:
+ <example>
+ binary-arch: build install
+ ...
+ dh_shlibdeps -a
+ dh_makeclilibs -V
+ dh_clideps -a -d
+ dh_installgac -a
+ ...
+ </example>
+ For binary-indep packages:
+ <example>
+ binary-indep: build install
+ dh_makeclilibs -V
+ dh_clideps -i
+ dh_installcligac -i
+ </example>
+ </p>
</sect1>
<sect1 id="cdbs-example">
<heading>cdbs Example</heading>
- <p>
- <example>
- common-binary-predeb-arch common-binary-predeb-indep::
- dh_shlibdeps
- dh_makeclilibs -V
- dh_clideps -d
- dh_installcligac
- </example>
- </p>
+ <p>
+ <example>
+ common-binary-predeb-arch common-binary-predeb-indep::
+ dh_shlibdeps
+ dh_makeclilibs -V
+ dh_clideps -d
+ dh_installcligac
+ </example>
+ </p>
</sect1>
<sect1 id="wrapper-script-example">
<heading>Executable Wrapper Script Example</heading>
- <p>
- <example>
- #!/bin/sh
- exec /usr/bin/cli /usr/lib/package/package.exe "$@"
- </example>
- </p>
+ <p>
+ <example>
+ #!/bin/sh
+ exec /usr/bin/cli /usr/lib/package/package.exe "$@"
+ </example>
+ </p>
</sect1>
<sect1 id="api-compat-example">
<heading>API Compatibility Check Example</heading>
- <p>TODO</p>
+ <p>TODO</p>
</sect1>
<sect1 id="policy-file-example">
<heading>Policy File Example</heading>
- <p>TODO</p>
+ <p>TODO</p>
</sect1>
</sect>
</chapt>
More information about the Pkg-mono-svn-commits
mailing list