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