diff options
Diffstat (limited to 'docs/users_guide/separate_compilation.rst')
| -rw-r--r-- | docs/users_guide/separate_compilation.rst | 178 |
1 files changed, 161 insertions, 17 deletions
diff --git a/docs/users_guide/separate_compilation.rst b/docs/users_guide/separate_compilation.rst index 06af6f0ddf..d17ed2111c 100644 --- a/docs/users_guide/separate_compilation.rst +++ b/docs/users_guide/separate_compilation.rst @@ -158,6 +158,9 @@ current directory). The following options can be used to add to or change the contents of the search path: .. ghc-flag:: -i⟨dir⟩[:⟨dir⟩]* + :shortdesc: add ⟨dir⟩, ⟨dir2⟩, etc. to import path + :type: dynamic + :category: search-path .. index:: single: search path; source code @@ -166,6 +169,10 @@ contents of the search path: the search path. .. ghc-flag:: -i + :shortdesc: Empty the import directory list + :type: dynamic + :category: search-path + resets the search path back to nothing. This isn't the whole story: GHC also looks for modules in pre-compiled @@ -182,6 +189,9 @@ Redirecting the compilation output(s) single: redirecting compilation output .. ghc-flag:: -o ⟨file⟩ + :shortdesc: set output filename + :type: dynamic + :category: GHC's compiled output normally goes into a ``.hc``, ``.o``, etc., file, depending on the last-run compilation phase. The option @@ -231,6 +241,9 @@ Redirecting the compilation output(s) will produce ``Prog`` (or ``Prog.exe`` if you are on Windows). .. ghc-flag:: -odir ⟨dir⟩ + :shortdesc: set directory for object files + :type: dynamic + :category: Redirects object files to directory ⟨dir⟩. For example: @@ -248,6 +261,9 @@ Redirecting the compilation output(s) ``parse/Bar.hi``, and ``gurgle/Bumble.hi``. .. ghc-flag:: -ohi ⟨file⟩ + :shortdesc: set the filename in which to put the interface + :type: dynamic + :category: The interface output may be directed to another file ``bar2/Wurble.iface`` with the option ``-ohi bar2/Wurble.iface`` @@ -265,11 +281,17 @@ Redirecting the compilation output(s) for example. .. ghc-flag:: -hidir ⟨dir⟩ + :shortdesc: set directory for interface files + :type: dynamic + :category: Redirects all generated interface files into ⟨dir⟩, instead of the default. .. ghc-flag:: -stubdir ⟨dir⟩ + :shortdesc: redirect FFI stub files + :type: dynamic + :category: Redirects all generated FFI stub files into ⟨dir⟩. Stub files are generated when the Haskell source contains a ``foreign export`` or @@ -279,31 +301,40 @@ Redirecting the compilation output(s) hierarchical modules. .. ghc-flag:: -dumpdir ⟨dir⟩ + :shortdesc: redirect dump files + :type: dynamic + :category: Redirects all dump files into ⟨dir⟩. Dump files are generated when ``-ddump-to-file`` is used with other ``-ddump-*`` flags. .. ghc-flag:: -outputdir ⟨dir⟩ + :shortdesc: set output directory + :type: dynamic + :category: The ``-outputdir`` option is shorthand for the combination of :ghc-flag:`-odir ⟨dir⟩`, :ghc-flag:`-hidir ⟨dir⟩`, :ghc-flag:`-stubdir ⟨dir⟩` and :ghc-flag:`-dumpdir ⟨dir⟩`. .. ghc-flag:: -osuf ⟨suffix⟩ - -hisuf ⟨suffix⟩ - -hcsuf ⟨suffix⟩ + :shortdesc: set the output file suffix + :type: dynamic + :category: The ``-osuf`` ⟨suffix⟩ will change the ``.o`` file suffix for object files to whatever you specify. We use this when compiling libraries, so that objects for the profiling versions of the libraries don't clobber the normal ones. +.. ghc-flag:: -hisuf ⟨suffix⟩ + :shortdesc: set the suffix to use for interface files + :type: dynamic + :category: + Similarly, the ``-hisuf`` ⟨suffix⟩ will change the ``.hi`` file suffix for non-system interface files (see :ref:`hi-options`). - Finally, the option ``-hcsuf`` ⟨suffix⟩ will change the ``.hc`` file - suffix for compiler-generated intermediate C files. - The ``-hisuf``/``-osuf`` game is particularly useful if you want to compile a program both with and without profiling, in the same directory. You can say: @@ -320,6 +351,15 @@ Redirecting the compilation output(s) to get the profiled version. + +.. ghc-flag:: -hcsuf ⟨suffix⟩ + :shortdesc: set the suffix to use for intermediate C files + :type: dynamic + :category: + + Finally, the option ``-hcsuf`` ⟨suffix⟩ will change the ``.hc`` file + suffix for compiler-generated intermediate C files. + .. _keeping-intermediates: Keeping Intermediate Files @@ -337,21 +377,45 @@ compilation: .. ghc-flag:: -keep-hc-file -keep-hc-files + :shortdesc: Retain intermediate ``.hc`` files. + :type: dynamic + :category: keep-intermediates Keep intermediate ``.hc`` files when doing ``.hs``-to-``.o`` compilations via :ref:`C <c-code-gen>` (Note: ``.hc`` files are only generated by :ref:`unregisterised <unreg>` compilers). .. ghc-flag:: -keep-hi-files + :shortdesc: Retain intermediate ``.hi`` files (the default). + :type: dynamic + :reverse: -no-keep-hi-files + :category: keep-intermediates .. index:: single: temporary files; keeping - Keep intermediate ``.hi`` files. This is the default. You may use - ``-no-keep-hi-files`` if you are not interested in the ``.hi`` files. + Keep intermediate ``.hi`` files. This is the default. You may use + ``-no-keep-hi-files`` if you are not interested in the ``.hi`` files. + +.. ghc-flag:: -keep-hscpp-file + -keep-hscpp-files + :shortdesc: Retain intermediate ``.hscpp`` files. + :type: dynamic + :category: keep-intermediates + + .. index:: + single: temporary files; keeping + + Keep the output of the ``CPP`` pre-processor phase as ``.hscpp`` files. + A ``.hscpp`` file is only created, if a module gets compiled and uses the + C pre-processor. .. ghc-flag:: -keep-llvm-file -keep-llvm-files + :shortdesc: Retain intermediate LLVM ``.ll`` files. + Implies :ghc-flag:`-fllvm`. + :type: dynamic + :category: keep-intermediates :implies: :ghc-flag:`-fllvm` @@ -361,19 +425,29 @@ compilation: to use :ghc-flag:`-fllvm` to force them to be produced). .. ghc-flag:: -keep-o-files + :shortdesc: Retain intermediate ``.o`` files (the default). + :type: dynamic + :reverse: -no-keep-o-files + :category: keep-intermediates .. index:: single: temporary files; keeping - Keep intermediate ``.o`` files. This is the default. You may use - ``-no-keep-o-files`` if you are not interested in the ``.o`` files. + Keep intermediate ``.o`` files. This is the default. You may use + ``-no-keep-o-files`` if you are not interested in the ``.o`` files. .. ghc-flag:: -keep-s-file -keep-s-files + :shortdesc: Retain intermediate ``.s`` files. + :type: dynamic + :category: keep-intermediates Keep intermediate ``.s`` files. .. ghc-flag:: -keep-tmp-files + :shortdesc: Retain all intermediate temporary files. + :type: dynamic + :category: keep-intermediates .. index:: single: temporary files; keeping @@ -392,6 +466,9 @@ Redirecting temporary files single: temporary files; redirecting .. ghc-flag:: -tmpdir ⟨dir⟩ + :shortdesc: set the directory for temporary files + :type: dynamic + :category: temp-files If you have trouble because of running out of space in ``/tmp`` (or wherever your installation thinks temporary files should go), you @@ -415,10 +492,16 @@ Other options related to interface files single: interface files, options .. ghc-flag:: -ddump-hi + :shortdesc: Dump the new interface to stdout + :type: dynamic + :category: interface-files Dumps the new interface to standard output. .. ghc-flag:: -ddump-hi-diffs + :shortdesc: Show the differences vs. the old interface + :type: dynamic + :category: interface-files The compiler does not overwrite an existing ``.hi`` interface file if the new one is the same as the old one; this is friendly to @@ -427,6 +510,9 @@ Other options related to interface files differences between the old and new ``.hi`` files. .. ghc-flag:: -ddump-minimal-imports + :shortdesc: Dump a minimal set of imports + :type: dynamic + :category: interface-files Dump to the file :file:`{M}.imports` (where ⟨M⟩ is the name of the module being compiled) a "minimal" set of import declarations. The @@ -441,6 +527,9 @@ Other options related to interface files is intended to reduce the labour. .. ghc-flag:: --show-iface ⟨file⟩ + :shortdesc: See :ref:`modes`. + :type: mode + :category: interface-files where ⟨file⟩ is the name of an interface file, dumps the contents of that interface in a human-readable format. See :ref:`modes`. @@ -454,12 +543,35 @@ The recompilation checker single: recompilation checker .. ghc-flag:: -fforce-recomp + :shortdesc: Turn off recompilation checking. This is implied by any + ``-ddump-X`` option when compiling a single file + (i.e. when using :ghc-flag:`-c`). + :type: dynamic + :reverse: -fno-force-recomp + :category: recompilation Turn off recompilation checking (which is on by default). Recompilation checking normally stops compilation early, leaving an existing ``.o`` file in place, if it can be determined that the module does not need to be recompiled. +.. ghc-flag:: -fignore-optim-changes + :shortdesc: Do not recompile modules just to match changes to + optimisation flags. This is especially useful for avoiding + recompilation when using GHCi, and is enabled by default for + GHCi. + :type: dynamic + :reverse: -fno-ignore-optim-changes + :category: recompilation + +.. ghc-flag:: -fignore-hpc-changes + :shortdesc: Do not recompile modules just to match changes to + HPC flags. This is especially useful for avoiding recompilation + when using GHCi, and is enabled by default for GHCi. + :type: dynamic + :reverse: -fno-ignore-hpc-changes + :category: recompilation + In the olden days, GHC compared the newly-generated ``.hi`` file with the previous version; if they were identical, it left the old one alone and didn't change its modification date. In consequence, importers of a @@ -522,11 +634,15 @@ files, thus: :: g :: TA -> TB g (MkTA x) = MkTB x -``hs-boot`` files importing, ``hi-boot`` files Here ``A`` imports ``B``, -but ``B`` imports ``A`` with a ``{-# SOURCE #-}`` pragma, which breaks -the circular dependency. Every loop in the module import graph must be -broken by a ``{-# SOURCE #-}`` import; or, equivalently, the module -import graph must be acyclic if ``{-# SOURCE #-}`` imports are ignored. +.. index:: + single: ``hs-boot`` files + single: importing, ``hi-boot`` files + +Here ``A`` imports ``B``, but ``B`` imports ``A`` with a +``{-# SOURCE #-}`` pragma, which breaks the circular dependency. Every +loop in the module import graph must be broken by a ``{-# SOURCE #-}`` +import; or, equivalently, the module import graph must be acyclic if +``{-# SOURCE #-}`` imports are ignored. For every module ``A.hs`` that is ``{-# SOURCE #-}``-imported in this way there must exist a source file ``A.hs-boot``. This file contains an @@ -564,7 +680,7 @@ There are several points to note here: - Just as compiling ``A.hs`` produces an interface file ``A.hi``, and an object file ``A.o``, so compiling ``A.hs-boot`` produces an - interface file ``A.hi-boot``, and an pseudo-object file ``A.o-boot``: + interface file ``A.hi-boot``, and a pseudo-object file ``A.o-boot``: - The pseudo-object file ``A.o-boot`` is empty (don't link it!), but it is very useful when using a Makefile, to record when the @@ -687,7 +803,7 @@ be able to pick a particular implementation of strings:: toString s = s module A where - import Text + import Str z = toString empty By replacing ``Str.hs`` with a signature ``Str.hsig``, ``A`` (and @@ -912,7 +1028,18 @@ to ``hs-boot`` files, but with some slight changes: If you do not write out the constructors, you may need to give a kind to tell GHC what the kinds of the type variables are, if they are not the default - ``*``. + ``*``. Unlike regular data type declarations, the return kind of an + abstract data declaration can be anything (in which case it probably + will be implemented using a type synonym.) This can be used + to allow compile-time representation polymorphism (as opposed to + `run-time representation polymorphism <#runtime-rep>`__), + as in this example:: + + signature Number where + import GHC.Types + data Rep :: RuntimeRep + data Number :: TYPE Rep + plus :: Number -> Number -> Number Roles of type parameters are subject to the subtyping relation ``phantom < representational < nominal``: for example, @@ -1168,6 +1295,9 @@ which you may find useful. The options which affect dependency generation are: .. ghc-flag:: -ddump-mod-cycles + :shortdesc: Dump module cycles + :type: dynamic + :category: Display a list of the cycles in the module graph. This is useful when trying to eliminate such cycles. @@ -1180,6 +1310,9 @@ generation are: ``-v3`` and ``-v4``; see :ref:`options-help`.) .. ghc-flag:: -dep-makefile ⟨file⟩ + :shortdesc: Use ⟨file⟩ as the makefile + :type: dynamic + :category: Use ⟨file⟩ as the makefile, rather than ``makefile`` or ``Makefile``. If ⟨file⟩ doesn't exist, ``mkdependHS`` creates it. We @@ -1188,6 +1321,10 @@ generation are: ``Makefile``. .. ghc-flag:: -dep-suffix ⟨suffix⟩ + :shortdesc: Make dependencies that declare that files with suffix + ``.⟨suf⟩⟨osuf⟩`` depend on interface files with suffix ``.⟨suf⟩hi`` + :type: dynamic + :category: Make dependencies that declare that files with suffix ``.⟨suf⟩⟨osuf⟩`` depend on interface files with suffix @@ -1199,11 +1336,18 @@ generation are: then pass ``-dep-suffix ''``. .. ghc-flag:: --exclude-module=⟨file⟩ + :shortdesc: Regard ``⟨file⟩`` as "stable"; i.e., exclude it from having + dependencies on it. + :type: dynamic + :category: Regard ``⟨file⟩`` as "stable"; i.e., exclude it from having dependencies on it. .. ghc-flag:: -include-pkg-deps + :shortdesc: Regard modules imported from packages as unstable + :type: dynamic + :category: Regard modules imported from packages as unstable, i.e., generate dependencies on any imported package modules (including ``Prelude``, |