7.13. Pragmas

GHC supports several pragmas, or instructions to the
compiler placed in the source code. Pragmas don't normally affect
the meaning of the program, but they might affect the efficiency
of the generated code.

Pragmas all take the form
{-# word ... #-}
where word indicates the type of
pragma, and is followed optionally by information specific to that
type of pragma. Case is ignored in
word. The various values for
word that GHC understands are described
in the following sections; any pragma encountered with an
unrecognised word is
ignored. The layout rule applies in pragmas, so the closing #-}
should start in a column to the right of the opening {-#.

Certain pragmas are file-header pragmas:

A file-header
pragma must precede the module keyword in the file.

There can be as many file-header pragmas as you please, and they can be
preceded or followed by comments.

File-header pragmas are read once only, before
pre-processing the file (e.g. with cpp).

7.13.1. LANGUAGE pragma

The LANGUAGE pragma allows language extensions to be enabled
in a portable way.
It is the intention that all Haskell compilers support the
LANGUAGE pragma with the same syntax, although not
all extensions are supported by all compilers, of
course. The LANGUAGE pragma should be used instead
of OPTIONS_GHC, if possible.

7.13.3. INCLUDE pragma

The INCLUDE used to be necessary for
specifying header files to be included when using the FFI and
compiling via C. It is no longer required for GHC, but is
accepted (and ignored) for compatibility with other
compilers.

7.13.4. WARNING and DEPRECATED pragmas

The WARNING pragma allows you to attach an arbitrary warning
to a particular function, class, or type.
A DEPRECATED pragma lets you specify that
a particular function, class, or type is deprecated.
There are two ways of using these pragmas.

When you compile any module that imports and uses any
of the specified entities, GHC will print the specified
message.

You can only attach to entities declared at top level in the module
being compiled, and you can only use unqualified names in the list of
entities. A capitalised name, such as T
refers to either the type constructor Tor the data constructor T, or both if
both are in scope. If both are in scope, there is currently no way to
specify one without the other (c.f. fixities
Section 7.4.2, “Infix type constructors, classes, and type variables”).

Warnings and deprecations are not reported for
(a) uses within the defining module, and
(b) uses in an export list.
The latter reduces spurious complaints within a library
in which one module gathers together and re-exports
the exports of several others.

You can suppress the warnings with the flag
-fno-warn-warnings-deprecations.

7.13.5. INLINE and NOINLINE pragmas

These pragmas control the inlining of function
definitions.

7.13.5.1. INLINE pragma

GHC (with -O, as always) tries to
inline (or “unfold”) functions/values that are
“small enough,” thus avoiding the call overhead
and possibly exposing other more-wonderful optimisations.
Normally, if GHC decides a function is “too
expensive” to inline, it will not do so, nor will it
export that unfolding for other modules to use.

The sledgehammer you can bring to bear is the
INLINE pragma, used thusly:

The major effect of an INLINE pragma
is to declare a function's “cost” to be very low.
The normal unfolding machinery will then be very keen to
inline it. However, an INLINE pragma for a
function "f" has a number of other effects:

No functions are inlined into f. Otherwise
GHC might inline a big function into f's right hand side,
making f big; and then inline f blindly.

The float-in, float-out, and common-sub-expression transformations are not
applied to the body of f.

An INLINE function is not worker/wrappered by strictness analysis.
It's going to be inlined wholesale instead.

All of these effects are aimed at ensuring that what gets inlined is
exactly what you asked for, no more and no less.

GHC ensures that inlining cannot go on forever: every mutually-recursive
group is cut by one or more loop breakers that is never inlined
(see
Secrets of the GHC inliner, JFP 12(4) July 2002).
GHC tries not to select a function with an INLINE pragma as a loop breaker, but
when there is no choice even an INLINE function can be selected, in which case
the INLINE pragma is ignored.
For example, for a self-recursive function, the loop breaker can only be the function
itself, so an INLINE pragma is always ignored.

Syntactically, an INLINE pragma for a
function can be put anywhere its type signature could be
put.

INLINE pragmas are a particularly
good idea for the
then/return (or
bind/unit) functions in
a monad. For example, in GHC's own
UniqueSupply monad code, we have:

Note: the HBC compiler doesn't like INLINE pragmas,
so if you want your code to be HBC-compatible you'll have to surround
the pragma with C pre-processor directives
#ifdef __GLASGOW_HASKELL__...#endif.

7.13.5.2. NOINLINE pragma

The NOINLINE pragma does exactly what
you'd expect: it stops the named function from being inlined
by the compiler. You shouldn't ever need to do this, unless
you're very cautious about code size.

NOTINLINE is a synonym for
NOINLINE (NOINLINE is
specified by Haskell 98 as the standard way to disable
inlining, so it should be used if you want your code to be
portable).

7.13.5.3. Phase control

Sometimes you want to control exactly when in GHC's
pipeline the INLINE pragma is switched on. Inlining happens
only during runs of the simplifier. Each
run of the simplifier has a different phase
number; the phase number decreases towards zero.
If you use -dverbose-core2core you'll see the
sequence of phase numbers for successive runs of the
simplifier. In an INLINE pragma you can optionally specify a
phase number, thus:

"INLINE[k] f" means: do not inline
f
until phase k, but from phase
k onwards be very keen to inline it.

"INLINE[~k] f" means: be very keen to inline
f
until phase k, but from phase
k onwards do not inline it.

"NOINLINE[k] f" means: do not inline
f
until phase k, but from phase
k onwards be willing to inline it (as if
there was no pragma).

"NOINLINE[~k] f" means: be willing to inline
f
until phase k, but from phase
k onwards do not inline it.

By "Maybe" we mean that the usual heuristic inlining rules apply (if the
function body is small, or it is applied to interesting-looking arguments etc).
Another way to understand the semantics is this:

For both INLINE and NOINLINE, the phase number says
when inlining is allowed at all.

The INLINE pragma has the additional effect of making the
function body look small, so that when inlining is allowed it is very likely to
happen.

7.13.6. ANN pragmas

GHC offers the ability to annotate various code constructs with additional
data by using three pragmas. This data can then be inspected at a later date by
using GHC-as-a-library.

7.13.6.1. Annotating values

Any expression that has both Typeable and Data instances may be attached to a top-level value
binding using an ANN pragma. In particular, this means you can use ANN
to annotate data constructors (e.g. Just) as well as normal values (e.g. take).
By way of example, to annotate the function foo with the annotation Just "Hello"
you would do this:

{-# ANN foo (Just "Hello") #-}
foo = ...

A number of restrictions apply to use of annotations:

The binder being annotated must be at the top level (i.e. no nested binders)

The binder being annotated must be declared in the current module

The expression you are annotating with must have a type with Typeable and Data instances

To be precise, the annotation {-# ANN x e #-} is well staged if and only if $(e) would be
(disregarding the usual type restrictions of the splice syntax, and the usual restriction on splicing inside a splice - $([|1|]) is fine as an annotation, albeit redundant).

However, apart from these restrictions, many things are allowed, including expressions which are not fully evaluated!
Annotation expressions will be evaluated by the compiler just like Template Haskell splices are. So, this annotation is fine:

7.13.6.2. Annotating types

7.13.6.3. Annotating modules

You can annotate modules with the ANN pragma by using the module keyword. For example:

{-# ANN module (Just "A `Maybe String' annotation") #-}

7.13.7. LINE pragma

This pragma is similar to C's #line
pragma, and is mainly for use in automatically generated Haskell
code. It lets you specify the line number and filename of the
original code; for example

{-# LINE 42 "Foo.vhs" #-}

if you'd generated the current file from something called
Foo.vhs and this line corresponds to line
42 in the original. GHC will adjust its error messages to refer
to the line/file named in the LINE
pragma.

A SPECIALIZE pragma for a function can
be put anywhere its type signature could be put.

A SPECIALIZE has the effect of generating
(a) a specialised version of the function and (b) a rewrite rule
(see Section 7.14, “Rewrite rules
”) that rewrites a call to the
un-specialised function into a call to the specialised one.

The type in a SPECIALIZE pragma can be any type that is less
polymorphic than the type of the original function. In concrete terms,
if the original function is f then the pragma

{-# SPECIALIZE f :: <type> #-}

is valid if and only if the definition

f_spec :: <type>
f_spec = f

is valid. Here are some examples (where we only give the type signature
for the original function, not its code):

The last of these examples will generate a
RULE with a somewhat-complex left-hand side (try it yourself), so it might not fire very
well. If you use this kind of specialisation, let us know how well it works.

A SPECIALIZE pragma can optionally be followed with a
INLINE or NOINLINE pragma, optionally
followed by a phase, as described in Section 7.13.5, “INLINE and NOINLINE pragmas”.
The INLINE pragma affects the specialised version of the
function (only), and applies even if the function is recursive. The motivating
example is this:

Here, (!:) is a recursive function that indexes arrays
of type Arr e. Consider a call to (!:)
at type (Int,Int). The second specialisation will fire, and
the specialised function will be inlined. It has two calls to
(!:),
both at type Int. Both these calls fire the first
specialisation, whose body is also inlined. The result is a type-based
unrolling of the indexing function.

Warning: you can make GHC diverge by using SPECIALISE INLINE
on an ordinarily-recursive function.

Note: In earlier versions of GHC, it was possible to provide your own
specialised function for a given type:

7.13.10. SPECIALIZE instance pragma

The pragma must occur inside the where part
of the instance declaration.

Compatible with HBC, by the way, except perhaps in the placement
of the pragma.

7.13.11. UNPACK pragma

The UNPACK indicates to the compiler
that it should unpack the contents of a constructor field into
the constructor itself, removing a level of indirection. For
example:

data T = T {-# UNPACK #-} !Float
{-# UNPACK #-} !Float

will create a constructor T containing
two unboxed floats. This may not always be an optimisation: if
the T constructor is scrutinised and the
floats passed to a non-strict function for example, they will
have to be reboxed (this is done automatically by the
compiler).

Unpacking constructor fields should only be used in
conjunction with -O, in order to expose
unfoldings to the compiler so the reboxing can be removed as
often as possible. For example:

f :: T -> Float
f (T f1 f2) = f1 + f2

The compiler will avoid reboxing f1
and f2 by inlining +
on floats, but only when -O is on.

Any single-constructor data is eligible for unpacking; for
example

data T = T {-# UNPACK #-} !(Int,Int)

will store the two Ints directly in the
T constructor, by flattening the pair.
Multi-level unpacking is also supported: