diff options
Diffstat (limited to 'docs/users_guide/separate_compilation.rst')
| -rw-r--r-- | docs/users_guide/separate_compilation.rst | 117 |
1 files changed, 108 insertions, 9 deletions
diff --git a/docs/users_guide/separate_compilation.rst b/docs/users_guide/separate_compilation.rst index 85c82540e4..29ee7bb1aa 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/ ``:set`` + :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/ ``:set`` + :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,32 @@ 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-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 +412,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 +453,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 +479,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 +497,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 +514,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,6 +530,12 @@ 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 @@ -1172,6 +1254,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. @@ -1184,6 +1269,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 @@ -1192,6 +1280,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 @@ -1203,11 +1295,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``, |