Fix more documentation wibbles
[ghc.git] / docs / users_guide / runghc.rst
1 .. _runghc:
2
3 Using runghc
4 ============
5
6 .. index::
7    single: runghc
8
9 ``runghc`` allows you to run Haskell programs without first having to
10 compile them.
11
12 .. _runghc-introduction:
13
14 Usage
15 -----
16
17 The ``runghc`` command-line looks like:
18
19 .. code-block:: none
20
21     runghc [runghc flags] [GHC flags] module [program args]
22
23 Any flags not recognized by runghc are automatically passed to GHC.
24 If a flag is recognized by both runghc and GHC but you want to
25 pass it to GHC then you can place it after a ``--`` separator. Flags after the
26 separator are treated as GHC only flags. Alternatively you can use the runghc
27 option ``--ghc-arg=<arg>`` to pass any flag or argument directly to GHC.
28
29 ``module`` could be a Haskell source filename with or without the extension.
30 If for some reason the filename starts with a ``-`` you can use a second
31 ``--`` to indicate the end of flags. Anything following a second
32 ``--`` will be considered a program file or module name followed by its
33 arguments. For example:
34
35 - ``runghc -- -- -hello.hs``
36
37 runghc flags
38 ------------
39
40 runghc accepts the following flags:
41
42 - ``-f /path/to/ghc``: tell runghc the path of GHC executable to use to run the program. By default runghc will search for GHC in the directories in the system search path.
43 - ``--ghc-arg=<arg>``: Pass an option or argument to GHC
44 - ``--help``: print usage information.
45 - ``--version``: print version information.
46
47 GHC Flags
48 ---------
49
50 As discussed earlier, use ``--`` or ``--ghc-arg=<arg>`` to disambiguate GHC
51 flags when needed. For example, ``-f`` is recognized by runghc, therefore to
52 pass ``-fliberate-case`` to GHC use any of the following:
53
54 - ``runghc -- -fliberate-case``
55 - ``runghc --ghc-arg=-fliberate-case``
56
57 Note that any non-flag arguments are never passed to GHC. An unused non-flag
58 argument will be considered as the name of the program to run. If a GHC flag
59 takes an argument use ``--ghc-arg=<arg>`` to pass the argument to GHC.
60 For example, if you want to pass ``-package foo`` to GHC use any of the
61 following:
62
63 - ``runghc -package --ghc-arg=foo Main.hs``
64 - ``runghc --ghc-arg=-package --ghc-arg=foo Main.hs``