# Custom compilers

If the compiler you are working with is not [supported by default](how-to-switch-compilers-in-clion.html) 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](embedded-stm32.html).

> **Tip:**
> See [Custom Compilers in CLion:
> A Quick Guide to Using an Arbitrary Compiler in CLion](https://blog.jetbrains.com/clion/2022/09/custom-compilers/) in CLion blog.

Procedure: 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 cannot; 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 the 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](https://resources.jetbrains.com.cn/help/img/idea/2026.2/cl_customcompiler_yaml_example.png)

|  |  |
| --- | --- |
| `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](settings-languages-cpp-clangd.html)  |
|  `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](https://yaml.org/spec/1.2.2/#3222-anchors-and-aliases) 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](https://github.com/JetBrains/clion-custom-defined-compiler-examples) to help you start. You can use them as-is or as a template for creating your own configs.

* [Embarcadero Free C Compiler](https://www.embarcadero.com/ru/free-tools/ccompiler):[configuration file](https://github.com/JetBrains/clion-custom-defined-compiler-examples/blob/master/CMake-Embarcadero-BCC32C/custom-compiler-bcc.yaml), [test project](https://github.com/JetBrains/clion-custom-defined-compiler-examples/tree/master/CMake-Embarcadero-BCC32C).

* [Texas Instruments Code Generation Tools for MSP430 MCU](https://www.ti.com/tool/MSP-CGT#downloads): [configuration file](https://github.com/JetBrains/clion-custom-defined-compiler-examples/blob/master/CMake-Texas-Instruments-MSP430-CGT/custom-compiler-msp430.yaml), [test project](https://github.com/JetBrains/clion-custom-defined-compiler-examples/tree/master/CMake-Texas-Instruments-MSP430-CGT).

* [SDCC for stm8](http://sdcc.sourceforge.net/): [configuration file](https://github.com/JetBrains/clion-custom-defined-compiler-examples/blob/master/CMake-SDCC/custom-compiler-sdcc-stm8.yaml), [test project](https://github.com/JetBrains/clion-custom-defined-compiler-examples/tree/master/CMake-SDCC).

> **Note:**
> If you prepare your own config for your custom compiler, we encourage you to create a pull request in [our GitHub repo](https://github.com/JetBrains/clion-custom-defined-compiler-examples/tree/master/configs) so it gets published and shared with the community.

Procedure: 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](https://resources.jetbrains.com.cn/help/img/idea/2026.2/cl_customcompiler_enable_setting.png)

> **Note:**
> This is a per-project setting.

3. Switch to the Toolchains dialog and select the toolchain to be edited or [create](how-to-create-toolchain-in-clion.html#new-toolchain) 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](https://resources.jetbrains.com.cn/help/img/idea/2026.2/cl_customcompiler_toolchain_settings.png)

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

Procedure: 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](reloading-project.html), [Makefile](makefiles-support.html#load-makefile-project), or [compilation database](compilation-database.html#compdb_load) 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](https://resources.jetbrains.com.cn/help/img/idea/2026.2/cl_customcompiler_showcompilerinfo.png)

Procedure: Edit the .yaml config in CLion

* CLion supports the YAML language by default (refer to [CLion features in different languages](clion-features-in-different-languages.html)). 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](https://resources.jetbrains.com.cn/help/img/idea/2026.2/cl_yaml_schema.png)

## See also

### Tutorials

[Custom Compilers in CLion:
A Quick Guide to Using an Arbitrary Compiler in CLion (blog post)](https://blog.jetbrains.com/clion/2022/09/custom-compilers/)

### How tos

[Embedded development](embedded-overview.html) [Compilers](how-to-switch-compilers-in-clion.html) [Toolchains](how-to-create-toolchain-in-clion.html)

### Procedures

[Quick CMake Tutorial](quick-cmake-tutorial.html) [Makefile projects](makefiles-support.html) [Compilation database](compilation-database.html)