352 lines
13 KiB
Plaintext
352 lines
13 KiB
Plaintext
*cmake.txt* Vim/Neovim plugin for working with CMake projects
|
|
*cmake* *vim-cmake*
|
|
|
|
Maintainer: Carlo Delle Donne <https://github.com/cdelledonne>
|
|
Version: 0.7.1
|
|
|
|
==============================================================================
|
|
CONTENTS *cmake-contents*
|
|
|
|
1. Intro .............................................. |cmake-intro|
|
|
2. Usage .............................................. |cmake-usage|
|
|
3. Commands ........................................... |cmake-commands|
|
|
3.1 Generating a project build system .............. |cmake-generate|
|
|
3.2 Building and installing a project .............. |cmake-build|
|
|
3.3 Switch between build configurations............. |cmake-switch|
|
|
3.4 Opening and closing the CMake console .......... |cmake-console|
|
|
3.5 Stopping the running command ................... |cmake-stop|
|
|
4. Mappings ........................................... |cmake-mappings|
|
|
4.1 Global <Plug> mappings ......................... |cmake-plug-mappings|
|
|
4.2 CMake console window key mappings .............. |cmake-key-mappings|
|
|
5. Events ............................................. |cmake-events|
|
|
6. Quickfix list ...................................... |cmake-quickfix|
|
|
7. Configuration ...................................... |cmake-configuration|
|
|
8. Contributing ....................................... |cmake-contributing|
|
|
9. License ............................................ |cmake-license|
|
|
|
|
==============================================================================
|
|
INTRO *cmake-intro*
|
|
|
|
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 and build configurations
|
|
- 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
|
|
|
|
==============================================================================
|
|
USAGE *cmake-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}.
|
|
|
|
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. Read on for a detailed explanation of commands,
|
|
mappings and configuration options.
|
|
|
|
==============================================================================
|
|
COMMANDS *cmake-commands*
|
|
|
|
Vim-CMake defines a small set of CMake-related commands.
|
|
|
|
------------------------------------------------------------------------------
|
|
*cmake-generate*
|
|
Generating a project build system~
|
|
*:CMakeGenerate*
|
|
:CMakeGenerate[!] [config] [opts]
|
|
Generate project build system for a CMake project. If
|
|
[!] is supplied, the existing build system is removed
|
|
before generating a new one. [config] specifies the
|
|
build configuration to generate. [opts] are passed
|
|
directly to CMake.
|
|
|
|
By default, the build system is generated for the build configuration
|
|
specified by `g:cmake_default_config` (see |cmake-configuration|). For
|
|
instance, if the default build configuration is "Debug", `cmake` will be
|
|
passed `-D CMAKE_BUILD_TYPE=Debug`, and the build system will be generated in
|
|
`Debug/`, relative to `g:cmake_build_dir_location` (see
|
|
|cmake-configuration|). That will result in the following `cmake` command:
|
|
>
|
|
cmake -D CMAKE_BUILD_TYPE=Debug [...] \
|
|
-S <project_root> -B <build_dir_location>/Debug
|
|
<
|
|
To generate a build system for another configuration, e.g., "Release", run
|
|
>
|
|
:CMakeGenerate Release [...]
|
|
<
|
|
which will result in the following `cmake` command:
|
|
>
|
|
cmake -D CMAKE_BUILD_TYPE=Release [...] \
|
|
-S <project_root> -B <build_dir_location>/Release
|
|
<
|
|
To generate a build system for a configuration, while passing a different
|
|
`CMAKE_BUILD_TYPE` to `cmake`, run
|
|
>
|
|
:CMakeGenerate SomeConfigName -D CMAKE_BUILD_TYPE=Release [...]
|
|
<
|
|
which will result in the following `cmake` command:
|
|
>
|
|
cmake -D CMAKE_BUILD_TYPE=Release [...] \
|
|
-S <project_root> -B <build_dir_location>/SomeConfigName
|
|
<
|
|
Use |:CMakeSwitch| to switch between build configurations.
|
|
|
|
*:CMakeClean*
|
|
:CMakeClean Remove project build system relative to the current
|
|
build configuration.
|
|
|
|
------------------------------------------------------------------------------
|
|
*cmake-build*
|
|
Building and installing a project~
|
|
*:CMakeBuild*
|
|
:CMakeBuild[!] [opts] [target] [-- [nativeopts]]
|
|
Build a project using the generated build system
|
|
from the current build configuration, and populate a
|
|
quickfix list (see |cmake-quickfix|). If [!] is
|
|
supplied, the existing build files are cleaned (using
|
|
CMake's `--clean-first` option) before building the
|
|
project. [opts] are passed directly to CMake.
|
|
[target] is the target to build instead of the default
|
|
target. [nativeopts] are passed directly to the
|
|
native tool.
|
|
|
|
For instance, to build the target `mytarget` using a maximum of 4 processes
|
|
and passing the `VERBOSE=1` option to the native tool, run
|
|
>
|
|
:CMakeBuild --parallel 4 mytarget -- VERBOSE=1
|
|
<
|
|
Vim-CMake provides autocompletion for build targets. Just press <TAB> at any
|
|
point after `:CMakeBuild` in the command line to trigger autocompletion, e.g.
|
|
>
|
|
:CMakeBuild --parallel 4 <TAB>
|
|
<
|
|
*:CMakeInstall*
|
|
:CMakeInstall Install a project from the current build
|
|
configuration.
|
|
|
|
------------------------------------------------------------------------------
|
|
*cmake-switch*
|
|
Switching between build configurations~
|
|
*:CMakeSwitch*
|
|
:CMakeSwitch {config} Switch to build configuration {config}. The build
|
|
configuration must exist, that is, there has to be a
|
|
project build system (for instance generated with
|
|
|:CMakeGenerate|) in the directory {config}.
|
|
|
|
For instance, to switch to an existing configuration called "Release", run
|
|
>
|
|
:CMakeSwitch Release
|
|
<
|
|
The default build configuration on start-up is specified by
|
|
`g:cmake_default_config` (see |cmake-configuration|). Use |:CMakeGenerate| to
|
|
generate a build configuration.
|
|
|
|
Vim-CMake provides autocompletion for existing build configurations. Press
|
|
<TAB> after `:CMakeSwitch` in the command line to trigger autocompletion.
|
|
|
|
------------------------------------------------------------------------------
|
|
*cmake-console*
|
|
Opening and closing the CMake console~
|
|
*:CMakeOpen*
|
|
:CMakeOpen Open the CMake console window.
|
|
|
|
*:CMakeClose*
|
|
:CMakeClose Close the CMake console window.
|
|
|
|
------------------------------------------------------------------------------
|
|
*cmake-stop*
|
|
Stopping the running command~
|
|
*:CMakeStop*
|
|
:CMakeStop Stop the command that is currently running in the
|
|
Vim-CMake console. Stopping a command does not
|
|
trigger the associated events (see |cmake-events|).
|
|
|
|
==============================================================================
|
|
MAPPINGS *cmake-mappings*
|
|
|
|
In addition to commands, Vim-CMake defines some global <Plug> mappings and
|
|
some key mappings specific to the CMake console window.
|
|
|
|
------------------------------------------------------------------------------
|
|
*cmake-plug-mappings*
|
|
Global <Plug> mappings~
|
|
|
|
<Plug>(CMakeGenerate) Equivalent to `:CMakeGenerate`.
|
|
|
|
<Plug>(CMakeClean) Equivalent to `:CMakeClean`.
|
|
|
|
<Plug>(CMakeBuild) Equivalent to `:CMakeBuild`.
|
|
|
|
<Plug>(CMakeBuildTarget)
|
|
Inserts `:CMakeBuild` in the command line, and leaves
|
|
the cursor there.
|
|
|
|
<Plug>(CMakeInstall) Equivalent to `:CMakeInstall`.
|
|
|
|
<Plug>(CMakeSwitch) Inserts `:CMakeSwitch` in the command line, and leaves
|
|
the cursor there.
|
|
|
|
<Plug>(CMakeOpen) Equivalent to `:CMakeOpen`.
|
|
|
|
<Plug>(CMakeClose) Equivalent to `:CMakeClose`.
|
|
|
|
<Plug>(CMakeStop) Equivalent to `:CMakeStop`.
|
|
|
|
Example usage of the <Plug> mappings:
|
|
>
|
|
nmap <leader>cg <Plug>(CMakeGenerate)
|
|
nmap <leader>cb <Plug>(CMakeBuild)
|
|
nmap <leader>ci <Plug>(CMakeInstall)
|
|
nmap <leader>cs <Plug>(CMakeSwitch)
|
|
nmap <leader>cq <Plug>(CMakeClose)
|
|
<
|
|
------------------------------------------------------------------------------
|
|
*cmake-key-mappings*
|
|
CMake console window key mappings~
|
|
|
|
cg Run `:CMakeGenerate`.
|
|
|
|
cb Run `:CMakeBuild`.
|
|
|
|
ci Run `:CMakeInstall`.
|
|
|
|
cq Close the CMake console window.
|
|
|
|
<C-C> Stop the running command.
|
|
|
|
==============================================================================
|
|
EVENTS *cmake-events*
|
|
|
|
To customize the behaviour after a `:CMakeBuild` command has finished, Vim-CMake
|
|
defines some user events.
|
|
|
|
`CMakeBuildFailed` Triggered after a build has failed
|
|
`CMakeBuildSucceeded` Triggered after a build has succeeded
|
|
|
|
Example usage of `CMakeBuildFailed` to jump to the first error
|
|
>
|
|
let g:cmake_jump_on_error = 0 " We do not want to focus the console
|
|
augroup vim-cmake-group
|
|
autocmd User CMakeBuildFailed :cfirst
|
|
augroup END
|
|
<
|
|
Example usage of `CMakeBuildSucceeded` to close the Vim-CMake console
|
|
>
|
|
augroup vim-cmake-group
|
|
autocmd! User CMakeBuildSucceeded CMakeClose
|
|
augroup END
|
|
<
|
|
==============================================================================
|
|
QUICKFIX LIST *cmake-quickfix*
|
|
|
|
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|).
|
|
|
|
Build errors are parsed using 'errorformat'.
|
|
|
|
==============================================================================
|
|
CONFIGURATION *cmake-configuration*
|
|
|
|
Vim-CMake has sensible defaults, but aims to be configurable. A list of
|
|
configuration options, with default values, follows.
|
|
|
|
g:cmake_command (default: `'cmake'`)
|
|
Name (or full path) of the CMake executable.
|
|
|
|
g:cmake_default_config (default: `'Debug'`)
|
|
Default build configuration on start-up.
|
|
|
|
g:cmake_build_dir_location (default: `'.'`)
|
|
Location of the build directory, relative to the
|
|
project root. Each build configuration creates a
|
|
build directory at this location.
|
|
|
|
g:cmake_generate_options (default: `[]`)
|
|
List of options to pass to CMake by default when
|
|
running |:CMakeGenerate|.
|
|
|
|
g:cmake_build_options (default: `[]`)
|
|
List of options to pass to CMake by default when
|
|
running |:CMakeBuild|.
|
|
|
|
g:cmake_native_build_options (default: `[]`)
|
|
List of options to pass to the native tool by default
|
|
when running |:CMakeBuild|.
|
|
|
|
g:cmake_console_size (default: `15`)
|
|
Size of the CMake console window.
|
|
|
|
g:cmake_console_position (default: `'botright'`)
|
|
Command modifier to use when opening the CMake console
|
|
window (see |:botright|).
|
|
|
|
g:cmake_console_echo_cmd (default: `1`)
|
|
Echo running command in the Vim-CMake console, before
|
|
showing the output for the command itself.
|
|
|
|
g:cmake_jump (default: `0`)
|
|
Whether to jump to the CMake console window when
|
|
running a `:CMake` command.
|
|
|
|
g:cmake_jump_on_completion (default: `0`)
|
|
Whether to jump to the CMake console window when a
|
|
`:CMake` command completes.
|
|
|
|
g:cmake_jump_on_error (default: `1`)
|
|
Whether to jump to the CMake console window when a
|
|
`:CMake` command returns an error.
|
|
|
|
g:cmake_link_compile_commands (default: `0`)
|
|
Whether to create a symlink in the CMake source
|
|
directory to the `compile_commands.json` file. If
|
|
this is enabled, the CMake configuration options
|
|
`CMAKE_EXPORT_COMPILE_COMMANDS` will be set to `ON`
|
|
(unless explicitly set to something else in the
|
|
command-line arguments to `:CMakeGenerate`). NOTE:
|
|
under MS-Windows, creating symlinks only work if the
|
|
"Developer mode" is enabled, or if running the console
|
|
as an administrator.
|
|
|
|
g:cmake_root_markers (default: `['.git', '.svn']`)
|
|
List of file/directory names used to locate the
|
|
project root. When Vim-CMake is loaded, it looks for
|
|
the project root starting from the CWD.
|
|
|
|
g:cmake_log_file (default: `''`)
|
|
Path to a file where to store the log of Vim-CMake.
|
|
An empty value disables logging.
|
|
|
|
==============================================================================
|
|
CONTRIBUTING *cmake-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:
|
|
|
|
https://github.com/cdelledonne/vim-cmake/blob/master/CONTRIBUTING.md
|
|
|
|
==============================================================================
|
|
LICENSE *cmake-license*
|
|
|
|
MIT license. Copyright (c) 2020-2022 Carlo Delle Donne.
|
|
|
|
------------------------------------------------------------------------------
|
|
vim:tw=78:ts=8:noet:ft=help:norl:
|