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