cmake4vim - CMake integration to Vim/Neovim

I created this plugin in order to improve integration CMake to the Vim editor. I tried different plugins for vim which allow to work with cmake but I didn't find the plugin which was satisfied my requrements.

Key features

• Written in pure Vimscript
• The plugin supports next CMake Generators:
  • Unix Makefiles
  • Visual Studio
  • Ninja
• The plugin shows cmake results using quickfix list. If you have installed vim-dispatch plugin, plugin will use it, this means that if you are using vim with tmux, cmake output will be printed in a separate window. In other case plugin will use jobs to async run if your Vim editor supports it.
• The plugin shows cmake results using quickfix list. If you have installed vim-dispatch plugin, plugin will use it, this means that if you are using vim with tmux, cmake output will be printed in a separate window. In other case plugin will use jobs to async run if your Vim editor supports it. * The plugin allows to specify cmake targets in order to avoid building of all project.
• The plugin has an integration with next fuzzy finder plugins:
  • CtrlP
  • FZF
  • Telescope is supported through extension.
• The plugin allows to specify make arguments for native build system (for example -jN and something else for Unix Make).
• The plugin parses the output of cmake command and supports jump to warnings or errors.
• Supports work with multiple build types
• For CMake newer than 3.13 the plugin uses the CMake file API
• Plugin allows to find and run executable file for selected target.
• Plugin supports Vimspector plugin. Plugin can generate and modify Vimspector configuration file in order to save command line arguments and allows to debug application.

Extensions

• SantinoKeupp/telescope-cmake4vim.nvim - Telescope integration.
• SantinoKeupp/lualine-cmake4vim.nvim - Integration with Lualine. Plugin adds information about elected kit, build type and build target.
• ilyachur/gtest-vim - Integrates vim with gtest. Plugin has a dependency on cmake4vim and can use cmake4vim capabilities to detect gtest executables.

Usage

Installation

You can use VimPlug for installation:

Plug 'ilyachur/cmake4vim'

Or Pathogen:

cd ~/.vim/bundle
git clone https://github.com/ilyachur/cmake4vim

Commands

The current version of the plugin supports next commands:

Basic

• :CMake creates a build directory (if it is necessary) and generates cmake project.
• :CMakeResetAndReload removes cmake cache and re-generates cmake project.
• :CMakeReset removes cmake cache (this command removes the cmake build directory).
• :CMakeBuild builds current cmake project. The command allows to specify cmake target.
• :CMakeSelectTarget selects a target for project. You should put target name as a command line argument.
• :CMakeSelectBuildType changes the cmake build type with argument passed and call :CMake.
• :CMakeInfo creates a window with CMake information.
• :CMakeClean cleans the project (it is equal of the execution make clean).
• :CMakeCompileSource compiles source file in current buffer.

Execute

• :CMakeRun Run the current the binary of currently selected target. Allows to automatically change the Vimspector config file.
• :CMakeRun! Run the current the binary of currently selected target. Command allows to reset previous arguments if plugin reads arguments from Vimspector config.
• :CTest run ctest. The command allows to specify CTest arguments and default arguments can be set in g:cmake_ctest_args
• :CTest! same as :CTest but ignores g:cmake_ctest_args.
• :CTestCurrent same as :CTest but run tests with -R current_cmake_target.
• :CTestCurrent! same as :CTest! but run tests with -R current_cmake_target.

Integration

• :CCMake allow to use ccmake command inside vim. The command supports next open modes: 'vsplit' - vertical mode, 'split' - horizontal mode, 'tab' - open ccmake in the new tab (by default the executor window split mode is used).

FZF plugins

• :CtrlPCMakeTarget you can use CtrlP in order to select a target for project.
• :CtrlPCMakeBuildType allows to use CtrlP in order to select a project build type.
• :CtrlPCMakeKit uses CtrlP to select a CMake kit for project.
• :FZFCMakeSelectTarget you can use FZF in order to select a target for project.
• :FZFCMakeSelectBuildType allows to use FZF in order to select a project build type.
• :FZFCMakeSelectKit uses FZF to select a CMake kit for project.

<Plug> mappings

<Plug> mapping	Command
(CMake)	:CMake
(CMakeResetAndReload)	:CMakeResetAndReload
(CMakeReset)	:CMakeReset
(CMakeBuild)	:CMakeBuild
(CMakeClean)	:CMakeClean
(CMakeInfo)	:CMakeInfo
(CMakeRun)	:CMakeRun
(CTest)	:CTest
(CTestCurrent)	:CTestCurrent
(CCMake)	:CCMake
(CMakeCompileSource)	:CMakeCompileSource

