--- /dev/null
+title: vim-mkbuild
+linktitle: vim-mkbuild
+parent: 2016-01
+ctime: 2016-01-18
+mtime: 2016-01-18
+
+# vim-mkbuild
+
+vim-mkbuild is a vim plugin for supporting code navigation when using the
+[mkbuild] build system. Builds in [mkbuild] are performed for a specific
+platform, with each successful build generating both a ctags tags file and a
+cscope database. Vim users can leverage these references by using the
+vim-mkbuild plugin. This plugin supports three principal use cases:
+
+* Identify which component implementations were selected for build of a given
+ platform, and
+
+* Browse the code base through identifiers rather than solely by file.
+
+* Browse the code based on a file basis, either selecting from all project
+ files, or only those used in the build for a specific platform.
+
+The plugin source is available [here](/gitweb/?p=vim-mkbuild.git;a=summary).
+
+## Selecting from available cross reference databses
+
+Two of the three use cases above require the input of a platform, which has been
+built using mkbuild, for selection of the generated cross reference databases.
+This feature is provided by the custom Unite! source mkbuild/xref provided by
+vim-mkbuild. An example of a mapping for its use:
+
+ nnoremap <leader>x :<C-u>Unite -buffer-name=xrefs mkbuild/xref<cr>
+
+Invoking Unite! using the above mapping will open a vim split populated with all
+of the available platform build directories. The developer will see in this
+list all platforms that have been compiled for the current application.
+Selecting one of the listed platforms will activate its cross reference
+databases.
+
+## Navigating code by identifier
+
+Once the cross reference databases are loaded, the standard vim ctags and cscope
+support becomes available. For a simple example, typing:
+
+ :ta main
+
+Will open a buffer for the source code file containing the main() function's
+definition and move the cursor to that definition. Similarly,
+
+ :cs f c main
+
+will present a list of code locations where the main() function is called. If
+there is only one such location, vim immediately jumps to that location. BTW,
+`cs f c <token>` means (cs)cope (f)ind (c)ode.
+
+The publicly available unite-tags plugin for vim provides a Unite! source that
+searches through the contents of the active tags file(s). This is useful
+because the built-in tags search mechanisms in vim assume one knows some part of
+the identifier of interest starting at its first character. Unite! and the
+unite-tags plugin offers a fuzzy search. A useful mapping is:
+
+ nnoremap <leader>ut :<C-u>Unite -start-insert -buffer-name=tags tag<cr>
+
+## Navigating code by source code unit
+
+vim-mkbuild also allows for navigating the application source code, including
+any referenced shared code repositories by providing two Unite! sources:
+mkbuild/file and mkbuild/file\_xref
+
+### mkbuild/file
+
+This source provides Unite! with a list of all files, regardless of whether they
+were used as part of a specific build. This means this source is available
+whether or not a cross reference has been selected via the `mkbuild/xref` source.
+It also means the list of source files presented is unaffected by the
+cross reference selection. A possible mapping for its use:
+
+ nnoremap <leader>E :<C-u>Unite -start-insert -buffer-name=files mkbuild/file<CR>
+
+Selecting a file through this source opens the file in vim.
+
+Another benefit of this source is that it includes all files, including those
+that aren't directly part of the compilation process. An example is each
+component's import.mk file.
+
+### mkbuild/file\_xref
+
+When a cross reference is not selected, this Unite! source falls back to working
+just like the `mkbuild/file` source. However, if a cross reference is active,
+then only the files used for the selected platform are presented for searching.
+A possible mapping for its use:
+
+ nnoremap <leader>e :<C-u>Unite -start-insert -buffer-name=files mkbuild/file_xref<CR>
+
+Selecting a file through this source opens the file in vim.
+
+This plugin is quite useful. If, for example, a shared library has several
+implementations of the same logical component, only the source units of the
+implementation actually used by the compilation of the platform selected via the
+`mkbuild/xref` source will be available for searching. The down-side of this
+method is that indirect files, such as platform .mk files, are not available via
+this method.
+
projects / oss-web.git / blobdiff