X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=ghc%2Fdocs%2Fusers_guide%2Fpackages.sgml;h=e6f0b7b2b440109eb8a1c80bdce5e48c116bbdab;hb=af76ab6142576b7cc4af11c4883c387e96b18f73;hp=1a98edd6a6b0192893718f09250bedffb700a490;hpb=e6120f49ee825c1094d0941d5ceed261f64d8873;p=ghc-hetmet.git diff --git a/ghc/docs/users_guide/packages.sgml b/ghc/docs/users_guide/packages.sgml index 1a98edd..e6f0b7b 100644 --- a/ghc/docs/users_guide/packages.sgml +++ b/ghc/docs/users_guide/packages.sgml @@ -13,8 +13,8 @@ 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 to or removed + 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 packages using - To use a package, add the -package flag - to the GHC command line: + Some 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: @@ -42,6 +50,20 @@ + There's one case where you need to use the + option even for auto packages: when + linking a program in batch modeThis 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: + +$ ghc -o myprog Foo.o Main.o -package network + 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 @@ -101,34 +123,47 @@ 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). Building packages as DLLs - doesn't work at the moment; see for the gory details. + 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 (the object suffix - varies between platforms, as usual) and load that. An - object file can be built from a .a - archive as follows (using GNU ld on - Unix): - - -ld -r --whole-archive -o HSfoo.o libHSfoo.a - + 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 @@ -178,8 +213,8 @@ ld -r --whole-archive -o HSfoo.o libHSfoo.a 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 or removed from a user-specified - configuration file using the + 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 []. @@ -188,12 +223,11 @@ ld -r --whole-archive -o HSfoo.o libHSfoo.a - + - - + - Reads a package specification (see below) on stdin, + 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. @@ -201,55 +235,143 @@ ld -r --whole-archive -o HSfoo.o libHSfoo.a - + + + + + 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 instead of the - default package configuration file. This, in conjunction - with GHC's option, allows - a user to have a local set of packages in addition to the - system-wide installed set. + 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. - + + + + + 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. + + When modifying the configuration file @@ -263,9 +385,10 @@ ld -r --whole-archive -o HSfoo.o libHSfoo.a 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 = [], @@ -288,18 +411,40 @@ ld -r --whole-archive -o HSfoo.o libHSfoo.a 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). @@ -350,7 +495,9 @@ ld -r --whole-archive -o HSfoo.o libHSfoo.a libHSfoo.a - The name of the library on Unix + 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. @@ -358,7 +505,7 @@ ld -r --whole-archive -o HSfoo.o libHSfoo.a HSfoo.dll The name of the dynamic library on Windows - systems. + systems (optional). @@ -394,6 +541,12 @@ ld -r --whole-archive -o HSfoo.o libHSfoo.a 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 after the hs_libraries for the same package. If @@ -465,11 +618,55 @@ ld -r --whole-archive -o HSfoo.o libHSfoo.a 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