CLion 2023.3 Help

Custom compilers

If the compiler you are working with is not supported by default in CLion, switch to the custom compiler option. You can define any compiler not yet known to the IDE, even a rare compiler which may not be available publicly. This option is especially useful for embedded development.

Prepare the compiler description

In order to work with a custom compiler in CLion, you need to create a configuration file with its description in YAML format.

  • In the custom compiler YAML file, you’ll need to identify the following details about your compiler:

    • Supported languages: every supported language or language variant requires at least one configuration section.

    • Compiler binary names (can be more than one): some toolchains have different compiler binaries for C and C++, different memory models, language variants, and so on; this information can be found in the toolchain documentation.

    • Standard include directories location: to identify these directories, read the compiler’s documentation or explore the installed toolchain folder tree.

    • List of predefined macros: some compilers can report a list of their predefined macros, while others can’t; refer to your compiler’s documentation to learn how to get them for your compiler.

    The custom compiler config format includes a mandatory compilers section with a list of records. Every record has a description of a compiler and several tags to identify compiler invocation.

    The first matching record is used to provide compiler information for CLion language engine, including a list of system-defined macros, target platform name for Clangd, and a list of system header paths.

    Custom compiler config example

    description

    compiler name (mandatory parameter)

    match-sources

    regular expression for source file names

    match-compiler-exe

    regular expression for the compiler executable name, required to use a compiler with such name from any location (mandatory parameter)

    match-args

    compiler command line keys

    match-language

    detected language, C or CPP (required for CMake only)

    code-insight-target-name

    target platform name for Clangd

    include-dirs

    compiler-specific header search paths; the variables allowed in this setting are ${compiler-exe}, ${compiler-exe-dir}, ${user-home}, and ${project-path}.

    defines

    compiler-specific macros in the 'name: value' YAML format (the value part can be empty)

    defines-text

    compiler-specific macros in the '#define name value' C format (the value part can be empty)

  • We prepared a few examples to help you start. You can use them as-is or as a template for creating your own configs.

Specify the .yaml config in toolchain settings

  1. Go to Settings | Build, Execution, Deployment | Toolchains | Custom Compiler.

  2. Set the Use custom compiler config (*.yaml) checkbox and provide the path:

    Custom compiler config setting
  3. Switch to the Toolchains dialog and select the toolchain to be edited or create a new one.

  4. Change the paths in the C Compiler and C++ Compiler fields to your custom compiler:

    Specifying a custom compiler in toolchain settings

    Alternatively, you can pass the custom compiler manually in your Makefile or via the CMake profile settings. In this case, the custom compiler will be used for the current project only.

Check the custom compiler

When a custom compiler is configured successfully, your code is resolved correctly and all coding assistance actions work as expected. To double-check that your custom compiler is set up properly, do the following:

  1. Load your CMake, Makefile, or compilation database project.

  2. Open any of the C/C++ project files in the editor.

  3. Call Help | Diagnostics Tool | Show Compiler Info from the main menu.

  4. If everything is okay, you will see the compiler type and name as defined in your config file, as well as the list of compiler predefined macros:

    Compiler info view

Edit the .yaml config in CLion

  • CLion supports the YAML language by default (refer to CLion features in different languages). To get schema-specific verification, code completion, quick documentation, and other actions, switch to the Custom Compiler Definition schema.

    Open the .yaml config, click the schema switcher on the IDE's status bar at the bottom, and select Custom Compiler Definition:

    YAML custom compiler config schema
Last modified: 15 March 2024