Sometimes it is useful to make the connection between a source file and the command-line options it requires quite tight. For instance, if a (Glasgow) Haskell source file uses `casm's, the C back-end often needs to be told about which header files to include. Rather than maintaining the list of files the source depends on in a `Makefile' (using the `-#include' command-line option), it is possible to do this directly in the source file using the `OPTIONS' pragma :
{-# OPTIONS -#include "foo.h" #-}
module X where
...
`OPTIONS' pragmas are only looked for at the top of your source files, upto the first (non-literate,non-empty) line not containing `OPTIONS'. Multiple `OPTIONS' pragmas are recognised. Note that your command shell does not get to the source file options, they are just included literally in the array of command-line arguments the compiler driver maintains internally, so you'll be desperately disappointed if you try to glob etc. inside `OPTIONS'.
NOTE: the contents of OPTIONS are prepended to the command-line options, so you *do* have the ability to override OPTIONS settings via the command line.
It is not recommended to move all the contents of your Makefiles into your source files, but in some circumstances, the `OPTIONS' pragma is the Right Thing. (If you use `-keep-hc-file-too' and have OPTION flags in your module, the OPTIONS will get put into the generated .hc file).