X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=docs%2Fusers_guide%2Fshared_libs.xml;h=def773c0a8ad8c02502b5ed6a3c52109355ab4dc;hb=1c1ed8694bdd24b003fa5935d001a1835e9b0f4e;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..def773c 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 .
+
+
+ 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).
+
- To build some Haskell modules into a shared library use the
+ 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
@@ -181,17 +218,6 @@ ghc -dynamic -shared Foo.o -o libfoo.so
-
- wrapped
-
-
- This mode generates a wrapper program which in turn calls the
- real program (in the same directory but with a .dyn extension)
- in such a way that it can find the shared libraries that it
- needs. At the current time this mode is somewhat experimental.
-
-
-
To use relative paths for dependent libraries on Linux and Solaris you
can use the deploy mode and pass suitable a -rpath
@@ -205,6 +231,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.
+