Commit 6400c768 authored by Ben Gamari's avatar Ben Gamari Committed by Ben Gamari
Browse files

users_guide: Describe order-dependence of -f and -O flags

The behavior of the -f and -O options can be quite surprising.
Document this fact. At some point this behavior should likely be changed.

Test Plan: documentation only

Reviewers: austin, trofi

Reviewed By: austin, trofi

Subscribers: thomie, bgamari

Differential Revision: https://phabricator.haskell.org/D1008

GHC Trac Issues: #10560
parent f07b7a87
......@@ -1753,7 +1753,7 @@
<sect2>
<title>Optimisation levels</title>
<para>These options are described in more detail in <xref linkend="options-optimise"/></para>
<para>These options are described in more detail in <xref linkend="options-optimise"/>.</para>
<informaltable>
<tgroup cols="4" align="left" colsep="1" rowsep="1">
......
......@@ -2105,6 +2105,29 @@ _ = rhs3 -- No warning: lone wild-card pattern
<emphasis>machine-specific</emphasis> optimisations to be turned
on/off.</para>
<para>Most of these options are boolean and have options to turn them both
&ldquo;on&rdquo; and &ldquo;off&rdquo; (beginning with the prefix
<option>no-</option>). For instance, while <option>-fspecialise</option>
enables specialisation, <option>-fno-specialise</option> disables it. When
multiple flags for the same option appear in the command-line they are
evaluated from left to right. For instance <option>-fno-specialise
-fspecialise</option> will enable specialisation.
</para>
<para>It is important to note that the <option>-O*</option> flags are roughly
equivalent to combinations of <option>-f*</option> flags. For this reason,
the effect of the <option>-O*</option> and <option>-f*</option> flags is
dependent upon the order in which they occur on the command line.
</para>
<para>For instance, take the example of <option>-fno-specialise
-O1</option>. Despite the <option>-fno-specialise</option> appearing in the
command line, specialisation will still be enabled. This is the case
as <option>-O1</option> implies <option>-fspecialise</option>, overriding
the previous flag. By contrast, <option>-O1 -fno-specialise</option> will
compile without specialisation, as one would expect.
</para>
<sect2 id="optimise-pkgs">
<title><option>-O*</option>: convenient &ldquo;packages&rdquo; of optimisation flags.</title>
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment