Implemented a few fixes we talked about on IRC:
[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  hps         "<application>Cabal</application>">
6 <!entity  tool        "<application>tool</application>">
7 <!entity  autoconf    "<application>autoconf</application>">
8 <!entity  impl        "Haskell Implementation">
9 <!entity  impls       "Haskell Implementations">
10 <!entity  distMod     "<className>Distribution</className> module">
11 <!entity  haskellConfig  "<application>haskell-config</application>">
12 <!entity  DistPackage  "<classname>Distribution.Package</classname>">
13 <!entity  DistBuild    "<classname>Distribution.Build</classname>">
14 <!entity  DistInstall  "<classname>Distribution.Install</classname>">
15 <!entity  DistConfigure   "<classname>Distribution.Config</classname>">
16 <!entity  hunit       "<application>HUnit</application>">
17 <!entity  distutils   "<application>Distutils</application>">
18 <!entity  cpan        "<application>CPAN</application>">
19 <!entity  xemacs      "<application>XEmacs</application>">
20 <!entity  hmake       "<application>hmake</application>">
21 <!entity  dpkg        "<application>dpkg</application>">
22 <!entity  rpm        "<application>rpm</application>">
23 <!entity  hc-pkg     "<command>hc-pkg</command>">
24 <!entity  pkg-desc     "<filename>Setup.description</filename>">
25 ]>
26  
27 <!-- Look for items marked "FIX" -->
28
29 <!-- ToDo: -->
30
31 <!-- Look at Package data types again and add the version information where -->
32 <!-- necessary. -->
33
34 <article id="hps">
35   <artHeader>
36     <date>2004-04-24</date>
37     <title>The Haskell Cabal</title>
38     <subtitle>A Common Architecture for Building Applications and Tools</subtitle>
39     <author>
40       <firstname>Isaac</firstname>
41       <surname>Jones</surname>
42     </author>
43     <author>
44       <firstname>Simon</firstname>
45       <surname>Peyton Jones</surname>
46     </author>
47     <author>
48       <firstname>Simon</firstname>
49       <surname>Marlow</surname>
50     </author>
51     <author>
52       <firstname>Malcolm</firstname>
53       <surname>Wallace</surname>
54     </author>
55     <author>
56       <firstname>Ross</firstname>
57       <surname>Patterson</surname>
58     </author>
59
60     <address><email>ijones@syntaxpolice.org</email></address>
61     <abstract>
62
63       <para>The Haskell Library and Tools Infrastructure Project is an
64       effort to provide a framework for developers to more effectively
65       contribute their software to the Haskell community.  This
66       document specifies the <emphasis>Common Architecture for
67       Building Applications and Tools(&hps;)</emphasis>, which
68       contributes to the goals of the Haskell Library and Tools
69       Infrastructure Project.  </para>
70       <para>Specifically, the &hps; describes what a Haskell 
71         package is, how these packages interact with the language,
72         and what Haskell implementations must to do to support packages.
73         The &hps; also specifies some infrastructure (code) that makes
74         it easy for &tool; authors to build and distribute conforming packages.
75         </para>
76       <para>The &hps; is only one contribution to the Library Infrastructure project.
77         In particular, the &hps; says nothing about more global issues such as
78         how authors decide where in the module name space their library should live;
79         how users can find a package they want; how orphan packages find new owners;
80         and so on.</para>
81       <para> The &hps; has been discussed by the implementors of
82         &ghc;, &nhc;, and &hugs;, all of whom are prepared to
83         implement it.  The proposal is now open for wider
84         debate. Please contribute by emailing
85         <email>libraries@haskell.org</email>.</para>
86     </abstract>
87   </artheader>
88
89
90 <!-- Solution ------------------------------------------------- -->
91
92 <sect1 id=hli-goals><title>The Haskell Package System: goals</title>
93
94 <para>The Haskell Package System (&hps;) has the following main goal:
95 to specify a standard way in which a Haskell &tool; can be packaged, so that it is
96 easy for consumers to use it, or re-package it, 
97 regardless of the Haskell implementation or installation platform.</para>  
98
99 <para>The &hps; also
100 supports &tool; authors by providing an infrastructure that automates the
101 process of building and packaging simple &tool;s.  It is not necessary to use
102 this code&mdash;indeed complex libraries may exceed its abilities&mdash;but it should
103 handle many cases with no trouble.</para>
104
105 <sect2><title>Dramatis personae</title>
106
107 <para>The &hps; serves a number of people in different ways:
108
109 <itemizedlist>
110 <listitem><para>
111  <emphasis>Joe User</emphasis> is simply a Haskell user.  He does not download new packages.  Nevertheless,
112 he needs to know about his Haskell compiler's <option>-package</option> flag (see <xref linkend="compiler-reqts">).
113             </para>
114           </listitem>
115 <listitem><para>
116  <emphasis>Bob the Builder</emphasis> and <emphasis>Sam Sysadmin</emphasis> both download, build,
117   and install new packages. The only difference between the two is that Sam has root permission,
118   and can install packages in more globally-visible places.
119             </para>
120           </listitem>
121
122 <listitem><para><emphasis>Peter Packager</emphasis> builds operating
123 system specific install files (e.g. .msi .rpm .deb) from packages
124 supplied by Marcus or Angela.  We might also call him <emphasis>Roland
125 RPM</emphasis>, <emphasis>Donald Debian</emphasis>, and
126 <emphasis>Willie Windows</emphasis> who build Linux RPM, Debian, and
127 Windows installer packages respectively (this list is not exhaustive).
128 They do this as a service to their platform's community, and may know
129 little or nothing about the internal details of the Haskell packages
130 they are wrapping up.  </para> </listitem>
131
132 <listitem><para><emphasis>Isabella Installer</emphasis> installs
133 binary packages supplied by Peter or Angela, (or Rowland, Donald, and
134 Willie).  Isabella requires only a Haskell compiler/interpreter.  She
135 can use rpm to install packages by Rowland.  She cannot or will not
136 build the packages herself, so she relies on Peter to provide them.
137 She won't use the Setup script directly from Angela, but she might use
138 a layered tool like <application>haskell-install</application>, which does all
139 the work of downloading and installing simple
140 packages.</para></listitem>
141
142 <listitem><para>
143  <emphasis>Angela Author</emphasis> wants to write a simple Haskell &tool;, and distribute it with 
144 minimum fuss, in such a way that all the above folk can easily use it.
145             </para>
146           </listitem>
147 <listitem><para>
148  <emphasis>Marcus Makefile</emphasis> is like Angela, but more sophisticated.  He has a complicated &tool;,
149 and uses makefiles.  Still, he wants to arrange that Roland, Donald, Bob, Sam, and Joe don't need to know
150 about his internal complexity.
151             </para>
152           </listitem>
153         </itemizedlist>
154
155 We describe Angela and Marcus as <emphasis>producers</emphasis> of
156 their packages, and all the others as package
157 <emphasis>consumers</emphasis>.
158       </para>
159
160 <para>Note that though these users all have different names, it is very
161 common for their roles to overlap when it comes to real people.  For
162 instance, if Bob builds packages for himself, he becomes Joe once
163 they're built.  These personas are <emphasis>use cases</emphasis>, and
164 not meant to represent completely distinct individuals.</para>
165
166     </sect2>
167
168 <sect2 id="example"><title>An example</title>
169
170 <para>To give the idea, here is a simple example.  Angela has written a couple of Haskell modules that
171 implement sets and bags; she wants to distribute them to Bob as a package called,
172 say, <literal>angela-coll</literal>.  Let's say that the modules are
173 <literal>Data.Set</literal>, <literal>Data.Bag</literal>, <literal>Angela.Internals</literal>.
174 (The &hps; says nothing about how Angela decides where in the name space to put her modules.)
175 Angela only wants to expose the first two to Bob; the <literal>Angela.Internals</literal> module is (as its
176 name suggests) internal to the package.
177 </para>
178 <para>Angela decides to use the simple build infrastructure that the &hps; provides.  She is working in
179 a directory <filename>~/coll</filename>.  In there she puts the modules, in sub-directories
180 driven by their module name: <filename>~/coll/Data/Set.hs</filename>,
181  <filename>~/coll/Data/Bag.hs</filename>,
182  and <filename>~/coll/Angela/Internals.hs</filename>.
183 Next, she writes
184 a <emphasis>package description</emphasis>, which she puts in <filename>~/coll/</filename>&pkg-desc;:
185 <programlisting>
186 Name: angela-col
187 Version: 0.1.1.1.1-foo-bar-bang
188 License: LGPL
189 Copyright: Copyright (c) 2004, Angela Author
190 Exposed-Modules: A, B, B.C
191 </programlisting>
192 She also creates a small Haskell file <filename>~/coll/Setup.lhs</filename> as follows:
193 <programlisting>
194   #! /usr/bin/env runhugs
195
196   > module Main where
197   > import Distribution.Simple( defaultMain )
198   > main = defaultMain
199 </programlisting>
200
201 This library implements the &hps; simple build infrastructure.</para>
202
203 <para>The first line arranges that when Angela, (or Joe, or Sam, etc.)
204 executes <filename>Setup.lhs</filename> as a shell script, the shell
205 will invoke <command>runhugs</command>, which will in turn run
206 <literal>main</literal> imported from the library
207 <literal>Distribution.Simple</literal>.  </para>
208
209 <para>It is not necessary that the script be run this way, it is just
210 a convinient way to run it.  Sam or Joe may choose to compile the
211 setup script into an executable with NHC or GHC and then run it
212 directly (it is a literate Haskell script so that it can be compiled
213 without the first line causing a syntax error).  Another option is for
214 that first line to read <programlisting>!# /usr/bin/env runhaskell</programlisting>
215 where <command>runhaskell</command> is a symlink to
216 <command>runhugs</command>, <command>runghc</command>, or
217 <command>runnhc</command>.</para>
218
219
220 <para> Now she is ready to go. She types:
221 <programlisting>
222   ./Setup.lhs configure --ghc
223   ./Setup.lhs build
224   ./Setup.lhs sdist
225 </programlisting>
226 The first line readies the system to build the &tool; using &ghc;; for example, it checks that &ghc; exists on the system.
227 The second line checks that
228 the &tool; does indeed build flawlessly.  (At this point she can write and execute tests, as we discuss later.)
229 The third line wraps up the package as a source distribution, making the file <filename>~/coll/angela-coll-1.tar.gz</filename>.
230 </para>
231 <para>
232 Angela emails the tar file to Bob, who untars it into <filename>tmp/coll</filename>.
233 He <command>cd</command>'s to that directory and types
234 <programlisting>
235   ./Setup.lhs configure --ghc
236   ./Setup.lhs build
237   ./Setup.lhs install
238 </programlisting>
239 He's all done. Now in his Haskell programs, Bob can simply <literal>import</literal> the new
240 modules <literal>Data.Set</literal> and <literal>Data.Bag</literal>. He does not need to give extra flags
241 to &ghc; to tell it to look for Angela's modules; they are there automatically.
242 If Angela used the same module names as someone else, Bob may need finer control: see <xref linkend="compiler-reqts">.</para>
243 <para>
244 If Angela wrote her modules in a suitably portable variant of Haskell,
245 Bob could also have said <option>--hugs</option> or
246 <option>--nhc</option> in his <option>configure</option> line, and the
247 package would have been built and installed for those compilers
248 instead.
249       </para>
250     </sect2>
251   </sect1>
252
253
254 <sect1 id=hli-overview><title>The Haskell Package System: overview</title>
255
256 <para>This section summarises the vocabulary and main features of the Haskell Package System.</para>
257
258 <sect2 id="package-descr"><title>Packages</title>
259
260 <para>A <emphasis>package</emphasis> is the unit of distribution for the &hps;.
261 Its purpose in life, when installed, is to make available some Haskell modules for
262 import by some other Haskell program.   However, a package may consist of 
263 much more than a bunch of Haskell
264 modules: it may also have C source code and header files, documentation, test cases, auxiliary 
265 tools and whatnot.</para>
266
267 <para>
268 Each package has:
269 <itemizedlist>
270 <listitem><para>A globally-unique <emphasis>package name</emphasis>, containing no spaces. Chaos will result
271 if two distinct packages with the same name are installed on the same system.  How unique package names are
272 handed out is not part of this specification, but there will presumably be some global web site where
273 package authors can go to register a package name. </para>
274 </listitem>
275 <listitem><para>A <emphasis>version</emphasis>, consisting of a sequence of one or more integers.
276 </para></listitem>
277
278 <listitem><para>
279 <emphasis>A list of explicit dependencies</emphasis> on other packages.  These are typically not exact; e.g. "I need <literal>hunit</literal> version
280 greater than 2.4".
281             </para>
282           </listitem>
283 <listitem><para>
284 <emphasis>A list of exposed modules</emphasis>.  Not all of the modules that comprise a package implementation are necessarily
285 exposed to a package client.
286 The ability to expose some, but not all, of the modules making up a package
287 is rather like using an explicit export list on a Haskell module.</para>
288           </listitem>
289 </itemizedlist>
290 The first two components can be combined to form a single text string called the <emphasis>package ID</emphasis>, 
291 using a hyphen to separate the version
292 from the name, and dots to separate the version components.  For example, "hunit-2.3".
293 </para>
294
295 </sect2>
296
297 <sect2 id="packages-and-haskell"><title>Packages and the Haskell language</title>
298 <para>A complete Haskell program will consist of one or more modules (including <literal>Main</literal>)
299 compiled against one or more packages (of which the Prelude is one).  These packages are not referred to
300 explicitly in the Haskell source; instead, the packages simply populate the hierarchical space of module names.
301 </para>
302 <para>Complete programs must obey the following invariant.  <emphasis>Consider all the Haskell modules that
303 constitute a complete program: no two modules must have the same module name.</emphasis></para>
304
305 <para>This invariant is conservative.  It preserves the existing semantics of Haskell, and is 
306 relatively easy to implement.  In particular, the the full name of an entity (type, class, function), which is
307 used to determine when two entities are the same, is simply a pair of the module name and the entity name.</para>
308
309 <para>The invariant is unsatisfactory, however, because it does not support abstraction at
310 the package level. For example, a module with an internal (hidden, non-exposed) module called <literal>Foo</literal>
311 cannot be used in the same program as another package with an unrelated internal module also called <literal>Foo</literal>.
312 Nor can a program use two packages, P and Q, which depend on different versions of the same underlying package R.
313 We considered more sophisticated schemes, in which (for example) the package name, or package ID, is implicitly
314 made part of every module name.  But (a) there is a big design space, and (b) it places new requirements on the
315 implementations.  Hence a conservative starting point.</para>
316     </sect2>
317
318 <sect2><title>Packages and compilers</title>
319
320 <para>We use the term ``compiler'' to mean &ghc;, &hugs;, &nhc;, hbc, etc.  (Even though
321 &hugs; isn't really a compiler, the term is less clumsy than ``Haskell implementation''.)</para>
322
323 <para> The
324 &hps; requires that a conforming Haskell compiler is somewhat package aware.
325 In summary, the requirements are these:
326 <itemizedlist>
327 <listitem><para>Each compiler <command>hc</command> must provide an
328 associated package-management program &hc-pkg;.  A compiler user
329 installs a package by placing the package's supporting files
330 somewhere, and then using &hc-pkg; to make the compiler aware of the
331 new package.  This step is called <emphasis>registering the package
332 with the compiler</emphasis>.  </para></listitem> <listitem><para>To
333 register a package, &hc-pkg; takes as input an <emphasis>installed
334 package description (IPD)</emphasis>, which describes the installed
335 form of the package in detail.  The format of an IPD is given in <xref
336 linkend="ipd">.</para>
337           </listitem>
338
339           <listitem>
340             <para>Subsequent invocations of <command>hc</command>
341             will include modules from the new package in the module
342             name space (i.e. visible to <literal>import</literal>
343             statements).</para>
344           </listitem>
345           <listitem>
346             <para>The compiler should support
347             <option>-package</option> and
348             <option>-hide-package</option> flags for finer-grain
349             control of package visibility.</para>
350           </listitem>
351         </itemizedlist>
352
353         A complete specification of these requirements is given in
354         <xref linkend="compiler-reqts">.</para>
355     </sect2>
356
357 <sect2><title>Package distributions</title>
358
359 <para>A &hps; package can be distributed in several forms:
360 <itemizedlist>
361 <listitem><para>
362 A <emphasis>&hps; source distribution</emphasis> is a tree of files (tar-ball, zip file etc)
363 containing the &tool;'s sources, which may need to be
364 compiled before being installed.  The same source tarball may well be installable for several
365 Haskell implementations, OSs, and platforms.
366             </para>
367 <para>A source distribution may contain fewer files than appear in the developer's CVS repository; for example,
368 design notes may be omitted.  It may also contain some derived files, that do not appear in the
369 the developer's repository; for example, ones made by a somewhat exotic pre-processor where it
370 seems simpler to ship the derived file than to ensure that all consumers have the pre-processor.</para></listitem>
371 <listitem><para>
372 A <emphasis>&hps; binary distribution</emphasis> is a tree of files that contains a pre-compiled &tool;, ready
373 for installation.  The pre-compilation means that the distribution will be Haskell-compiler-specific, and certain 
374 "looser" dependencies (<literal>hunit > 2.3</literal>) will now be precisely fixed (<literal>hunit == 2.4</literal>).
375             </para>
376           </listitem>
377
378 <listitem><para>
379 The package may be wrapped up as an <emphasis>RPM</emphasis>, <emphasis>Debian</emphasis> package, 
380 or <emphasis>Windows installer</emphasis> (this list is not exhaustive).
381 In that case, the way it is installed is prescribed by the respective distribution mechanism;
382 the only role of the &hps; is to make it easy to construct such distributions. All three are
383 compiler-specific (indeed compiler-version-specific) binary distributions.
384             </para>
385           </listitem>
386         </itemizedlist></para>
387     </sect2>
388
389 <sect2><title>The Setup script</title>
390
391 <para>The key question is this: how should Angela Author present her &hps; package so that 
392 her consumers (Bob, Sam, Willie, etc) can conveniently use it?</para>
393
394 <para>Answer: she provides a tree of files, with two specific files in the
395 root directory of the tree:  
396 <itemizedlist>
397 <listitem><para>&pkg-desc; contains a short description of the package:
398 specifically, the package name, version, and dependencies.  It may also contain further information
399 specific to the particular build system.  The syntax of the package description file
400 is given in <xref linkend="pkg-desc">.
401             </para>
402           </listitem>
403 <listitem><para>
404 <filename>Setup.lhs</filename> is an executable Haskell program 
405 which conforms to a particular specification, given in detail in <xref linkend="setup">.
406 In summary, though, <filename>Setup.lhs</filename> allows a consumer to configure, build,
407 test, install, register, and unregister a package.  </para>
408           </listitem>
409         </itemizedlist>
410
411 The Setup script is an <emphasis>interface</emphasis>.  It is meant to
412 give a standard look-and-feel to packages for the sake of Joe User,
413 Bob Builder, Peter Packager, Sam Sysadmin, and Rowland RPM, as well as for layered
414 software tools.  This interface provides an abstraction layer on top
415 of any implementation that Angela or Marcus prefers.</para>
416
417 <para>The &hps; allows a package author to write the setup script in any way
418 she pleases, provided it conforms to the specification of <xref
419 linkend="setup">.  However, many Haskell packages consist of little
420 more than a bunch of Haskell modules, and for these the &hps; provides
421 <emphasis>the simple build infrastructure</emphasis>, a Haskell
422 library that does all the work.  The simple build infrastructure,
423 which was used for the example in <xref linkend="example">, is
424 described in <xref linkend="sbi">.</para>
425
426 <!-- Why Haskell ---------------------------- -->
427
428 <para>In principle, the <literal>Setup</literal> script
429 could be written in any language; so why do we use Haskell?
430 <itemizedList>
431
432 <listItem><para>Haskell runs on all the systems of interest.</para></listItem>
433
434 <listItem><para>Haskell's standard libraries should include a rich set of operating
435 system operations needed for the task.  These can abstract-away the
436 differences between systems in a way that is not possible for
437 Make-based tools.</para></listItem>
438
439 <listItem><para>Haskell is a great language for many things, including tasks
440 typically relegated to languages like Python.  Building, installing,
441 and managing packages is a perfect proving ground for these tasks, and
442 can help us to discover weaknesses in Haskell or its libraries that
443 prevent it from breaking into this "market".  A positive side-effect
444 of this project might be to make Haskell more suitable for "scripting"
445 tasks.</para></listItem>
446
447 <listItem><para>Likewise, each piece of the project (Building, Installing, and
448 Packaging) can be leveraged elsewhere if we make them into
449 libraries.</para></listItem>
450
451 <listItem><para>Make is not particularly good for parsing, processing, and sharing
452 meta-information about packages.  The availability of this information
453 to Haskell systems (including compilers, interpreters, and other
454 tools) is useful.  Unlike Make, Haskell can also reuse unrelated
455 algorithms, parsers, and other libraries that have been developed in
456 the past.</para></listItem>
457
458 <listItem><para><emphasis>Dogfooding</emphasis>, the act of using the tools you
459 develop, is a healthy policy.</para></listItem>
460
461 </itemizedList>
462 It is convenient for consumers to execute <filename>Setup.lhs</filename> directly, thus:
463 <programlisting>
464   ./Setup.lhs ...
465 </programlisting>
466 This can be achieved by starting <filename>Setup.lhs</filename> with "<literal>#! /usr/bin/env runhugs</literal>"
467 or "<literal>#! /usr/bin/env runghc</literal>" .
468 Since it's a literate Haskell script (<literal>.lhs</literal> file), the Haskell compiler will ignore
469 this line.
470 However, nothing stops a consumer from running the script interactively, or compiling it and running 
471 the compiled binary.  Any implementation of Haskell should suffice to run the script, provided 
472 the implementation has the &hps; libraries installed.  
473         </para>
474       </sect2>
475   </sect1>
476
477 <!-- COMPILER REQUIREMENTS ---------------------------- -->
478
479 <sect1 id="compiler-reqts"><title>What the compilers must implement</title>
480
481 <para>The &hps; requires that the Haskell implementations be somewhat package-aware.
482 This section documents those requirements.</para>
483
484 <sect2><title>Building and registering a package</title>
485
486 <para>Installing a package ultimately involves these steps:
487 <itemizedlist>
488 <listitem> <para>
489  <emphasis>Compiling the source files</emphasis>, by invoking the compiler.  Even &hugs; may require 
490      some processing (e.g running cpp or cpphs).
491 </para></listitem>
492
493 <listitem> <para>
494   <emphasis>Copying the compiled files into some permanent place</emphasis>.  Typically the compiler
495      places no pre-conditions on where "some place" is; instead one
496      usually follows the conventions of the host operating system.
497 </para></listitem>
498
499 <listitem> <para>
500   <emphasis>Registering the package</emphasis>: telling the compiler about the 
501      existence of the package, and where its files are.
502   To register the package one invokes a compiler-specific program &hc-pkg; (i.e. <command>ghc-pkg</command>, 
503   <command>hugs-pkg</command> etc), passing it an <emphasis>installed package description (IPD)</emphasis>
504   describing the package.  The format of an IPD is given in <xref linkend="ipd">.
505 </para></listitem>
506 </itemizedlist>
507 </para>
508 <para>It must be possible to register many versions of the same package.</para>
509
510 <sect3><title>Global packages and user packages</title>
511
512 <para>
513 A package can be registered either as a <emphasis>global package</emphasis> or as a <emphasis>user package</emphasis>.
514 The former means that anyone invoking <command>hc</command> will see the new package.  The latter means
515 that only the user who installed the package will see it.
516 </para>
517 <para>
518 User packages <emphasis>shadow</emphasis> global packages, in the following sense:</para>
519         <itemizedlist>
520           <listitem>
521             <para>A Haskell <literal>import</literal> for module M
522             will seek M in a user package first.</para>
523           </listitem>
524           <listitem>
525             <para>The &hc-pkg; commands that take package IDs will
526             look for a user package first.</para>
527           </listitem>
528         </itemizedlist>
529
530         <para>Each user has one package database per compiler and
531         version.  That is, the user packages for GHC 6.2 are separate
532         from those for GHC 6.2.1.  If there are multiple installations
533         of a particular compiler version on the system, then they will
534         all use the same user packages, so the user should refrain
535         from using user packages with different installations of the
536         same compiler version, unless they can guarantee that the
537         different installations are binary compatible, such as if they
538         were installed from identical binary distributions.</para>
539         
540         <para>For instance, lets say that Joe User mounts his home
541         directory on his Linux machine and on his Solaris machine.  He
542         also uses ghc-6.2 on both machines.  His user packages are
543         installed in ~/ghc-6.2-packages (or something) and are
544         compiled for Linux.  Now he had better not use these packages
545         with the Solaris compiler, because they are in a spot where
546         the Solaris compiler will find them!</para> </sect3>
547
548 <sect3><title>Exposed packages and hidden packages</title>
549
550 <para>
551 An installed package can be <emphasis>exposed</emphasis> or <emphasis>hidden</emphasis>.  An exposed package
552 populates the module name space, while a hidden package does not.  Hidden packages are nevertheless necessary.
553 For example, the user might use
554 package A-2.1 and B-1.0; 
555 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
556 should be hidden, so that user imports see A-2.1. (However, note that the 
557 whole-program invariant described in <xref linkend="packages-and-haskell"> implies that a program using B-1.0 could
558 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 
559 use the same module names.)
560 </para>
561 <para>The registration program &hc-pkg; provides operations to expose or hide an 
562 already-installed package.  By default, installing a package installs it exposed, and hides any
563 existing installed package of the same name (and presumably different version).
564           </para>
565 <para>Hiding or exposing a package is an operation that can be performed, by &hc-pkg;,
566 on any package.  It is quite distinct from the question of which modules in a package are hidden or
567 exposed (see <xref linkend="package-descr">), which is a property of the package itself.  Only the exposed
568 modules of an exposed package populate the module name space seen by a Haskell <literal>import</literal> statement.
569 </para>
570 </sect3>
571
572 <sect3><title>Registration invariants</title>
573
574 <para>The registration program &hc-pkg; checks the following invariants:
575 <itemizedlist>
576 <listitem> <para>
577 Before registering a package P, check all the packages that P depends on are already registered.
578 If P is being registered as a global package, P's dependencies must also be global packages.
579 </para></listitem>
580
581 <listitem> <para> Before registering an exposed user package P, check
582 that the modules that are exposed by P do not have the same names (in
583 the hierarchical module name space) as any other module in an exposed
584 user package Q.  Similarly for system packages.  (However, one may
585 register a system package which exposes a module with the same name as
586 a user package, and vice-versa.)  </para></listitem>
587
588 <listitem> <para>
589 Before un-registering a package P, check that no package that depends on P is registered.
590 The exception is that when un-registering a global package, &hc-pkg; cannot
591 check that no user has a user package depending on P.</para>
592             </listitem>
593 </itemizedlist>
594         </para>
595       </sect3>
596     </sect2
597
598     <sect2>
599       <title>The <option>-package</option> compiler flag</title>
600
601       <para>By default, the module namespace is populated only by the
602       exposed modules of exposed packages.  This can be overridden
603       using the <option>-package</option> flag, which temporarily
604       exposes a particular package, hiding any other packages of the
605       same name.</para>
606
607       <para>Later options override earlier ones, so that for example
608       <literal>-package hunit-1.2 -package hunit-1.3</literal> will
609       result in <literal>hunit-1.3</literal> being exposed.</para>
610
611       <para>Additionally, compilers should provide a
612       <option>-hide-package</option> flag, which does the opposite of
613       <literal>-package</literal>: it temporarily hides a package for
614       this run of the compiler.</para>
615
616       <para>When all the <option>-package</option> and
617       <option>-hide-package</option> flags on the compiler's command
618       line have been processed, the resulting module namespace must
619       not contain any overlapping modules; the compiler should check
620       this and report any errors.</para>
621     </sect2>
622
623 <sect2><title>The interface to &hc-pkg;</title>
624
625 <para>Registering a package with a compiler records the package information in some
626 implementation-specific way; how it does so is not constrained by the &hps;.
627 Much of an IPD is independent of the compiler, but it may also include compiler-specific
628 fields.</para>
629
630 <para>Each Haskell implementation <command>hc</command> must provide an associated program &hc-pkg; which 
631 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
632
633 <note><para>Some of these commands (unregister, hide, and describe) make sense for package IDs which offer a range, such as "hc-pkg unregister hunit&lt;2.3".</para></note>
634
635      <table frame=all><title>&hc-pkg; interface</title>
636
637      <tgroup cols=2 align=left colsep=1 rowsep=1>     <tbody>
638
639      <row><Entry><cmdsynopsis><command>hc-pkg register</command> <group choice=req>
640                       <arg><replaceable>filename</replaceable></arg>
641                       <arg><option>-</option></arg></group>
642                   <group choice=opt><arg>--user</arg><arg>--global</arg>
643                     </group>
644                 </cmdsynopsis></entry>
645                     <Entry><para>Register the package using the specified installed package description.
646                   The syntax for the latter is given in <xref linkend="ipd">.</para></entry></row>
647
648
649      <row><Entry><cmdsynopsis><command>hc-pkg unregister</command> 
650                 <arg><replaceable>pkg-id</replaceable></arg>
651                   </cmdsynopsis></entry>
652                     <Entry><para>Unregister the specified package.</para></entry></row>
653
654      <row><Entry><cmdsynopsis><command>hc-pkg expose</command> 
655                 <arg><replaceable>pkg-id</replaceable></arg>
656                   </cmdsynopsis></entry>
657                     <Entry><para>Expose the specified package.</para></entry></row>
658
659      <row><Entry><cmdsynopsis><command>hc-pkg hide</command> 
660                 <arg><replaceable>pkg-id</replaceable></arg>
661                   </cmdsynopsis></entry>
662                     <Entry><para>Hide the specified package.</para></entry></row>
663
664      <row><Entry><command>hc-pkg list</command></entry>
665                     <Entry><para>List all registered packages, both global and user, hidden and exposed. </para></entry></row>
666
667
668      <row><Entry><cmdsynopsis><command>hc-pkg describe</command> <arg choice=req><replaceable>pkg-id</replaceable> </arg>
669                   </cmdsynopsis></entry>
670          <Entry><para>Give the registered description for the specified package.
671                     The description is returned in precisely the syntax required by 
672                     <command>hc-pkg register</command>.  
673                 </para></entry></row>
674
675      <row><Entry><cmdsynopsis><command>hc-pkg field</command> <arg choice=req><replaceable>pkg-id</replaceable> </arg>
676                 <arg choice=req><replaceable>field</replaceable> </arg>
677                   </cmdsynopsis></entry>
678
679          <Entry><para>Extract the specified field of the package description for the specified package.
680                 </para></entry></row>
681
682      </tbody></tgroup>
683      </table>
684      A <replaceable>pkg</replaceable> argument can be a package ID, such as "<literal>hunit-2.3</literal>", or just a package name, 
685 such as "<literal>hunit</literal>".  To determine which package is meant, &hc-pkg; searches first the
686 registered user packages and then the global packages.  If no such package exists, the command fails; that is, it does nothing, 
687 returning a non-zero error code.
688 If only a name is specified, &hc-pkg; fails
689 unless the name identifies a unique package among the user packages, or among the global packages.  As usual, the
690 user packages win.
691       </para>
692 <note><para>Can we give the <option>--user</option> flag to <command>hide</command>, <command>expose</command>,
693 <command>describe</command>?  Can we register a package that is already registered?  What if it's registered
694 as a global package and we register it as a user package?</para>
695       </note>
696 </sect2>
697
698 <sect2 id=ipd><title>Syntax of installed package description</title>
699
700 <note><para>...include the list of ``externally visible modules''.</para></note>
701 </sect2>
702 </sect1> <!-- End of compiler requirements --> 
703
704
705 <!-- Setup script -->
706
707 <sect1 id=setup><title>The setup script</title>
708
709 <para>
710 The sole requirement of an &hps; package is that it should contain,
711 in the root of its file structure, (a) a package description file &pkg-desc;,
712 and (b) a setup script, <filename>Setup.lhs</filename>.
713 This section
714 specifies the syntax of the package description, and the command-line interface for the setup script.
715 </para>
716
717 <sect2 id=pkg-desc><title>The package description</title>
718
719 <para>Here is a sample package description file:
720 <programlisting>-- Required
721 Name: Cabal
722 Version: 0.1.1.1.1-rain
723 License: LGPL
724 Copyright: Free Text String
725 -- Optional - may be in source?
726 Stability: Free Text String
727 Build-Depends: haskell-src, HUnit>=1.0.0-rain
728 Modules: Distribution.Package, Distribution.Version,
729          Distribution.Simple.GHCPackageConfig
730 ...</programlisting>
731
732 The Name, Version, License, and Copyright are compulsory.</para>
733
734 <para>The rest of the lines are optional.  Any fields the system
735 doesn't understand will be ignored (to allow addition of fields at a
736 later date, or to allow Setup script authors to provide their own
737 fields). Each field must begin with "Field-Name:".</para>
738
739 <para>Lines beginning with "--" will be considered comments and
740 ignored.</para>
741
742 <para>Each field must begin with "Field-Name:".  In order to allow for
743 long fields, any line that begins with whitespace will be considered
744 part of the previous field.  </para>
745
746 <para>As given, there should be no reason to have completely empty
747 lines (except perhaps for the last line in the file).  In the future,
748 if there is need to add more records, they will be separated by at
749 least one completely empty line.</para>
750
751 <para>For the &hps;-provided simple build infrastructure, the package
752 description fields and syntax are given in <xref
753 linkend="sbi-pkg-desc">.</para>
754
755 </sect2>
756
757 <sect2 id=setup-spec><title>The setup script specification</title>
758
759 <para>Here is the command-line interface the setup script must satisfy.
760      <table frame=all><title>setup.lhs interface</title>
761
762      <tgroup cols=2 align=left colsep=1 rowsep=1>     <tbody>
763
764      <row><Entry><command>./Setup.lhs configure [flags] </command></entry>
765          <Entry><para> Prepare to build the package.  Typically, this step checks
766                 that the target platform is capable of building the package, and
767                 discovers platform-specific features that are needed during the build. 
768                 </para></entry></row>
769
770
771      <row><Entry><command>./Setup.lhs build</command></entry>
772                     <Entry><para>Make this package ready for installation.  For a true compiler,
773                   this step involves compiling the Haskell source code.  Even for an interpreter, however, 
774                   it may involve running a pre-processor.</para></entry></row>
775
776
777      <row><Entry><command>./Setup.lhs install [install-prefix]</command></entry>
778                     <Entry><para>Copy the files into the install locations, and register
779                   the package with the compiler.</para></entry></row>
780
781      <row><Entry><cmdsynopsis>
782                   <command>./Setup.lhs register</command><sbr>
783                   <command>./Setup.lhs unregister</command>
784               </cmdsynopsis>
785               </entry>
786                     <Entry><para>Register (or un-register) this package with the
787                     compiler.  (NB: registration is also done automatically by <literal>install</literal>.)
788                 </para></entry></row>
789
790      <row><Entry><command>./Setup.lhs clean</command></entry>
791                     <Entry><para>Clean out the files created during the configure, build, or register steps.</para></entry></row>
792      <row><Entry><command>./Setup.lhs test</command></entry>
793                     <Entry><para>Run the package's test suite.</para></entry></row>
794
795      </tbody></tgroup>
796      </table>
797     </para>
798
799       <para>For wrapped make-based systems (for instance), a
800       command-line parser that understands the standard
801       <literal>Setup.lhs</literal> command-line syntax will be
802       provided as a library.</para>
803
804       <sect3>
805         <title><option>configure</option></title>
806
807         <para>The command <literal>./Setup.lhs configure</literal>
808         prepares to build the package.  For sophisticated packages,
809         the configure step may perform elaborate checks, to gather
810         information about the target system.  It may write a file to
811         record its results, but the name and format of this file are
812         not part of the specification.</para>
813
814 <para>All flags are optional.  The flags are these:</para>
815 <itemizedlist>
816 <listitem><para><option>--with-compiler=</option><replaceable>path</replaceable>, 
817 <option>--ghc</option>, 
818 <option>--nhc</option>, 
819 <option>--hugs</option>: 
820 specifies which compiler to use.  At most one of the value of these flags may be specified.
821 The configure step checks
822 that the compiler is available, in a sufficiently up-to-date form for the package, and that the package
823 expects to work with that compiler.  If the compiler name
824 is not specified, <literal>Setup.lhs</literal> will choose one; some packages will come with one compiler baked in.
825 </para>
826           </listitem>
827 <listitem><para><option>--prefix=</option><replaceable>path</replaceable>: specifies where the installed files
828 for the package should be installed (ie the location of the files themselves).  Typically on Unix this will be <filename>/usr/local</filename> and
829 on Windows it will be <filename>Program Files</filename>.  The setup script will use a sensible default
830 (often platform-specific) if the flag is not specified.
831             </para>
832           </listitem>
833
834 <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>
835
836         </itemizedlist>
837
838         <para>It is OK for these flags to be "baked into" the compiled
839         &tool;.  In particular, the build system may bake the
840         installation path into the compiled files.  There is no
841         provision for changing these baked-into values after
842         configuration.</para> </sect3>
843
844       <sect3><title><option>build</option></title>
845         
846         <para>The command <literal>./Setup.lhs build</literal> makes
847         this package ready for installation.  It takes no
848         flags.</para>
849
850       </sect3>
851
852       <sect3><title><option>install</option></title>
853
854         <para>The command <literal>./Setup.lhs install</literal>
855         copies files from the built package to the right location for
856         installed files, specified in the configure step.  Then it
857         registers the new package with the compiler, using the
858         &hc-pkg; command.</para>
859
860         <itemizedlist>
861           <listitem>
862
863             <para><option>--install-prefix=</option><replaceable>path</replaceable>:
864             specifies where the installed files for the package should
865             be installed (ie the location of the files themselves).
866             It has three effects.  First, it over-rides the
867             <option>--prefix</option> flag specified in the
868             <option>configure</option> step, providing an alternative
869             location.  Second, it does not call &hc-pkg; to register
870             the package.  Instead, third, it creates an installed
871             package description file,
872             <filename>installed-pkg-descr</filename>, which can later
873             be fed to &hc-pkg;.  </para> </listitem>
874
875           <listitem>
876             <para><option>--user</option>: if present, this flag is
877             passed to &hc-pkg; so that the package is registed for the
878             current user only.  This flag has no effect if
879             <option>--install-prefix</option> is used, because in
880             that case &hc-pkg; is not called.</para>
881           </listitem>
882
883           <listitem>
884             <para><option>--global</option>: if present, this flag is
885             passed to &hc-pkg; so that the package is registed
886             globally (this is the default if neither
887             <option>--user</option> or <option>--global</option> are
888             given). This flag has no effect if
889             <option>--install-prefix</option> is used, because in
890             that case &hc-pkg; is not called.</para>
891           </listitem>
892         </itemizedlist>
893
894         <para>The reason for the <option>--install-prefix</option>
895         flag is that Roland RPM wants to create an exact installation
896         tree, all ready to bundle up for the target machine,
897         <emphasis>but in a temporary location</emphasis>. He cannot
898         use this location for <option>--prefix</option> in the
899         <option>configure</option> step, because that might bake
900         the wrong path into some compiled files.  Nor does he want to
901         register this temporary tree with the compiler on his
902         machine. Instead, he bundles up the temporary installation
903         tree, plus the <filename>installed-pkg-descr</filename>, and
904         ships them all to the target machine.  When they are installed
905         there, the post-installation script runs
906         &hc-pkg; on the
907         <filename>installed-pkg-descr</filename> file.
908             </para>
909
910         <para>Note that there is no <command>uninstall</command>
911         command in the setup script.  While it would be easy enough to
912         implement in the simple build infrastructure, we don't want to
913         require make-based build systems to implement <literal>make
914         uninstall</literal>, which is fairly non-standard and
915         difficult to get right.  In the majority of cases, we expect
916         libraries to be installed via a package manager (eg. RPM,
917         Debian APT), which already provide uninstallation
918         services.</para>
919       </sect3>
920
921       <sect3>
922         <title><option>register</option> and
923         <option>unregister</option></title>
924
925         <para>The command <literal>./Setup.lhs register</literal>
926         registers the now-installed package with the compiler.
927         Similarly, <literal>./Setup.lhs unregister</literal>
928         un-registers the package.</para>
929
930         <itemizedlist>
931           <listitem>
932             <para><option>--global</option>: registers/un-registers a
933             package as global.  This is the default.</para>
934           </listitem>
935           <listitem>
936             <para><option>--user</option>: registers/un-registers a
937             package for the current user only.</para>
938           </listitem>
939         </itemizedlist>
940       </sect3>
941     </sect2>
942
943 <sect2><title>Examples</title>
944 <sect3><title>Bob the Builder and Sam Sysadmin</title>
945
946 <para>Bob the Builder can install a &hps; source distribution thus.
947 He downloads the source distribution and unpacks it into a temporary directory,
948 <literal>cd</literal>'s to that directory, and says
949 <programlisting>
950   ./Setup.lhs configure --ghc
951   ./Setup.lhs build
952   ./Setup.lhs install --user
953 </programlisting>
954 Similarly, Sam Sysadmin does exactly the same, except that he says 
955 <programlisting>
956   ./Setup.lhs install --global
957 </programlisting>
958 in the final step, so that the package is installed where all users will see it.
959       </para>
960 <para>For a binary distribution, both Bob and Sam would omit the first two steps, and just do the install step.</para>
961 </sect3>
962
963 <sect3><title>System packagers (Debian, RPM etc)</title>
964
965         <para>System packagers, such as Peter Packager or Donald
966         Debian, will run the configure and build steps just like Bob
967         and Sam.  A that point, Donald will say <programlisting>
968         ./Setup.lhs install --install-prefix=/tmp/donald
969         </programlisting> to construct a ready-to-zip tree of all the
970         installed files, plus a file
971         <filename>installed-pkg-descr</filename> that describes the
972         installed package.  He arranges to deliver both these
973         components to the target machine, and then feed
974         <filename>installed-pkg-descr</filename> to &hc-pkg; on the
975         target machine.  </para>
976
977         <para>The file <filename>installed-pkg-descr</filename> also
978         contains information he needs for building his Debian
979         distribution, namely the package name, version, and (exact)
980         dependencies.</para>
981
982         <para>We expect there to be additional tools to help System
983         Packagers to prepare the materials necessary to build their
984         packages from a source distribution.  For example, an RPM tool
985         could take a Haskell package source distribution and build an
986         initial <literal>.spec</literal> file with as many of the
987         fields as possible filled in automatically.  In most cases
988         some intervention by the System Packager will be necessary;
989         for example platform-specific dependencies may need to be
990         specified.</para>
991
992
993         <para>After Peter has constructed the package, Isabella can
994         install it in a manner she is comfortable with.</para>
995
996
997       </sect3>
998    </sect2>
999 </sect1>
1000
1001 <sect1 id=sbi><title>The &hps; simple build infrastructure</title>
1002
1003 <para>A package author must fulfil the specification of <xref linkend=setup>.
1004 In many cases, a Haskell package will consist of nothing more than a bunch of Haskell modules,
1005 with perhaps the odd C file.  In that case, the &hps; provides a <emphasis>simple build infrastructure</emphasis> that
1006 fulfils the specification of <xref linkend=setup>, and provides some modest further facilities besides.</para>
1007 <para>This simple build infrastructure is meant to automate the common case.
1008 (Think <command>hmake</command>.)  The emphasis is on ``simple'': 
1009 if you want something more elaborate, you can (a) modify the simple build infrastructure (which is written in Haskell)
1010 (b) use makefiles, or (c) implement something else entirely.
1011 </para>
1012
1013 <sect2><title>Overview</title>
1014 <para>
1015 The simple build infrastructure works as follows.  First, Angela puts the following Haskell 
1016 file <filename>Setup.lhs</filename> in the
1017 root of her tree:
1018 <programlisting>
1019   #! /usr/bin/env runghc
1020
1021   > import Distribution.Simple
1022 </programlisting>
1023 Second, she writes a package description &pkg-desc; in the syntax of <xref linkend="sbi-pkg-desc">,
1024 which describes the package and gives extra information to the simple build infrastructure.
1025 </para><para>
1026 Now Angela can build her package by saying
1027 <programlisting>
1028   ./Setup.lhs configure
1029   ./Setup.lhs build
1030 </programlisting>
1031 She can even install it on her own machine by saying
1032 <programlisting>
1033   ./Setup.lhs install
1034 </programlisting>
1035 She can build a &hps; source distribution:
1036 <programlisting>
1037   ./Setup.lhs source-dist
1038 </programlisting>
1039 The full details are given in <xref linkend="sbi-setup">.  
1040 </para><para>
1041 It is no coincidence that the interface is very similar to that for the setup script
1042 for an &hps; package distribution (<xref linkend="setup">).
1043 In fact, <literal>Distribution.Simple.defaultMain</literal> conforms to the specification of <xref linkend="setup-spec">, and when it builds
1044 a distribution, it includes <filename>./Setup.lhs</filename> in the tarball, ready to be run by Bob the Builder.
1045 However, <literal>Distribution.Simple.defaultMain</literal> of course implements a richer interface than that required by
1046 <xref linkend="setup-spec">, because it's intended to support Angela as well as Bob.
1047 The full specification is in <xref linkend="sbi-setup">.
1048 </para>
1049     </sect2>
1050 <sect2 id=sbi-pkg-desc><title>Package description in the simple build infrastructure</title>
1051
1052 <para>When using the simple build infrastructure, the package
1053 description file &pkg-desc; contains not only the name of the package,
1054 its version and dependencies, but also a collection of information to
1055 explain to the simple build infrastructure how to build the package.
1056 This section gives the specific fields, and the syntax of those
1057 fields.  For the general syntax of the file, please see <xref
1058 linkend="pkg-desc">.</para>
1059
1060 <para>Here is a sample package description file with all the fields understood by the simple build infrastructure:
1061 <programlisting>
1062         -- Required
1063         Name: Cabal
1064         Version: 0.1.1.1.1-rain
1065         License: LGPL
1066         Copyright: Free Text String
1067         -- Optional - may be in source?
1068         Stability: Free Text String
1069         Build-Depends: haskell-src, HUnit>=1.0.0-rain
1070         Modules: Distribution.Package, Distribution.Version,
1071                  Distribution.Simple.GHCPackageConfig
1072         C-Sources: not/even/rain.c, such/small/hands
1073         HS-Source-Dir: src
1074         Exposed-Modules: Distribution.Void, Foo.Bar
1075         Extensions: OverlappingInstances, TypeSynonymInstances
1076         Extra-Libs: libfoo, bar, bang
1077         Include-Dirs: your/slightest, look/will
1078         Includes: /easily/unclose, /me, "funky, path\\name"
1079         Options-ghc: -fTH -fglasgow-exts
1080         Options-hugs: +TH
1081
1082         -- Next is an executable
1083         Executable: somescript
1084         Main-is: SomeFile.hs
1085         Modules: Foo1, Util, Main
1086         HS-Source-Dir: scripts
1087         Extensions: OverlappingInstances</programlisting>
1088 The Name, Version, License, and Copyright are compulsory.</para>
1089
1090 <para>All other fields, such as dependency-related fields, will be
1091 considered empty if they are absent.  Any fields that the system does
1092 not understand will be ignored.</para>
1093
1094 <para>Note that in the future, though the Modules field will be
1095 available, it will not be necessary to provide it for building
1096 executables and libraries.  Instead, the user will provide only the
1097 "Main-Is" field (for executables) and the "Exposed-Modules" field (for
1098 libraries).  The system will chase down dependencies from those
1099 modules and include them in the library or source
1100 distributions.</para>
1101
1102 <para>The description file fields:
1103    <table frame=all><title>Description File Fields</title>
1104    <tgroup cols=4 align=left colsep=1 rowsep=1> <tbody>
1105       <row><entry>Field Name</entry>
1106            <entry>Description</entry>
1107            <entry>Example</entry>
1108            <entry>Notes</entry>
1109       </row>
1110
1111       <row><entry>name</entry>
1112            <entry>[a-zA-Z][-a-zA-Z0-9]*</entry>
1113            <entry>haskell-cabal12345</entry></row>
1114       <row><entry>version</entry>
1115            <entry>[0-9.]+(-?)[-a-zA-Z]*: branch numbers, separated by dots, and optional tags separated by dashes.</entry>
1116            <entry>1.2.3.4.5-foo-bar-bang</entry>
1117       </row>
1118       <row><entry>copyright</entry>
1119            <entry>--FREE TEXT--</entry>
1120            <entry>(c) 2004 Isaac Jones</entry>
1121       </row>
1122
1123       <row><entry>license</entry>
1124            <entry>GPL | LGPL | BSD3 | BSD4 | PublicDomain | AllRightsReserved</entry>
1125            <entry>BSD3</entry>
1126            <entry>If your license isn't on this list, use the
1127            <emphasis>license-file</emphasis> field.</entry>
1128
1129       </row>
1130
1131       <row><entry>license-file</entry>
1132            <entry>--PATH--</entry>
1133            <entry>doc/myLicense.txt</entry>
1134            <entry>Specify the license you use as a relative path from the root of the source tree.</entry>
1135       </row>
1136
1137       <row><entry>maintainer</entry>
1138            <entry>--FREE TEXT--</entry>
1139            <entry>T.S. Elliot &lt;elliot@email.com> </entry>
1140       </row>
1141
1142       <row><entry>stability</entry>
1143            <entry>--FREE TEXT--</entry>
1144            <entry>Don't hook this up to your coffee machine</entry>
1145       </row>
1146
1147       <row><entry>executable</entry>
1148            <entry>--FREE TEXT--</entry>
1149            <entry>cpphs</entry>
1150            <entry>For this Executable stanza, what is the name of the produced executable.</entry>
1151       </row>
1152
1153       <row><entry>main-is</entry>
1154            <entry>--PATH--</entry>
1155            <entry>/foo/bar/bang/Baz.hs</entry>
1156            <entry>The filename to look for the main module for this Executable stanza.</entry>
1157       </row>
1158
1159       <row><entry>extra-libs</entry>
1160            <entry>comma list of --FREE TEXT-- and spaces</entry>
1161            <entry>libfoo, libbar  ,   libbang</entry>
1162            <entry>for non-haskell libraries that this package needs to link to</entry>
1163       </row>
1164
1165       <row><entry>build-depends</entry>
1166            <entry>package name (== | < | > | <= | >=) version</entry>
1167            <entry>foo > 1.2, bar < 3.3.5, bang</entry>
1168            <entry>If the version isn't listed, it's assumed any version is OK.</entry>
1169       </row>
1170
1171       <row><entry>c-sources</entry>
1172            <entry>--PATH--</entry>
1173            <entry>/foo/bar/bang</entry>
1174            <entry>C source files to build using the FFI.</entry>
1175       </row>
1176
1177       <row><entry>include-dirs</entry>
1178            <entry>--PATH--</entry>
1179            <entry>"/foo/bar/  ,bang"</entry>
1180            <entry>Not Yet Used</entry>
1181       </row>
1182
1183       <row><entry>includes</entry>
1184            <entry>--PATH--</entry>
1185            <entry>/foo/bar/bang</entry>
1186            <entry>Not Yet Used</entry>
1187       </row>
1188
1189       <row><entry>hs-source-dir</entry>
1190            <entry>--PATH--</entry>
1191            <entry>src</entry>
1192            <entry>A relative path from the root of your source tree.  Look here for the Haskell modules.</entry>
1193       </row>
1194
1195       <row><entry>modules</entry>
1196            <entry>--MODULE LIST--</entry>
1197            <entry>Foo.Bar, Bang.Baz, Boo</entry>
1198            <entry>May not be necessary in the future, since we'll
1199            chase dependencies from exposed modules and main
1200            module.</entry>
1201       </row>
1202
1203       <row><entry>exposed-modules</entry>
1204            <entry>--MODULE LIST--</entry>
1205            <entry>Foo.Bar, Bang.Baz, Boo</entry>
1206            <entry>For a library package, which modules should be
1207            available for import by the end user?</entry>
1208       </row>
1209
1210       <row><entry>extensions</entry>
1211            <entry>OverlappingInstances
1212                | RecursiveDo
1213                | ParallelListComp
1214                | MultiParamTypeClasses
1215                | NoMonomorphismRestriction
1216                | FunctionalDependencies
1217                | RankNTypes
1218                | PolymorphicComponents
1219                | ExistentialQuantification
1220                | ScopedTypeVariables
1221                | ImplicitParams
1222                | FlexibleContexts
1223                | FlexibleInstances
1224                | EmptyDataDecls
1225
1226                | TypeSynonymInstances
1227                | TemplateHaskell
1228                | ForeignFunctionInterface
1229                | AllowOverlappingInstances
1230                | AllowUndecidableInstances
1231                | AllowIncoherentInstances
1232                | InlinePhase
1233                | ContextStack
1234                | Arrows
1235                | Generics
1236                | NoImplicitPrelude
1237                | NamedFieldPuns
1238
1239                | ExtensibleRecords
1240                | RestrictedTypeSynonyms
1241                | HereDocuments
1242                | UnsafeOverlappingInstances</entry>
1243            <entry>ForeignFunctionInterface, Arrows</entry>
1244            <entry>Not all extensions are understood by all &impls;</entry>
1245       </row>
1246
1247       <row><entry>options-ghc</entry>
1248            <entry>--OPTIONS--</entry>
1249            <entry>-fth -cpp</entry>
1250            <entry>For command-line options not covered under
1251            <emphasis>extensions</emphasis>, add them here, separated
1252            by whitespace.</entry>
1253
1254       </row>
1255
1256       <row><entry>options-nhc</entry>
1257            <entry>--OPTIONS--</entry>
1258            <entry>-P -t</entry>
1259            <entry>For command-line options not covered under
1260            <emphasis>extensions</emphasis>, add them here, separated
1261            by whitespace.</entry>
1262       </row>
1263
1264       <row><entry>options-hugs</entry>
1265            <entry>--OPTIONS--</entry>
1266            <entry>-98 +g</entry>
1267            <entry>For command-line options not covered under
1268            <emphasis>extensions</emphasis>, add them here, separated
1269            by whitespace.</entry>
1270       </row>
1271
1272    </tbody></tgroup></table></para>
1273
1274 <para>Further details on some fields:
1275   <itemizedlist>
1276
1277    <listitem><para><emphasis>--PATH--</emphasis> Paths are written in
1278    the Unix style, with directories separated by slashes, optionally
1279    ending in a filename.  There are two kinds of paths supported:
1280    "Simple" and "Complex".  "Simple" paths are alpha-numeric values
1281    separated by slashes (foo/bar/bang).  More "Complex" paths such as
1282    those with spaces or non-alphanumeric characters must be put in
1283    quotes ("foo, /bar \//bang").  You should assume that the paths are
1284    case sensitive, though in practice this varies depending on the end
1285    user's file system.  </para></listitem>
1286
1287    <listitem><para><emphasis>--MODULE LIST--</emphasis> A module list
1288    is a standard Haskell module name, without any file suffixes (.lhs
1289    or .hs).  Each module should be separated by a
1290    comma.</para></listitem>
1291
1292    <listitem><para><emphasis>--FREE TEXT--</emphasis> You may put
1293    anything in these fields.  For multi-line fields, start the
1294    subsequent lines with whitespace.</para></listitem>
1295
1296    <listitem><para><emphasis>--OPTIONS--</emphasis>The exact syntax of
1297    the options field is dependent on the compiler you're using.  Refer
1298    to your compiler's man page for details.  Multiple options should
1299    be separated by whitespace.</para></listitem> </itemizedlist>
1300
1301 </para>
1302
1303 <para>On hidden modules: Hidden modules form part of the
1304 implementation of the package, but not its interface: a client of the
1305 package cannot import an internal module.  The system still must
1306 derive their existence, or they must be listed explicity for two
1307 reasons: (a) to allow the global program invariant to be checked (see
1308 <xref linkend="packages-and-haskell">) and (b) to enable a build
1309 system or programming environment to find the source files.  </para>
1310 </sect2>
1311
1312 <sect2 id="sbi-setup"><title><literal>Distribution.Simple</literal></title>
1313
1314 <para>This section gives the command line interface supported by
1315 <literal>Distribution.Simple.defaultMain</literal>.  It supports all the
1316 commands described in <xref linkend=setup-spec>, (except for "test" -
1317 FIX) and in addition the following: <table frame=all><title>Extra
1318 commands supported by the simple build infrastructure setup
1319 script</title>
1320
1321      <tgroup cols=2 align=left colsep=1 rowsep=1>     <tbody>
1322
1323      <row><Entry><command>./Setup.lhs sdist </command></entry>
1324          <Entry><para> Create a source tarball</para></entry></row>
1325      <row><Entry><command>... </command></entry>
1326          <Entry><para>...</para></entry></row>
1327
1328      </tbody></tgroup>
1329      </table>
1330     </para>
1331
1332 <para>Distribution.Simple.defaultMain provides interactive command-line
1333 help.  For each command, a help string is available by typing
1334 "./Setup.lhs COMMAND --help".</para>
1335
1336 </sect2>
1337
1338 <sect2><title>The Makefile route</title>
1339
1340 <para>The Haskell libraries that support the simple build infrastructure can, of course, also
1341 be re-used to make setup scripts that work quite differently.  At one extreme is a setup
1342 script that immediately shells out into <literal>make</literal>, which does all the work.</para>
1343
1344 <para>To support this, &hps; provides a trivial setup library <literal>Distribution.Make</literal>, which
1345 simply parses the command line arguments and shells out into <literal>make</literal>.  Marcus uses the following
1346 <filename>Setup.lhs</filename>
1347 <programlisting>
1348   #! /usr/bin/env runhugs
1349
1350   > module Main where
1351   > import Distribution.Make (defaultMain)
1352   > main = defaultMain
1353 </programlisting>
1354 All the package description information is assumed to be known to the makefile system, and so does not
1355 appear in the setup script.
1356 Thus, 
1357 <programlisting>
1358   ./Setup.lhs configure --ghc
1359 </programlisting>
1360 invokes
1361 <programlisting>
1362   ./configure --with-compiler=ghc
1363 </programlisting>
1364 Similarly
1365 <literal>./Setup.lhs build</literal>
1366 invokes
1367 <literal>make all</literal> And so on.</para>
1368
1369 <para>Marcus simply arranges that when his makefiles build a distribution, they include this simple setup script in
1370 the root of the distribution, where the Bob the Builder expects to find it.</para>
1371
1372 <note><para> Isaac isn't sure that we can provide much value here
1373 beside providing a standard command-line parser (which is pretty good
1374 at least).  I think it might be good to offer a boilerplate Setup.lhs
1375 file for makefiles, but implementing it in a library is a bit
1376 overkill.  Perhaps in the future, if the build system is delivered w/
1377 fptools or something, we could provide an API to wrap
1378 that. </para> <para>Simon says: fine -- but we should make it easy for Marcus Makefile.  What do we offer?</para></note>
1379
1380
1381 </sect2>
1382
1383 </sect1>
1384
1385
1386
1387 <!-- Appendix: Layered Tools --------------------------------- -->
1388 <appendix><title>Layered Tools</title>
1389
1390 <para>One great advantage to having a standard configure/build/install
1391 interface for all Haskell packages is that end users don't need to
1392 learn a new method for each package they install.</para>
1393
1394 <para>Likewise, with such an interface, we can build layered tools in
1395 a typical Unix fashion.  For instance, we might want a tool that
1396 downloads and installs Haskell packages.  It can be implemented as a
1397 simple shell script, <application>haskell-install</application> (where
1398 "$@" represents the command-line argument):
1399
1400 <programlisting>#!/bin/sh
1401
1402 echo "wget http://packages.haskell.org/$@"
1403 echo "tar -zxvf $@.tgz"
1404 echo "cd $@"
1405 echo "./Setup.lhs configure"
1406 echo "./Setup.lhs build"
1407 echo "./Setup.lhs install"</programlisting></para>
1408
1409 <para>Now the end-user (Isabella) only needs to say "haskell-install
1410 myPackage", rather than performing all of the Setup steps by
1411 hand.</para>
1412
1413 </appendix>
1414
1415
1416 <!-- Appendix: Related Systems --------------------------------- -->
1417 <appendix><title>Related Systems</title>
1418
1419 <para>I will try to outline interesting points in a variety of systems
1420 that we can learn from.  These systems may be intended for building or
1421 installing packages, or repositories for packages.  I am not deeply
1422 familiar with all of the tools here, and would be interested in
1423 hearing more relevant points from someone with more knowledge.
1424 Another weakness of mine is that I don't know much about Microsoft
1425 Windows, so some good examples for Windows systems would be
1426 helpful.</para>
1427
1428 <section id="lip-appendix-debian"><Title>Debian</title>
1429
1430 <para>
1431 The <ulink url="http://www.debian.org">Debian GNU/Linux system</ulink>
1432 is a good example of a <emphasis>binary</emphasis> distribution
1433 (meaning that packages are distributed in binary, as opposed to source
1434 code form), and its packaging system (<application>dpkg</application>)
1435 is somewhat similar to the more famous <application>RPM</application>.
1436 Debian has several other tools to help the user to install packages,
1437 most notably, <command>apt</command>.  The Debian toolset is
1438 interesting for several reasons:
1439
1440 <itemizedList>
1441
1442   <listItem><para>It handles dependencies extremely well.  A single
1443   command can download and install a package, as well as downloading
1444   and installing all of its dependencies.</para></listItem>
1445
1446   <listItem><para>It handles updates extremely well.  One command
1447   (<command>apt-get update</command>) checks for new versions of
1448   packages and updates a local database.  Another command
1449   (<command>apt-get dist-upgrade</command>) downloads and installs all
1450   new versions of installed packages and any new
1451   dependencies.</para></listItem>
1452
1453
1454   <listItem><para>There are standard commands for downloading and
1455   building packages from source.  If I'm interested in hacking on a
1456   package, I can run <command>apt-get source packagename</command>
1457   which will download and unpack the source code for the package.  The
1458   source can then be built with the standard command
1459   <command>debuild</command>.</para></listItem>
1460
1461
1462   <listItem><para>The Debian Project maintains a central repository
1463   for packages, and the packaging tools offer support for using
1464   unofficial repositories as well.  The central repositories include a
1465   set of servers, the <emphasis>autobuilders</emphasis>, which compile
1466   uploaded source packages for a variety of hardware architectures
1467   (see below) and make them available as binary packages.  As a
1468   packager, I merely upload the source code to my package, and the
1469   autobuilders do the rest.</para></listItem>
1470
1471   <listitem><para>Currently the hardware architectures supported by
1472   Debian are Intel x86, Motorola 68k, Sun SPARC, Alpha, PowerPC, ARM,
1473   MIPS, HP PA-RISC, IA-64, S/390.  Debian also runs on non-Linux
1474   systems, including GNU/Hurd, GNU/NetBSD, and GNU/FreeBSD.  The
1475   package management tools also run on MacOS X under the name of the
1476   <application>Fink</application> project.</para></listItem>
1477
1478 </itemizedList>
1479 </para>
1480
1481 </section>
1482
1483 <section id="lip-appendix-distutils"><title>Python Distutils</title>
1484
1485 <para>Python's <ulink
1486 url="http://www.python.org/sigs/distutils-sig/">&distutils;
1487 system</ulink> is in many ways similar to what we propose here.  It is
1488 a system for building and installing Python modules, written purely in
1489 Python.  The user interface is a Python script,
1490 (<filename>setup.py</filename> by convention) and a setup
1491 configuration file (<filename>setup.cfg</filename> by convention). To
1492 quote from <ulink
1493 url="http://www.python.org/doc/current/dist/dist.html">Distributing
1494 Python Modules</ulink>, "The setup configuration file is a useful
1495 middle-ground between the setup script--which, ideally, would be
1496 opaque to installers -- and the command-line to the setup script,
1497 which is outside of your control and entirely up to the
1498 installer. "</para>
1499
1500 <para>Its noteworthy that Python has a big advantage over many
1501 programming languages when implementing a system like &distutils;: It
1502 is designed to be well suited to so-called scripting tasks, which are
1503 common to the installation task, and Python has done these tasks in a
1504 portable way for a long time.  I believe that Haskell should evolve
1505 portable ways to perform common scripting tasks.</para>
1506
1507 </section>
1508
1509 <section id="lip-appendix-cpan-boost"><title>&cpan; and Boost</title>
1510
1511 <para> Quoting from &cpan;'s <ulink url="http://www.cpan.org"> web
1512 site </ulink> "&cpan; is the Comprehensive Perl Archive Network, a
1513 large collection of Perl software and documentation."  That really
1514 says it all.  It is a central location where Perl developers can
1515 contribute the software they write.</para>
1516
1517 <para>&cpan; has a means of standardizing installation,
1518 <filename>Makefile.pl</filename> (which is a Perl script which creates
1519 a Makefile with targets like "install", "test", "config", "clean", etc.). Makefile.pl typically uses the <ulink
1520 url="http://www.perldoc.com/perl5.6/lib/ExtUtils/MakeMaker.html">MakeMover
1521 module</ulink>. It also has a means of registering a namespace for the
1522 module that a developer is contributing.</para>
1523
1524 <para>From the Boost <ulink url="http://www.boost.org">web
1525 site</ulink> "[Boost] provides free peer-reviewed portable C++ source
1526 libraries. The emphasis is on libraries which work well with the C++
1527 Standard Library. One goal is to establish "existing practice" and
1528 provide reference implementations so that the Boost libraries are
1529 suitable for eventual standardization. Some of the libraries have
1530 already been proposed for inclusion in the C++ Standards Committee's
1531 upcoming C++ Standard Library Technical Report."</para>
1532
1533 <para>From what I can tell, unlike &cpan;, Boost is a bit more focused
1534 on standards and review.  That is, it is perhaps more Cathedral than
1535 Bazaar <footnote><para>See Eric Raymond's essay <ulink
1536 url="http://catb.org/~esr/writings/cathedral-bazaar/cathedral-bazaar/">The
1537 Cathedral and the Bazaar</ulink>.</para></footnote>. Boost does not
1538 currently have a standard means of installation.</para>
1539 </section>
1540
1541 <section id="lip-appendix-freebsd"><title>FreeBSD's Ports System</title>
1542
1543 <para>The FreeBSD <ulink url="http://www.freebsd.org/ports/">Ports
1544 Collection</ulink> is a collection of software with a standard means
1545 of compilation and installation.  FreeBSD is a source distribution
1546 (whereas Debian is a Binary Distribution).  Packages come in
1547 source-code form with a Makefile suitable for installing the program
1548 on a FreeBSD system.  The ports collection is very large (around 9000
1549 packages).</para>
1550
1551 <para>Some things may be simpler with a source distribution than with
1552 a binary distribution.  For instance, since the code is expected to be
1553 already on the machine and buildable, when a new compiler is installed
1554 one merely needs to rebuild the dependant libraries.  In contrast,
1555 with a binary distribution like Debian one must wait for a new binary
1556 package to be made available.  However, as I understand it, FreeBSD
1557 has no means of recompiling dependant packages automatically when a
1558 new compiler is installed.</para>
1559
1560 </section>
1561
1562 <!-- FIX: I'm not sure why I thought this was so interesting.  I don't -->
1563 <!-- reference it anywhere and it really doesn't add anything that the perl -->
1564 <!-- and python systems don't have. -->
1565
1566 <section id="lip-appendix-xemacs"><title>The &xemacs; Packaging
1567 System</title>
1568
1569 <para>
1570 As most folks know, &xemacs; is not only a text editor, but also a
1571 Lisp environment.  Its functionality can be extended with lisp
1572 programs, and many such programs are available from &xemacs;' <ulink
1573 url="http://www.xemacs.org/Documentation/21.5/html/lispref_4.html">Packaging
1574 System</ulink>.  Simply put, the packaging system offers a menu-driven
1575 interface within &xemacs; where the user can browse available
1576 packages, select packages she is interested in, and ask &xemacs; to
1577 download and install them.  This system is interesting because it is
1578 cross-platform (Unix, Linux, Windows, etc.) and is designed to work
1579 only with elisp.
1580 </para>
1581
1582
1583
1584  </section>
1585
1586 <section id="lip-appendix-make-based"><title>Make-Based Systems</title>
1587
1588 <para>The "fptools" build system has been used for many years in the
1589 cross-platform &ghc; compiler.  It is a make-based system which is
1590 capable of a wide variety of installation tasks, compilation tasks,
1591 and system configuration tasks.  Currently, it is not entirely generic
1592 across &impls;, and does not yet deal with some of the package
1593 registration issues mentioned above.</para>
1594
1595 <para>At Yale, another system is being developed.  It is also a
1596 make-based system and works reasonably well on various platforms
1597 (Unix, Linux, Windows) and &impls;.  It also does not yet deal with
1598 all of the package registration issues mentioned above.</para>
1599
1600 <para>Both tools can benefit from a standard packaging system.</para>
1601
1602 <para>Because <application>make</application> has been used for many
1603 years, it is expected that these systems will be able to do more than
1604 the initial release of the &distMod;.  The Setup script will be
1605 designed with this in mind, and should be able to wrap these tools in
1606 order to provide a common interface for users and for layered
1607 tools.</para>
1608
1609 </section>
1610
1611 <section id="lip-appendix-hmake"><title>&hmake;</title>
1612
1613 <para>From the &hmake; <ulink
1614 url="http://www.cs.york.ac.uk/fp/hmake/">home page</ulink>,
1615 <quote>&hmake; is an intelligent compilation management tool for
1616 Haskell programs. It automatically extracts dependencies between
1617 source modules, and issues the appropriate compiler commands to
1618 rebuild only those that have changed, given just the name of the
1619 program or module that you want to build. Yes, you need never write a
1620 Makefile again!</quote> &hmake; also does a good job of handling the
1621 variety of compilers that might be installed on a user's system.  It
1622 maintains a list of compilers and can switch between them according to
1623 a flag.  It also has a default compiler.</para>
1624
1625 <para>&hmake; is particularly interesting to us because it is written
1626 in Haskell and handles the task of compiling Haskell tools quite well.
1627 One shortcoming is that it is not extensible on a per-project basis:
1628 it is difficult to add support for new preprocessors without editing
1629 the &hmake; code itself.  It does, however, perform a lot of the tasks
1630 that &DistBuild; will ultimately have to perform, and we hope to reuse
1631 some of the code.</para>
1632
1633 <para>Another interesting feature of &hmake; is the
1634 <application>Haskell Interactive</application> tool (hi).  hi
1635 <quote>is, an interpreter-like environment that you can wrap over any
1636 common Haskell compiler to achieve an interactive development
1637 style.</quote> This is interesting because it would be nice to have a
1638 generic <filename>/usr/bin/haskell</filename> which would use the
1639 default compiler to interpret Haskell scripts.</para>
1640
1641 </section>
1642
1643 </appendix>
1644  
1645 </article>