Vim-CMake

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

Installation

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 --recurse-submodules https://github.com/cdelledonne/vim-cmake.git

Usage

Run :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.

Commands and <Plug> mappings

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

Additional <Plug> mappings

<Plug> mapping	Behaves as
(CMakeBuildTarget)	(CMakeBuild), but leaves cursor in the command line

Key mappings

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

Events

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

Quickfix list

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).

Configuration

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

Public API

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.

Contributing

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.

License

Vim-CMake is licensed under the MIT license. Copyright (c) 2020–2024 Carlo Delle Donne.