Codebase list cli-common / 7212d2f
- CLI Policy Mirco Bauer 18 years ago
1 changed file(s) with 273 addition(s) and 0 deletion(s). Raw diff Collapse all Expand all
+273
-0
cli-policy.sgml less more
0 <!doctype debiandoc public "-//DebianDoc//DTD DebianDoc//EN"> <book>
1 <title>
2 Debian CLI Policy (DRAFT)
3 </title>
4
5 <author>
6 <name>Mirco Bauer</name>
7 <email>meebey@meebey.net</email>
8 </author>
9 <author>
10 <name>Brandon Hale</name>
11 <email>brandon@smarterits.com</email>
12 </author>
13
14 <version>
15 Version 0.1.1
16 </version>
17
18 <abstract>
19 This document lays out basic policies regarding packaging Mono and other
20 CLRs or CLI-based applications/libraries on Debian GNU/Linux.
21 </abstract>
22
23 <copyright>
24 <copyrightsummary>
25 Copyright &copy; 2005 Mirco Bauer and Brandon Hale.
26 </copyrightsummary>
27
28 <p>This manual is free software; you may redistribute it and/or modify it
29 under the terms of the GNU General Public License as published by the Free
30 Software Foundation; either version 2, or (at your option) any later
31 version.</p>
32
33 <p>This is distributed in the hope that it will be useful, but without
34 any warranty; without even the implied warranty of merchantability or
35 fitness for a particular purpose. See the GNU General Public License
36 for more details.</p>
37
38 <p>A copy of the GNU General Public License is available as
39 /usr/share/common-licenses/GPL in the Debian GNU/Linux distribution or
40 on the World Wide Web at the GNU General Public Licence. You can also
41 obtain it by writing to the Free Software Foundation, Inc., 59 Temple
42 Place - Suite 330, Boston, MA 02111-1307, USA.</p>
43 </copyright>
44
45 <toc>
46
47 <chapt>
48 <heading>Used Terms</heading>
49
50 <p>The ".NET" area uses an own set of abbreviations, which can
51 look confusing to other people.
52 Here a short list with their explanations:</p>
53
54 <sect>
55 <heading>CLI - Common Language Infrastructure</heading>
56
57 <p>This is what most people mean when they say ".NET".
58 The CLI defines mainly the virtual machine, bytecode and how everything
59 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>
60 </sect>
61
62 <sect>
63 <heading>CLR - Common Language Runtime</heading>
64
65 <p>The CLR is an implementation of the CLI (often with a lot of addons
66 for developers), like Mono or Microsoft .NET Framework is.</p>
67 </sect>
68
69 <sect>
70 <heading>CIL - Common Intermediate Language</heading>
71
72 <p>CIL is the the format of the bytecode (for binaries and libraries)
73 used by CLI.</p>
74 </sect>
75
76 <sect>
77 <heading>".NET" or long "Microsoft .NET Framework"</heading>
78
79 <p>The word .NET is a marketing word by Microsoft, which is basically a
80 CLR with added Microsoft technologies like: ASP.NET, VB.NET,
81 System.Windows.Forms, Passport and a lot of other things.
82 <strong>We highly discourage from using any form of the word ".NET", it is
83 burdened by copyright and marketing.</strong> We advice to use the correct
84 term instead, which is often CLI.</p>
85 </sect>
86 </chapt>
87
88 <chapt>
89 <heading>Library Package Naming</heading>
90
91 <p>Most other languages have unified names for library/plugins/module
92 packages in Debian, which makes it easier for users and maintainers. Perl
93 for example uses libfoo-perl, Java uses also libfoo-java. For CLI libraries
94 (CIL bytecode) libfoo-cil should be used, e.g. libgecko-cil. The term
95 "sharp" does not represent the language, a CLI library can be used with all
96 CLI implemented/enabled languages like C#, J#, ASP.NET, VB.NET (<url
97 id="http://www.go-mono.com/languages.html" name="click here"> for the full
98 list), this is why the extension "-cil" is the right one.</p>
99 </chapt>
100
101 <chapt>
102 <heading>Build Dependencies</heading>
103
104 <p>At a minimum, CLI applications must build-depend on the following
105 packages: <package>cli-common</package> (&gt;= 0.1.3),
106 <package>mono-mcs</package> (&gt;= 1.0) | c-sharp-compiler</p>
107
108 <p>If your package is Arch: all, you should specify this as
109 Build-Depends-Indep.</p>
110
111 <p>Software that access Mono via the C interface (libmono.so) or requires
112 the mono.pc file must build-depend also on: libmono-dev (&gt;= 1.0)</p>
113
114 <sect>
115 <heading>cli-common</heading>
116
117 <p>All CLI applications must build-depend on
118 <package>cli-common</package> (&gt;= 0.1.3) and use the included dh_*
119 scripts (this version may change later, when cli-common has changes which
120 are required to be used by all CLI packages, the CLI Policy version will
121 represent such change).</p>
122
123 <p>
124 dh_clideps
125 <list>
126 <item>Call this in the binary-indep stage of debian/rules to generate
127 a list of runtime dependencies, similar to dh_shlibdeps.</item>
128 <item>Add ${cli:Depends} to your Depends: in debian/control.</item>
129 </list>
130 </p>
131
132 <p>
133 dh_makeclilibs
134 <list>
135 <item>Call this in the binary-indep stage of debian/rules if your
136 package contains DLLs that other packages may make use of (e.g.
137 libgtk2.0-cil or libgecko-cil).</item>
138 </list>
139 </p>
140
141 <p>See <manref name="dh_clideps" section="1"> or <manref
142 name="dh_makeclilibs" section="1"> for details about the parameters.</p>
143 </sect>
144 </chapt>
145
146 <chapt>
147 <heading>Migrating Existing Packages</heading>
148
149 <p>Many CLI packages already exist in Debian, or are in ITP, and conform to
150 the deprecated <url id="http://wiki.debian.net/?MonoConventions"
151 name="Mono Conventions">.</p>
152
153 <p>Any <file>debian/rules</file> hacks or patches that exist to redirect
154 files to <file>/usr/share/dotnet</file> should be removed, and adjusted
155 according to upstream file locations (<file>/usr/lib</file>). See
156 <url id="http://wiki.debian.net/?MonoDebianPlan" name="Mono Debian Plan">
157 for the rationale behind this change.</p>
158
159 <p>Also, be sure to replace references to dh_netdepends, dh_makenetlibs, and
160 ${net:Depends} with the CLI functions detailed above.</p>
161
162 <p>
163 Please remove any build-deps on <package>mono-jit</package>,
164 <package>mono-mint</package>, <package>mono-utils</package> (this one had
165 the dh_* helper scripts which are now in <package>cli-common</package>)
166 and <package>libmono-dev</package> (use this one only if the package
167 really links against <package>mono</package> or requires the mono.pc
168 file).
169 </p>
170 </chapt>
171
172 <chapt>
173 <heading>Mono Specifics</heading>
174
175 <p>This section will offer workarounds to common problems encountered when
176 packaging Mono-specific applications for Debian.</p>
177 <sect>
178 <heading>Naming</heading>
179
180 <p>The official name of the Mono Project is: Mono, mono:: or mono.
181 To keep it unified (more transparent to the user) it should be <em>always
182 </em> called "Mono", not MONO, not mono, not mono:: even no
183 mixing with .NET in it. The explanation of Mono goes into the package
184 <em>long</em> description.</p>
185 </sect>
186
187 <sect>
188 <heading>DLL Maps</heading>
189
190 <p>Often times, upstream software developers are not
191 packagers, and vice versa. Developers do not necessarily test their
192 software with packaging issues in mind. The most common problem we
193 see from this are missing dll exceptions.</p>
194
195 <sect1>
196 <heading>Introduction</heading>
197
198 <p>When Mono code invokes an external library, it usually calls
199 something like [DllImport("foo")]. "foo" is expanded to libfoo.so, and
200 searched for in your library path.</p>
201
202 <p>In Debian and some other binary Linux distributions, packages are
203 split into runtime and -dev packages. Since the versioned library
204 libfoo.so.X is usually used at runtime, and .so is a symlink only used
205 at build time, .so is moved to the -dev package.</p>
206
207 <p>When packaging an application which uses libfoo, we don't want
208 normal users to need to need the -dev packages just to run the
209 application. As you saw above, however, Mono defaults to looking for
210 the unversioned .so, which is unavailable in the runtime packages.</p>
211 </sect1>
212
213 <sect1>
214 <heading>Solution</heading>
215
216 <p>We can fix this by creating a dll map to the exe or dll that is
217 trying to invoke libfoo.
218 If libfoo is invoked by the dll bar.dll, we will create an xml file,
219 bar.dll.config to tell Mono which .so we really want to load at runtime.
220 bar.dll.config should be installed to the same directory as bar.dll.</p>
221
222 <p>
223 <example>
224 &lt;configuration&gt;
225 &lt;dllmap dll="foo" target="libfoo.so.0"/&gt;
226 &lt;/configuration&gt;
227 </example>
228 </p>
229
230 <p>A config file can contain as many dllmap directives as are needed.
231 If the upstream developer already ships a config file, but it is
232 incomplete, you should create a patch against it in your package.</p>
233
234 <p>Most Mono software developers are very helpful people, and will
235 readily accept patches to solve this type of bug if you bring it to
236 their attention. Please be sure to inform them of all these changes.</p>
237 </sect1>
238 </sect>
239
240 <sect>
241 <heading>MONO_SHARED_DIR</heading>
242
243 <p>The Mono runtime uses a shared directory, by default
244 <file>~/.wapi</file>. This directory will be created/used when any CLI
245 application is executed (like the C# compiler mcs).</p>
246
247 <p>
248 Here comes 2 problems with it:
249 <list>
250 <item>In an autobuilder environment often does no home directory
251 exist.</item>
252 <item>Mono uses the wrong home directory when running within fakeroot
253 (it tries <file>/root/.wapi</file> instead of <file>$HOME/.wapi
254 </file>).</item>
255 </list>
256 </p>
257
258 <p>Means when you don't set MONO_SHARED_DIR explicity, the package
259 building will fail! Applications will either hang, die with strange Mono
260 runtime errors or segfault (for instance dh_clideps or dh_makeclideps,
261 they use monodis).
262 So change the MONO_SHARED_DIR by calling
263 <example>
264 export MONO_SHARED_DIR=$(CURDIR)
265 </example>
266 in the debian/rules file.</p>
267 <p>The clean target should later remove $(MONO_SHARED_DIR)/.wapi.
268 For more information what this .wapi directory is used for, please take
269 a look at <manref name="mono" section="1">.</p>
270 </sect>
271 </chapt>
272 </book>