diff --git a/ghc/docs/users_guide/installing.sgml b/ghc/docs/users_guide/installing.sgml index 8a28e3c63607dbeacbbe6d7653b68ed6d5b68d53..b03bbdcb582e64984e0e87da58afdba48ddbbc58 100644 --- a/ghc/docs/users_guide/installing.sgml +++ b/ghc/docs/users_guide/installing.sgml @@ -123,7 +123,7 @@ These sub-directories have the following general structure: <VariableList> <VarListEntry> -<Term><Literal>libHS.a</Literal> etc:</Term> +<Term><Literal>libHSstd.a</Literal> etc:</Term> <ListItem> <Para> supporting library archives. diff --git a/ghc/docs/users_guide/using.sgml b/ghc/docs/users_guide/using.sgml index 595e13d6b0c222f1d119aae9b165d0e1cd47db77..5c42c419f0f99591254b8a609943b33bd2819697 100644 --- a/ghc/docs/users_guide/using.sgml +++ b/ghc/docs/users_guide/using.sgml @@ -704,9 +704,6 @@ sanity, not yours.) <IndexTerm><Primary>separate compilation</Primary></IndexTerm> <IndexTerm><Primary>recompilation checker</Primary></IndexTerm> <IndexTerm><Primary>make and recompilation</Primary></IndexTerm> -</Para> - -<Para> This section describes how GHC supports separate compilation. </Para> @@ -990,40 +987,74 @@ sight! </Para> <Para> -GHC <Emphasis>only</Emphasis> keeps detailed dependency information -for “user” modules, not for “Prelude” modules. -It distinguishes Prelude modules because their names start with -"Prel", so don't start your modules that way! +Patrick Sansom had a workshop paper about how all this is done (though +the details have changed quite a bit). <ULink URL="mailto:sansom@dcs.gla.ac.uk">Ask him</ULink> if you want a copy. +</Para> -<!-- April 2000: hack disabled. Now we use a different hack! +<Sect3 id="packages"> +<Title>Packages</Title> -It distinguishes the two by a hack: a module whose -<Filename>.hi</Filename> file has an absolute path name is considered -a library module, while a relative path name indicates a user module. -So if you have a multi-directory application, use -<Emphasis>relative</Emphasis> path names in your <Option>-i</Option> -path, to force GHC to record detailed dependency information. Use -absolute path names only for directories containing slowly-changing -library modules. +<Para> +<IndexTerm><Primary>packages</Primary></IndexTerm> +To simplify organisation and compilation, GHC keeps libraries in <Emphasis>packages</Emphasis>. Packages are also compiled into single libraries on Unix, and DLLs on Windows. The term ``package'' can be used pretty much synonymously with ``library'', except that an application also forms a package, the Main package. +</Para> + +<ItemizedList> +<ListItem> +<Para> +A package is a group of modules. It may span many directories, or many packages may exist in a single directory. Packages may not be mutually recursive. </Para> +</ListItem> +<ListItem> <Para> -A path is considered “absolute” if it starts with -“<Filename>/</Filename>”, or -“<Filename>A:/</Filename>”, or -“<Filename>A:\</Filename>” (or -“<Filename>B:/</Filename>”, -“<Filename>B:\</Filename>” etc). +A package has a name (e.g. <Filename>std</Filename>) </Para> ---> +</ListItem> +<ListItem> <Para> -Patrick Sansom had a workshop paper about how all this is done (though -the details have changed quite a bit). <ULink URL="mailto:sansom@dcs.gla.ac.uk">Ask him</ULink> if you want a copy. +Each package is built into a single library (Unix; e.g. <Filename>libHSfoo.a</Filename>), or a single DLL (Windows; e.g. <Filename>HSfoo.dll</Filename>) </Para> +</ListItem> + +<ListItem> +<Para> +The <Option>-package-name foo</Option> flag tells GHC that the module being compiled is destined for package <Filename>foo</Filename>. If this is omitted, the default package, <Filename>Main</Filename>, is assumed. +</Para> +</ListItem> + +<ListItem> +<Para> +The <Option>-package foo</Option> flag tells GHC to make available modules +from package <Filename>foo</Filename>. It replaces <Option>-syslib foo</Option>, which is now deprecated. +</Para> +</ListItem> + +<ListItem> +<Para> +GHC does not maintain detailed cross-package dependency information. +It does remember which modules in other packages the current module +depends on, but not which things within those imported things. +</Para> +</ListItem> +</ItemizedList> + +<Para> +All of this tidies up the Prelude enormously. The Prelude and +Standard Libraries are built into a single package called <Filename>std</Filename>. (This +is a change; the library is now called <Filename>libHSstd.a</Filename> instead of <Filename>libHS.a</Filename>). +</Para> + +<Para> +It is worth noting that on Windows, because each package is built as a DLL, and a reference to a DLL costs an extra indirection, intra-package references are cheaper than inter-package references. Of course, this applies to the <Filename>Main</Filename> package as well. This is not normally the case on most Unices. +</Para> + +</Sect3> </Sect2> + <Sect2 id="using-make"> <Title>Using <Command>make</Command> </Title>