From: simonmar Date: Thu, 6 Jul 2000 13:32:35 +0000 (+0000) Subject: [project @ 2000-07-06 13:32:35 by simonmar] X-Git-Tag: Approximately_9120_patches~4073 X-Git-Url: http://git.megacz.com/?a=commitdiff_plain;h=a058828dfcb5af02b87f9522542773f183fa69de;p=ghc-hetmet.git [project @ 2000-07-06 13:32:35 by simonmar] New section on Packages, collecting together the various package-related documentation and adding some new stuff about the package management features. --- diff --git a/ghc/docs/users_guide/using.sgml b/ghc/docs/users_guide/using.sgml index 6df35de..250cb95 100644 --- a/ghc/docs/users_guide/using.sgml +++ b/ghc/docs/users_guide/using.sgml @@ -827,20 +827,6 @@ country. - - - --package <lib> option -If you are using a system-supplied non-Prelude library (e.g., the -POSIX library), just use a option (for -example). The right interface files should then be available. The -accompanying HsLibs document lists the libraries available by this -mechanism. - - - - - @@ -991,67 +977,6 @@ Patrick Sansom had a workshop paper about how all this is done (though the details have changed quite a bit). Ask him if you want a copy. - -Packages - - -packages -To simplify organisation and compilation, GHC keeps libraries in packages. 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. - - - - - -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. - - - - - -A package has a name (e.g. std) - - - - - -Each package is built into a single library (Unix; e.g. libHSfoo.a), or a single DLL (Windows; e.g. HSfoo.dll) - - - - - -The flag tells GHC that the module being compiled is destined for package foo. If this is omitted, the default package, Main, is assumed. - - - - - -The flag tells GHC to make available modules -from package foo. It replaces , which is now deprecated. - - - - - -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. - - - - - -All of this tidies up the Prelude enormously. The Prelude and -Standard Libraries are built into a single package called std. (This -is a change; the library is now called libHSstd.a instead of libHS.a). - - - -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 Main package as well. This is not normally the case on most Unices. - - - - @@ -1484,6 +1409,327 @@ construction of interface files, is (allegedly) in the works. + + Packages + packages + + Packages are collections of libraries, conveniently grouped + together as a single entity. The package system is flexible: a + package may consist of Haskell code, foreign language code (eg. C + libraries), or a mixture of the two. A package is a good way to + group together related Haskell modules, and is essential if you + intend to make the modules into a Windows DLL (see below). + + Because packages can contain both Haskell and C libraries, they + are also a good way to provide convenient access to a Haskell + layer over a C library. + + GHC comes with several packages (see ), and packages can be added/removed from an + existing GHC installation. + + + Listing the available packages + packages + listing + + To see what packages are currently installed, use the + --list-packages option: + --list-packages + + + + $ ghc --list-packages + gmp, rts, std, lang, concurrent, data, net, posix, text, util + + + Note that your GHC installation might have a slightly + different set of packages installed. + + The gmp and rts + packages are always present, and represent the multi-precision + integer and runtime system libraries respectively. The + std package contains the Haskell prelude. + The rest of the packages are optional libraries. + + + + + Using a package + packages + using + + To use a package, add the -package flag + to the command line: + + + + + -package <lib> option + + This option brings into scope all the modules from + package <lib> (they still have to + be imported in your Haskell source, however). It also + causes the relevant libraries to be linked when linking is + being done. + + + + + Some packages depend on other packages, for example the + text package makes use of some of the modules + in the lang package. The package system + takes care of all these dependencies, so that when you say + -package text on the command line, you + automatically get -package lang too. + + + + Building a package from Haskell source + packages + building + + It takes some special considerations to build a new + package: + + + + A package may contain several Haskell modules. A + package may span many directories, or many packages may + exist in a single directory. Packages may not be mutually + recursive. + + + + A package has a name + (e.g. std) + + + + The Haskell code in a package may be built into one or + more Unix libraries (e.g. libHSfoo.a), + or a single DLL on Windows + (e.g. HSfoo.dll). The restriction to a + single DLL on Windows is that the package system is used to + tell the compiler when it should make an inter-DLL call + rather than an intra-DLL call (inter-DLL calls require an + extra indirection). + + + + 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. + + + + To compile a module which is to be part of a new package, + use the -package-name option: + + + + + -package-name + option + + This option is added to the command line when + compiling a module that is destined to be part of package + foo. If this flag is omitted then the + default package Main is assumed. + + + + + Failure to use the -package-name option + when compiling a package will result in disaster on Windows, but + is relatively harmless on Unix at the moment (it will just cause + a few extra dependencies in some interface files). However, + bear in mind that we might add support for Unix shared libraries + at some point in the future. + + 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 + Main package as well. + + + + Package management + packages + management + + GHC uses a package configuration file, called + packages.conf, which can be found in your GHC + install directory. This file isn't intended to be edited + directly, instead GHC provides options for adding & removing + packages: + + + + + --add-package + option + + Reads a package specification (see below) on stdin, + and adds it to the database of installed packages. The + package specification must be a package that isn't already + installed. + + + + + + --delete-package + option + + Removes the specified package from the installed + configuration. + + + + + In both cases, the old package configuration file is saved + in packages.conf.old in your GHC install + directory, so in an emergency you can always copy this file into + package.conf to restore the old + settings. + + A package specification looks like this: + + + ("mypkg", + "4.08", + Package + { + import_dirs = ["/usr/local/lib/imports/mypkg"], + library_dirs = ["/usr/local/lib"], + libraries = ["HSmypkg", "HSmypkg_cbits"], + include_dir = "", + c_include = "HsMyPkg.h", + package_deps = ["text", "data"], + extra_ghc_opts = "", + extra_cc_opts = "", + extra_ld_opts = "-lmy_clib" + } + ) + + + The first line is the name of the package, for use with + the -package flag and as listed in the + --list-packages list. The second line is the + version of GHC that was used to compile any Haskell code in this + package (GHC will refuse to add the package if its version + number differs from this one). The rest of the components of + the package speecification may be specified in any order, and + are: + + + + import_dirs + import_dirs + package specification + + A list of directories containing interface files + (.hi files) for this package. + + + + + library_dirs + library_dirs + package specification + + A list of directories containing libraries for this + package. + + + + + libraries + libraries + package specification + + A list of libraries for this package, with the + .a or .dll suffix + omitted. On Unix, the lib prefix is + also omitted. + + + + + include_dir + include_dir + package specification + + A directory containing C includes for this package + (may be the empty string). + + + + + c_include + c_include + package specification + + A file to include for via-C compilations using this + package. Typically this include file will contain + function prototypes for any C functions used in the + package, in case they end up being called as a result of + Haskell functions from the package being inlined. + + + + + package_deps + package_deps + package specification + + A list of packages which this package depends + on. + + + + + extra_ghc_opts + extra_ghc_opts + package specification + + Extra arguments to be added to the GHC command line + when this package is being used. + + + + + extra_cc_opts + extra_cc_opts + package specification + + Extra arguments to be added to the gcc command line + when this package is being used (only for via-C + compilations). + + + + + extra_ld_opts + extra_ld_opts + package specification + + Extra arguments to be added to the gcc command line + (for linking) when this package is being used. + + + + + For examples of more package specifications, take a look + at the package.conf in your GHC + installation. + + + + Optimisation (code improvement)