X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;ds=sidebyside;f=ghc%2Fdocs%2Fusers_guide%2Fpackages.sgml;h=9e8e7c9222802345784d3cea8562644e415db8c4;hb=2dfd507259664e6f28df4a9467a8de34d01d70a0;hp=4eeff0112a53ab778db6d00f57f2efa305829e13;hpb=cf136928e058162eaeed7273c135ec08edc92f35;p=ghc-hetmet.git diff --git a/ghc/docs/users_guide/packages.sgml b/ghc/docs/users_guide/packages.sgml index 4eeff01..9e8e7c9 100644 --- a/ghc/docs/users_guide/packages.sgml +++ b/ghc/docs/users_guide/packages.sgml @@ -13,20 +13,29 @@ 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, using the supplied + GHC comes with several packages (see the accompanying + library documentation), and packages can be added to or removed + from an existing GHC installation, using the supplied ghc-pkgghc-pkg tool, described in . + linkend="package-management"/>. Using a package packages using - To use a package, add the -package flag - to the GHC command line: + Some packages, called auto packages, + are automatically available: you don't need + to specify any extra flags to use them (except in certain + circumstances; see below). All the packages which contain + hierarchical libraries fall into this category. + + Some other packages are not + automatically available: those are normally the packages + containing old non-hierarchical libraries. To gain access to a + non-auto package, use the command-line + flag: @@ -38,16 +47,72 @@ 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. - 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. + There's one case where you need to use the + option even for auto packages: when + linking a program in batch mode mode () + This is because + GHC can't figure out from the object files which packages are + required; in mode and in + GHCi the compiler has more information available to figure out + the package dependencies. We might try to lift this restriction + in the future.. For example, to link a + program consisting of objects Foo.o and + Main.o, where we made use of the + network package, we need to give GHC the -package flag thus: + +$ ghc -o myprog Foo.o Main.o -package network + + The same flag is necessary even if we compiled the modules from source, because GHC still + reckons it's in batch mode: +$ ghc -o myprog Foo.hs Main.hs -package network +In --make and --interactive modes (), however, GHC figures out +the auto packages required for linking without further assistance. + + + + + + + Maintaining a local set of packages + + When GHC starts up, it automatically reads the default set + of packages from a configuration file, normally named + package.conf in your GHC installation + directory. + + You can load in additional package configuration files + using the option: + + + + + + + + Read in the package configuration file + file in addition to the system + default file. This allows the user to have a local set of + packages in addition to the system-wide ones. + + + + + To create your own package configuration file, just create + a new file and put the string + [] in it. Packages can be + added to the new configuration file using the + ghc-pkg tool, described in . @@ -68,21 +133,54 @@ A package has a name - (e.g. std) + (e.g. base) 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). + more archive libraries + (e.g. libHSfoo.a), or a single DLL on + Windows (e.g. HSfoo.dll). The + restriction to a single DLL on Windows is because 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). Building packages as DLLs doesn't + work at the moment; see + for the gory details. + + + Building a static library is done by using the + ar tool, like so: + +ar cqs libHSfoo.a A.o B.o C.o ... + + where A.o, + B.o and so on are the compiled Haskell + modules, and libHSfoo.a is the library + you wish to create. The syntax may differ slightly on your + system, so check the documentation if you run into + difficulties. + + Versions of the Haskell libraries for use with GHCi + may also be included: GHCi cannot load .a + files directly, instead it will look for an object file + called HSfoo.o and load that. On some + systems, the ghc-pkg tool can + automatically build the GHCi version of each library, see + . To build these + libraries by hand from the .a archive, it + is possible to use GNU ld as + follows: + +ld -r ––whole-archive -o HSfoo.o libHSfoo.a + (replace + ––--whole-archive with + –all_load on MacOS X) + 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 @@ -114,8 +212,8 @@ 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 + It is worth noting that on Windows, when each package + is built as a DLL, since 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. @@ -126,78 +224,185 @@ 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 packages can be added or removed using GHC's - package management tool, ghc-pkg. + The ghc-pkg tool allows packages to be + added or removed from a package configuration file. By default, + the system-wide configuration file is used, but alternatively + packages can be added, updated or removed from a user-specified + configuration file using the + option. An empty package configuration file consists of the + string []. + + The ghc-pkg program accepts the + following options: - + + + + + Reads package specification from the input (see below), + and adds it to the database of installed packages. The + package specification must be a package that isn't already + installed. + + + + + + + + + Read new package specifications from file + file. If a value of + "-" is given, standard input is used. + If no is present on the command-line, + an input file of "-" is assumed. + + + + + + + + + + + Automatically generate the GHCi + .o version of each + .a Haskell library, using GNU ld (if + that is available). Without this option, + ghc-pkg will warn if GHCi versions of + any Haskell libraries in the package don't exist. + + GHCi .o libraries don't + necessarily have to live in the same directory as the + corresponding .a library. However, + this option will cause the GHCi library to be created in + the same directory as the .a + library. + + + + + + + + + + Use file as an additional + package configuration file. This is used to modify + configuration files for use with GHC's + option. + + There may be any number of configuration files named + on the command line; files mentioned later on the + command-line override those mentioned earlier. The + last configuration file mentioned on + the command-line is the only one that is actually modified + by ghc-pkg. + + + + + + - + This option displays the list of currently installed - packages. + packages, including those in extra configuration files + specified with the + option. - $ ghc-pkg --list-packages - gmp, rts, std, lang, concurrent, data, net, posix, text, util + $ ghc-pkg ––list-packages + /usr/local/lib/ghc-5.05/package.conf: + hdirect, readline, lang, concurrent, posix, util, data, text, net, + hssource, rts, haskell98, network, haskell-src, unix, base 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 and standard - libraries. The rest of the packages are optional - libraries. + The rts package is always + present, and represents the runtime system library. The + base package contains the Haskell + prelude and basic hierarchical libraries, and the + haskell98 package contains the Haskell + 98 standard libraries. The rest of the packages are + optional libraries. - - - - + + + - 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. + Displays the list of packages installed in the + topmost configuration file only: that will be the + configuration file specified using on + the command line, or the system configuration file + otherwise. + + This option may be more convenient than + when the output needs to be parsed by + a script. - + - + Removes the specified package from the installed configuration. + + + + + + Reads package specification from the input, and + adds it to the database of installed packages. If a package + with the same name is already installed, its configuration + data is replaced with the new information. If the package + doesn't already exist, it's added. + + + + + + + + Causes ghc-pkg to ignore missing + directories and libraries when adding a package, and just + go ahead and add it anyway. This might be useful if your + package installation system needs to add the package to + GHC before building and installing the files. + + - 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. + When modifying the configuration file + file, a copy of the original file is + saved in file.old, + so in an emergency you can always restore the old settings by + copying the old file back again. A package specification looks like this: Package { name = "mypkg", - import_dirs = ["/usr/local/lib/imports/mypkg"], + auto = True, + import_dirs = ["${installdir}/imports/mypkg"], source_dirs = [], - library_dirs = ["/usr/local/lib"], + library_dirs = ["${installdir}"], hs_libraries = ["HSmypkg" ], extra_libraries = ["HSmypkg_cbits"], include_dirs = [], @@ -220,18 +425,40 @@ The package's name, for use with the -package flag and as listed in the - --list-packages list. + ––list-packages list. + auto + auto + package specification + + + Set to True if the package should + be automatically available (see ). This is normally set to + True for packages which contain + hierarchical libraries, because in that case there is no + danger of polluting the module namespace. + + + + import_dirs import_dirs package specification A list of directories containing interface files (.hi files) for this package. + + If the package contains profiling libraries, then + the interface files for those library modules should have + the suffix .p_hi. So the package can + contain both normal and profiling versions of the same + library without conflict (see also + library_dirs below). @@ -264,8 +491,47 @@ A list of libraries containing Haskell code for this package, with the .a or - .dll suffix omitted. On Unix, the + .dll suffix omitted. When packages are + built as libraries, the lib prefix is also omitted. + + For use with GHCi, each library should have an + object file too. The name of the object file does + not have a lib + prefix, and has the normal object suffix for your + platform. + + For example, if we specify a Haskell library as + HSfoo in the package spec, then the + various flavours of library that GHC actually uses will be + called: + + + libHSfoo.a + + The name of the library on Unix and Windows + (mingw) systems. Note that we don't support + building dynamic libraries of Haskell code on Unix + systems. + + + + HSfoo.dll + + The name of the dynamic library on Windows + systems (optional). + + + + HSfoo.o + HSfoo.obj + + The object version of the library used by + GHCi. + + + + @@ -289,11 +555,20 @@ for libraries in extra_libraries. + The libraries listed in + extra_libraries may be any libraries + supported by your system's linker, including dynamic + libraries (.so on Unix, + .DLL on Windows). + Also, extra_libraries are placed - on the linker command line before the + on the linker command line after the hs_libraries for the same package. If - your package has dependencies in the other direction, you - might need to make two separate packages. + your package has dependencies in the other direction (i.e. + extra_libraries depends on + hs_libraries), and the libraries are + static, you might need to make two separate + packages. @@ -357,11 +632,55 @@ extra_ld_opts package specification - Extra arguments to be added to the gcc command line - (for linking) when this package is being used. + Extra arguments to be added to the + gcc command line (for linking) when + this package is being used. + + + + + framework_dirs + framework_dirs + package specification + + On Darwin/MacOS X, a list of directories containing frameworks for this + package. This corresponds to the option. + It is ignored on all other platforms. + + + + + extra_frameworks + extra_frameworks + package specification + + On Darwin/MacOS X, a list of frameworks to link to. This corresponds to the + option. Take a look at Apple's developer documentation + to find out what frameworks actually are. This entry is ignored on all other platforms. + + + The ghc-pkg tool performs expansion of + environment variables occurring in input package specifications. + So, if the mypkg was added to the package + database as follows: + + + $ installdir=/usr/local/lib ghc-pkg -a < mypkg.pkg + + + + The occurrence of ${installdir} is replaced + with /usr/local/lib in the package data that + is added for mypkg. + + + + This feature enables the distribution of package specification + files that can be easily configured when installing. + For examples of more package specifications, take a look at the package.conf in your GHC