vim-mkbuild is a vim plugin that enhances code navigation for projects using the mkbuild build system. When building an application for a particular platform (embedded target), mkbuild generates platform specific ctags and cscope database files. vim-mkbuild leverages these files to provide the following three features:

  • Activate cross reference databases for a compiled platform, selecting from the list of available compiled platforms;

  • Open a file selected from only those source code files compiled when buildng for the selected platform; or

  • Open a file selected from all files within the application project, including files from any external repositories referenced by the application's extrefs file.

vim-mkbuild presents lists of platforms and/or files to the developer using the excellent Unite! plugin for vim. The vim-mkbuild plugin source is available here.

Selecting a platform for cross reference databases

vim-mkbuild provides a Unite! source, mkbuild/xref, used to select cross reference databases for any platform for which the current application code has been built. This source lists all such platforms, and selecting a platform loads its cross reference databases. The mapping we use to run Unite! on the mkbuild/xref source is <leader>x, where x is a mnemonic for "cross reference".

nnoremap <leader>x :<C-u>Unite -buffer-name=xrefs mkbuild/xref<cr>

mkbuild cross references are based only on files actually compiled for the given platform. All other project files are ignored. This is quite useful for mkbuild based applications which tend to both target multiple platforms and use shared libraries containing code supporting many applications.

Navigating code by identifier

Once cross reference databases are selected using the platform selection feature of vim-mkbuild, vim's full ctags and cscope support becomes usable. For a simple example, typing

:ta main

will open a buffer for the source code file containing the main() function's definition, moving the cursor to that definition. Often more productive, place the cursor on any identifier and use vim's "goto tag" function, which we map to g], to navigate to the identifier's definition. Similarly,

:cs f c main

will use the cscope database to jump to the line in the code file containing the call to the main function. This is the (cs)cope (f)ind (c)ode function. It's often more productive to use a mapping to access this cscope feature. The standard mapping for cscope find code is <C-\>c (control backslash, then c).

Plugins that extend vim's tag features, like unite-tags, work perfectly well with vim-mkbuild. We use unite-tags with the following mapping. unite-tags can become slow on code bases of non-trivial size.

nnoremap <leader>ut :<C-u>Unite -start-insert -buffer-name=tags tag<cr>

Navigating code by source code unit

vim-mkbuild allows for fast file select and open in vim through two custom Unite! sources: mkbuild/file and mkbuild/file_xref. These sources define the list of files through which Unite! can search. Unite!'s file search is very powerful; use it and you probably won't want to return to what you used before. See Unite!'s github page for more information.


The mkbuild/file_xref Unite! source includes only the list of souce code files compiled when building the application for the selected platform. We use the mapping <leader>e to use this Unite! source, as a mnemonic for "edit file".

nnoremap <leader>e :<C-u>Unite -start-insert -buffer-name=files mkbuild/file_xref<CR>

If no platform has been selected, then mkbuild/file_xref behaves just like mkbuild/file, described below.


This Unite! source provides the list of project files in the application directory, and those in any referenced repositories, independent of any platform selection via mkbuild/xref. This includes files that are part of the project but never compiled, such as makefiles, documentation, etc. We use the mapping <leader>E to use this Unite! source. The mnenomic is "edit file", with the capitalized E indicating all files.

nnoremap <leader>E :<C-u>Unite -start-insert -buffer-name=files mkbuild/file<CR>