ghc/docs/users_guide/using.xml

   1 <?xml version="1.0" encoding="iso-8859-1"?>
   2 <chapter id="using-ghc">
   3   <title>Using GHC</title>
   4
   5   <indexterm><primary>GHC, using</primary></indexterm>
   6   <indexterm><primary>using GHC</primary></indexterm>
   7
   8   <sect1>
   9     <title>Options overview</title>
  10
  11     <para>GHC's behaviour is controlled by
  12     <firstterm>options</firstterm>, which for historical reasons are
  13     also sometimes referred to as command-line flags or arguments.
  14     Options can be specified in three ways:</para>
  15
  16     <sect2>
  17       <title>command-line arguments</title>
  18
  19       <indexterm><primary>structure, command-line</primary></indexterm>
  20       <indexterm><primary>command-line</primary><secondary>arguments</secondary></indexterm>
  21       <indexterm><primary>arguments</primary><secondary>command-line</secondary></indexterm>
  22
  23       <para>An invocation of GHC takes the following form:</para>
  24
  25 <screen>
  26 ghc [argument...]
  27 </screen>
  28
  29       <para>command-line arguments are either options or file names.</para>
  30
  31       <para>command-line options begin with <literal>-</literal>.
  32       They may <emphasis>not</emphasis> be grouped:
  33       <option>-vO</option> is different from <option>-v -O</option>.
  34       Options need not precede filenames: e.g., <literal>ghc *.o -o
  35       foo</literal>.  All options are processed and then applied to
  36       all files; you cannot, for example, invoke <literal>ghc -c -O1
  37       Foo.hs -O2 Bar.hs</literal> to apply different optimisation
  38       levels to the files <filename>Foo.hs</filename> and
  39       <filename>Bar.hs</filename>.</para>
  40     </sect2>
  41
  42     <sect2 id="source-file-options">
  43       <title>command line options in source files</title>
  44
  45       <indexterm><primary>source-file options</primary></indexterm>
  46
  47       <para>Sometimes it is useful to make the connection between a
  48       source file and the command-line options it requires quite
  49       tight. For instance, if a Haskell source file uses GHC
  50       extensions, it will always need to be compiled with the
  51       <option>-fglasgow-exts</option> option.  Rather than maintaining
  52       the list of per-file options in a <filename>Makefile</filename>,
  53       it is possible to do this directly in the source file using the
  54       <literal>OPTIONS_GHC</literal> pragma <indexterm><primary>OPTIONS_GHC
  55       pragma</primary></indexterm>:</para>
  56
  57 <programlisting>
  58 {-# OPTIONS_GHC -fglasgow-exts #-}
  59 module X where
  60 ...
  61 </programlisting>
  62
  63       <para><literal>OPTIONS_GHC</literal> pragmas are only looked for at
  64       the top of your source files, upto the first
  65       (non-literate,non-empty) line not containing
  66       <literal>OPTIONS_GHC</literal>. Multiple <literal>OPTIONS_GHC</literal>
  67       pragmas are recognised. Note that your command shell does not
  68       get to the source file options, they are just included literally
  69       in the array of command-line arguments the compiler driver
  70       maintains internally, so you'll be desperately disappointed if
  71       you try to glob etc. inside <literal>OPTIONS_GHC</literal>.</para>
  72
  73       <para>NOTE: the contents of OPTIONS_GHC are prepended to the
  74       command-line options, so you <emphasis>do</emphasis> have the
  75       ability to override OPTIONS_GHC settings via the command
  76       line.</para>
  77
  78       <para>It is not recommended to move all the contents of your
  79       Makefiles into your source files, but in some circumstances, the
  80       <literal>OPTIONS_GHC</literal> pragma is the Right Thing. (If you
  81       use <option>-keep-hc-file-too</option> and have OPTION flags in
  82       your module, the OPTIONS_GHC will get put into the generated .hc
  83       file).</para>
  84     </sect2>
  85
  86     <sect2>
  87       <title>Setting options in GHCi</title>
  88
  89       <para>Options may also be modified from within GHCi, using the
  90       <literal>:set</literal> command.  See <xref linkend="ghci-set"/>
  91       for more details.</para>
  92     </sect2>
  93   </sect1>
  94
  95   <sect1 id="static-dynamic-flags">
  96     <title>Static vs. Dynamic options</title>
  97     <indexterm><primary>static</primary><secondary>options</secondary>
  98     </indexterm>
  99     <indexterm><primary>dynamic</primary><secondary>options</secondary>
 100     </indexterm>
 101
 102     <para>Each of GHC's command line options is classified as either
 103     <firstterm>static</firstterm> or <firstterm>dynamic</firstterm>.
 104     A static flag may only be specified on the command line, whereas a
 105     dynamic flag may also be given in an <literal>OPTIONS_GHC</literal>
 106     pragma in a source file or set from the GHCi command-line with
 107     <literal>:set</literal>.</para>
 108
 109     <para>As a rule of thumb, options which relate to filenames are
 110     static, and the rest are dynamic. The flag reference tables (<xref
 111     linkend="flag-reference"/>) lists the status of each flag.</para>
 112   </sect1>
 113
 114   <sect1 id="file-suffixes">
 115     <title>Meaningful file suffixes</title>
 116
 117     <indexterm><primary>suffixes, file</primary></indexterm>
 118     <indexterm><primary>file suffixes for GHC</primary></indexterm>
 119
 120     <para>File names with &ldquo;meaningful&rdquo; suffixes (e.g.,
 121     <filename>.lhs</filename> or <filename>.o</filename>) cause the
 122     &ldquo;right thing&rdquo; to happen to those files.</para>
 123
 124     <variablelist>
 125
 126       <varlistentry>
 127         <term>
 128           <filename>.lhs</filename>
 129           <indexterm><primary><literal>lhs</literal> suffix</primary></indexterm>
 130         </term>
 131         <listitem>
 132           <para>A &ldquo;literate Haskell&rdquo; module.</para>
 133         </listitem>
 134       </varlistentry>
 135
 136       <varlistentry>
 137         <term><filename>.hs</filename></term>
 138         <listitem>
 139           <para>A not-so-literate Haskell module.</para>
 140         </listitem>
 141       </varlistentry>
 142
 143       <varlistentry>
 144         <term><filename>.hi</filename></term>
 145         <listitem>
 146           <para>A Haskell interface file, probably
 147           compiler-generated.</para>
 148         </listitem>
 149       </varlistentry>
 150
 151       <varlistentry>
 152         <term><filename>.hc</filename></term>
 153         <listitem>
 154           <para>Intermediate C file produced by the Haskell
 155           compiler.</para>
 156         </listitem>
 157       </varlistentry>
 158
 159       <varlistentry>
 160         <term><filename>.c</filename></term>
 161         <listitem>
 162           <para>A C&nbsp;file not produced by the Haskell
 163           compiler.</para>
 164         </listitem>
 165       </varlistentry>
 166
 167       <varlistentry>
 168         <term><filename>.s</filename></term>
 169         <listitem>
 170           <para>An assembly-language source file, usually produced by
 171           the compiler.</para>
 172         </listitem>
 173       </varlistentry>
 174
 175       <varlistentry>
 176         <term><filename>.o</filename></term>
 177         <listitem>
 178           <para>An object file, produced by an assembler.</para>
 179         </listitem>
 180       </varlistentry>
 181     </variablelist>
 182
 183     <para>Files with other suffixes (or without suffixes) are passed
 184     straight to the linker.</para>
 185
 186   </sect1>
 187
 188   <sect1 id="modes">
 189     <title>Modes of operation</title>
 190
 191     <para>GHC's behaviour is firstly controlled by a mode flag.  Only
 192     one of these flags may be given, but it does not necessarily need
 193     to be the first option on the command-line.  The available modes
 194     are:</para>
 195
 196     <variablelist>
 197       <varlistentry>
 198         <term>
 199           <cmdsynopsis><command>ghc</command>
 200             <arg choice='plain'>&ndash;&ndash;interactive</arg>
 201           </cmdsynopsis>
 202           <indexterm><primary>interactive mode</primary></indexterm>
 203           <indexterm><primary>ghci</primary></indexterm>
 204         </term>
 205         <listitem>
 206           <para>Interactive mode, which is also available as
 207           <command>ghci</command>.  Interactive mode is described in
 208           more detail in <xref linkend="ghci"/>.</para>
 209         </listitem>
 210       </varlistentry>
 211
 212       <varlistentry>
 213         <term>
 214           <cmdsynopsis><command>ghc</command>
 215             <arg choice='plain'>&ndash;&ndash;make</arg>
 216           </cmdsynopsis>
 217           <indexterm><primary>make mode</primary></indexterm>
 218           <indexterm><primary><option>&ndash;&ndash;make</option></primary></indexterm>
 219         </term>
 220         <listitem>
 221           <para>In this mode, GHC will build a multi-module Haskell
 222           program automatically, figuring out dependencies for itself.
 223           If you have a straightforward Haskell program, this is
 224           likely to be much easier, and faster, than using
 225           <command>make</command>.  Make mode is described in <xref
 226           linkend="make-mode"/>.</para>
 227         </listitem>
 228       </varlistentry>
 229
 230       <varlistentry>
 231         <term>
 232           <cmdsynopsis><command>ghc</command>
 233             <arg choice='plain'>&ndash;e</arg> <arg choice='plain'><replaceable>expr</replaceable></arg>
 234           </cmdsynopsis>
 235           <indexterm><primary>eval mode</primary></indexterm>
 236         </term>
 237         <listitem>
 238           <para>Expression-evaluation mode.  This is very similar to
 239           interactive mode, except that there is a single expression
 240           to evaluate (<replaceable>expr</replaceable>) which is given
 241           on the command line.  See <xref linkend="eval-mode"/> for
 242           more details.</para>
 243         </listitem>
 244       </varlistentry>
 245
 246       <varlistentry>
 247         <term>
 248           <cmdsynopsis>
 249             <command>ghc</command>
 250             <group>
 251               <arg>-E</arg>
 252               <arg>-C</arg>
 253               <arg>-S</arg>
 254               <arg>-c</arg>
 255             </group>
 256           </cmdsynopsis>
 257           <indexterm><primary><option>-E</option></primary></indexterm>
 258           <indexterm><primary><option>-C</option></primary></indexterm>
 259           <indexterm><primary><option>-S</option></primary></indexterm>
 260           <indexterm><primary><option>-c</option></primary></indexterm>
 261         </term>
 262         <listitem>
 263           <para>This is the traditional batch-compiler mode, in which
 264           GHC can compile source files one at a time, or link objects
 265           together into an executable.  This mode also applies if
 266           there is no other mode flag specified on the command line,
 267           in which case it means that the specified files should be
 268           compiled and then linked to form a program. See <xref
 269           linkend="options-order"/>.</para>
 270         </listitem>
 271       </varlistentry>
 272
 273       <varlistentry>
 274         <term>
 275           <cmdsynopsis>
 276             <command>ghc</command>
 277             <arg choice='plain'>&ndash;M</arg>
 278           </cmdsynopsis>
 279           <indexterm><primary>dependency-generation mode</primary></indexterm>
 280         </term>
 281         <listitem>
 282           <para>Dependency-generation mode.  In this mode, GHC can be
 283           used to generate dependency information suitable for use in
 284           a <literal>Makefile</literal>.  See <xref
 285           linkend="sec-makefile-dependencies"/>.</para>
 286         </listitem>
 287       </varlistentry>
 288
 289       <varlistentry>
 290         <term>
 291           <cmdsynopsis>
 292             <command>ghc</command>
 293             <arg choice='plain'>&ndash;&ndash;mk-dll</arg>
 294           </cmdsynopsis>
 295           <indexterm><primary>dependency-generation mode</primary></indexterm>
 296         </term>
 297         <listitem>
 298           <para>DLL-creation mode (Windows only).  See <xref
 299           linkend="win32-dlls-create"/>.</para>
 300         </listitem>
 301       </varlistentry>
 302     </variablelist>
 303
 304     <sect2 id="make-mode">
 305       <title>Using <command>ghc</command> <option>&ndash;&ndash;make</option></title>
 306       <indexterm><primary><option>&ndash;&ndash;make</option></primary></indexterm>
 307       <indexterm><primary>separate compilation</primary></indexterm>
 308
 309       <para>When given the <option>&ndash;&ndash;make</option> option,
 310       GHC will build a multi-module Haskell program by following
 311       dependencies from a single root module (usually
 312       <literal>Main</literal>).  For example, if your
 313       <literal>Main</literal> module is in a file called
 314       <filename>Main.hs</filename>, you could compile and link the
 315       program like this:</para>
 316
 317 <screen>
 318 ghc &ndash;&ndash;make Main.hs
 319 </screen>
 320
 321       <para>The command line may contain any number of source file
 322       names or module names; GHC will figure out all the modules in
 323       the program by following the imports from these initial modules.
 324       It will then attempt to compile each module which is out of
 325       date, and finally if there is a <literal>Main</literal> module,
 326       the program will also be linked into an executable.</para>
 327
 328       <para>The main advantages to using <literal>ghc
 329       &ndash;&ndash;make</literal> over traditional
 330       <literal>Makefile</literal>s are:</para>
 331
 332       <itemizedlist>
 333         <listitem>
 334           <para>GHC doesn't have to be restarted for each compilation,
 335           which means it can cache information between compilations.
 336           Compiling a multi-module program with <literal>ghc
 337           &ndash;&ndash;make</literal> can be up to twice as fast as
 338           running <literal>ghc</literal> individually on each source
 339           file.</para>
 340         </listitem>
 341         <listitem>
 342           <para>You don't have to write a<literal>Makefile</literal>.</para>
 343           <indexterm><primary><literal>Makefile</literal>s</primary><secondary>avoiding</secondary></indexterm>
 344         </listitem>
 345         <listitem>
 346           <para>GHC re-calculates the dependencies each time it is
 347           invoked, so the dependencies never get out of sync with the
 348           source.</para>
 349         </listitem>
 350       </itemizedlist>
 351
 352       <para>Any of the command-line options described in the rest of
 353       this chapter can be used with
 354       <option>&ndash;&ndash;make</option>, but note that any options
 355       you give on the command line will apply to all the source files
 356       compiled, so if you want any options to apply to a single source
 357       file only, you'll need to use an <literal>OPTIONS_GHC</literal>
 358       pragma (see <xref linkend="source-file-options"/>).</para>
 359
 360       <para>If the program needs to be linked with additional objects
 361       (say, some auxiliary C code), then the object files can be
 362       given on the command line and GHC will include them when linking
 363       the executable.</para>
 364
 365       <para>Note that GHC can only follow dependencies if it has the
 366       source file available, so if your program includes a module for
 367       which there is no source file, even if you have an object and an
 368       interface file for the module, then GHC will complain.  The
 369       exception to this rule is for package modules, which may or may
 370       not have source files.</para>
 371
 372       <para>The source files for the program don't all need to be in
 373       the same directory; the <option>-i</option> option can be used
 374       to add directories to the search path (see <xref
 375       linkend="search-path"/>).</para>
 376     </sect2>
 377
 378     <sect2 id="eval-mode">
 379       <title>Expression evaluation mode</title>
 380
 381       <para>This mode is very similar to interactive mode, except that
 382       there is a single expression to evaluate which is specified on
 383       the command line as an argument to the <option>-e</option>
 384       option:</para>
 385
 386 <screen>
 387 ghc -e <replaceable>expr</replaceable>
 388 </screen>
 389
 390       <para>Haskell source files may be named on the command line, and
 391       they will be loaded exactly as in interactive mode.  The
 392       expression is evaluated in the context of the loaded
 393       modules.</para>
 394
 395       <para>For example, to load and run a Haskell program containing
 396       a module <literal>Main</literal>, we might say</para>
 397
 398 <screen>
 399 ghc -e Main.main Main.hs
 400 </screen>
 401
 402       <para>or we can just use this mode to evaluate expressions in
 403       the context of the <literal>Prelude</literal>:</para>
 404
 405 <screen>
 406 $ ghc -e "interact (unlines.map reverse.lines)"
 407 hello
 408 olleh
 409 </screen>
 410     </sect2>
 411
 412     <sect2 id="options-order">
 413       <title>Batch compiler mode</title>
 414
 415       <para>In <emphasis>batch mode</emphasis>, GHC will compile one or more source files
 416       given on the command line.</para>
 417
 418       <para>The first phase to run is determined by each input-file
 419       suffix, and the last phase is determined by a flag.  If no
 420       relevant flag is present, then go all the way through linking.
 421       This table summarises:</para>
 422
 423       <informaltable>
 424         <tgroup cols="4">
 425           <colspec align="left"/>
 426           <colspec align="left"/>
 427           <colspec align="left"/>
 428           <colspec align="left"/>
 429
 430           <thead>
 431             <row>
 432               <entry>Phase of the compilation system</entry>
 433               <entry>Suffix saying &ldquo;start here&rdquo;</entry>
 434               <entry>Flag saying &ldquo;stop after&rdquo;</entry>
 435               <entry>(suffix of) output file</entry>
 436             </row>
 437           </thead>
 438           <tbody>
 439             <row>
 440               <entry>literate pre-processor</entry>
 441               <entry><literal>.lhs</literal></entry>
 442               <entry>-</entry>
 443               <entry><literal>.hs</literal></entry>
 444             </row>
 445
 446             <row>
 447               <entry>C pre-processor (opt.) </entry>
 448               <entry><literal>.hs</literal> (with
 449               <option>-cpp</option>)</entry>
 450               <entry><option>-E</option></entry>
 451               <entry><literal>.hspp</literal></entry>
 452             </row>
 453
 454             <row>
 455               <entry>Haskell compiler</entry>
 456               <entry><literal>.hs</literal></entry>
 457               <entry><option>-C</option>, <option>-S</option></entry>
 458               <entry><literal>.hc</literal>, <literal>.s</literal></entry>
 459             </row>
 460
 461             <row>
 462               <entry>C compiler (opt.)</entry>
 463               <entry><literal>.hc</literal> or <literal>.c</literal></entry>
 464               <entry><option>-S</option></entry>
 465               <entry><literal>.s</literal></entry>
 466             </row>
 467
 468             <row>
 469               <entry>assembler</entry>
 470               <entry><literal>.s</literal></entry>
 471               <entry><option>-c</option></entry>
 472               <entry><literal>.o</literal></entry>
 473             </row>
 474
 475             <row>
 476               <entry>linker</entry>
 477               <entry><replaceable>other</replaceable></entry>
 478               <entry>-</entry>
 479               <entry><filename>a.out</filename></entry>
 480             </row>
 481           </tbody>
 482         </tgroup>
 483       </informaltable>
 484
 485       <indexterm><primary><option>-C</option></primary></indexterm>
 486       <indexterm><primary><option>-E</option></primary></indexterm>
 487       <indexterm><primary><option>-S</option></primary></indexterm>
 488       <indexterm><primary><option>-c</option></primary></indexterm>
 489
 490       <para>Thus, a common invocation would be: </para>
 491
 492 <screen>
 493 ghc -c Foo.hs</screen>
 494
 495       <para>to compile the Haskell source file
 496       <filename>Foo.hs</filename> to an object file
 497       <filename>Foo.o</filename>.</para>
 498
 499       <para>Note: What the Haskell compiler proper produces depends on
 500       whether a native-code generator<indexterm><primary>native-code
 501       generator</primary></indexterm> is used (producing assembly
 502       language) or not (producing C).  See <xref
 503       linkend="options-codegen"/> for more details.</para>
 504
 505       <para>Note: C pre-processing is optional, the
 506       <option>-cpp</option><indexterm><primary><option>-cpp</option></primary></indexterm>
 507       flag turns it on.  See <xref linkend="c-pre-processor"/> for more
 508       details.</para>
 509
 510       <para>Note: The option <option>-E</option><indexterm><primary>-E
 511       option</primary></indexterm> runs just the pre-processing passes
 512       of the compiler, dumping the result in a file.  Note that this
 513       differs from the previous behaviour of dumping the file to
 514       standard output.</para>
 515     </sect2>
 516   </sect1>
 517
 518   <sect1 id="options-help">
 519     <title>Help and verbosity options</title>
 520
 521     <indexterm><primary>help options</primary></indexterm>
 522     <indexterm><primary>verbosity options</primary></indexterm>
 523
 524     <variablelist>
 525       <varlistentry>
 526         <term>
 527           <option>&ndash;&ndash;help</option>
 528           <indexterm><primary><option>&ndash;&ndash;help</option></primary></indexterm>
 529         </term>
 530         <term>
 531           <option>-?</option>
 532           <indexterm><primary><option>-?</option></primary></indexterm>
 533         </term>
 534         <listitem>
 535           <para>Cause GHC to spew a long usage message to standard
 536           output and then exit.</para>
 537         </listitem>
 538       </varlistentry>
 539
 540       <varlistentry>
 541         <term>
 542           <option>-v</option>
 543           <indexterm><primary><option>-v</option></primary></indexterm>
 544         </term>
 545         <listitem>
 546           <para>The <option>-v</option> option makes GHC
 547           <emphasis>verbose</emphasis>: it reports its version number
 548           and shows (on stderr) exactly how it invokes each phase of
 549           the compilation system.  Moreover, it passes the
 550           <option>-v</option> flag to most phases; each reports its
 551           version number (and possibly some other information).</para>
 552
 553           <para>Please, oh please, use the <option>-v</option> option
 554           when reporting bugs!  Knowing that you ran the right bits in
 555           the right order is always the first thing we want to
 556           verify.</para>
 557         </listitem>
 558       </varlistentry>
 559
 560       <varlistentry>
 561         <term>
 562           <option>-v</option><replaceable>n</replaceable>
 563           <indexterm><primary><option>-v</option></primary></indexterm>
 564         </term>
 565         <listitem>
 566           <para>To provide more control over the compiler's verbosity,
 567           the <option>-v</option> flag takes an optional numeric
 568           argument.  Specifying <option>-v</option> on its own is
 569           equivalent to <option>-v3</option>, and the other levels
 570           have the following meanings:</para>
 571
 572           <variablelist>
 573             <varlistentry>
 574               <term><option>-v0</option></term>
 575               <listitem>
 576                 <para>Disable all non-essential messages (this is the
 577                 default).</para>
 578               </listitem>
 579             </varlistentry>
 580
 581             <varlistentry>
 582               <term><option>-v1</option></term>
 583               <listitem>
 584                 <para>Minimal verbosity: print one line per
 585                 compilation (this is the default when
 586                 <option>&ndash;&ndash;make</option> or
 587                 <option>&ndash;&ndash;interactive</option> is on).</para>
 588               </listitem>
 589             </varlistentry>
 590
 591             <varlistentry>
 592               <term><option>-v2</option></term>
 593               <listitem>
 594                 <para>Print the name of each compilation phase as it
 595                 is executed. (equivalent to
 596                 <option>-dshow-passes</option>).</para>
 597               </listitem>
 598             </varlistentry>
 599
 600             <varlistentry>
 601               <term><option>-v3</option></term>
 602               <listitem>
 603                 <para>The same as <option>-v2</option>, except that in
 604                 addition the full command line (if appropriate) for
 605                 each compilation phase is also printed.</para>
 606               </listitem>
 607             </varlistentry>
 608
 609             <varlistentry>
 610               <term><option>-v4</option></term>
 611               <listitem>
 612                 <para>The same as <option>-v3</option> except that the
 613                 intermediate program representation after each
 614                 compilation phase is also printed (excluding
 615                 preprocessed and C/assembly files).</para>
 616               </listitem>
 617             </varlistentry>
 618           </variablelist>
 619         </listitem>
 620       </varlistentry>
 621
 622       <varlistentry>
 623         <term>
 624           <option>-V</option>
 625           <indexterm><primary><option>-V</option></primary></indexterm>
 626         </term>
 627         <term>
 628           <option>&ndash;&ndash;version</option>
 629           <indexterm><primary><option>&ndash;&ndash;version</option></primary></indexterm>
 630         </term>
 631         <listitem>
 632           <para>Print a one-line string including GHC's version number.</para>
 633         </listitem>
 634       </varlistentry>
 635
 636       <varlistentry>
 637         <term>
 638           <option>&ndash;&ndash;numeric-version</option>
 639           <indexterm><primary><option>&ndash;&ndash;numeric-version</option></primary></indexterm>
 640         </term>
 641         <listitem>
 642           <para>Print GHC's numeric version number only.</para>
 643         </listitem>
 644       </varlistentry>
 645
 646       <varlistentry>
 647         <term>
 648           <option>&ndash;&ndash;print-libdir</option>
 649           <indexterm><primary><option>&ndash;&ndash;print-libdir</option></primary></indexterm>
 650         </term>
 651         <listitem>
 652           <para>Print the path to GHC's library directory.  This is
 653           the top of the directory tree containing GHC's libraries,
 654           interfaces, and include files (usually something like
 655           <literal>/usr/local/lib/ghc-5.04</literal> on Unix).  This
 656           is the value of
 657           <literal>$libdir</literal><indexterm><primary><literal>libdir</literal></primary>
 658           </indexterm>in the package configuration file (see <xref
 659           linkend="packages"/>).</para>
 660         </listitem>
 661       </varlistentry>
 662
 663       <varlistentry>
 664         <term><option>-ferror-spans</option>
 665           <indexterm><primary><option>-ferror-spans</option></primary>
 666           </indexterm>
 667         </term>
 668         <listitem>
 669           <para>Causes GHC to emit the full source span of the
 670           syntactic entity relating to an error message.  Normally, GHC
 671           emits the source location of the start of the syntactic
 672           entity only.</para>
 673
 674           <para>For example:</para>
 675
 676 <screen>test.hs:3:6: parse error on input `where'</screen>
 677
 678           <para>becomes:</para>
 679
 680 <screen>test296.hs:3:6-10: parse error on input `where'</screen>
 681
 682           <para>And multi-line spans are possible too:</para>
 683
 684 <screen>test.hs:(5,4)-(6,7):
 685     Conflicting definitions for `a'
 686     Bound at: test.hs:5:4
 687               test.hs:6:7
 688     In the binding group for: a, b, a</screen>
 689
 690           <para>Note that line numbers start counting at one, but
 691           column numbers start at zero.  This choice was made to
 692           follow existing convention (i.e. this is how Emacs does
 693           it).</para>
 694         </listitem>
 695       </varlistentry>
 696     </variablelist>
 697   </sect1>
 698
 699   &separate;
 700
 701   <sect1 id="options-sanity">
 702     <title>Warnings and sanity-checking</title>
 703
 704     <indexterm><primary>sanity-checking options</primary></indexterm>
 705     <indexterm><primary>warnings</primary></indexterm>
 706
 707
 708     <para>GHC has a number of options that select which types of
 709     non-fatal error messages, otherwise known as warnings, can be
 710     generated during compilation.  By default, you get a standard set
 711     of warnings which are generally likely to indicate bugs in your
 712     program.  These are:
 713     <option>-fwarn-overlapping-patterns</option>,
 714     <option>-fwarn-deprecations</option>,
 715     <option>-fwarn-duplicate-exports</option>,
 716     <option>-fwarn-missing-fields</option>, and
 717     <option>-fwarn-missing-methods</option>.  The following flags are
 718     simple ways to select standard &ldquo;packages&rdquo; of warnings:
 719     </para>
 720
 721     <variablelist>
 722
 723       <varlistentry>
 724         <term><option>-W</option>:</term>
 725         <listitem>
 726           <indexterm><primary>-W option</primary></indexterm>
 727           <para>Provides the standard warnings plus
 728           <option>-fwarn-incomplete-patterns</option>,
 729           <option>-fwarn-unused-matches</option>,
 730           <option>-fwarn-unused-imports</option>,
 731           <option>-fwarn-misc</option>, and
 732           <option>-fwarn-unused-binds</option>.</para>
 733         </listitem>
 734       </varlistentry>
 735
 736       <varlistentry>
 737         <term><option>-w</option>:</term>
 738         <listitem>
 739           <indexterm><primary><option>-w</option></primary></indexterm>
 740           <para>Turns off all warnings, including the standard ones.</para>
 741         </listitem>
 742       </varlistentry>
 743
 744       <varlistentry>
 745         <term><option>-Wall</option>:</term>
 746         <listitem>
 747           <indexterm><primary><option>-Wall</option></primary></indexterm>
 748           <para>Turns on all warning options.</para>
 749         </listitem>
 750       </varlistentry>
 751
 752       <varlistentry>
 753         <term><option>-Werror</option>:</term>
 754         <listitem>
 755           <indexterm><primary><option>-Werror</option></primary></indexterm>
 756           <para>Makes any warning into a fatal error. Useful so that you don't
 757             miss warnings when doing batch compilation. </para>
 758         </listitem>
 759       </varlistentry>
 760
 761     </variablelist>
 762
 763     <para>The full set of warning options is described below.  To turn
 764     off any warning, simply give the corresponding
 765     <option>-fno-warn-...</option> option on the command line.</para>
 766
 767     <variablelist>
 768
 769       <varlistentry>
 770         <term><option>-fwarn-deprecations</option>:</term>
 771         <listitem>
 772           <indexterm><primary><option>-fwarn-deprecations</option></primary>
 773           </indexterm>
 774           <indexterm><primary>deprecations</primary></indexterm>
 775           <para>Causes a warning to be emitted when a deprecated
 776           function or type is used.  Entities can be marked as
 777           deprecated using a pragma, see <xref
 778           linkend="deprecated-pragma"/>.</para>
 779         </listitem>
 780       </varlistentry>
 781
 782       <varlistentry>
 783         <term><option>-fwarn-duplicate-exports</option>:</term>
 784         <listitem>
 785           <indexterm><primary><option>-fwarn-duplicate-exports</option></primary></indexterm>
 786           <indexterm><primary>duplicate exports, warning</primary></indexterm>
 787           <indexterm><primary>export lists, duplicates</primary></indexterm>
 788
 789           <para>Have the compiler warn about duplicate entries in
 790           export lists. This is useful information if you maintain
 791           large export lists, and want to avoid the continued export
 792           of a definition after you've deleted (one) mention of it in
 793           the export list.</para>
 794
 795           <para>This option is on by default.</para>
 796         </listitem>
 797       </varlistentry>
 798
 799       <varlistentry>
 800         <term><option>-fwarn-hi-shadowing</option>:</term>
 801         <listitem>
 802           <indexterm><primary><option>-fwarn-hi-shadowing</option></primary></indexterm>
 803           <indexterm><primary>shadowing</primary>
 804             <secondary>interface files</secondary></indexterm>
 805
 806           <para>Causes the compiler to emit a warning when a module or
 807           interface file in the current directory is shadowing one
 808           with the same module name in a library or other
 809           directory.</para>
 810         </listitem>
 811       </varlistentry>
 812
 813       <varlistentry>
 814         <term><option>-fwarn-incomplete-patterns</option>:</term>
 815         <listitem>
 816           <indexterm><primary><option>-fwarn-incomplete-patterns</option></primary></indexterm>
 817           <indexterm><primary>incomplete patterns, warning</primary></indexterm>
 818           <indexterm><primary>patterns, incomplete</primary></indexterm>
 819
 820           <para>Similarly for incomplete patterns, the function
 821           <function>g</function> below will fail when applied to
 822           non-empty lists, so the compiler will emit a warning about
 823           this when <option>-fwarn-incomplete-patterns</option> is
 824           enabled.</para>
 825
 826 <programlisting>
 827 g [] = 2
 828 </programlisting>
 829
 830           <para>This option isn't enabled be default because it can be
 831           a bit noisy, and it doesn't always indicate a bug in the
 832           program.  However, it's generally considered good practice
 833           to cover all the cases in your functions.</para>
 834         </listitem>
 835       </varlistentry>
 836
 837       <varlistentry>
 838         <term><option>-fwarn-incomplete-record-updates</option>:</term>
 839         <listitem>
 840           <indexterm><primary><option>-fwarn-incomplete-record-updates</option></primary></indexterm>
 841           <indexterm><primary>incomplete record updates, warning</primary></indexterm>
 842           <indexterm><primary>record updates, incomplete</primary></indexterm>
 843
 844           <para>The function
 845           <function>f</function> below will fail when applied to
 846           <literal>Bar</literal>, so the compiler will emit a warning about
 847           this when <option>-fwarn-incomplete-record-updates</option> is
 848           enabled.</para>
 849
 850 <programlisting>
 851 data Foo = Foo { x :: Int }
 852          | Bar
 853
 854 f :: Foo -> Foo
 855 f foo = foo { x = 6 }
 856 </programlisting>
 857
 858           <para>This option isn't enabled be default because it can be
 859           very noisy, and it often doesn't indicate a bug in the
 860           program.</para>
 861         </listitem>
 862       </varlistentry>
 863
 864       <varlistentry>
 865         <term>
 866           <option>-fwarn-misc</option>:
 867           <indexterm><primary><option>-fwarn-misc</option></primary></indexterm>
 868         </term>
 869         <listitem>
 870           <para>Turns on warnings for various harmless but untidy
 871           things.  This currently includes: importing a type with
 872           <literal>(..)</literal> when the export is abstract, and
 873           listing duplicate class assertions in a qualified type.</para>
 874         </listitem>
 875       </varlistentry>
 876
 877       <varlistentry>
 878         <term>
 879           <option>-fwarn-missing-fields</option>:
 880           <indexterm><primary><option>-fwarn-missing-fields</option></primary></indexterm>
 881           <indexterm><primary>missing fields, warning</primary></indexterm>
 882           <indexterm><primary>fields, missing</primary></indexterm>
 883         </term>
 884         <listitem>
 885
 886           <para>This option is on by default, and warns you whenever
 887           the construction of a labelled field constructor isn't
 888           complete, missing initializers for one or more fields. While
 889           not an error (the missing fields are initialised with
 890           bottoms), it is often an indication of a programmer error.</para>
 891         </listitem>
 892       </varlistentry>
 893
 894       <varlistentry>
 895         <term><option>-fwarn-missing-methods</option>:</term>
 896         <listitem>
 897           <indexterm><primary><option>-fwarn-missing-methods</option></primary></indexterm>
 898           <indexterm><primary>missing methods, warning</primary></indexterm>
 899           <indexterm><primary>methods, missing</primary></indexterm>
 900
 901           <para>This option is on by default, and warns you whenever
 902           an instance declaration is missing one or more methods, and
 903           the corresponding class declaration has no default
 904           declaration for them.</para>
 905           <para>The warning is suppressed if the method name
 906           begins with an underscore.  Here's an example where this is useful:
 907             <programlisting>
 908               class C a where
 909                 _simpleFn :: a -> String
 910                 complexFn :: a -> a -> String
 911                 complexFn x y = ... _simpleFn ...
 912               </programlisting>
 913             The idea is that: (a) users of the class will only call <literal>complexFn</literal>;
 914             never <literal>_simpleFn</literal>; and (b)
 915             instance declarations can define either <literal>complexFn</literal> or <literal>_simpleFn</literal>.
 916             </para>
 917         </listitem>
 918       </varlistentry>
 919
 920       <varlistentry>
 921         <term><option>-fwarn-missing-signatures</option>:</term>
 922         <listitem>
 923           <indexterm><primary><option>-fwarn-missing-signatures</option></primary></indexterm>
 924           <indexterm><primary>type signatures, missing</primary></indexterm>
 925
 926           <para>If you would like GHC to check that every top-level
 927           function/value has a type signature, use the
 928           <option>-fwarn-missing-signatures</option> option.  This
 929           option is off by default.</para>
 930         </listitem>
 931       </varlistentry>
 932
 933       <varlistentry>
 934         <term><option>-fwarn-name-shadowing</option>:</term>
 935         <listitem>
 936           <indexterm><primary><option>-fwarn-name-shadowing</option></primary></indexterm>
 937           <indexterm><primary>shadowing, warning</primary></indexterm>
 938
 939           <para>This option causes a warning to be emitted whenever an
 940           inner-scope value has the same name as an outer-scope value,
 941           i.e. the inner value shadows the outer one.  This can catch
 942           typographical errors that turn into hard-to-find bugs, e.g.,
 943           in the inadvertent cyclic definition <literal>let x = ... x
 944           ... in</literal>.</para>
 945
 946           <para>Consequently, this option does
 947           <emphasis>will</emphasis> complain about cyclic recursive
 948           definitions.</para>
 949         </listitem>
 950       </varlistentry>
 951
 952       <varlistentry>
 953         <term><option>-fwarn-orphans</option>:</term>
 954         <listitem>
 955           <indexterm><primary><option>-fwarn-orphans</option></primary></indexterm>
 956           <indexterm><primary>orphan instances, warning</primary></indexterm>
 957           <indexterm><primary>orphan rules, warning</primary></indexterm>
 958
 959           <para>This option causes a warning to be emitted whenever the
 960             module contains an "orphan" instance declaration or rewrite rule.
 961             An instance declartion is an orphan if it appears in a module in
 962             which neither the class nor the type being instanced are declared
 963             in the same module.  A rule is an orphan if it is a rule for a
 964             function declared in another module.  A module containing any
 965           orphans is called an orphan module.</para>
 966           <para>The trouble with orphans is that GHC must pro-actively read the interface
 967             files for all orphan modules, just in case their instances or rules
 968             play a role, whether or not the module's interface would otherwise
 969             be of any use.  Other things being equal, avoid orphan modules.</para>
 970         </listitem>
 971       </varlistentry>
 972
 973       <varlistentry>
 974         <term>
 975           <option>-fwarn-overlapping-patterns</option>:
 976           <indexterm><primary><option>-fwarn-overlapping-patterns</option></primary></indexterm>
 977           <indexterm><primary>overlapping patterns, warning</primary></indexterm>
 978           <indexterm><primary>patterns, overlapping</primary></indexterm>
 979         </term>
 980         <listitem>
 981           <para>By default, the compiler will warn you if a set of
 982           patterns are overlapping, i.e.,</para>
 983
 984 <programlisting>
 985 f :: String -&#62; Int
 986 f []     = 0
 987 f (_:xs) = 1
 988 f "2"    = 2
 989 </programlisting>
 990
 991           <para>where the last pattern match in <function>f</function>
 992           won't ever be reached, as the second pattern overlaps
 993           it. More often than not, redundant patterns is a programmer
 994           mistake/error, so this option is enabled by default.</para>
 995         </listitem>
 996       </varlistentry>
 997
 998       <varlistentry>
 999         <term><option>-fwarn-simple-patterns</option>:</term>
1000         <listitem>
1001           <indexterm><primary><option>-fwarn-simple-patterns</option></primary>
1002           </indexterm>
1003           <para>Causes the compiler to warn about lambda-bound
1004           patterns that can fail, eg. <literal>\(x:xs)->...</literal>.
1005           Normally, these aren't treated as incomplete patterns by
1006           <option>-fwarn-incomplete-patterns</option>.</para>
1007           <para>``Lambda-bound patterns'' includes all places where there is a single pattern,
1008             including list comprehensions and do-notation.  In these cases, a pattern-match
1009             failure is quite legitimate, and triggers filtering (list comprehensions) or
1010             the monad <literal>fail</literal> operation (monads). For example:
1011             <programlisting>
1012               f :: [Maybe a] -> [a]
1013               f xs = [y | Just y &lt;- xs]
1014               </programlisting>
1015             Switching on <option>-fwarn-simple-patterns</option> will elicit warnings about
1016             these probably-innocent cases, which is why the flag is off by default. </para>
1017           <para> The <literal>deriving( Read )</literal> mechanism produces monadic code with
1018             pattern matches, so you will also get misleading warnings about the compiler-generated
1019             code.  (This is arguably a Bad Thing, but it's awkward to fix.)</para>
1020
1021         </listitem>
1022       </varlistentry>
1023
1024       <varlistentry>
1025         <term><option>-fwarn-type-defaults</option>:</term>
1026         <listitem>
1027           <indexterm><primary><option>-fwarn-type-defaults</option></primary></indexterm>
1028           <indexterm><primary>defaulting mechanism, warning</primary></indexterm>
1029           <para>Have the compiler warn/inform you where in your source
1030           the Haskell defaulting mechanism for numeric types kicks
1031           in. This is useful information when converting code from a
1032           context that assumed one default into one with another,
1033           e.g., the `default default' for Haskell 1.4 caused the
1034           otherwise unconstrained value <constant>1</constant> to be
1035           given the type <literal>Int</literal>, whereas Haskell 98
1036           defaults it to <literal>Integer</literal>.  This may lead to
1037           differences in performance and behaviour, hence the
1038           usefulness of being non-silent about this.</para>
1039
1040           <para>This warning is off by default.</para>
1041         </listitem>
1042       </varlistentry>
1043
1044       <varlistentry>
1045         <term><option>-fwarn-unused-binds</option>:</term>
1046         <listitem>
1047           <indexterm><primary><option>-fwarn-unused-binds</option></primary></indexterm>
1048           <indexterm><primary>unused binds, warning</primary></indexterm>
1049           <indexterm><primary>binds, unused</primary></indexterm>
1050           <para>Report any function definitions (and local bindings)
1051           which are unused.  For top-level functions, the warning is
1052           only given if the binding is not exported.</para>
1053           <para>A definition is regarded as "used" if (a) it is exported, or (b) it is
1054             mentioned in the right hand side of another definition that is used, or (c) the
1055             function it defines begins with an underscore.  The last case provides a
1056             way to suppress unused-binding warnings selectively.  </para>
1057           <para> Notice that a variable
1058             is reported as unused even if it appears in the right-hand side of another
1059             unused binding. </para>
1060         </listitem>
1061       </varlistentry>
1062
1063       <varlistentry>
1064         <term><option>-fwarn-unused-imports</option>:</term>
1065         <listitem>
1066           <indexterm><primary><option>-fwarn-unused-imports</option></primary></indexterm>
1067           <indexterm><primary>unused imports, warning</primary></indexterm>
1068           <indexterm><primary>imports, unused</primary></indexterm>
1069
1070           <para>Report any modules that are explicitly imported but
1071           never used.  However, the form <literal>import M()</literal> is
1072           never reported as an unused import, because it is a useful idiom
1073           for importing instance declarations, which are anonymous in Haskell.</para>
1074         </listitem>
1075       </varlistentry>
1076
1077       <varlistentry>
1078         <term><option>-fwarn-unused-matches</option>:</term>
1079         <listitem>
1080           <indexterm><primary><option>-fwarn-unused-matches</option></primary></indexterm>
1081           <indexterm><primary>unused matches, warning</primary></indexterm>
1082           <indexterm><primary>matches, unused</primary></indexterm>
1083
1084           <para>Report all unused variables which arise from pattern
1085           matches, including patterns consisting of a single variable.
1086           For instance <literal>f x y = []</literal> would report
1087           <varname>x</varname> and <varname>y</varname> as unused.  The
1088           warning is suppressed if the variable name begins with an underscore, thus:
1089             <programlisting>
1090                f _x = True
1091             </programlisting>
1092           </para>
1093         </listitem>
1094       </varlistentry>
1095
1096     </variablelist>
1097
1098     <para>If you're feeling really paranoid, the
1099     <option>-dcore-lint</option>
1100     option<indexterm><primary><option>-dcore-lint</option></primary></indexterm>
1101     is a good choice.  It turns on heavyweight intra-pass
1102     sanity-checking within GHC.  (It checks GHC's sanity, not
1103     yours.)</para>
1104
1105   </sect1>
1106
1107   &packages;
1108
1109   <sect1 id="options-optimise">
1110     <title>Optimisation (code improvement)</title>
1111
1112     <indexterm><primary>optimisation</primary></indexterm>
1113     <indexterm><primary>improvement, code</primary></indexterm>
1114
1115     <para>The <option>-O*</option> options specify convenient
1116     &ldquo;packages&rdquo; of optimisation flags; the
1117     <option>-f*</option> options described later on specify
1118     <emphasis>individual</emphasis> optimisations to be turned on/off;
1119     the <option>-m*</option> options specify
1120     <emphasis>machine-specific</emphasis> optimisations to be turned
1121     on/off.</para>
1122
1123     <sect2 id="optimise-pkgs">
1124       <title><option>-O*</option>: convenient &ldquo;packages&rdquo; of optimisation flags.</title>
1125
1126       <para>There are <emphasis>many</emphasis> options that affect
1127       the quality of code produced by GHC.  Most people only have a
1128       general goal, something like &ldquo;Compile quickly&rdquo; or
1129       &ldquo;Make my program run like greased lightning.&rdquo; The
1130       following &ldquo;packages&rdquo; of optimisations (or lack
1131       thereof) should suffice.</para>
1132
1133       <para>Note that higher optimisation levels cause more
1134       cross-module optimisation to be performed, which can have an
1135       impact on how much of your program needs to be recompiled when
1136       you change something.  This is one reaosn to stick to
1137       no-optimisation when developing code.</para>
1138
1139       <variablelist>
1140
1141         <varlistentry>
1142           <term>
1143             No <option>-O*</option>-type option specified:
1144             <indexterm><primary>-O* not specified</primary></indexterm>
1145           </term>
1146           <listitem>
1147             <para>This is taken to mean: &ldquo;Please compile
1148             quickly; I'm not over-bothered about compiled-code
1149             quality.&rdquo; So, for example: <command>ghc -c
1150             Foo.hs</command></para>
1151           </listitem>
1152         </varlistentry>
1153
1154         <varlistentry>
1155           <term>
1156             <option>-O0</option>:
1157             <indexterm><primary><option>-O0</option></primary></indexterm>
1158           </term>
1159           <listitem>
1160             <para>Means &ldquo;turn off all optimisation&rdquo;,
1161             reverting to the same settings as if no
1162             <option>-O</option> options had been specified.  Saying
1163             <option>-O0</option> can be useful if
1164             eg. <command>make</command> has inserted a
1165             <option>-O</option> on the command line already.</para>
1166           </listitem>
1167         </varlistentry>
1168
1169         <varlistentry>
1170           <term>
1171             <option>-O</option> or <option>-O1</option>:
1172             <indexterm><primary>-O option</primary></indexterm>
1173             <indexterm><primary>-O1 option</primary></indexterm>
1174             <indexterm><primary>optimise</primary><secondary>normally</secondary></indexterm>
1175           </term>
1176           <listitem>
1177             <para>Means: &ldquo;Generate good-quality code without
1178             taking too long about it.&rdquo; Thus, for example:
1179             <command>ghc -c -O Main.lhs</command></para>
1180
1181             <para><option>-O</option> currently also implies
1182             <option>-fvia-C</option>.  This may change in the
1183             future.</para>
1184           </listitem>
1185         </varlistentry>
1186
1187         <varlistentry>
1188           <term>
1189             <option>-O2</option>:
1190             <indexterm><primary>-O2 option</primary></indexterm>
1191             <indexterm><primary>optimise</primary><secondary>aggressively</secondary></indexterm>
1192           </term>
1193           <listitem>
1194             <para>Means: &ldquo;Apply every non-dangerous
1195             optimisation, even if it means significantly longer
1196             compile times.&rdquo;</para>
1197
1198             <para>The avoided &ldquo;dangerous&rdquo; optimisations
1199             are those that can make runtime or space
1200             <emphasis>worse</emphasis> if you're unlucky.  They are
1201             normally turned on or off individually.</para>
1202
1203             <para>At the moment, <option>-O2</option> is
1204             <emphasis>unlikely</emphasis> to produce better code than
1205             <option>-O</option>.</para>
1206           </listitem>
1207         </varlistentry>
1208
1209         <varlistentry>
1210           <term>
1211             <option>-Ofile &lt;file&gt;</option>:
1212             <indexterm><primary>-Ofile &lt;file&gt; option</primary></indexterm>
1213             <indexterm><primary>optimising, customised</primary></indexterm>
1214           </term>
1215           <listitem>
1216             <para>(NOTE: not supported since GHC 4.x.  Please ask if
1217             you're interested in this.)</para>
1218
1219             <para>For those who need <emphasis>absolute</emphasis>
1220             control over <emphasis>exactly</emphasis> what options are
1221             used (e.g., compiler writers, sometimes :-), a list of
1222             options can be put in a file and then slurped in with
1223             <option>-Ofile</option>.</para>
1224
1225             <para>In that file, comments are of the
1226             <literal>&num;</literal>-to-end-of-line variety; blank
1227             lines and most whitespace is ignored.</para>
1228
1229             <para>Please ask if you are baffled and would like an
1230             example of <option>-Ofile</option>!</para>
1231           </listitem>
1232         </varlistentry>
1233       </variablelist>
1234
1235       <para>We don't use a <option>-O*</option> flag for day-to-day
1236       work.  We use <option>-O</option> to get respectable speed;
1237       e.g., when we want to measure something.  When we want to go for
1238       broke, we tend to use <option>-O2 -fvia-C</option> (and we go for
1239       lots of coffee breaks).</para>
1240
1241       <para>The easiest way to see what <option>-O</option> (etc.)
1242       &ldquo;really mean&rdquo; is to run with <option>-v</option>,
1243       then stand back in amazement.</para>
1244     </sect2>
1245
1246     <sect2 id="options-f">
1247       <title><option>-f*</option>: platform-independent flags</title>
1248
1249       <indexterm><primary>-f* options (GHC)</primary></indexterm>
1250       <indexterm><primary>-fno-* options (GHC)</primary></indexterm>
1251
1252       <para>These flags turn on and off individual optimisations.
1253       They are normally set via the <option>-O</option> options
1254       described above, and as such, you shouldn't need to set any of
1255       them explicitly (indeed, doing so could lead to unexpected
1256       results).  However, there are one or two that may be of
1257       interest:</para>
1258
1259       <variablelist>
1260         <varlistentry>
1261           <term><option>-fexcess-precision</option>:</term>
1262           <listitem>
1263             <indexterm><primary><option>-fexcess-precision</option></primary></indexterm>
1264             <para>When this option is given, intermediate floating
1265             point values can have a <emphasis>greater</emphasis>
1266             precision/range than the final type.  Generally this is a
1267             good thing, but some programs may rely on the exact
1268             precision/range of
1269             <literal>Float</literal>/<literal>Double</literal> values
1270             and should not use this option for their compilation.</para>
1271           </listitem>
1272         </varlistentry>
1273
1274         <varlistentry>
1275           <term><option>-fignore-asserts</option>:</term>
1276           <listitem>
1277             <indexterm><primary><option>-fignore-asserts</option></primary></indexterm>
1278             <para>Causes GHC to ignore uses of the function
1279             <literal>Exception.assert</literal> in source code (in
1280             other words, rewriting <literal>Exception.assert p
1281             e</literal> to <literal>e</literal> (see <xref
1282             linkend="sec-assertions"/>).  This flag is turned on by
1283             <option>-O</option>.
1284             </para>
1285           </listitem>
1286         </varlistentry>
1287
1288         <varlistentry>
1289           <term>
1290             <option>-fno-strictness</option>
1291             <indexterm><primary><option>-fno-strictness</option></primary></indexterm>
1292           </term>
1293           <listitem>
1294             <para>Turns off the strictness analyser; sometimes it eats
1295             too many cycles.</para>
1296           </listitem>
1297         </varlistentry>
1298
1299         <varlistentry>
1300           <term>
1301             <option>-fno-cpr-analyse</option>
1302             <indexterm><primary><option>-fno-cpr-analyse</option></primary></indexterm>
1303           </term>
1304           <listitem>
1305             <para>Turns off the CPR (constructed product result)
1306             analysis; it is somewhat experimental.</para>
1307           </listitem>
1308         </varlistentry>
1309
1310         <varlistentry>
1311           <term>
1312             <option>-funbox-strict-fields</option>:
1313             <indexterm><primary><option>-funbox-strict-fields</option></primary></indexterm>
1314             <indexterm><primary>strict constructor fields</primary></indexterm>
1315             <indexterm><primary>constructor fields, strict</primary></indexterm>
1316           </term>
1317           <listitem>
1318             <para>This option causes all constructor fields which are
1319             marked strict (i.e. &ldquo;!&rdquo;) to be unboxed or
1320             unpacked if possible.  It is equivalent to adding an
1321             <literal>UNPACK</literal> pragma to every strict
1322             constructor field (see <xref
1323             linkend="unpack-pragma"/>).</para>
1324
1325             <para>This option is a bit of a sledgehammer: it might
1326             sometimes make things worse.  Selectively unboxing fields
1327             by using <literal>UNPACK</literal> pragmas might be
1328             better.</para>
1329           </listitem>
1330         </varlistentry>
1331
1332         <varlistentry>
1333           <term>
1334             <option>-funfolding-update-in-place&lt;n&gt;</option>
1335             <indexterm><primary><option>-funfolding-update-in-place</option></primary></indexterm>
1336           </term>
1337           <listitem>
1338             <para>Switches on an experimental "optimisation".
1339             Switching it on makes the compiler a little keener to
1340             inline a function that returns a constructor, if the
1341             context is that of a thunk.
1342 <programlisting>
1343    x = plusInt a b
1344 </programlisting>
1345             If we inlined plusInt we might get an opportunity to use
1346             update-in-place for the thunk 'x'.</para>
1347           </listitem>
1348         </varlistentry>
1349
1350         <varlistentry>
1351           <term>
1352             <option>-funfolding-creation-threshold&lt;n&gt;</option>:
1353             <indexterm><primary><option>-funfolding-creation-threshold</option></primary></indexterm>
1354             <indexterm><primary>inlining, controlling</primary></indexterm>
1355             <indexterm><primary>unfolding, controlling</primary></indexterm>
1356           </term>
1357           <listitem>
1358             <para>(Default: 45) Governs the maximum size that GHC will
1359             allow a function unfolding to be.   (An unfolding has a
1360             &ldquo;size&rdquo; that reflects the cost in terms of
1361             &ldquo;code bloat&rdquo; of expanding that unfolding at
1362             at a call site. A bigger function would be assigned a
1363             bigger cost.) </para>
1364
1365             <para> Consequences: (a) nothing larger than this will be
1366             inlined (unless it has an INLINE pragma); (b) nothing
1367             larger than this will be spewed into an interface
1368             file. </para>
1369
1370
1371             <para> Increasing this figure is more likely to result in longer
1372             compile times than faster code.  The next option is more
1373             useful:</para>
1374           </listitem>
1375         </varlistentry>
1376
1377         <varlistentry>
1378           <term><option>-funfolding-use-threshold&lt;n&gt;</option>:</term>
1379           <listitem>
1380             <indexterm><primary><option>-funfolding-use-threshold</option></primary></indexterm>
1381             <indexterm><primary>inlining, controlling</primary></indexterm>
1382             <indexterm><primary>unfolding, controlling</primary></indexterm>
1383
1384             <para>(Default: 8) This is the magic cut-off figure for
1385             unfolding: below this size, a function definition will be
1386             unfolded at the call-site, any bigger and it won't.  The
1387             size computed for a function depends on two things: the
1388             actual size of the expression minus any discounts that
1389             apply (see <option>-funfolding-con-discount</option>).</para>
1390           </listitem>
1391         </varlistentry>
1392       </variablelist>
1393
1394     </sect2>
1395
1396   </sect1>
1397
1398   &phases;
1399
1400   <sect1 id="sec-using-concurrent">
1401 <title>Using Concurrent Haskell</title>
1402
1403              <indexterm><primary>Concurrent Haskell&mdash;use</primary></indexterm>
1404
1405 <para>
1406 GHC supports Concurrent Haskell by default, without requiring a
1407 special option or libraries compiled in a certain way.  To get access
1408 to the support libraries for Concurrent Haskell, just import
1409 <literal>Control.Concurrent</literal> (details are in the accompanying
1410 library documentation).</para>
1411
1412 <para>
1413 RTS options are provided for modifying the behaviour of the threaded
1414 runtime system.  See <xref linkend="parallel-rts-opts"/>.
1415 </para>
1416
1417 <para>
1418 Concurrent Haskell is described in more detail in the documentation
1419 for the <literal>Control.Concurrent</literal> module.
1420 </para>
1421
1422 </sect1>
1423
1424 <sect1 id="sec-using-parallel">
1425 <title>Using parallel Haskell</title>
1426
1427 <para>
1428 <indexterm><primary>parallel Haskell&mdash;use</primary></indexterm>
1429 </para>
1430
1431 <para>
1432 &lsqb;You won't be able to execute parallel Haskell programs unless PVM3
1433 (parallel Virtual Machine, version 3) is installed at your site.&rsqb;
1434 </para>
1435
1436 <para>
1437 To compile a Haskell program for parallel execution under PVM, use the
1438 <option>-parallel</option> option,<indexterm><primary>-parallel
1439 option</primary></indexterm> both when compiling <emphasis>and
1440 linking</emphasis>.  You will probably want to <literal>import
1441 parallel</literal> into your Haskell modules.
1442 </para>
1443
1444 <para>
1445 To run your parallel program, once PVM is going, just invoke it
1446 &ldquo;as normal&rdquo;.  The main extra RTS option is
1447 <option>-qp&lt;n&gt;</option>, to say how many PVM
1448 &ldquo;processors&rdquo; your program to run on.  (For more details of
1449 all relevant RTS options, please see <xref
1450 linkend="parallel-rts-opts"/>.)
1451 </para>
1452
1453 <para>
1454 In truth, running parallel Haskell programs and getting information
1455 out of them (e.g., parallelism profiles) is a battle with the vagaries of
1456 PVM, detailed in the following sections.
1457 </para>
1458
1459 <sect2 id="pvm-dummies">
1460 <title>Dummy's guide to using PVM</title>
1461
1462 <para>
1463 <indexterm><primary>PVM, how to use</primary></indexterm>
1464 <indexterm><primary>parallel Haskell&mdash;PVM use</primary></indexterm>
1465 Before you can run a parallel program under PVM, you must set the
1466 required environment variables (PVM's idea, not ours); something like,
1467 probably in your <filename>.cshrc</filename> or equivalent:
1468
1469 <programlisting>
1470 setenv PVM_ROOT /wherever/you/put/it
1471 setenv PVM_ARCH `$PVM_ROOT/lib/pvmgetarch`
1472 setenv PVM_DPATH $PVM_ROOT/lib/pvmd
1473 </programlisting>
1474
1475 </para>
1476
1477 <para>
1478 Creating and/or controlling your &ldquo;parallel machine&rdquo; is a purely-PVM
1479 business; nothing specific to parallel Haskell. The following paragraphs
1480 describe how to configure your parallel machine interactively.
1481 </para>
1482
1483 <para>
1484 If you use parallel Haskell regularly on the same machine configuration it
1485 is a good idea to maintain a file with all machine names and to make the
1486 environment variable PVM_HOST_FILE point to this file. Then you can avoid
1487 the interactive operations described below by just saying
1488 </para>
1489
1490 <programlisting>
1491 pvm $PVM_HOST_FILE
1492 </programlisting>
1493
1494 <para>
1495 You use the <command>pvm</command><indexterm><primary>pvm command</primary></indexterm> command to start PVM on your
1496 machine.  You can then do various things to control/monitor your
1497 &ldquo;parallel machine;&rdquo; the most useful being:
1498 </para>
1499
1500 <para>
1501 <informaltable>
1502 <tgroup cols="2">
1503 <colspec align="left"/>
1504 <tbody>
1505
1506 <row>
1507 <entry><keycombo><keycap>Control</keycap><keycap>D</keycap></keycombo></entry>
1508 <entry>exit <command>pvm</command>, leaving it running</entry>
1509 </row>
1510
1511 <row>
1512 <entry><command>halt</command></entry>
1513 <entry>kill off this &ldquo;parallel machine&rdquo; &amp; exit</entry>
1514 </row>
1515
1516 <row>
1517 <entry><command>add &lt;host&gt;</command></entry>
1518 <entry>add <command>&lt;host&gt;</command> as a processor</entry>
1519 </row>
1520
1521 <row>
1522 <entry><command>delete &lt;host&gt;</command></entry>
1523 <entry>delete <command>&lt;host&gt;</command></entry>
1524 </row>
1525
1526 <row>
1527 <entry><command>reset</command></entry>
1528 <entry>kill what's going, but leave PVM up</entry>
1529 </row>
1530
1531 <row>
1532 <entry><command>conf</command></entry>
1533 <entry>list the current configuration</entry>
1534 </row>
1535
1536 <row>
1537 <entry><command>ps</command></entry>
1538 <entry>report processes' status</entry>
1539 </row>
1540
1541 <row>
1542 <entry><command>pstat &lt;pid&gt;</command></entry>
1543 <entry>status of a particular process</entry>
1544 </row>
1545
1546 </tbody>
1547 </tgroup>
1548 </informaltable>
1549 </para>
1550
1551 <para>
1552 The PVM documentation can tell you much, much more about <command>pvm</command>!
1553 </para>
1554
1555 </sect2>
1556
1557 <sect2 id="par-profiles">
1558 <title>parallelism profiles</title>
1559
1560 <para>
1561 <indexterm><primary>parallelism profiles</primary></indexterm>
1562 <indexterm><primary>profiles, parallelism</primary></indexterm>
1563 <indexterm><primary>visualisation tools</primary></indexterm>
1564 </para>
1565
1566 <para>
1567 With parallel Haskell programs, we usually don't care about the
1568 results&mdash;only with &ldquo;how parallel&rdquo; it was!  We want pretty pictures.
1569 </para>
1570
1571 <para>
1572 parallelism profiles (&agrave; la <command>hbcpp</command>) can be generated with the
1573 <option>-qP</option><indexterm><primary>-qP RTS option (concurrent, parallel)</primary></indexterm> RTS option.  The
1574 per-processor profiling info is dumped into files named
1575 <filename>&lt;full-path&gt;&lt;program&gt;.gr</filename>.  These are then munged into a PostScript picture,
1576 which you can then display.  For example, to run your program
1577 <filename>a.out</filename> on 8 processors, then view the parallelism profile, do:
1578 </para>
1579
1580 <para>
1581
1582 <screen>
1583 <prompt>&dollar;</prompt> ./a.out +RTS -qP -qp8
1584 <prompt>&dollar;</prompt> grs2gr *.???.gr &#62; temp.gr # combine the 8 .gr files into one
1585 <prompt>&dollar;</prompt> gr2ps -O temp.gr              # cvt to .ps; output in temp.ps
1586 <prompt>&dollar;</prompt> ghostview -seascape temp.ps   # look at it!
1587 </screen>
1588
1589 </para>
1590
1591 <para>
1592 The scripts for processing the parallelism profiles are distributed
1593 in <filename>ghc/utils/parallel/</filename>.
1594 </para>
1595
1596 </sect2>
1597
1598 <sect2>
1599 <title>Other useful info about running parallel programs</title>
1600
1601 <para>
1602 The &ldquo;garbage-collection statistics&rdquo; RTS options can be useful for
1603 seeing what parallel programs are doing.  If you do either
1604 <option>+RTS -Sstderr</option><indexterm><primary>-Sstderr RTS option</primary></indexterm> or <option>+RTS -sstderr</option>, then
1605 you'll get mutator, garbage-collection, etc., times on standard
1606 error. The standard error of all PE's other than the `main thread'
1607 appears in <filename>/tmp/pvml.nnn</filename>, courtesy of PVM.
1608 </para>
1609
1610 <para>
1611 Whether doing <option>+RTS -Sstderr</option> or not, a handy way to watch
1612 what's happening overall is: <command>tail -f /tmp/pvml.nnn</command>.
1613 </para>
1614
1615 </sect2>
1616
1617 <sect2 id="parallel-rts-opts">
1618 <title>RTS options for Concurrent/parallel Haskell
1619 </title>
1620
1621 <para>
1622 <indexterm><primary>RTS options, concurrent</primary></indexterm>
1623 <indexterm><primary>RTS options, parallel</primary></indexterm>
1624 <indexterm><primary>Concurrent Haskell&mdash;RTS options</primary></indexterm>
1625 <indexterm><primary>parallel Haskell&mdash;RTS options</primary></indexterm>
1626 </para>
1627
1628 <para>
1629 Besides the usual runtime system (RTS) options
1630 (<xref linkend="runtime-control"/>), there are a few options particularly
1631 for concurrent/parallel execution.
1632 </para>
1633
1634 <para>
1635 <variablelist>
1636
1637 <varlistentry>
1638 <term><option>-qp&lt;N&gt;</option>:</term>
1639 <listitem>
1640 <para>
1641 <indexterm><primary>-qp&lt;N&gt; RTS option</primary></indexterm>
1642 (paraLLEL ONLY) Use <literal>&lt;N&gt;</literal> PVM processors to run this program;
1643 the default is 2.
1644 </para>
1645 </listitem>
1646 </varlistentry>
1647 <varlistentry>
1648 <term><option>-C[&lt;us&gt;]</option>:</term>
1649 <listitem>
1650 <para>
1651 <indexterm><primary>-C&lt;us&gt; RTS option</primary></indexterm> Sets
1652 the context switch interval to <literal>&lt;s&gt;</literal> seconds.
1653 A context switch will occur at the next heap block allocation after
1654 the timer expires (a heap block allocation occurs every 4k of
1655 allocation).  With <option>-C0</option> or <option>-C</option>,
1656 context switches will occur as often as possible (at every heap block
1657 allocation).  By default, context switches occur every 20ms
1658 milliseconds.  Note that GHC's internal timer ticks every 20ms, and
1659 the context switch timer is always a multiple of this timer, so 20ms
1660 is the maximum granularity available for timed context switches.
1661 </para>
1662 </listitem>
1663 </varlistentry>
1664 <varlistentry>
1665 <term><option>-q[v]</option>:</term>
1666 <listitem>
1667 <para>
1668 <indexterm><primary>-q RTS option</primary></indexterm>
1669 (paraLLEL ONLY) Produce a quasi-parallel profile of thread activity,
1670 in the file <filename>&lt;program&gt;.qp</filename>.  In the style of <command>hbcpp</command>, this profile
1671 records the movement of threads between the green (runnable) and red
1672 (blocked) queues.  If you specify the verbose suboption (<option>-qv</option>), the
1673 green queue is split into green (for the currently running thread
1674 only) and amber (for other runnable threads).  We do not recommend
1675 that you use the verbose suboption if you are planning to use the
1676 <command>hbcpp</command> profiling tools or if you are context switching at every heap
1677 check (with <option>-C</option>).
1678 -->
1679 </para>
1680 </listitem>
1681 </varlistentry>
1682 <varlistentry>
1683 <term><option>-qt&lt;num&gt;</option>:</term>
1684 <listitem>
1685 <para>
1686 <indexterm><primary>-qt&lt;num&gt; RTS option</primary></indexterm>
1687 (paraLLEL ONLY) Limit the thread pool size, i.e. the number of concurrent
1688 threads per processor to <literal>&lt;num&gt;</literal>.  The default is
1689 32.  Each thread requires slightly over 1K <emphasis>words</emphasis> in
1690 the heap for thread state and stack objects.  (For 32-bit machines, this
1691 translates to 4K bytes, and for 64-bit machines, 8K bytes.)
1692 </para>
1693 </listitem>
1694 </varlistentry>
1695 <!-- no more -HWL
1696 <varlistentry>
1697 <term><option>-d</option>:</term>
1698 <listitem>
1699 <para>
1700 <indexterm><primary>-d RTS option (parallel)</primary></indexterm>
1701 (paraLLEL ONLY) Turn on debugging.  It pops up one xterm (or GDB, or
1702 something&hellip;) per PVM processor.  We use the standard <command>debugger</command>
1703 script that comes with PVM3, but we sometimes meddle with the
1704 <command>debugger2</command> script.  We include ours in the GHC distribution,
1705 in <filename>ghc/utils/pvm/</filename>.
1706 </para>
1707 </listitem>
1708 </varlistentry>
1709 -->
1710 <varlistentry>
1711 <term><option>-qe&lt;num&gt;</option>:</term>
1712 <listitem>
1713 <para>
1714 <indexterm><primary>-qe&lt;num&gt; RTS option
1715 (parallel)</primary></indexterm> (paraLLEL ONLY) Limit the spark pool size
1716 i.e. the number of pending sparks per processor to
1717 <literal>&lt;num&gt;</literal>. The default is 100. A larger number may be
1718 appropriate if your program generates large amounts of parallelism
1719 initially.
1720 </para>
1721 </listitem>
1722 </varlistentry>
1723 <varlistentry>
1724 <term><option>-qQ&lt;num&gt;</option>:</term>
1725 <listitem>
1726 <para>
1727 <indexterm><primary>-qQ&lt;num&gt; RTS option (parallel)</primary></indexterm>
1728 (paraLLEL ONLY) Set the size of packets transmitted between processors
1729 to <literal>&lt;num&gt;</literal>. The default is 1024 words. A larger number may be
1730 appropriate if your machine has a high communication cost relative to
1731 computation speed.
1732 </para>
1733 </listitem>
1734 </varlistentry>
1735 <varlistentry>
1736 <term><option>-qh&lt;num&gt;</option>:</term>
1737 <listitem>
1738 <para>
1739 <indexterm><primary>-qh&lt;num&gt; RTS option (parallel)</primary></indexterm>
1740 (paraLLEL ONLY) Select a packing scheme. Set the number of non-root thunks to pack in one packet to
1741 &lt;num&gt;-1 (0 means infinity). By default GUM uses full-subgraph
1742 packing, i.e. the entire subgraph with the requested closure as root is
1743 transmitted (provided it fits into one packet). Choosing a smaller value
1744 reduces the amount of pre-fetching of work done in GUM. This can be
1745 advantageous for improving data locality but it can also worsen the balance
1746 of the load in the system.
1747 </para>
1748 </listitem>
1749 </varlistentry>
1750 <varlistentry>
1751 <term><option>-qg&lt;num&gt;</option>:</term>
1752 <listitem>
1753 <para>
1754 <indexterm><primary>-qg&lt;num&gt; RTS option
1755 (parallel)</primary></indexterm> (paraLLEL ONLY) Select a globalisation
1756 scheme. This option affects the
1757 generation of global addresses when transferring data. Global addresses are
1758 globally unique identifiers required to maintain sharing in the distributed
1759 graph structure. Currently this is a binary option. With &lt;num&gt;=0 full globalisation is used
1760 (default). This means a global address is generated for every closure that
1761 is transmitted. With &lt;num&gt;=1 a thunk-only globalisation scheme is
1762 used, which generated global address only for thunks. The latter case may
1763 lose sharing of data but has a reduced overhead in packing graph structures
1764 and maintaining internal tables of global addresses.
1765 </para>
1766 </listitem>
1767 </varlistentry>
1768 </variablelist>
1769 </para>
1770
1771 </sect2>
1772
1773 </sect1>
1774
1775   <sect1 id="options-platform">
1776     <title>Platform-specific Flags</title>
1777
1778     <indexterm><primary>-m* options</primary></indexterm>
1779     <indexterm><primary>platform-specific options</primary></indexterm>
1780     <indexterm><primary>machine-specific options</primary></indexterm>
1781
1782     <para>Some flags only make sense for particular target
1783     platforms.</para>
1784
1785     <variablelist>
1786
1787       <varlistentry>
1788         <term><option>-mv8</option>:</term>
1789         <listitem>
1790           <para>(SPARC machines)<indexterm><primary>-mv8 option (SPARC
1791           only)</primary></indexterm> Means to pass the like-named
1792           option to GCC; it says to use the Version 8 SPARC
1793           instructions, notably integer multiply and divide.  The
1794           similar <option>-m*</option> GCC options for SPARC also
1795           work, actually.</para>
1796         </listitem>
1797       </varlistentry>
1798
1799       <varlistentry>
1800         <term><option>-monly-[32]-regs</option>:</term>
1801         <listitem>
1802           <para>(iX86 machines)<indexterm><primary>-monly-N-regs
1803           option (iX86 only)</primary></indexterm> GHC tries to
1804           &ldquo;steal&rdquo; four registers from GCC, for performance
1805           reasons; it almost always works.  However, when GCC is
1806           compiling some modules with four stolen registers, it will
1807           crash, probably saying:
1808
1809 <screen>
1810 Foo.hc:533: fixed or forbidden register was spilled.
1811 This may be due to a compiler bug or to impossible asm
1812 statements or clauses.
1813 </screen>
1814
1815           Just give some registers back with
1816           <option>-monly-N-regs</option>.  Try `3' first, then `2'.
1817           If `2' doesn't work, please report the bug to us.</para>
1818         </listitem>
1819       </varlistentry>
1820     </variablelist>
1821
1822   </sect1>
1823
1824 &runtime;
1825
1826 <sect1 id="ext-core">
1827   <title>Generating and compiling External Core Files</title>
1828
1829   <indexterm><primary>intermediate code generation</primary></indexterm>
1830
1831   <para>GHC can dump its optimized intermediate code (said to be in &ldquo;Core&rdquo; format)
1832   to a file as a side-effect of compilation. Core files, which are given the suffix
1833   <filename>.hcr</filename>, can be read and processed by non-GHC back-end
1834   tools.  The Core format is formally described in <ulink url="http://www.haskell.org/ghc/docs/papers/core.ps.gz">
1835   <citetitle>An External Representation for the GHC Core Language</citetitle></ulink>,
1836   and sample tools (in Haskell)
1837   for manipulating Core files are available in the GHC source distribution
1838   directory <literal>/fptools/ghc/utils/ext-core</literal>.
1839   Note that the format of <literal>.hcr</literal>
1840   files is <emphasis>different</emphasis> (though similar) to the Core output format generated
1841   for debugging purposes (<xref linkend="options-debugging"/>).</para>
1842
1843   <para>The Core format natively supports notes which you can add to
1844   your source code using the <literal>CORE</literal> pragma (see <xref
1845   linkend="pragmas"/>).</para>
1846
1847     <variablelist>
1848
1849         <varlistentry>
1850           <term>
1851             <option>-fext-core</option>
1852             <indexterm><primary><option>-fext-core</option></primary></indexterm>
1853           </term>
1854           <listitem>
1855             <para>Generate <literal>.hcr</literal> files.</para>
1856           </listitem>
1857         </varlistentry>
1858
1859     </variablelist>
1860
1861 <para>GHC can also read in External Core files as source; just give the <literal>.hcr</literal> file on
1862 the command line, instead of the <literal>.hs</literal> or <literal>.lhs</literal> Haskell source.
1863 A current infelicity is that you need to give the <literal>-fglasgow-exts</literal> flag too, because
1864 ordinary Haskell 98, when translated to External Core, uses things like rank-2 types.</para>
1865 </sect1>
1866
1867 &debug;
1868 &flags;
1869
1870 </chapter>
1871
1872 <!-- Emacs stuff:
1873      ;;; Local Variables: ***
1874      ;;; mode: xml ***
1875      ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter") ***
1876      ;;; End: ***
1877  -->