Variables

Plugin supports special global variables which are allow to change behaviour of commands (you can change them in your .vimrc):

Common

The options below allow to change plugin behavior.

• g:cmake_executable the path to CMake. Default is 'cmake'.
• g:cmake_reload_after_save if this variable is not equal 0, plugin will reload CMake project after saving CMake files. Default is 0.
• g:cmake_change_build_command if this variable is not equal 0, plugin will change the make command. Default is 1.
• g:cmake_compile_commands if this variable is not equal 0, plugin will generate compile commands data base. Default is 0.
• g:cmake_compile_commands_link set the path for a link on compile_commands.json. Default is empty.
• g:cmake_vimspector_support enables generation and modification of Vimspector config file. Default is 0.
• g:cmake_vimspector_default_configuration is a default configuration for new vimspector target. Default is:

   let g:cmake_vimspector_default_configuration = {
               \ 'adapter': '',
               \ 'configuration': {
                   \ 'request': 'launch',
                   \ 'cwd': '${workspaceRoot}',
                   \ 'Mimode': '',
                   \ 'args': [],
                   \ 'program': ''
                   \ }
               \ }

• g:cmake_build_executor allows to force set the build executor. Default is empty. Available values are:
  • 'job' uses job to asynchronous build
  • 'term' uses terminal to asynchronous build Experimental
  • 'dispatch' uses vim-dispatch plugin to asynchronous build
  • 'system' uses synchronous build
  • '' uses automatic detection of supported modes (the priority is dispatch, job, term, system)
• g:cmake_build_executor_window_size defines the size of build window and quickfixlist. Default is 10.
• g:cmake_build_executor_split_mode Allows to configure split mode for build window and quickfixlist. Avaulable values are:
  • 'sp' enables horizontal mode. It is the default value.
  • 'vsp' enables vertical mode.
• g:cmake_build_executor_height defines the height (in rows) of the build window and quickfixlist window showing the results. The option was deprecated, please use let g:cmake_build_executor_window_size=<size> instead. Default is 10.

Build path

Below the list of options which allow to customize the path to CMake build directory. The list order is from higher to lower priority (it means if you initialize several options plugin will use the first initialized option from the list):

• g:cmake_build_dir allows to set cmake build directory. Default is ''. If variable is empty the plugin will use the prefix plus build type.
• g:cmake_build_path_pattern pattern for build dir, two strings that will be evaluated in a printf. e.g.: let g:cmake_build_path_pattern = [ "%s/workspace/build/%s/%s/%s", "$HOME, fnamemodify( getcwd(), ':t' ), g:cmake_selected_kit, g:cmake_build_type" ]
• g:cmake_build_dir_prefix allows to set cmake build directory prefix, in this case the plugin uses the next rule to generate build directory name: g:cmake_build_dir_prefix + g:cmake_build_type. This option is used by default, the default prefix is 'cmake-build-'.

CMake build options

The list contains variables which allow to configure CMake build.

