[commit: ghc] master: user-guide: Note order-dependence of flags (128b678)

[git at git.haskell.org]

Repository : ssh://git@git.haskell.org/ghc

On branch  : master
Link       : http://ghc.haskell.org/trac/ghc/changeset/128b678061120270d3d4fe3eccd1b7dc76a8de35/ghc

>---------------------------------------------------------------

commit 128b678061120270d3d4fe3eccd1b7dc76a8de35
Author: Ben Gamari <bgamari.foss at gmail.com>
Date:   Mon Jan 25 15:18:13 2016 +0100

    user-guide: Note order-dependence of flags
    
    This supplements the description previously added in
    6400c7687223c5b2141176aa92f7ff987f61aba6. See #10560 for details.
    
    Test Plan: read it
    
    Reviewers: austin
    
    Subscribers: thomie, hvr
    
    Differential Revision: https://phabricator.haskell.org/D1831
    
    GHC Trac Issues: #10560


>---------------------------------------------------------------

128b678061120270d3d4fe3eccd1b7dc76a8de35
 docs/users_guide/using.rst | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/docs/users_guide/using.rst b/docs/users_guide/using.rst
index 91b6291..3b192ef 100644
--- a/docs/users_guide/using.rst
+++ b/docs/users_guide/using.rst
@@ -85,6 +85,28 @@ all files; you cannot, for example, invoke
 ``ghc -c -O1 Foo.hs -O2 Bar.hs`` to apply different optimisation levels
 to the files ``Foo.hs`` and ``Bar.hs``.
 
+.. note::
+
+    .. index::
+       single: command-line; order of arguments
+
+    Note that command-line options are *order-dependent*, with arguments being
+    evaluated from left-to-right. This can have seemingly strange effects in the
+    presence of flag implication. For instance, consider
+    :ghc-flag:`-fno-specialise` and :ghc-flag:`-O1` (which implies
+    :ghc-flag:`-fspecialise`). These two command lines mean very different
+    things:
+
+    ``-fno-specialise -O1``
+
+        ``-fspecialise`` will be enabled as the ``-fno-specialise`` is overriden
+        by the ``-O1``.
+
+    ``-O1 -fno-specialise``
+
+        ``-fspecialise`` will not be enabled, since the ``-fno-specialise``
+        overrides the ``-fspecialise`` implied by ``-O1``.
+
 .. _source-file-options:
 
 Command line options in source files