Custom compilers

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.

  

  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)

  tip

  Useful tips:

  • You can define multiple compilers in one single file.

  • Parts of the .yaml file can be reused using standard YAML anchor/alias syntax. There may be a non-structured optional aliases section as a container for the reused parts.

  • If Clangd does not support your actual platform, try to use the closest analogue with the same bitness, same byte order, and so on. For example, 8-bit platforms might be declared as avr.

  • If your compiler has custom language keywords (like _DATA_ACCESS for the TI compiler), put them as empty symbols in the defines: block to avoid red code.

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

  • Embarcadero Free C Compiler: configuration file, test project.

  • Texas Instruments Code Generation Tools for MSP430 MCU: configuration file, test project.

  • SDCC for stm8: configuration file, test project.

  note

  If you prepare your own config for your custom compiler, we encourage you to create a pull request in our GitHub repo so it gets published and shared with the community.

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

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

   

   note

   This is a per-project 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:

   

   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.

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:

   

• 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: