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