[[project @ 2000-07-06 13:32:35 by simonmar]
simonmar**20000706133235
New section on Packages, collecting together the various
package-related documentation and adding some new stuff about the package
management features.
] {
hunk ./ghc/docs/users_guide/using.sgml 829
-
-
-
-
--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.
-
-
-
-
hunk ./ghc/docs/users_guide/using.sgml 980
-
-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.
-
-
-
-
hunk ./ghc/docs/users_guide/using.sgml 1412
+
+ 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.
+
+
+
+
}