• g:cmake_src_dir allows to set cmake source directory. Default is '' which evaluates to the current working directory.
• g:cmake_build_type allows to change -DCMAKE_BUILD_TYPE. Default is empty. If variable is empty, plugin tries to detect cached build type. And selects 'Release' type if cmake cache doesn't exist.
• g:cmake_variants enables predefined cmake build variants in the form of a dictionary, e.g. { 'Debug' : { 'cmake_build_type' : 'Debug', 'cmake_usr_args' : { 'CONAN_PATH' : '~/.conan' } }
• g:cmake_build_target set the target name for build. Default is empty and default value depends on CMake Generator
• g:cmake_usr_args allows to set user arguments for cmake. Default is empty. It can be either a string or a dictionary.
• g:cmake_build_args allows to set custom cmake build arguments (for example --parallel). Default is empty.
• g:make_arguments allows to set custom parameters for make command. Default is empty. If variable is empty, plugin launches make without arguments.
• g:cmake_ctest_args enables arguments for ctest, e.g. '-j8 --output-on-failure --verbose'. Default is empty. If the user calls :CTest <some arguments>, the g:cmake_ctest_args are inserted directly after ctest, before the <some arguments> parameter.
• g:cmake_kits enables predefined cmake kits in the form of a dictionary of dictionaries that specify a toolchain file, environment variables, cmake variables among other things
• g:cmake_kits_global_path specifies a path to the JSON containing cmake kits. Default is empty.
• g:cmake_selected_kit currently selected cmake kit. Default is empty.

Examples

CMake kits can be given in the following ways:

• as a variable g:cmake_kits
• as a JSON file in the current folder named .cmake-kits.json
• as a JSON file specified by g:cmake_kits_global_path variable

The variable g:cmake_kits has the lowest, and the local .cmake-kits.json file has the highest priority.

Example of supported functions in CMake kits:

let g:cmake_kits = {
            \  "android-ndk-r22": {
            \    "toolchain_file": "~/toolchains/android.cmake",
            \    "environment_variables": {
            \      "PATH_TO_CACHE": "/Users/vimmer/cache",
            \      "PATH_TO_CONFIG": "/Users/vimmer/config"
            \    },
            \    "cmake_usr_args": {
            \      "USE_BROWSER": "chrome",
            \      "TIMEOUT_IN_SECONDS": "300"
            \    },
            \    "generator": "Ninja"
            \  } }
let g:cmake_kits = {
            \  "gcc": {
            \    "compilers": {
            \        "C": "/usr/bin/gcc",
            \        "CXX": "/usr/bin/g++"
            \  } }

If you specify both toolchain_file and compilers, the toolchain_file takes precedence and compilers are ignored.

Example of a .cmake-kits.json file:

{ "gcc": {
  "compilers" : {
      "C": "/usr/bin/gcc",
      "CXX": "/usr/bin/g++"
} } }

Jump to

Plugin is closely integrated with quickfix list and allows to use quickfix features to jump between error or warning messages.

• :cp[revious] command jumps to previous error/warning message
• :cn[ext] command jumps to next error/warning message

Demos

• CMakeInfo window:
• Select build type
• Jump to cmake error:
• Ninja compilation error

Contributing

Bug reports, feedback, feature and other pull requests are appreciated. Check the Contributing Guidelines for how to create a feature request, submit a pull request or post an issue.

Tips and tricks

Open shell in the build directory

nnoremap <expr> <leader>db printf(":bo new\<CR>:lcd %s\<CR>:res 15\<CR>:term ++curwin\<CR>", utils#cmake#getBuildDir() )

YouCompleteMe

If you're using YouCompleteMe and want clangd-completer to work with different compilers, you could pass clangd a -query-driver argument.

E.g. for developing emscripten, you could pass em++ to clangd via g:ycm_clangd_args.

You could add such entries to your g:cmake_kits and override CMakeSelectKit and FZFCMakeSelectKit.

Add this to the after directory, e.g. ~/.vim/after/plugin/cmake.vim:

function! s:customSelectKit(name) abort
    let l:loaded_kits = utils#cmake#kits#getCMakeKits()
    if !has_key( l:loaded_kits, a:name )
        call utils#common#Warning(printf("CMake kit '%s' not found", a:name))
        return
    endif

    call cmake4vim#SelectKit(a:name)

    let l:cmake_kit = l:loaded_kits[ g:cmake_selected_kit ]
    let g:ycm_clangd_args = filter( g:ycm_clangd_args, "v:val !~# 'query-driver'" )
    if has_key( l:cmake_kit, 'query_driver' )
        let g:ycm_clangd_args += [ printf( '-query-driver=%s', l:cmake_kit[ 'query_driver' ] ) ]
        YcmRestartServer
    endif
endfunction

function! s:FZFSelectKit() abort
    if exists(':FZF')
        return fzf#run({
                    \ 'source': sort( keys( utils#cmake#kits#getCMakeKits() ), 'i' ),
                    \ 'options': '+m -n 1 --prompt CMakeKit\>\ ',
                    \ 'down':    '30%',
                    \ 'sink':    function('s:customSelectKit')})
    endif
endfunction

command! -nargs=1 -complete=custom,cmake4vim#CompleteKit CMakeSelectKit    call s:customSelectKit(<f-args>)
command!                                                 FZFCMakeSelectKit call s:FZFSelectKit()

Supported CMake version

The plugin supports all CMake versions since 2.8.

Since the CMake 3.14 version the plugin uses file API, this feature helps to have more information about CMake project and implement a smart detection of executable files for :CMakeRun command.

References

Author

Ilya Churaev [email protected]

Licence

MIT