--- /dev/null
+title: mkbuild
+linktitle: mkbuild
+parent: 2016-01
+ctime: 2016-01-18
+mtime: 2016-01-18
+
+# mkbuild -- An intro
+
+mkbuild is a make-based build system we've used for many embedded projects over
+the years. The goal of this build system is to provide efficient management of
+common code targeting multiple deeply embedded platforms. This happens quite
+frequently in our embedded development business. For example, a customer might
+go through several implementations of a hardware platform as the design is
+researched, evaluated, and refined.
+
+mkbuild achieves its objectives by providing a framework where a common set of
+component interfaces can have multiple implementations, with selection of
+implementations based on information ultimately associated with the hardware
+platform for which the code is being compiled. The methodology is rather
+straight-forward:
+
+* Code is organized into components. Each component is a directory which also
+ contains an `import.mk` file, which provide the necessary build instructions
+ for that component.
+* mkbuild crafts a list of include directories from which to search for
+ components, based in part upon the hardware platform targeted for compilation.
+* The application Makefile, and other components, may state a dependency on a
+ particular component by naming that component via a make include directive.
+ Multiple implementations may exist for the same component interface, placed
+ within different directories, allowing for a unified application build for
+ different platforms.
+
+Here's an example. Say that each platform has its own implementation of a
+component called stdio, which provides a simple byte-based IO interface to the
+outside world. Each platform's implementation would be present in a
+platform-specific directory. mkbuild, during build, would include the proper
+directory for the platform for which the code is being compiled. Since each
+component implements the same interface, higher level code using the stdio
+component will be platform independent.
+
+# Code directories
+
+mkbuild enforces a directory structure onto the code it compiles. Each
+application is placed in its own repository, and may contain both the
+application's main source code units in addition to any application specific
+component implementations. Other code used by an application will generally be
+shared code, and is therefore stored in a shared respository. mkbuild supports
+one, or more, shared code paths, where each path points to a checkout of the
+associated shared repository. Generally we've used a single library for
+simplicity. Below is an example of two repositories checked out on a developer
+workstation: an application `someapp` and a shared library `shared`.
+
+ workspace
+ |
+ +-- someapp
+ | |
+ | +-- Makefile
+ | +-- someapp.c
+ | +-- componentA
+ | |
+ | +-- import.mk
+ | +-- componentA.c
+ | +-- componentA.h
+ +-- shared
+ |
+ +-- mkbuild
+ | |
+ | +-- (mkbuild files)
+ |
+ +-- components
+ | |
+ | +-- kinetis
+ | | |
+ | | +-- componentB (kinetis uC specific component)
+ | |
+ | +-- nxp_lpc
+ | | |
+ | | +-- componentB (lpc uC specific component)
+ | |
+ | +-- nvcfg
+ | +-- sio
+ | +-- verinfo
+ |
+ +-- platforms
+ |
+ +-- platformA
+ | |
+ | +-- mkincludes.mk
+ | +-- rules.mk
+ | +-- ucinit
+ | | |
+ | | +-- ucinit.c
+ | |
+ | +-- componentC (platform specific)
+ |
+ +-- platformB
+
+
+mkbuild enforces a general structure to shared libraries, and provides an
+application Makefile template. Combined, mkbuild is able to construct a
+directory search path used during compilation for source code selection.
+
+# Navigating platform code
+
+One challenge posted by the strategy employed by mkbuild is code management.
+If, for example, there exist a half-dozen implementations of a given component,
+which one is used for compilation of a given platform? The developer can
+examine the include directory order used during the build, finding the first
+occurrence of the component. But a simpler solution is to have mkbuild provide
+some cross reference information which can then be used by a code editor.
+
+mkbuild builds two cross reference databases as part of a successful build
+operation: a ctags tags file, and a cscope database. Since the build products
+are placed in a platform-specific build directory, cross references are
+appropriately platform specific. Code inspection tools and editors can use
+these reference sources for effective code navigation.
+
--- /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 / commitdiff