Early Access Program News

CLion 2021.3 EAP: Custom Compiler

The CLion 2021.3 Early Access Preview program has now begun and it includes several useful new features for you to try:

  • New type hints in the editor.
  • Parallel Stacks view in the debugger and new views for multi-threaded FreeRTOS debugging.
  • Ninja as the default generator in CMake.
  • Bundled MinGW and System Toolchain on Windows.
  • New Docker toolchain.

The new EAP build, 213.4928.11, is available from our website via the Toolbox App, or as a snap package (if you are using Ubuntu). If you are on macOS, there is a separate build for Apple silicon (M1 chip). A patch update will also be available shortly.


Using a Custom Compiler in CLion

CLion works with a predefined set of compilers (GCC-based family of compilers, Clang and Clang-cl, Visual Studio C++ compiler, and IAR compiler). The IDE needs to know how to extract compiler information, like compiler predefined macros, in order to correctly resolve the code. That’s why the set of compilers CLion can work with is limited. However, it is common to use a custom compiler not yet known to the IDE, like for embedded development. In this case, a new Custom Compiler can be helpful! This is a way to describe all the necessary information about the compiler in a way CLion understands.

A custom compiler might be a bit tricky to configure from scratch, but is the most general and customizable way to work with rare compilers which may not even be available publicly, but you are using in your project.

Configuring a custom compiler in CLion

To work with custom compilers in CLion, you need to enable it and configure the path to the config file in *.yaml format that contains your custom compiler definition. You can do this in Preferences/Settings | Build, Execution, Deployment | Toolchains | Custom Defined Compiler.
Enable Custom Defined Compiler

Next, open the toolchain you’re going to use and update the path to C and C++ compilers there to your custom compilers:
Custom Compiler toolchain
Alternatively, you can pass the custom compiler via the Makefile or CMake settings.

To check the custom compiler is working:

  1. Load your CMake, Makefile, or compilation database project.
  2. Open any C or C++ file in the editor.
  3. Call the Help | Diagnostics Tool | Show Compiler Info action.

Note: C or C++ files belonging to the project have to be opened, otherwise the action won’t be available in the corresponding submenu.

If everything is okay, you’ll see the compiler type and name as defined in your config file, as well as the list of compiler predefined macros read from the config:
Compiler Info collected
Your code should be resolved correctly in CLion and all code assistance actions should work correctly as well.

That’s it! But what about this *.yaml config file? You need to provide it to CLion, so let’s see how you can create it.

How-to: Examples of custom compiler config files

We have prepared a few examples for you. You can use them as-is or use them as a template for creating your own config files.

  1. Embarcadero Free C Compiler: find the example of the configuration file and the test project on our GitHub.
  2. Texas Instruments Code Generation Tools for MSP430 MCU: find the example of the configuration file and the test project on our GitHub.
  3. SDCC for stm8: find the example of the configuration file and the test project on our GitHub.

How-to: Custom compiler config format

The file contains a mandatory compilers section, with a list of records. Every record has a mandatory description of a compiler and several tags to identify compiler invocation. The invocation is described with:

  • description – the compiler name (mandatory parameter)
  • match-sources – source file name regular expression
  • match-compiler-exe – regular expression with the compiler executable name (in order to use a compiler with such name from any location)
  • match-args – compiler command-line keys
  • match-language – detected language, C or CPP (this is required for CMake only)
  • code-insight-target-name – target platform name for clangd
  • include-dirs – compiler-specific header search paths. Variables allowed in this setting: ${compiler-exe}, ${compiler-exe-dir}, ${user-home}, ${project-path}.
  • defines – compiler-specific macros in the 'name: value' .yaml format. The value can be empty.
  • defines-text – compiler-specific macros in the '#define name value' C format. The value can be empty

Custom Compiler config

The first matching section is used to provide information for the compiler invocation (i.e. source file) to the CLion language engine, including a list of system-defined macros, target platform name for clangd, and a list of system header folders.

A few tips to note here:

  1. Parts of the .yaml file may be reused using standard YAML anchor/alias syntax. There may be a non-structured optional aliases section as a container for the reused parts.
  2. Multiple compilers may be defined using one single file.
  3. If clangd does not support your actual platform, try to use the closest analogue, i.e. same bitness, same byte order, etc.

If you prepare a configuration file for some known yet unsupported compiler in CLion, feel free to publish it and share with the community in the comments section below! We’ll be happy to include the links to our online documentation on the Custom Compiler feature.

The full release notes are available here.


Your CLion team
The Drive to Develop