Common compilation flags 
========================
.. index::
    single: Mercurium; common flags

Usual flags like ``-O``, ``-O1``, ``-O2``, ``-O3``, ``-D``, ``-c``, ``-o``, ... are recognized by Mercurium.

Almost every Mercurium-specific flag is of the form ``--xxx``.

Mercurium drivers are deliberately compatible with ``gcc``. This means that flags
of the form ``-fXXX``, ``-mXXX`` and ``-Wxxx`` are accepted and passed onto the backend
compiler without interpretation by Mercurium drivers.

.. warning::
  In GCC a flag of the form ``-fXXX`` is equivalent to a flag of the form ``--XXX``. This is **not** the case in Mercurium.

.. index::
    single: Mercurium; help

Getting command line help
-------------------------

You can get a summary of all the flags accepted by Mercurium using ``--help`` with any of the drivers::

  $ mcc --help
  Usage: mcc options file [file..]
  Options:
    -h, --help               Shows this help and quits
    --version                Shows version and quits
    --v, --verbose           Runs verbosely, displaying the programs
                             invoked by the compiler
  ...

.. index::
    single: Mercurium; vendor-specific flags

Passing vendor-specific flags
-----------------------------

While almost every ``gcc`` of the form ``-fXXX`` or ``-mXXX`` can be passed
directly to a Mercurium driver, some other vendor-specific flags may not be
well known or be misunderstood by Mercurium. When this happens, Mercurium has a
generic way to pass parameters to the backend compiler and linker.

``--Wn,<comma-separated-list-of-flags>``
    Passes comma-separated flags to the native compiler. These flags are used when
    Mercurium invokes the backend compiler to generate the object file (``.o``)

``--Wl,<comma-separated-list-of-flags>``
    Passes comma-separated-flags to the linker. These flags are used when Mercurium
    invokes the linker

``--Wp,<comma-separated-list-of-flags>``
    Passes comma-separated flags to the C/Fortran preprocessor. These flags are used
    when Mercurium invokes the preprocessor on a C or Fortran file.

These flags can be combined. Flags ``--Wp,a --Wp,b`` are equivalent to
``--Wp,a,b``. Flag ``--Wnp,a`` is equivalent to ``--Wn,a --Wp,a``

.. important::
  Do not confuse ``--Wl`` and ``--Wp`` with the ``gcc`` similar flags ``-Wl``
  and ``-Wp`` (note that ``gcc`` ones have a single ``-``).  The latter can be
  used with the former, as in ``--Wl,-Wl,muldefs``. That said, Mercurium
  supports ``-Wl`` and ``-Wp`` directly, so ``-Wl,muldefs`` should be enough.