From: R. Steve McKown Date: Fri, 4 Mar 2016 03:03:37 +0000 (-0700) Subject: Update vim-mkbuild blog post. X-Git-Url: https://oss.titaniummirror.com/gitweb?p=oss-web.git;a=commitdiff_plain;h=4b585e666be0cdebe2f497f58341a7463456a5cb Update vim-mkbuild blog post. --- diff --git a/in/blog/vim-mkbuild.md b/in/blog/vim-mkbuild.md index 8e0e8aa..f3a6c79 100644 --- a/in/blog/vim-mkbuild.md +++ b/in/blog/vim-mkbuild.md @@ -2,102 +2,102 @@ title: vim-mkbuild linktitle: vim-mkbuild parent: 2016-01 ctime: 2016-01-18 -mtime: 2016-01-18 +mtime: 2016-03-03 # 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: +[[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: -* Identify which component implementations were selected for build of a given - platform, and +* Activate cross reference databases for a compiled platform, selecting from the + list of available compiled platforms; -* Browse the code base through identifiers rather than solely by file. +* Open a file selected from only those source code files compiled when buildng + for the selected platform; or -* 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. +* Open a file selected from all files within the application project, including + files from any external repositories referenced by the application's `extrefs` + file. -The plugin source is available [here](/gitweb/?p=vim-mkbuild.git;a=summary). +[[vim-mkbuild]] presents lists of platforms and/or files to the developer using +the excellent [Unite! plugin for vim](https://github.com/Shougo/unite.vim). The +[[vim-mkbuild]] plugin source is available +[here](/gitweb/?p=vim-mkbuild.git;a=summary). -## Selecting from available cross reference databses +## Selecting a platform for cross reference databases -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: +[[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 `x`, where x is a mnemonic for "cross +reference". nnoremap x :Unite -buffer-name=xrefs mkbuild/xref -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. +[[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 the cross reference databases are loaded, the standard vim ctags and cscope -support becomes available. For a simple example, typing: +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 and move the cursor to that definition. Similarly, +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 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 ` means (cs)cope (f)ind (c)ode. +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` (control backslash, then c). -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: +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 ut :Unite -start-insert -buffer-name=tags tag ## 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 E :Unite -start-insert -buffer-name=files mkbuild/file - -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. +[[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](https://github.com/Shougo/unite.vim) for more +information. ### 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: +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 `e` to use this Unite! source, as a mnemonic for "edit +file". nnoremap e :Unite -start-insert -buffer-name=files mkbuild/file_xref -Selecting a file through this source opens the file in vim. +If no platform has been selected, then `mkbuild/file_xref` behaves just like +`mkbuild/file`, described below. + +### mkbuild/file -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. +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 +`E` to use this Unite! source. The mnenomic is "edit file", with the +capitalized E indicating all files. + + nnoremap E :Unite -start-insert -buffer-name=files mkbuild/file