X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=ghc%2Fdocs%2Fusers_guide%2Fpackages.sgml;h=bf56e9644c28b342e2497c787e5fd18a3cd21dbb;hb=dac19c07b199bcce81cd29a8f858af7f97e9a21e;hp=3d0bbac3754decf71f010a26b7630bf4ce65cde2;hpb=ec655d31e7a73d0e2b9eb160faa7ebd7c9fe3577;p=ghc-hetmet.git diff --git a/ghc/docs/users_guide/packages.sgml b/ghc/docs/users_guide/packages.sgml index 3d0bbac..bf56e96 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 A package has a name - (e.g. std) + (e.g. base) The Haskell code in a package may be built into one or - 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 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 and load that. 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: + 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 @@ -177,7 +191,7 @@ 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 + 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 []. @@ -297,6 +311,17 @@ + + + + + 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 @@ -310,9 +335,9 @@ Package { name = "mypkg", - import_dirs = ["/usr/local/lib/imports/mypkg"], + import_dirs = ["${installdir}/imports/mypkg"], source_dirs = [], - library_dirs = ["/usr/local/lib"], + library_dirs = ["${installdir}"], hs_libraries = ["HSmypkg" ], extra_libraries = ["HSmypkg_cbits"], include_dirs = [], @@ -347,6 +372,13 @@ 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). @@ -397,7 +429,9 @@ 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. @@ -405,7 +439,7 @@ HSfoo.dll The name of the dynamic library on Windows - systems. + systems (optional). @@ -441,6 +475,12 @@ 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 @@ -516,7 +556,50 @@ (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