From: R. Steve McKown Date: Tue, 19 Jan 2016 01:59:05 +0000 (-0700) Subject: Articles on mkbuild X-Git-Url: https://oss.titaniummirror.com/gitweb?p=oss-web.git;a=commitdiff_plain;h=a1aa195781628088eaf92a1f53cefe392b29871b Articles on mkbuild --- diff --git a/in/blog/2016-01.md b/in/blog/2016-01.md new file mode 100644 index 0000000..5dda90d --- /dev/null +++ b/in/blog/2016-01.md @@ -0,0 +1,5 @@ +title: 2016-01 blogs +linktitle: 2016-01 +parent: 2016 +ctime: 2016-01-01 +mtime: 2000-01-01 diff --git a/in/blog/2016.md b/in/blog/2016.md new file mode 100644 index 0000000..a03979a --- /dev/null +++ b/in/blog/2016.md @@ -0,0 +1,5 @@ +title: 2016 blogs +linktitle: 2016 +parent: blog +ctime: 2016-01-01 +mtime: 2000-01-01 diff --git a/in/blog/mkbuild.md b/in/blog/mkbuild.md new file mode 100644 index 0000000..eaffcfd --- /dev/null +++ b/in/blog/mkbuild.md @@ -0,0 +1,117 @@ +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. + 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 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. + +## 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 ` 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 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. + +### 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 e :Unite -start-insert -buffer-name=files mkbuild/file_xref + +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. +