X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=docs%2Fusers_guide%2Fshared_libs.xml;h=ea5500b89d5d5037e5567b57bf4cbc14b207cdf0;hb=26f164e5759e9eca73deb0531ddec422d36a6924;hp=e2152d1818bb83fd38189899f224eac034a751ad;hpb=a7981216f157c0d7faac9e9acf98cf0351951a8d;p=ghc-hetmet.git diff --git a/docs/users_guide/shared_libs.xml b/docs/users_guide/shared_libs.xml index e2152d1..ea5500b 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,37 +160,12 @@ 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. + 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. - - 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. - - - - - 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 . - @@ -205,6 +242,19 @@ ghc -dynamic Main.hs -o main -lfoo -L. -optl-Wl,-rpath,'$ORIGIN' Similarly it would be possible to use a subdirectory relative to the executable e.g. -optl-Wl,-rpath,'$ORIGIN/lib'. + + The standard assumption on Darwin/MacOS X is that dynamic libraries will + be stamped at build time with an "install name", which is the full + ultimate install path of the library file. Any libraries or executables + that subsequently link against it (even if it hasn't been installed yet) + will pick up that path as their runtime search location for it. When + compiling with ghc directly, the install name is set by default to the + location where it is built. You can override this with the + -dylib-install-name option (which passes + -install_name to the Apple linker). Cabal does this + for you. It automatically sets the install name for dynamic libraries to + the absolute path of the ultimate install location. +