From: Duncan Coutts Date: Tue, 8 Sep 2009 18:32:41 +0000 (+0000) Subject: Improve the user guide section on shared libs X-Git-Url: http://git.megacz.com/?p=ghc-hetmet.git;a=commitdiff_plain;h=5364ea8bd2086d3ce973988d583e3b4585d37b4d Improve the user guide section on shared libs Make it clear that Haskell code to be used by other Haskell code must be built as a package. --- diff --git a/docs/users_guide/shared_libs.xml b/docs/users_guide/shared_libs.xml index e2152d1..00f6f67 100644 --- a/docs/users_guide/shared_libs.xml +++ b/docs/users_guide/shared_libs.xml @@ -68,10 +68,72 @@ ghc --make -dynamic Main.hs - Building shared libraries + Shared libraries for Haskell packages + + You can build Haskell code into a shared library and make a package to be + used by other Haskell programs. The easiest way is using Cabal, simply + configure the Cabal package with the --enable-shared + flag. + + + If you want to do the steps manually or are writing your own build + system then there are certain conventions that must be followed. Building + a shared library that exports Haskell code, to be used by other Haskell + code is a bit more complicated than it is for one that exports a C API + and will be used by C code. If you get it wrong you will usually end up + with linker errors. + + + In particular Haskell shared libraries must be + made into packages. You cannot freely assign which modules go in which + shared libraries. The Haskell shared libraries must match the package + boundaries. Most of the conventions GHC expects when using packages are + described in . + - To build some Haskell modules into a shared library use the + GHC handles references to symbols within the same + shared library (or main executable binary) differently from references + to symbols between different shared libraries. GHC + needs to know for each imported module if that module lives locally in + the same shared lib or in a separate shared lib. The way it does this + is by using packages. When using -dynamic, a module + from a separate package is assumed to come from a separate shared lib, + while modules from the same package (or the default "main" package) are + assumed to be within the same shared lib (or main executable binary). + + + Most of the conventions GHC expects when using packages are described + in . In addition note that GHC + expects the .hi files to use the extension + .dyn_hi. The other requirements are the same as for + C libraries and are described below, in particular the use of the flags -dynamic, -fPIC and + -shared. + + + + + Shared libraries that export a C API + + Building Haskell code into a shared library is a good way to include + Haskell code in a larger mixed-language project. While with static + linking it is recommended to use GHC to perform the final link step, + with shared libaries a Haskell library can be treated just like any + other shared libary. The linking can be done using the normal system C + compiler or linker. + + + It is possible to load shared libraries generated by GHC in other + programs not written in Haskell, so they are suitable for using as + plugins. Of course to construct a plugin you will have to use the FFI + to export C functions and follow the rules about initialising the RTS. + See . In particular you will probably want + to export a C function from your shared library to initialise the + plugin before any Haskell functions are called. + + + To build Haskell modules that export a C API into a shared library use + the -dynamic, -fPIC and -shared flags: ghc --make -dynamic -shared -fPIC Foo.hs -o libfoo.so @@ -98,39 +160,14 @@ ghc -dynamic -shared Foo.o -o libfoo.so suitable to include into a shared library and we do not do that at the moment. - - - - Shared libraries that export a C API - - Building Haskell code into a shared library is a good way to include - Haskell code in a larger mixed-language project. While with static - linking it is recommended to use GHC to perform the final link step, - with shared libaries a Haskell library can be treated just like any - other shared libary. The linking can be done using the normal system C - compiler or linker. - - It is possible to load shared libraries generated by GHC in other - programs not written in Haskell, so they are suitable for using as - plugins. Of course to construct a plugin you will have to use the FFI - to export C functions and follow the rules about initialising the RTS. - See . In particular you will probably want - to export a C function from your shared library to initialise the - plugin before any Haskell functions are called. + Warning: if your shared library exports a Haskell + API then you cannot directly link it into another Haskell program and + use that Haskell API. You will get linker errors. You must instead make + it into a package as described in the section above. - - Shared libraries for Haskell packages - - When building Haskell packages as shared libraries to be used by other - Haskell programs there are certain conventions that must be followed. - These are handled by Cabal but for the details see . - - - Finding shared libraries at runtime