diff options
| author | Ben Gamari <ben@smart-cactus.org> | 2021-11-19 12:39:45 -0500 |
|---|---|---|
| committer | Marge Bot <ben+marge-bot@smart-cactus.org> | 2021-12-14 20:53:51 -0500 |
| commit | 5686f47ba1866094a1546473ae2f0c523fb20d9e (patch) | |
| tree | 97c2ba629c19186cccbf1cedfc295dcd00406fcf /docs | |
| parent | 71ecb55b0b3ada2c9841dbc9f4a36fed52eb652e (diff) | |
| download | haskell-5686f47ba1866094a1546473ae2f0c523fb20d9e.tar.gz | |
ghc-bin: Add --merge-objs mode
This adds a new mode, `--merge-objs`, which can be used to produce
merged GHCi library objects.
As future work we will rip out the object-merging logic in Hadrian and
Cabal and instead use this mode.
Closes #20712.
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/users_guide/ghci.rst | 15 | ||||
| -rw-r--r-- | docs/users_guide/using.rst | 8 |
2 files changed, 23 insertions, 0 deletions
diff --git a/docs/users_guide/ghci.rst b/docs/users_guide/ghci.rst index 07377dab77..427829da99 100644 --- a/docs/users_guide/ghci.rst +++ b/docs/users_guide/ghci.rst @@ -3488,6 +3488,21 @@ will be executed on the target. As such packages like ``git-embed``, ``file-embed`` and others might not behave as expected if the target and host do not share the same filesystem. +.. _building-ghci-libraries: + +Building GHCi libraries +----------------------- + +When invoked in the static way, GHCi will use the GHC RTS's static runtime +linker to load object files for imported modules when available. However, when +these modules are built with :ghc-flag:`-split-sections` this linking can be +quite expensive. To reduce this cost, package managers and build systems may +opt to produce a pre-linked *GHCi object* using the :ghc-flag:`-merge-objs` +mode. This merges the per-module objects into a single object, collapsing +function sections into a single text section which can be efficiently loaded by +the runtime linker. + + .. _ghci-faq: FAQ and Things To Watch Out For diff --git a/docs/users_guide/using.rst b/docs/users_guide/using.rst index 59b89d1348..2184946571 100644 --- a/docs/users_guide/using.rst +++ b/docs/users_guide/using.rst @@ -345,6 +345,14 @@ The available mode flags are: compile source files one at a time, or link objects together into an executable. See :ref:`options-order`. +.. ghc-flag:: -merge-objs + :shortdesc: Merge a set of objects into a GHCi library. + :type: mode + :category: phases + + Merge a set of static object files into a library optimised for loading in + GHCi. See :ref:`building-ghci-libraries`. + .. ghc-flag:: -M :shortdesc: generate dependency information suitable for use in a ``Makefile``; see :ref:`makefile-dependencies` for details. |