uCMake.vim

A vim helper for cmake build system.

Features

• Asynchronously configuration and compilation.
• Multi-config support for different build types.
• Multi-project support, no interfering with each other.
• Detect the source tree root automatically.
• Create binary trees for building automatically.
• Link compilation database compile_commands.json automatically.
• Automatically pass some common used options to cmake, such as -DCMAKE_BUILD_TYPE=Debug . As long as any additional options.

uCmake.vim needs vim with +job feature, to run cmake asynchronously. It is such a common requirement in nowadays.

Usage

uCMake.vim provides several commands to make it easier to use cmake in vim:

:Cmake

For running configuration for all active config types. Any additional cmake options can be appended to the command.

:Amake

For running compilation for all active config types. Additional make options such as -j4 could be appended directly, such as :Amake test -j4 . This is the asynchronous version of :make .

:make

It is just the original built-in command for compilation. In the case of multi-config, it only applies to the first one. Additional make options such as -j4 should be appended directly, such as :make test -j4 .

Every commands above will create one quickfix list of their own. To switch between these lists use commands such as :col :cnew :chi .

Options

uCMake.vim provides options to tweek its behavior:

g:ucmake_open_quickfix_window

1 enable to open quickfix windows for commands output. This is the default value. While 0 is disabled to.

This option has no nothing to do with the built-in :make command.

g:ucmake_cmakelists_file

A string of the cmake lists file name, used to detect the top most cmake list file. The default value is 'CMakeLists.txt' .

g:ucmake_cmake_prg

A string of the cmake program, used to run the cmake program. The default value is 'cmake' . If the program can not be find in the $PATH enviroment, provide a absolute path, suct as g:ucmake_cmake_prg = '/path/to/cmake' .

g:ucmake_source_tree_root_symbolics

A string list specifying symbolic to detect the source tree root. The default value is ['.git', 'CMakeLists.txt'] .

g:ucmake_active_config_types

A string list specifying all active configuration types to be generated. The defult value is ['Debug'] . Another sample for multi-config could be: ['Release', 'Debug'] .

Always keep items in this list unique.

g:ucmake_enable_link_compilation_database

If true, link compilation database to g:ucmake_compilation_database_link_target . The default value is 'ON' .

g:ucmake_binary_directory

A string specifying where the binary tree(s) located. Sepcial macros in it are allowed. The default value is ../build_{project_name}_{build_type} . Available values could be:

• {source_tree_root} or empty, means the source tree root. This will result building in source tree.
• /path/to/build-tree absolute path for building.
• ../build-tree relative path to the source tree root. Not relative to the current working directory.
• ../build-{project_name}-{build_type} path with macros, either absolute or relative are both ok.

If multi-config types are provided in g:ucmake_active_config_types , without {build_type} macro in it, then the build type macro will be appended to the build target directly.

For example, if g:ucmake_active_config_types=['Release', 'Debug'] , and g:ucmake_binary_directory='/path/to/build' , uCMake.vim will threat it as /path/to/build{build_type} .

g:ucmake_compilation_database_link_target

A string specifying the location where the compilation database linked to. Available value is the same with g:ucmake_binary_directory . The default value is empty, means the source tree root.

In the case of multi-config, only the database generated by the first configuration will be link to g:ucmake_compilation_database_link_target .

g:ucmake_compilation_database_name

File name of the compilation database generated by cmake. The default value is compile_commands.json .

This option is used to search the database only, not for the linking target. To specify the link target name of the database, just use g:ucmake_compilation_database_link_target instead.

g:ucmake_cache_entries

A dictionary containing variables to pass to cmake with -D . Every key-value pair in the dictionary is one cmake cache entry and its value. For example, g:ucmake_cache_entries={'CMAKE_INSTALL_PREFIX':'tmp'} will pass -DCMAKE_INSTALL_PREFIX=tmp to cmake.

Don't define CMAKE_BUILD_TYPE and CMAKE_EXPORT_COMPILE_COMMANDS in the dictionary, use g:ucmake_active_config_types and g:ucmake_enable_link_compilation_database instead.

Macros

uCMake.vim provides some read-only macros to use in options, which will be replace with their own values when applied. They are:

• {source_tree_root} the full path of the source tree root.
• {project_name} the directory name of the source tree root.
• {build_type} the build type about to use.
• {top_cmakelists} the full path of the top most CMakeLists.txt file.

Installation

Any vim package manager plugin can easily install uCmake.vim, just use your favorite one, and import uCmake.vim as your other packages do.

You can also use the the built-in :packadd command to install manually. It is not so difficult.

TODOs

• vim documentation.
• cmake server.
• remove {source_tree_root} and {top_cmakelists} , useless.
• fix the fail set cwd in job_start() for cmake.