Engines

Available features

Metashell supports different underlying compilers and preprocessors, but not all compilers support everything needed by Metashell. For example Boost.Wave can not evaluate template metaprograms, as it is a preprocessor, but it is still supported by Metashell for getting an insight into preprocessing.

The functionality of Metashell has been split up into a number of features to make it easier to document what functionality is available for the different compilers:

  • type shell
    It is used for evaluating template metaprograms in Metashell.

  • preprocessor shell
    It is used for evaluating preprocessor metaprograms in Metashell in preprocessor mode.

  • code completer
    It is used for code-completion in the shell.

  • header discoverer
    It is used for analysing the included headers and the include path.

  • metaprogram tracer
    It is used by MDB to get an insight into template instantiations.

  • cpp validator
    It is used for checking that the code entered into Metashell is valid C++ code.

  • macro discovery
    It is used for querying the defined macros.

  • preprocessor tracer
    It is used by PDB to get an insight into preprocessing (macro calls, includes, etc).

Available engines

An engine is a Metashell plugin for executing Metashell commands using a specific compiler. Metashell provides the following engines:

  • auto
    Usage: metashell --engine auto

    Chooses an engine based on the compiler specified in the arguments.

  • clang
    Usage: metashell --engine clang -- <Clang binary> -std=<standard to use> [<Clang args>]

    Uses the Clang compiler. <Clang args> are passed to the compiler as command line-arguments. Note that Metashell requires C++11 or above. If your Clang uses such a standard by default, you can omit the -std argument. Metaprogram debugging (MDB) is supported only when Clang has been patched with templight

    Supported features: type shell, preprocessor shell, code completer, header discoverer, metaprogram tracer, cpp validator, macro discovery

  • gcc
    Usage: metashell --engine gcc -- <gcc binary> -std=<standard to use> [<gcc args>]

    Uses the gcc compiler. <gcc args> are passed to the compiler as command line-arguments. Note that Metashell requires C++11 or above. If your gcc uses such a standard by default, you can omit the -std argument. Also note that currently only the preprocessor shell is supported.

    Supported features: preprocessor shell, header discoverer, cpp validator, macro discovery

  • internal
    Usage: metashell --engine internal -- [<Clang args>]

    Uses the Templight shipped with Metashell. <Clang args> are passed to the compiler as command line-arguments.

    Supported features: type shell, preprocessor shell, code completer, header discoverer, metaprogram tracer, cpp validator, macro discovery

  • msvc
    Usage: metashell --engine msvc -- <path to cl.exe> [<cl.exe args>]

    Uses the Visual C++ compiler. <cl.exe args> are passed to the compiler as command line-arguments. Note that currently only the preprocessor shell is supported. You need to run Metashell from the Visual Studio Developer Prompt to use this engine.

    Supported features: preprocessor shell, header discoverer, cpp validator

  • null
    Usage: metashell --engine null

    An engine which does not support anything. Mainly for testing purposes.

    Supported features: no features are supported

  • pure_wave
    Usage: metashell --engine pure_wave -- <Wave options>

    Uses Boost.Wave, which is a preprocessor. Only the preprocessor shell is supported.

    Wave options:
      -I [ --include ] specify an additional include directory
      -S [ --sysinclude ] specify an additional system include directory
      -iquote specify an additional quote include directory
      -idirafter specify an additional include directory to be checked after system headers
      -D [ --define ] specify a macro to define (as macro[=[value]])
      -U specify a macro to undefine
      --long_long enable long long support in C++ mode
      --variadics enable certain C99 extensions in C++ mode
      --c99 enable C99 mode (implies --variadics)
      --c++11 enable C++11 mode (implies --variadics and --long_long)
      --nostdinc++ ignored (accepted to be compatible with the wave engine)


    Supported features: preprocessor shell, header discoverer, cpp validator, macro discovery, preprocessor tracer

  • templight
    Usage: metashell --engine templight -- <Templight binary> -std=<standard to use> [<Clang args>]

    Uses Templight. <Clang args> are passed to the compiler as command line-arguments. Note that Metashell requires C++11 or above. If your Templight uses such a standard by default, you can omit the -std argument.

    Supported features: type shell, preprocessor shell, code completer, header discoverer, metaprogram tracer, cpp validator, macro discovery

  • wave
    Usage: metashell --engine wave -- <Wave options>

    Uses Boost.Wave, which is a preprocessor. Only the preprocessor shell is supported. It uses the headers of Templight deployed with Metashell.

    Wave options:
      -I [ --include ] specify an additional include directory
      -S [ --sysinclude ] specify an additional system include directory
      -iquote specify an additional quote include directory
      -idirafter specify an additional include directory to be checked after system headers
      -D [ --define ] specify a macro to define (as macro[=[value]])
      -U specify a macro to undefine
      --long_long enable long long support in C++ mode
      --variadics enable certain C99 extensions in C++ mode
      --c99 enable C99 mode (implies --variadics)
      --c++11 enable C++11 mode (implies --variadics and --long_long)
      --nostdinc++ don't add standard headers to the include path


    Supported features: preprocessor shell, header discoverer, cpp validator, macro discovery, preprocessor tracer

Compiler support matrix

Here is a table displaying which engine supports which features:

Feature clang gcc internal msvc null pure_wave templight wave
type shell
preprocessor shell
code completer
header discoverer
metaprogram tracer
cpp validator
macro discovery
preprocessor tracer