X-Git-Url: https://oss.titaniummirror.com/gitweb?a=blobdiff_plain;f=in%2Fblog%2Fvim-mkbuild.md;fp=in%2Fblog%2Fvim-mkbuild.md;h=8e0e8aaef8322d8f268fd41f47064b6096f3ba62;hb=a1aa195781628088eaf92a1f53cefe392b29871b;hp=0000000000000000000000000000000000000000;hpb=ebd5ba42e384ea23ca335f52aea34e2bad2ba4c4;p=oss-web.git

diff --git a/in/blog/vim-mkbuild.md b/in/blog/vim-mkbuild.md
new file mode 100644
index 0000000..8e0e8aa
--- /dev/null
+++ b/in/blog/vim-mkbuild.md
@@ -0,0 +1,103 @@
+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.
+