Vim-CMake is a plugin for building CMake projects inside of Vim/Neovim, with a nice visual feedback.
Features
- Visual experience, shows CMake output in a console-like window
- Slick management of build configurations
- Autocompletion for build targets, configurations, executables and tests
- Quickfix list population after each build
- Airline/statusline status information, including current build configuration
- Plug-and-play, but configurable
- Written in Vimscript
Requirements
- Vim with
+terminal, or Neovim >= 0.5 - Under Windows, only Neovim is supported at the moment
- Target completion uses the
cmake-file-api(7), which requires CMake 3.14 or later - Running executables also requires the
cmake-file-api(7), and thus CMake 3.14 or later
Use a package manager like vim-plug:
Plug 'cdelledonne/vim-cmake'or Vim's native package manager:
mkdir -p ~/.vim/pack/plug/start
cd ~/.vim/pack/plug/start
git clone https://github.com/cdelledonne/vim-cmake.gitRun :CMakeGenerate from the top-level CMake source directory to generate a
build system for the project. Then, run :CMakeBuild to build the project.
The built files will end up in the binary directory (out-of-source
build). To switch between build configurations, run :CMakeSwitch <config>. To run executable targets in an overlay window, run :CMakeRun <target>. To run CMake-generated tests with CTest, run :CMakeTest.
With Vim-CMake, you can easily manage build configurations (Debug, Release,
etc.), build specific targets and control build options, and fix errors using
Vim's quickfix feature. For a detailed explanation of commands, mappings and
functionalities run :help cmake. A quick overview follows.
| Command | <Plug> mapping |
Description |
|---|---|---|
:CMakeGenerate[!] |
(CMakeGenerate) |
Generate build system |
:CMakeClean |
(CMakeClean) |
Remove build system and build files |
:CMakeBuild[!] [target] |
(CMakeBuild) |
Build a project |
:CMakeInstall |
(CMakeInstall) |
Install build output |
:CMakeRun <target> |
(CMakeRun) |
Run executable target |
:CMakeTest |
(CMakeTest) |
Run CMake-generated tests with CTest |
:CMakeSwitch <config> |
(CMakeSwitch) |
Switch to another build configuration |
:CMakeOpen |
(CMakeOpen) |
Open CMake console window |
:CMakeClose[!] |
(CMakeClose) |
Close CMake console window |
:CMakeToggle |
(CMakeToggle) |
Toggle CMake console window |
:CMakeCloseOverlay |
(CMakeCloseOverlay) |
Close overlay window |
:CMakeStop |
(CMakeStop) |
Stop running command |
<Plug> mapping |
Behaves as |
|---|---|
(CMakeBuildTarget) |
(CMakeBuild), but leaves cursor in the command line |
Mappings in the CMake console window:
| Key mapping | Description |
|---|---|
cg |
Run :CMakeGenerate |
cb |
Run :CMakeBuild |
ci |
Run :CMakeInstall |
ct |
Run :CMakeTest |
cq |
Run :CMakeClose |
<C-C> |
Stop running command |
Mappings in the overlay window:
| Key mapping | Description |
|---|---|
cq |
Run :CMakeCloseOverlay |
Vim-CMake provides a set of custom events to trigger further actions. Run
:help cmake for full documentation on all configuration options and examples.
| Event | Description |
|---|---|
User CMakeGeneratePre |
Triggered before running :CMakeGenerate |
User CMakeBuildPre |
Triggered before running :CMakeBuild |
User CMakeBuildSucceeded |
Triggered after a successful :CMakeBuild |
User CMakeBuildFailed |
Triggered after a failed :CMakeBuild |
After each build (e.g. run with :CMakeBuild), Vim-CMake populates a quickfix
list to speedup the edit-compile-run cycle, similarly to when running :make in
Vim/Neovim. Upon an unsuccessful build, just use the standard quickfix commands
to open the list of errors (e.g. :copen) and jump between errors (e.g.
:cfirst, :cnext).
Vim-CMake has sensible defaults. Again, run :help cmake for full
documentation on all the configuration options. A list of default values
follows.
| Options | Default |
|---|---|
g:cmake_command |
'cmake' |
g:cmake_test_command |
'ctest' |
g:cmake_default_config |
'Debug' |
g:cmake_build_dir_location |
'.' |
g:cmake_generate_options |
[] |
g:cmake_build_options |
[] |
g:cmake_native_build_options |
[] |
g:cmake_test_options |
[] |
g:cmake_console_size |
15 |
g:cmake_console_position |
'botright' |
g:cmake_console_echo_cmd |
1 |
g:cmake_jump |
0 |
g:cmake_jump_on_completion |
0 |
g:cmake_jump_on_error |
1 |
g:cmake_link_compile_commands |
0 |
g:cmake_root_markers |
['.git', '.svn'] |
g:cmake_log_file |
'' |
g:cmake_log_level |
'INFO' |
g:cmake_statusline |
0 |
g:cmake_restore_state |
1 |
g:cmake_reinit_on_dir_changed |
1 |
Vim-CMake provides a public API to query information about the CMake environment
as well as plugin state. The public API consists of a single function
cmake#GetInfo() which returns a dictionary containing the information. For
extensive information run :help cmake-api.
To show the CMake version in your statusline you could do:
set statusline=%{cmake#GetInfo().cmake_version.string}or integrate this as a component in your preferred statusline plugin.
Feedback and feature requests are appreciated. Bug reports and pull requests are very welcome. Check the Contributing Guidelines for how to write a feature request, post an issue or submit a pull request.
Vim-CMake is licensed under the MIT license. Copyright (c) 2020–2023 Carlo Delle Donne.