mainly markup
[haskell-report.git] / packages / pkg-spec.sgml
1 <!DOCTYPE ARTICLE PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
2 <!entity  ghc         "<application>GHC</application>">
3 <!entity  nhc         "<application>Nhc98</application>">
4 <!entity  hugs        "<application>Hugs</application>">
5 <!entity  autoconf    "<application>autoconf</application>">
6 <!entity  impl        "Haskell Implementation">
7 <!entity  impls       "Haskell Implementations">
8 <!entity  distMod     "<className>Distribution</className> module">
9 <!entity  haskellConfig  "<application>haskell-config</application>">
10 <!entity  DistPackage  "<classname>Distribution.Package</classname>">
11 <!entity  DistBuild    "<classname>Distribution.Build</classname>">
12 <!entity  DistInstall  "<classname>Distribution.Install</classname>">
13 <!entity  DistConfigure   "<classname>Distribution.Config</classname>">
14 <!entity  hunit       "<application>HUnit</application>">
15 <!entity  distutils   "<application>Distutils</application>">
16 <!entity  cpan        "<application>CPAN</application>">
17 <!entity  xemacs      "<application>XEmacs</application>">
18 <!entity  hmake       "<application>hmake</application>">
19 <!entity  dpkg        "<application>dpkg</application>">
20 <!entity  rpm        "<application>rpm</application>">
21 <!entity  hc-pkg     "<command>hc-pkg</command>">
22 ]>
23  
24 <!-- You should search this document for 'foo' and delete it. -->
25 <!-- Look for FIX too -->
26
27 <!-- ToDo: -->
28
29 <!-- Look at Package data types again and add the version information where -->
30 <!-- necessary. -->
31
32 <article id="lip">
33   <artHeader>
34     <date>2003-09-12</date>
35     <title>The Haskell Package System</title>
36     <author>
37       <firstname>Isaac</firstname>
38       <surname>Jones</surname>
39     </author>
40     <author>
41       <firstname>Simon</firstname>
42       <surname>Peyton Jones</surname>
43     </author>
44     <author>
45       <firstname>Simon</firstname>
46       <surname>Marlow</surname>
47     </author>
48     <author>
49       <firstname>Malcolm</firstname>
50       <surname>Wallace</surname>
51     </author>
52
53     <address><email>ijones@syntaxpolice.org</email></address>
54     <abstract>
55
56       <para>The Haskell Library Infrastructure Project is an effort to provide
57       a framework for developers to more effectively contribute their
58       software to the Haskell community.  This document specifies
59       the <emphasis>Haskell Package System (HPS)</emphasis>, which contributes 
60         to the goals of the Haskell Library Infrastructure Project.
61       </para>
62       <para>Specifically, the HPS describes what a Haskell 
63         package is, how these packages interact with the language,
64         and what Haskell implementations must to do to support packages.
65         The HPS also specifies some infrastructure (code) that makes
66         it easy for library authors to build and distribute conforming packages.
67         </para>
68       <para>The HPS is only one contribution to the Library Infrastructure project.
69         In particular, the HPS says nothing about more global issues such as
70         how authors decide where in the module name space their library should live;
71         how users can find a package they want; how orphan packages find new owners;
72         and so on.</para>
73       <para> The HPS has been discussed by the implementors of &ghc;, &nhc;, and &hugs;,
74         all of whom are prepared to implement it.  The proposal is now open
75         for wider debate. Please contribute by emailing <email>libraries@haskell.org</email>.</para>
76     </abstract>
77   </artheader>
78
79
80 <!-- Solution ------------------------------------------------- -->
81
82 <sect1 id=hli-goals><title>The Haskell Package System: goals</title>
83
84 <para>The Haskell Package System (HPS) has the following main goal:
85 to specify a standard way in which a Haskell library can be packaged, so that it is
86 easy for consumers to use it, or re-package it, 
87 regardless of the Haskell implementation or installation platform.</para>  
88
89 <para>The HPS also
90 supports library authors by providing an infrastructure that automates the
91 process of building and packaging simple libraries.  It is not necessary to use
92 this code&mdash;indeed complex libraries may exceed its abilities&mdash;but it should
93 handle many cases with no trouble.</para>
94
95 <sect2><title>Dramatis personae</title>
96
97 <para>The HPS serves a number of different people:
98 <itemizedlist>
99 <listitem><para>
100  <emphasis>Joe User</emphasis> is simply a Haskell user.  He does not download new packages.  Nevertheless,
101 he needs to know about his Haskell compiler's <option>-package</option> flag (see <xref linkend="compiler-reqts">).
102             </para>
103           </listitem>
104 <listitem><para>
105  <emphasis>Bob the Builder</emphasis> and <emphasis>Sam Sysadmin</emphasis> both download, build,
106   and install new packages. The only difference between the two is that Sam has root permission,
107   and can install packages in more globally-visible places.
108             </para>
109           </listitem>
110 <listitem><para> <emphasis>Roland RPM</emphasis>, <emphasis>Donald
111  Debian</emphasis>, and <emphasis>Willie Windows</emphasis> build
112  Linux RPM, Debian, and Windows installer packages respectively (this
113  list is not exhaustive).  They do this as a service for Angela Author
114  and the community, and may know little or nothing about the internal
115  details of the Haskell packages they are wrapping up.
116             </para>
117           </listitem>
118 <listitem><para>
119  <emphasis>Angela Author</emphasis> wants to write a simple Haskell library, and distribute it with 
120 minimum fuss, in such a way that all the above folk can easily use it.
121             </para>
122           </listitem>
123 <listitem><para>
124  <emphasis>Marcus Makefile</emphasis> is like Angela, but more sophisticated.  He has a complicated library,
125 and uses makefiles.  Still, he wants to arrange that Roland, Donald, Bob, Sam, and Joe don't need to know
126 about his internal complexity.
127             </para>
128           </listitem>
129         </itemizedlist>
130 We describe Angela and Marcus as <emphasis>producers</emphasis> of their packages, and all the others
131 as package <emphasis>consumers</emphasis>.  
132       </para>
133     </sect2>
134
135 <sect2 id="example"><title>An example</title>
136
137 <para>To give the idea, here is a simple example.  Angela has written a couple of Haskell modules that
138 implement sets and bags; she wants to distribute them to Bob as a package called,
139 say, <literal>angela-coll</literal>.  Let's say that the modules are
140 <literal>Data.Set</literal>, <literal>Data.Bag</literal>, <literal>Angela.Internals</literal>.
141 (The HPS says nothing about how Angela decides where in the name space to put her modules.)
142 Angela only wants to expose the first two to Bob; the <literal>Angela.Internals</literal> module is (as its
143 name suggests) internal to the package.
144 </para>
145 <para>Angela decides to use the simple build infrastructure that the HPS provides.  She is working in
146 a directory <filename>~/coll</filename>.  In there she puts the modules, in sub-directories
147 driven by their module name: <filename>~/coll/Data/Set.hs</filename>,
148  <filename>~/coll/Data/Bag.hs</filename>,
149  and <filename>~/coll/Angela/Internals.hs</filename>.
150 Next, she writes
151 a <emphasis>package description</emphasis>, which she puts in <filename>~/coll/pkg.desc</filename>:
152 <programlisting>
153     name:     angela-coll
154     version:  1
155 </programlisting>
156 She also creates a three-line Haskell file <filename>~/coll/Setup.lhs</filename> as follows:
157 <programlisting>
158   #! runhugs
159
160   > import Distribution.Simple( main )
161 </programlisting>
162 The first line arranges that when Angela executes <filename>Setup.lhs</filename> as a shell script,
163 the shell will invoke <command>runhugs</command>, which will in turn run <literal>main</literal> imported
164 from the library <literal>Distribution.Simple</literal>.  This library implements the HPS simple build infrastructure.
165 </para>
166 <para> Now she is ready to go. She types:
167 <programlisting>
168   ./Setup.lhs configure --ghc
169   ./Setup.lhs build
170   ./Setup.lhs src-dist
171 </programlisting>
172 The first line readies the system to build the library using &ghc;; for example, it checks that &ghc; exists on the system.
173 The second line checks that
174 the library does indeed build flawlessly.  (At this point she can write and execute tests, as we discuss later.)
175 The third line wraps up the package as a source distribution, making the file <filename>~/coll/angela-coll-1.tar.gz</filename>.
176 </para>
177 <para>
178 Angela emails the tar file to Bob, who untars it into <filename>tmp/coll</filename>.
179 He <command>cd</command>'s to that directory and types
180 <programlisting>
181   ./Setup.lhs configure --ghc
182   ./Setup.lhs build
183   ./Setup.lhs install
184 </programlisting>
185 He's all done. Now in his Haskell programs, Bob can simply <literal>import</literal> the new
186 modules <literal>Data.Set</literal> and <literal>Data.Bag</literal>. He does not need to give extra flags
187 to &ghc; to tell it to look for Angela's modules; they are there automatically.
188 If Angela used the same module names as someone else, Bob may need finer control: see <xref linkend="compiler-reqts">.</para>
189 <para>
190 If Angela wrote her modules in a suitably portable variant of Haskell,
191 Bob could also have said <option>--hugs</option> or
192 <option>--nhc</option> in his <option>configure</option> line, and the
193 package would have been built and installed for those compilers
194 instead.
195       </para>
196     </sect2>
197   </sect1>
198
199
200 <sect1 id=hli-overview><title>The Haskell Package System: overview</title>
201
202 <para>This section summarises the vocabulary and main features of the Haskell Package System.</para>
203
204 <sect2 id="package-descr"><title>Packages</title>
205
206 <para>A <emphasis>package</emphasis> is the unit of distribution for the HPS.
207 Its purpose in life, when installed, is to make available some Haskell modules for
208 import by some other Haskell program.   However, a package may consist of 
209 much more than a bunch of Haskell
210 modules: it may also have C source code and header files, documentation, test cases, auxiliary 
211 tools and whatnot.</para>
212
213 <para>
214 Each package has:
215 <itemizedlist>
216 <listitem><para>A globally-unique <emphasis>package name</emphasis>, containing no spaces. Chaos will result
217 if two distinct packages with the same name are installed on the same system.  How unique package names are
218 handed out is not part of this specification, but there will presumably be some global web site where
219 package authors can go to register a package name. </para>
220 </listitem>
221 <listitem><para>A <emphasis>version</emphasis>, consisting of a sequence of one or more integers.
222 </para></listitem>
223
224 <listitem><para>
225 <emphasis>A list of explicit dependencies</emphasis> on other packages.  These are typically not exact; e.g. "I need <literal>hunit</literal> version
226 greater than 2.4".
227             </para>
228           </listitem>
229 <listitem><para>
230 <emphasis>A list of exposed modules</emphasis>.  Not all of the modules that comprise a package implementation are necessarily
231 exposed to a package client.
232 The ability to expose some, but not all, of the modules making up a package
233 is rather like using an explicit export list on a Haskell module.</para>
234           </listitem>
235 </itemizedlist>
236 The first two components can be combined to form a single text string called the <emphasis>package ID</emphasis>, 
237 using a hyphen to separate the version
238 from the name, and dots to separate the version components.  For example, "hunit-2.3".
239 </para>
240
241 </sect2>
242
243 <sect2 id="packages-and-haskell"><title>Packages and the Haskell language</title>
244 <para>A complete Haskell program will consist of one or more modules (including <literal>Main</literal>)
245 compiled against one or more packages (of which the Prelude is one).  These packages are not referred to
246 explicitly in the Haskell source; instead, the packages simply populate the hierarchical space of module names.
247 </para>
248 <para>Complete programs must obey the following invariant.  <emphasis>Consider all the Haskell modules that
249 constitute a complete program: no two modules must have the same module name.</emphasis></para>
250
251 <para>This invariant is conservative.  It preserves the existing semantics of Haskell, and is 
252 relatively easy to implement.  In particular, the the full name of an entity (type, class, function), which is
253 used to determine when two entities are the same, is simply a pair of the module name and the entity name.</para>
254
255 <para>The invariant is unsatisfactory, however, because it does not support abstraction at
256 the package level. For example, a module with an internal (hidden, non-exposed) module called <literal>Foo</literal>
257 cannot be used in the same program as another package with an unrelated internal module also called <literal>Foo</literal>.
258 Nor can a program use two packages, P and Q, which depend on different versions of the same underlying package R.
259 We considered more sophisticated schemes, in which (for example) the package name, or package ID, is implicitly
260 made part of every module name.  But (a) there is a big design space, and (b) it places new requirements on the
261 implementations.  Hence a conservative starting point.</para>
262     </sect2>
263
264 <sect2><title>Packages and compilers</title>
265
266 <para>We use the term ``compiler'' to mean &ghc;, &hugs;, &nhc;, hbc, etc.  (Even though
267 &hugs; isn't really a compiler, the term is less clumsy than ``Haskell implementation''.)</para>
268
269 <para> The
270 HPS requires that a conforming Haskell compiler is somewhat package aware.
271 In summary, the requirements are these:
272 <itemizedlist>
273 <listitem><para>Each compiler <command>hc</command> must provide an
274 associated package-management program &hc-pkg;.  A compiler user
275 installs a package by placing the package's supporting files
276 somewhere, and then using &hc-pkg; to make the compiler aware of the
277 new package.  This step is called <emphasis>registering the package
278 with the compiler</emphasis>.  </para></listitem> <listitem><para>To
279 register a package, &hc-pkg; takes as input an <emphasis>installed
280 package description (IPD)</emphasis>, which describes the installed
281 form of the package in detail.  The format of an IPD is given in <xref
282 linkend="ipd">.</para>
283           </listitem>
284
285           <listitem>
286             <para>Subsequent invocations of <command>hc</command>
287             will include modules from the new package in the module
288             name space (i.e. visible to <literal>import</literal>
289             statements).</para>
290           </listitem>
291           <listitem>
292             <para>The compiler should support
293             <option>-package</option> and
294             <option>-hide-package</option> flags for finer-grain
295             control of package visibility.</para>
296           </listitem>
297         </itemizedlist>
298
299         A complete specification of these requirements is given in
300         <xref linkend="compiler-reqts">.</para>
301     </sect2>
302
303 <sect2><title>Package distributions</title>
304
305 <para>A HPS package can be distributed in several forms:
306 <itemizedlist>
307 <listitem><para>
308 A <emphasis>HPS source distribution</emphasis> is a tree of files (tar-ball, zip file etc)
309 containing the library sources, which may need to be
310 compiled before being installed.  The same source tarball may well be installable for several
311 Haskell implementations, OSs, and platforms.
312             </para>
313 <para>A source distribution may contain fewer files than appear in the developer's CVS repository; for example,
314 tests and design notes may be omitted.  It may also contain some derived files, that do not appear in the
315 the developer's repository; for example, ones made by a somewhat exotic pre-processor where it
316 seems simpler to ship the derived file than to ensure that all consumers have the pre-processor.</para></listitem>
317 <listitem><para>
318 A <emphasis>HPS binary distribution</emphasis> is a tree of files that contains a pre-compiled library, ready
319 for installation.  The pre-compilation means that the distribution will be Haskell-compiler-specific, and certain 
320 "looser" dependencies (<literal>hunit > 2.3</literal>) will now be precisely fixed (<literal>hunit == 2.4</literal>).
321             </para>
322           </listitem>
323
324 <listitem><para>
325 The package may be wrapped up as an <emphasis>RPM</emphasis>, <emphasis>Debian</emphasis> distribution, 
326 or <emphasis>Windows installer</emphasis> (this list is not exhaustive).
327 In that case, the way it is installed is prescribed by the respective distribution mechanism;
328 the only role of the HPS is to make it easy to construct such distributions. All three are
329 compiler-specific (indeed compiler-version-specific) binary distributions.
330             </para>
331           </listitem>
332         </itemizedlist></para>
333     </sect2>
334
335 <sect2><title>The Setup script</title>
336
337 <para>The key question is this: how should Angela Author present her HPS package so that 
338 her consumers (Bob, Sam, Willie, etc) can conveniently use it?</para>
339
340 <para>Answer: she provides a tree of files, with two specific files in the
341 root directory of the tree:  
342 <itemizedlist>
343 <listitem><para><filename>pkg.desc</filename> contains a short description of the package:
344 specifically, the package name, version, and dependencies.  It may also contain further information
345 specific to the particular build system.  The syntax of the package description file
346 is given in <xref linkend="pkg-desc">.
347             </para>
348           </listitem>
349 <listitem><para>
350 <filename>Setup.lhs</filename> is an executable Haskell program 
351 which conforms to a particular specification, given in detail in <xref linkend="setup">.
352 In summary, though, <filename>Setup.lhs</filename> allows a consumer to configure, build,
353 test, install, register, and un-register a package.  </para>
354           </listitem>
355         </itemizedlist>
356 The HPS allows a package author to write the setup script in any way she pleases, provided
357 it conforms to the specification of <xref linkend="setup">.  However, many Haskell packages consist
358 of little more than a bunch of Haskell modules, and for these the HPS provides <emphasis>the simple
359 build infrastructure</emphasis>, a Haskell library that does
360 all the work.  The simple build infrastructure, which was used for the example in 
361 <xref linkend="example">, is described in <xref linkend="sbi">.</para>
362
363 <!-- Why Haskell ---------------------------- -->
364
365 <para>In principle, the <literal>Setup</literal> script
366 could be written in any language; so why do we use Haskell?
367 <itemizedList>
368
369 <listItem><para>Haskell runs on all the systems of interest.</para></listItem>
370
371 <listItem><para>Haskell's standard libraries should include a rich set of operating
372 system operations needed for the task.  These can abstract-away the
373 differences between systems in a way that is not possible for
374 Make-based tools.</para></listItem>
375
376 <listItem><para>Haskell is a great language for many things, including tasks
377 typically relegated to languages like Python.  Building, installing,
378 and managing packages is a perfect proving ground for these tasks, and
379 can help us to discover weaknesses in Haskell or its libraries that
380 prevent it from breaking into this "market".  A positive side-effect
381 of this project might be to make Haskell more suitable for "scripting"
382 tasks.</para></listItem>
383
384 <listItem><para>Likewise, each piece of the project (Building, Installing, and
385 Packaging) can be leveraged elsewhere if we make them into
386 libraries.</para></listItem>
387
388 <listItem><para>Make is not particularly good for parsing, processing, and sharing
389 meta-information about packages.  The availability of this information
390 to Haskell systems (including compilers, interpreters, and other
391 tools) is useful.  Unlike Make, Haskell can also reuse unrelated
392 algorithms, parsers, and other libraries that have been developed in
393 the past.</para></listItem>
394
395 <listItem><para><emphasis>Dogfooding</emphasis>, the act of using the tools you
396 develop, is a healthy policy.</para></listItem>
397
398 </itemizedList>
399 It is convenient for consumers to execute <filename>Setup.lhs</filename> directly, thus:
400 <programlisting>
401   ./Setup.lhs ...
402 </programlisting>
403 This can be achieved by starting <filename>Setup.lhs</filename> with "<literal>#! runhugs</literal>"
404 or "<literal>#! runghc</literal>" .
405 Since it's a literate Haskell script (<literal>.lhs</literal> file), the Haskell compiler will ignore
406 this line.
407 However, nothing stops a consumer from running the script interactively, or compiling it and running 
408 the compiled binary.  Any implementation of Haskell should suffice to run the script, provided 
409 the implementation has the HPS libraries installed.  
410         </para>
411       </sect2>
412   </sect1>
413
414 <!-- COMPILER REQUIREMENTS ---------------------------- -->
415
416 <sect1 id="compiler-reqts"><title>What the compilers must implement</title>
417
418 <para>The HPS requires that the Haskell implementations be somewhat package-aware.
419 This section documents those requirements</para>
420
421 <sect2><title>Building and registering a package</title>
422
423 <para>Installing a package ultimately involves these steps:
424 <itemizedlist>
425 <listitem> <para>
426  <emphasis>Compiling the source files</emphasis>, by invoking the compiler.  Even &hugs; may require 
427      some processing (e.g running cpp).
428 </para></listitem>
429
430 <listitem> <para>
431   <emphasis>Copying the compiled files into some permanent place</emphasis>.  Typically the compiler
432      places no pre-conditions on where "some place" is; instead one
433      usually follows the conventions of the host operating system.
434 </para></listitem>
435
436 <listitem> <para>
437   <emphasis>Registering the package</emphasis>: telling the compiler about the 
438      existence of the package, and where its files are.
439   To register the package one invokes a compiler-specific program &hc-pkg; (i.e. <command>ghc-pkg</command>, 
440   <command>hugs-pkg</command> etc), passing it an <emphasis>installed package description (IPD)</emphasis>
441   describing the package.  The format of an IPD is given in <xref linkend="ipd">.
442 </para></listitem>
443 </itemizedlist>
444 </para>
445 <para>It must be possible to register many versions of the same package.</para>
446
447 <sect3><title>Shared packages and user packages</title>
448
449 <para>
450 A package can be registered either as a <emphasis>shared package</emphasis> or as a <emphasis>user package</emphasis>.
451 The former means that anyone invoking <command>hc</command> will see the new package.  The latter means
452 that only the user who installed the package will see it.
453 </para>
454 <para>
455 User packages <emphasis>shadow</emphasis> shared packages, in the following sense:
456           <itemizedlist><listitem><para>
457                 A Haskell <literal>import</literal> for module M will seek M in a user package first.
458               </para>
459             </listitem><listitem><para>
460                 The &hc-pkg; commands that take package IDs will look for a user package first.
461               </para>
462             </listitem>
463           </itemizedlist></para>
464 <note><para>Hmm.  If there are several ghc's around, can their user packages get mixed up?  I hope not.</para></note>
465
466 </sect3>
467
468 <sect3><title>Exposed packages and hidden packages</title>
469
470 <para>
471 An installed package can be <emphasis>exposed</emphasis> or <emphasis>hidden</emphasis>.  An exposed package
472 populates the module name space, while a hidden package does not.  Hidden packages are nevertheless necessary.
473 For example, the user might use
474 package A-2.1 and B-1.0; 
475 but B-1.0 might depend on A-1.9. So the latter must be installed (else B-1.0 could not be installed), but
476 should be hidden, so that user imports see A-2.1. (However, note that the 
477 whole-program invariant described in <xref linkend="packages-and-haskell"> implies that a program using B-1.0 could
478 not also use A-2.1, because then both A-2.1 and A-1.9 would form part of the program, and they almost certainly 
479 use the same module names.)
480 </para>
481 <para>The registration program &hc-pkg; provides operations to expose or hide an 
482 already-installed package.  By default, installing a package installs it exposed, and hides any
483 existing installed package of the same name (and presumably different version).
484           </para>
485 <para>Hiding or exposing a package is an operation that can be performed, by &hc-pkg;,
486 on any package.  It is quite distinct from the question of which modules in a package are hidden or
487 exposed (see <xref linkend="package-descr">), which is a property of the package itself.  Only the exposed
488 modules of an exposed package populate the module name space seen by a Haskell <literal>import</literal> statement.
489 </para>
490 </sect3>
491
492 <sect3><title>Registration invariants</title>
493
494 <para>The registration program &hc-pkg; checks the following invariants:
495 <itemizedlist>
496 <listitem> <para>
497 Before registering a package P, check all the packages that P depends on are already registered.
498 If P is being registered as a shared package, P's dependencies must also be shared packages.
499 </para></listitem>
500 <listitem> <para>
501 Before registering an exposed user package P, check that the modules that are exposed by P do not have the same
502 names (in the hierarchical module name space) as any other module in an exposed user package Q.  Similarly
503 for system packages.  (However, a system package may expose a module with the same name as a user package.)
504 </para></listitem>
505 <listitem> <para>
506 Before un-registering a package P, check that no package that depends on P is registered.
507 The exception is that when un-registering a shared package, &hc-pkg; cannot
508 check that no user has a user package depending on P.</para>
509             </listitem>
510 </itemizedlist>
511         </para>
512       </sect3>
513     </sect2
514
515     <sect2>
516       <title>The <option>-package</option> compiler flag</title>
517
518       <para>By default, the module namespace is populated only by the
519       exposed modules of exposed packages.  This can be overridden
520       using the <option>-package</option> flag, which temporarily
521       exposes a particular package, hiding any other packages of the
522       same name.</para> <note><para>Question: what does
523       <literal>-package hunit-1.2 -package hunit-1.3</literal> do?
524       Does the second override the first?  Or are they both in scope?
525       I think the former.</para> <para>Question: what if the -package
526       flag breaks the registration invariants?  For example, the
527       newly-exposed package might expose a module that clashes with an
528       existing one.  Maybe the second registration invariant should be
529       checked for each run of the compiler, rather than by
530       hc-pkg?</para></note>
531     </sect2>
532
533 <sect2><title>The interface to &hc-pkg;</title>
534
535 <para>Registering a package with a compiler records the package information in some
536 implementation-specific way; how it does so is not constrained by the HPS.
537 Much of an IPD is independent of the compiler, but it may also include compiler-specific
538 fields.</para>
539
540 <para>Each Haskell implementation <command>hc</command> must provide an associated program &hc-pkg; which 
541 allows a user to make a new package known to the compiler, and to ask what packages it knows. Here is a summary of its interface
542
543 <note><para>Some of these commands (unregister, hide, and describe) make sense for package IDs which offer a range, such as "hc-pkg unregister "hmake<2.3".</para></note>
544
545      <table frame=all><title>&hc-pkg; interface</title>
546
547      <tgroup cols=2 align=left colsep=1 rowsep=1>     <tbody>
548
549      <row><Entry><cmdsynopsis><command>hc-pkg register</command> <group choice=req>
550                       <arg><replaceable>filename</replaceable></arg>
551                       <arg><option>-</option></arg></group>
552                   <group choice=opt><arg>--user</arg><arg>--global</arg>
553                     </group>
554                 </cmdsynopsis></entry>
555                     <Entry><para>Register the package using the specified installed package description.
556                   The syntax for the latter is given in <xref linkend="ipd">.</para></entry></row>
557
558
559      <row><Entry><cmdsynopsis><command>hc-pkg unregister</command> 
560                 <arg><replaceable>pkg-id</replaceable></arg>
561                   </cmdsynopsis></entry>
562                     <Entry><para>Unregister the specified package.</para></entry></row>
563
564      <row><Entry><cmdsynopsis><command>hc-pkg expose</command> 
565                 <arg><replaceable>pkg-id</replaceable></arg>
566                   </cmdsynopsis></entry>
567                     <Entry><para>Expose the specified package.</para></entry></row>
568
569      <row><Entry><cmdsynopsis><command>hc-pkg hide</command> 
570                 <arg><replaceable>pkg-id</replaceable></arg>
571                   </cmdsynopsis></entry>
572                     <Entry><para>Hide the specified package.</para></entry></row>
573
574      <row><Entry><command>hc-pkg list</command></entry>
575                     <Entry><para>List all registered packages, both shared and user, hidden and exposed. </para></entry></row>
576
577
578      <row><Entry><cmdsynopsis><command>hc-pkg describe</command> <arg choice=req><replaceable>pkg-id</replaceable> </arg>
579                   </cmdsynopsis></entry>
580          <Entry><para>Give the registered description for the specified package.
581                     The description is returned in precisely the syntax required by 
582                     <command>hc-pkg register</command>.  
583                 </para></entry></row>
584
585      <row><Entry><cmdsynopsis><command>hc-pkg field</command> <arg choice=req><replaceable>pkg-id</replaceable> </arg>
586                 <arg choice=req><replaceable>field</replaceable> </arg>
587                   </cmdsynopsis></entry>
588
589          <Entry><para>Extract the specified field of the package description for the specified package.
590                 </para></entry></row>
591
592      </tbody></tgroup>
593      </table>
594 A <replaceable>pkg</replaceable> argument can be a package ID, such as "<literal>hunit-2.3</literal>", or just a package name, 
595 such as "<literal>hunit</literal>".  To determine which package is meant, &hc-pkg; searches first the
596 registered user packages and then the shared packages.  If no such package exists, the command fails; that is, it does nothing, 
597 returning a non-zero error code.
598 If only a name is specified, &hc-pkg; fails
599 unless the name identifies a unique package among the user packages, or among the shared packages.  As usual, the
600 user packages win.
601       </para>
602 <note><para>Can we give the <option>--user</option> flag to <command>hide</command>, <command>expose</command>,
603 <command>describe</command>?  Can we register a package that is already registered?  What if it's registered
604 as a shared package and we register it as a user package?</para>
605       </note>
606 </sect2>
607
608 <sect2 id=ipd><title>Syntax of installed package description</title>
609
610 <note><para>...include the list of ``externally visible modules''.</para></note>
611 </sect2>
612 </sect1> <!-- End of compiler requirements --> 
613
614
615 <!-- Setup script -->
616
617 <sect1 id=setup><title>The setup script</title>
618
619 <para>
620 The sole requirement of an HPS package is that it should contain,
621 in the root of its file structure, (a) a package description file <filename>pkg.desc</filename>,
622 and (b) a setup script, <filename>Setup.lhs</filename>.
623 This section
624 specifies the syntax of the package description, and the command-line interface for the setup script.
625 </para>
626
627 <sect2 id=pkg-desc><title>The package description</title>
628
629 <para>Here is a sample package description file:
630 <programlisting>
631   name:    hunit
632   version: 4.3
633   deps:    [ foogle > 2.9, bargle = 2.5.1 ]
634 </programlisting>
635 The first two lines are compulsory. The dependencies are optional, assumed empty if omitted. 
636 There can be more lines, all of the form <emphasis>name: stuff</emphasis>, specific to the particular
637 setup script in use.  For the HPS-provided simple build infrastructure, the package description syntax
638 is given in <xref linkend="sbi-pkg-desc">.
639 </para>
640 <para>The exact syntax is still undecided.  Should we put everything in quotes?
641 <programlisting>
642   deps:    [ "foogle > 2.9", "bargle = 2.5.1" ]
643 </programlisting>
644 If not, how can a program that doesn't understand a particular field safely ignore it?  Skip to end of line?
645 But there may be many lines in fields like <literal>deps</literal>.
646 <emphasis>ToDo: pick a syntax, provide a parser in the Distribution
647 libraries somewhere.</emphasis>
648 </para>
649     </sect2>
650
651 <sect2 id=setup-spec><title>The setup script specification</title>
652
653 <para>Here is the command-line interface the setup script must satisfy.
654      <table frame=all><title>setup.lhs interface</title>
655
656      <tgroup cols=2 align=left colsep=1 rowsep=1>     <tbody>
657
658      <row><Entry><command>./Setup.lhs configure [flags] </command></entry>
659          <Entry><para> Prepare to build the package.  Typically, this step checks
660                 that the target platform is capable of building the package, and
661                 discovers platform-specific features that are needed during the build. 
662                 </para></entry></row>
663
664
665      <row><Entry><command>./Setup.lhs build</command></entry>
666                     <Entry><para>Make this package ready for installation.  For a true compiler,
667                   this step involves compiling the Haskell source code.  Even for an interpreter, however, 
668                   it may involve running a pre-processor.</para></entry></row>
669
670
671      <row><Entry><command>./Setup.lhs install [install-prefix]</command></entry>
672                     <Entry><para>Copy the files into the install locations, and register
673                   the package with the compiler.</para></entry></row>
674
675      <row><Entry><cmdsynopsis>
676                   <command>./Setup.lhs register</command><sbr>
677                   <command>./Setup.lhs unregister</command>
678               </cmdsynopsis>
679               </entry>
680                     <Entry><para>Register (or un-register) this package with the
681                     compiler.  (NB: registration is also done automatically by <literal>install</literal>.)
682                 </para></entry></row>
683
684      <row><Entry><command>./Setup.lhs test</command></entry>
685                     <Entry><para>Run the package's test suite.</para></entry></row>
686
687      </tbody></tgroup>
688      </table>
689     </para>
690
691       <para>For wrapped make-based systems (for instance), a
692       command-line parser that understands the standard
693       <literal>Setup.lhs</literal> command-line syntax will be
694       provided as a library.</para>
695
696       <sect3>
697         <title><option>configure</option></title>
698
699         <para>The command <literal>./Setup.lhs configure</literal>
700         prepares to build the package.  For sophisticated packages,
701         the configure step may perform elaborate checks, to gather
702         information about the target system.  It may write a file to
703         record its results, but the name and format of this file are
704         not part of the specification.</para>
705
706 <para>All flags are optional.  The flags are these:</para>
707 <itemizedlist>
708 <listitem><para><option>--with-compiler=</option><replaceable>path</replaceable>, 
709 <option>--ghc</option>, 
710 <option>--nhc</option>, 
711 <option>--hugs</option>: 
712 specifies which compiler to use.  At most one of the value of these flags may be specified.
713 The configure step checks
714 that the compiler is available, in a sufficiently up-to-date form for the package, and that the package
715 expects to work with that compiler.  If the compiler name
716 is not specified, <literal>setup</literal> will choose one; some packages will come with one compiler baked in.
717 </para>
718           </listitem>
719 <listitem><para><option>--prefix=</option><replaceable>path</replaceable>: specifies where the installed files
720 for the package should be installed.  Typically on Unix this will be <filename>/usr/local</filename> and
721 on Windows it will be <filename>Program Files</filename>.  The setup script will use a sensible default
722 (often platform-specific) if the flag is not specified.
723             </para>
724           </listitem>
725
726 <listitem><para>Unrecognized flags are errors in the default build system, but may be meaningful to wrapped make-based systems (for instance).  Therefore, the provided command-line parser will pass unrecognized command-line flags on to the wrapped system.</para></listitem>
727
728         </itemizedlist>
729
730         <para>It is OK for these flags to be "baked into" the compiled
731         library.  In particular, the build system may bake the
732         installation path into the compiled files.  There is no
733         provision for installing the compiled files anywhere other
734         than the place specified in the <option>--prefix</option>
735         flag.</para>
736     </sect3>
737
738       <sect3><title><option>build</option></title>
739         
740         <para>The command <literal>./Setup.lhs build</literal> makes
741         this package ready for installation.  It takes no
742         flags.</para>
743
744       </sect3>
745
746       <sect3><title><option>install</option></title>
747
748         <para>The command <literal>./Setup.lhs install</literal>
749         copies files from the built package to the right location for
750         installed files, specified in the configure step.  Then it
751         registers the new package with the compiler, using the
752         &hc-pkg; command.</para>
753
754         <itemizedlist>
755           <listitem>
756             <para><option>--install-prefix=</option><replaceable>path</replaceable>
757             has three effects.  First, it over-rides the
758             <option>--prefix</option> flag specified in the
759             <option>configure</option> step, providing an
760             alternative location.  Second, it does not call
761             &hc-pkg; to register the package.
762             Instead, third, it creates an installed package
763             description file,
764             <filename>installed-pkg-descr</filename>, which can later
765             be fed to &hc-pkg;.
766             </para>
767           </listitem>
768
769           <listitem>
770             <para><option>--user</option>: if present, this flag is
771             passed to &hc-pkg; so that the package is registed for the
772             current user only.  This flag has no effect if
773             <option>--install-prefix</option> is used, because in
774             that case &hc-pkg; is not called.</para>
775           </listitem>
776
777           <listitem>
778             <para><option>--global</option>: if present, this flag is
779             passed to &hc-pkg; so that the package is registed
780             globally (this is the default if neither
781             <option>--user</option> or <option>--global</option> are
782             given).</para>
783           </listitem>
784         </itemizedlist>
785
786         <para>The reason for the <option>--install-prefix</option>
787         flag is that Roland RPM wants to create an exact installation
788         tree, all ready to bundle up for the target machine,
789         <emphasis>but in a temporary location</emphasis>. He cannot
790         use this location for <option>--prefix</option> in the
791         <option>configure</option> step, because that might bake
792         the wrong path into some compiled files.  Nor does he want to
793         register this temporary tree with the compiler on his
794         machine. Instead, he bundles up the temporary installation
795         tree, plus the <filename>installed-pkg-descr</filename>, and
796         ships them all to the target machine.  When they are installed
797         there, the post-installation script runs
798         &hc-pkg; on the
799         <filename>installed-pkg-descr</filename> file.
800             </para>
801
802         <para>Note that there is no <command>uninstall</command>
803         command in the setup script.  While it would be easy enough to
804         implement in the simple build infrastructure, we don't want to
805         require make-based build systems to implement <literal>make
806         uninstall</literal>, which is fairly non-standard and
807         difficult to get right.  In the majority of cases, we expect
808         libraries to be installed via a package manager (eg. RPM,
809         Debian apt), which already provide uninstallation
810         services.</para>
811       </sect3>
812
813       <sect3>
814         <title><option>register</option> and
815         <option>unregister</option></title>
816
817         <para>The command <literal>./Setup.lhs register</literal>
818         registers the now-installed package with the compiler.
819         Similarly, <literal>./Setup.lhs unregister</literal>
820         un-registers the package.</para>
821
822         <itemizedlist>
823           <listitem>
824             <para><option>--global</option>: registers/un-registers a
825             package as global.  This is the default.</para>
826           </listitem>
827           <listitem>
828             <para><option>--user</option>: registers/un-registers a
829             package for the current user only.</para>
830           </listitem>
831         </itemizedlist>
832       </sect3>
833     </sect2>
834
835 <sect2><title>Examples</title>
836 <sect3><title>Bob the Builder and Sam Sysadmin</title>
837
838 <para>Bob the Builder can install a HPS source distribution thus.
839 He downloads the source distribution and unpacks it into a temporary directory,
840 <literal>cd</literal>'s to that directory, and says
841 <programlisting>
842   ./Setup.lhs configure --ghc
843   ./Setup.lhs build
844   ./Setup.lhs install --user
845 </programlisting>
846 Similarly, Sam Sysadmin does exactly the same, except that he says 
847 <programlisting>
848   ./Setup.lhs install --global
849 </programlisting>
850 in the final step, so that the package is installed where all users will see it.
851       </para>
852 <para>For a binary distribution, both Bob and Sam would omit the first two steps, and just do the install step.</para>
853 </sect3>
854
855 <sect3><title>System packagers (Debian, RPM etc)</title>
856
857 <para>System packagers, such as Donald Debian, will run the configure and build steps just like Bob and Sam.
858 A that point, Donald will say
859 <programlisting>
860   ./Setup.lhs install --install-prefix=/tmp/donald
861 </programlisting>
862 to construct a ready-to-zip tree of all the installed files, plus a file <filename>installed-pkg-descr</filename>
863 that describes the installed package.  He arranges to deliver both these components to the target machine,
864 and then feed <filename>installed-pkg-descr</filename> to &hc-pkg; on the target machine.
865       </para>
866 <para>
867 The file <filename>installed-pkg-descr</filename> also contains information he needs for building
868 his Debian distribution, namely the
869 package name, version, and (exact) dependencies.
870       </para>
871       </sect3>
872    </sect2>
873 </sect1>
874
875 <sect1 id=sbi><title>The HPS simple build infrastructure</title>
876
877 <para>A package author must fulfil the specification of <xref linkend=setup>.
878 In many cases, a Haskell package will consist of nothing more than a bunch of Haskell modules,
879 with perhaps the odd C file.  In that case, the HPS provides a <emphasis>simple build infrastructure</emphasis> that
880 fulfils the specification of <xref linkend=setup>, and provides some modest further facilities besides.</para>
881 <para>This simple build infrastructure is meant to automate the common case.
882 (Think <command>hmake</command>.)  The emphasis is on ``simple'': 
883 if you want something more elaborate, you can (a) modify the simple build infrastructure (which is written in Haskell)
884 (b) use makefiles, or (c) implement something else entirely.
885 </para>
886
887 <sect2><title>Overview</title>
888 <para>
889 The simple build infrastructure works as follows.  First, Angela puts the following Haskell 
890 file <filename>Setup.lhs</filename> in the
891 root of her tree:
892 <programlisting>
893   #! runghc
894
895   > import Distribution.Simple
896 </programlisting>
897 Second, she writes a package description <filename>pkg.desc</filename> in the syntax of <xref linkend="sbi-pkg-desc">,
898 which describes the package and gives extra information to the simple build infrastructure.
899 </para><para>
900 Now Angela can build her package by saying
901 <programlisting>
902   ./Setup.lhs configure
903   ./Setup.lhs build
904 </programlisting>
905 She can even install it on her own machine by saying
906 <programlisting>
907   ./Setup.lhs install
908 </programlisting>
909 She can build a HPS source distribution:
910 <programlisting>
911   ./Setup.lhs source-dist
912 </programlisting>
913 The full details are given in <xref linkend="sbi-setup">.  
914 </para><para>
915 It is no coincidence that the interface is very similar to that for the setup script
916 for an HPS package distribution (<xref linkend="setup">).
917 In fact, <literal>Distribution.Simple.defaultMain</literal> conforms to the specification of <xref linkend="setup-spec">, and when it builds
918 a distribution, it includes <filename>./Setup.lhs</filename> in the tarball, ready to be run by Bob the Builder.
919 However, <literal>Distribution.Simple.defaultMain</literal> of course implements a richer interface than that required by
920 <xref linkend="setup-spec">, because it's intended to support Angela as well as Bob.
921 The full specification is in <xref linkend="sbi-setup">.
922 </para>
923     </sect2>
924 <sect2 id=sbi-pkg-desc><title>Package description in the simple build infrastructure</title>
925
926 <para>When using the simple build infrastructure, the package description file <filename>pkg.desc</filename>
927 contains not only the name of the package, its version and dependencies, but also a collection of information 
928 to explain to the simple build infrastructure how to build the package.  This section gives the syntax.</para>
929
930 <para>For now, we just have a checklist of what must be there
931 <itemizedlist>
932 <listitem><para><literal>exposed:</literal> Exposed modules</para>
933             </listitem>
934 <listitem><para><literal>hidden:</literal> Hidden (or internal) modules</para>
935             </listitem>
936 <listitem><para><literal>ghc-flags:</literal>,<literal>hugs-flags:</literal>,<literal>nhc-flags:</literal>  
937                 Extra compiler flags for &ghc;, &hugs;, &nhc;.</para>
938             </listitem>
939 <listitem><para> <emphasis>What else?</emphasis></para>
940           </listitem></itemizedlist></para>
941
942 <para>Why must we list hidden modules? 
943 These modules form part of the implementation of the package, but not its interface: a
944 client of the package cannot import an internal module.  They must nevertheless be listed
945 explicitly for two reasons: (a) to allow the global program invariant to be 
946 checked (see <xref linkend="packages-and-haskell">)
947 and (b) to enable a build system or programming environment to find the source files.
948         </para>
949 </sect2>
950
951 <sect2 id="sbi-setup"><title><literal>Distribution.Simple</literal></title>
952
953 <para>This section gives the command line interface supported by <literal>Distribution.Simple.main</literal>.
954 It supports all the commands described in <xref linkend=setup-spec>, and in addition the following:
955      <table frame=all><title>Extra commands supported by the simple build infrastructure setup script</title>
956
957      <tgroup cols=2 align=left colsep=1 rowsep=1>     <tbody>
958
959      <row><Entry><command>./Setup.lhs woggle </command></entry>
960          <Entry><para> Blurgh </para></entry></row>
961
962      </tbody></tgroup>
963      </table>
964     </para>
965 </sect2>
966
967 <sect2><title>The Makefile route</title>
968
969 <para>The Haskell libraries that support the simple build infrastructure can, of course, also
970 be re-used to make setup scripts that work quite differently.  At one extreme is a setup
971 script that immediately shells out into <literal>make</literal>, which does all the work.</para>
972
973 <para>To support this, HPS provides a trivial setup library <literal>Distribution.Make</literal>, which
974 simply parses the command line arguments and shells out into <literal>make</literal>.  Marcus uses the following
975 <filename>Setup.lhs</filename>
976 <programlisting>
977   module Main where
978   import Distribution.Make
979   main = setup
980 </programlisting>
981 All the package description information is assumed to be known to the makefile system, and so does not
982 appear in the setup script.
983 Thus, 
984 <programlisting>
985   setup configure --ghc
986 </programlisting>
987 invokes
988 <programlisting>
989   ./configure --with-hc=ghc
990 </programlisting>
991 Similarly
992 <literal>setup build</literal>
993 invokes
994 <literal>make all</literal> And so on.</para>
995
996 <para>Marcus simply arranges that when his makefiles build a distribution, they include this simple setup script in
997 the root of the distribution, where the Bob the Builder expects to find it.</para>
998
999 <note><para> Isaac isn't sure that we can provide much value here
1000 beside providing a standard command-line parser (which is pretty good
1001 at least).  I think it might be good to offer a boilerplate Setup.lhs
1002 file for makefiles, but implementing it in a library is a bit
1003 overkill.  Perhaps in the future, if the build system is delivered w/
1004 fptools or something, we could provide an API to wrap
1005 that. </para> <para>Simon says: fine -- but we should make it easy for Marcus Makefile.  What do we offer?</para></note>
1006
1007
1008 </sect2>
1009
1010 </sect1>
1011
1012
1013
1014 <!-- Appendix: Related Systems --------------------------------- -->
1015 <appendix><title>Related Systems</title>
1016
1017 <para>I will try to outline interesting points in a variety of systems
1018 that we can learn from.  These systems may be intended for building or
1019 installing packages, or repositories for packages.  I am not deeply
1020 familiar with all of the tools here, and would be interested in
1021 hearing more relevant points from someone with more knowledge.
1022 Another weakness of mine is that I don't know much about Microsoft
1023 Windows, so some good examples for Windows systems would be
1024 helpful.</para>
1025
1026 <section id="lip-appendix-debian"><Title>Debian</title>
1027
1028 <para>
1029 The <ulink url="http://www.debian.org">Debian GNU/Linux system</ulink>
1030 is a good example of a <emphasis>binary</emphasis> distribution
1031 (meaning that packages are distributed in binary, as opposed to source
1032 code form), and its packaging system (<application>dpkg</application>)
1033 is somewhat similar to the more famous <application>RPM</application>.
1034 Debian has several other tools to help the user to install packages,
1035 most notably, <command>apt</command>.  The Debian toolset is
1036 interesting for several reasons:
1037
1038 <itemizedList>
1039
1040   <listItem><para>It handles dependencies extremely well.  A single
1041   command can download and install a package, as well as downloading
1042   and installing all of its dependencies.</para></listItem>
1043
1044   <listItem><para>It handles updates extremely well.  One command
1045   (<command>apt-get update</command>) checks for new versions of
1046   packages and updates a local database.  Another command
1047   (<command>apt-get dist-upgrade</command>) downloads and installs all
1048   new versions of installed packages and any new
1049   dependencies.</para></listItem>
1050
1051
1052   <listItem><para>There are standard commands for downloading and
1053   building packages from source.  If I'm interested in hacking on a
1054   package, I can run <command>apt-get source packagename</command>
1055   which will download and unpack the source code for the package.  The
1056   source can then be built with the standard command
1057   <command>debuild</command>.</para></listItem>
1058
1059
1060   <listItem><para>The Debian Project maintains a central repository
1061   for packages, and the packaging tools offer support for using
1062   unofficial repositories as well.  The central repositories include a
1063   set of servers, the <emphasis>autobuilders</emphasis>, which compile
1064   uploaded source packages for a variety of hardware architectures
1065   (see below) and make them available as binary packages.  As a
1066   packager, I merely upload the source code to my package, and the
1067   autobuilders do the rest.</para></listItem>
1068
1069   <listitem><para>Currently the hardware architectures supported by
1070   Debian are Intel x86, Motorola 68k, Sun SPARC, Alpha, PowerPC, ARM,
1071   MIPS, HP PA-RISC, IA-64, S/390.  Debian also runs on non-Linux
1072   systems, including GNU/Hurd, GNU/NetBSD, and GNU/FreeBSD.  The
1073   package management tools also run on MacOS X under the name of the
1074   <application>Fink</application> project.</para></listItem>
1075
1076 </itemizedList>
1077 </para>
1078
1079 </section>
1080
1081 <section id="lip-appendix-distutils"><title>Python Distutils</title>
1082
1083 <para>Python's <ulink
1084 url="http://www.python.org/sigs/distutils-sig/">&distutils;
1085 system</ulink> is in many ways similar to what we propose here.  It is
1086 a system for building and installing Python modules, written purely in
1087 Python.  The user interface is a Python script,
1088 (<filename>setup.py</filename> by convention) and a setup
1089 configuration file (<filename>setup.cfg</filename> by convention). To
1090 quote from <ulink
1091 url="http://www.python.org/doc/current/dist/dist.html">Distributing
1092 Python Modules</ulink>, "The setup configuration file is a useful
1093 middle-ground between the setup script--which, ideally, would be
1094 opaque to installers -- and the command-line to the setup script,
1095 which is outside of your control and entirely up to the
1096 installer. "</para>
1097
1098 <para>Its noteworthy that Python has a big advantage over many
1099 programming languages when implementing a system like &distutils;: It
1100 is designed to be well suited to so-called scripting tasks, which are
1101 common to the installation task, and Python has done these tasks in a
1102 portable way for a long time.  I believe that Haskell should evolve
1103 portable ways to perform common scripting tasks.</para>
1104
1105 </section>
1106
1107 <section id="lip-appendix-cpan-boost"><title>&cpan; and Boost</title>
1108
1109 <para> Quoting from &cpan;'s <ulink url="http://www.cpan.org"> web
1110 site </ulink> "&cpan; is the Comprehensive Perl Archive Network, a
1111 large collection of Perl software and documentation."  That really
1112 says it all.  It is a central location where Perl developers can
1113 contribute the software they write.</para>
1114
1115 <para>&cpan; has a means of standardizing installation,
1116 <filename>Makefile.pl</filename> (which is a Perl script which creates
1117 a Makefile with targets like "install", "test", "config", "clean", etc.). Makefile.pl typically uses the <ulink
1118 url="http://www.perldoc.com/perl5.6/lib/ExtUtils/MakeMaker.html">MakeMover
1119 module</ulink>. It also has a means of registering a namespace for the
1120 module that a developer is contributing.</para>
1121
1122 <para>From the Boost <ulink url="http://www.boost.org">web
1123 site</ulink> "[Boost] provides free peer-reviewed portable C++ source
1124 libraries. The emphasis is on libraries which work well with the C++
1125 Standard Library. One goal is to establish "existing practice" and
1126 provide reference implementations so that the Boost libraries are
1127 suitable for eventual standardization. Some of the libraries have
1128 already been proposed for inclusion in the C++ Standards Committee's
1129 upcoming C++ Standard Library Technical Report."</para>
1130
1131 <para>From what I can tell, unlike &cpan;, Boost is a bit more focused
1132 on standards and review.  That is, it is perhaps more Cathedral than
1133 Bazaar <footnote><para>See Eric Raymond's essay <ulink
1134 url="http://catb.org/~esr/writings/cathedral-bazaar/cathedral-bazaar/">The
1135 Cathedral and the Bazaar</ulink>.</para></footnote>. Boost does not
1136 currently have a standard means of installation.</para>
1137 </section>
1138
1139 <section id="lip-appendix-freebsd"><title>FreeBSD's Ports System</title>
1140
1141 <para>The FreeBSD <ulink url="http://www.freebsd.org/ports/">Ports
1142 Collection</ulink> is a collection of software with a standard means
1143 of compilation and installation.  FreeBSD is a source distribution
1144 (whereas Debian is a Binary Distribution).  Packages come in
1145 source-code form with a Makefile suitable for installing the program
1146 on a FreeBSD system.  The ports collection is very large (around 9000
1147 packages).</para>
1148
1149 <para>Some things may be simpler with a source distribution than with
1150 a binary distribution.  For instance, since the code is expected to be
1151 already on the machine and buildable, when a new compiler is installed
1152 one merely needs to rebuild the dependant libraries.  In contrast,
1153 with a binary distribution like Debian one must wait for a new binary
1154 package to be made available.  However, as I understand it, FreeBSD
1155 has no means of recompiling dependant packages automatically when a
1156 new compiler is installed.</para>
1157
1158 </section>
1159
1160 <!-- FIX: I'm not sure why I thought this was so interesting.  I don't -->
1161 <!-- reference it anywhere and it really doesn't add anything that the perl -->
1162 <!-- and python systems don't have. -->
1163
1164 <section id="lip-appendix-xemacs"><title>The &xemacs; Packaging
1165 System</title>
1166
1167 <para>
1168 As most folks know, &xemacs; is not only a text editor, but also a
1169 Lisp environment.  Its functionality can be extended with lisp
1170 programs, and many such programs are available from &xemacs;' <ulink
1171 url="http://www.xemacs.org/Documentation/21.5/html/lispref_4.html">Packaging
1172 System</ulink>.  Simply put, the packaging system offers a menu-driven
1173 interface within &xemacs; where the user can browse available
1174 packages, select packages she is interested in, and ask &xemacs; to
1175 download and install them.  This system is interesting because it is
1176 cross-platform (Unix, Linux, Windows, etc.) and is designed to work
1177 only with elisp.
1178 </para>
1179
1180
1181
1182  </section>
1183
1184 <section id="lip-appendix-make-based"><title>Make-Based Systems</title>
1185
1186 <para>The "fptools" build system has been used for many years in the
1187 cross-platform &ghc; compiler.  It is a make-based system which is
1188 capable of a wide variety of installation tasks, compilation tasks,
1189 and system configuration tasks.  Currently, it is not entirely generic
1190 across &impls;, and does not yet deal with some of the package
1191 registration issues mentioned above.</para>
1192
1193 <para>At Yale, another system is being developed.  It is also a
1194 make-based system and works reasonably well on various platforms
1195 (Unix, Linux, Windows) and &impls;.  It also does not yet deal with
1196 all of the package registration issues mentioned above.</para>
1197
1198 <para>Both tools can benefit from a standard packaging system.</para>
1199
1200 <para>Because <application>make</application> has been used for many
1201 years, it is expected that these systems will be able to do more than
1202 the initial release of the &distMod;.  The Setup script will be
1203 designed with this in mind, and should be able to wrap these tools in
1204 order to provide a common interface for users and for layered
1205 tools.</para>
1206
1207 </section>
1208
1209 <section id="lip-appendix-hmake"><title>&hmake;</title>
1210
1211 <para>From the &hmake; <ulink
1212 url="http://www.cs.york.ac.uk/fp/hmake/">home page</ulink>,
1213 <quote>&hmake; is an intelligent compilation management tool for
1214 Haskell programs. It automatically extracts dependencies between
1215 source modules, and issues the appropriate compiler commands to
1216 rebuild only those that have changed, given just the name of the
1217 program or module that you want to build. Yes, you need never write a
1218 Makefile again!</quote> &hmake; also does a good job of handling the
1219 variety of compilers that might be installed on a user's system.  It
1220 maintains a list of compilers and can switch between them according to
1221 a flag.  It also has a default compiler.</para>
1222
1223 <para>&hmake; is particularly interesting to us because it is written
1224 in Haskell and handles the task of compiling Haskell tools quite well.
1225 One shortcoming is that it is not extensible on a per-project basis:
1226 it is difficult to add support for new preprocessors without editing
1227 the &hmake; code itself.  It does, however, perform a lot of the tasks
1228 that &DistBuild; will ultimately have to perform, and we hope to reuse
1229 some of the code.</para>
1230
1231 <para>Another interesting feature of &hmake; is the
1232 <application>Haskell Interactive</application> tool (hi).  hi
1233 <quote>is, an interpreter-like environment that you can wrap over any
1234 common Haskell compiler to achieve an interactive development
1235 style.</quote> This is interesting because it would be nice to have a
1236 generic <filename>/usr/bin/haskell</filename> which would use the
1237 default compiler to interpret Haskell scripts.</para>
1238
1239 </section>
1240
1241 </appendix>
1242  
1243 </article>