ceedling 1.0.0 → 1.1.0

data/docs/mkdocs/overview/test-environments.md

@@ -0,0 +1,33 @@
+# Test Suite Execution Environments
+
+**All your sweet, sweet test suite options**
+
+Ceedling, Unity, and CMock help you create and run test suites using any 
+of the following approaches. For more on this topic, please see this 
+[handy dandy article][tts-which-build] and/or follow the links for each 
+item listed below.
+
+[tts-which-build]: https://throwtheswitch.org/build/which
+
+1. **[Native][tts-build-native].** This option builds and runs code on your 
+   host system.
+    * In the simplest case this means you are testing code that is intended
+      to run on the same sort of system as the test suite. Your test 
+      compiler toolchain is the same as your release compiler toolchain.
+    * However, a native build can also mean your test compiler is different
+      than your release compiler. With some thought and effort, code for
+      another platform can be tested on your host system. This is often
+      the best approach for embedded and other specialized development.
+1. **[Emulator][tts-build-cross].** In this option, you build your test code with your target's
+   toolchain, and then run the test suite using an emulator provided for
+   that target. This is a good option for embedded and other specialized
+   development — if an emulator is available.
+1. **[On target][tts-build-cross].** The Ceedling bundle of tools can create test suites that
+   run on a target platform directly. Particularly in embedded development
+   — believe it or not — this is often the option of last resort. That is,
+   you should probably go with the other options in this list.
+
+[tts-build-cross]: https://throwtheswitch.org/build/cross
+[tts-build-native]: https://throwtheswitch.org/build/native
+
+<br/><br/>

data/docs/mkdocs/overview/tools-and-frameworks.md

@@ -0,0 +1,115 @@
+# So Many Tools and Acronyms
+
+**Hold on. Back up. Unity? CMock? CException? Ruby? Rake? YAML?**
+
+## Ceedling suite frameworks
+
+### Unity
+
+[Unity] is a [unit test framework][unit-testing] for C. It provides facilities
+for test assertions, executing tests, and collecting / reporting test
+results. Unity derives its name from its implementation in a single C
+source file (plus two C header files) and from the nature of its
+implementation - Unity will build in any C toolchain and is configurable
+for even the very minimalist of processors.
+
+[Unity]: http://github.com/ThrowTheSwitch/Unity
+[unit-testing]: http://en.wikipedia.org/wiki/Unit_testing
+
+### CMock
+
+[CMock]<sup>†</sup> is a tool written in Ruby able to generate [function mocks & stubs][test-doubles] 
+in C code from a given C header file. Mock functions are invaluable in 
+[interaction-based unit testing][interaction-based-tests].
+CMock's generated C code uses Unity.
+
+<sup>†</sup> Through a [plugin][FFF-plugin], Ceedling also supports
+[FFF], _Fake Function Framework_, for [fake functions][test-doubles] as an
+alternative to CMock's mocks and stubs.
+
+[CMock]: http://github.com/ThrowTheSwitch/CMock
+[test-doubles]: https://blog.pragmatists.com/test-doubles-fakes-mocks-and-stubs-1a7491dfa3da
+[FFF]: https://github.com/meekrosoft/fff
+[FFF-plugin]: ../plugins/fff.md
+[interaction-based-tests]: http://martinfowler.com/articles/mocksArentStubs.html
+
+### CException
+
+[CException] is a C source and header file that provide a simple
+[exception mechanism][exn] for C by way of wrapping up the
+[setjmp / longjmp][setjmp] standard library calls. Exceptions are a much
+cleaner and preferable alternative to managing and passing error codes
+up your return call trace.
+
+[CException]: http://github.com/ThrowTheSwitch/CException
+[exn]: http://en.wikipedia.org/wiki/Exception_handling
+[setjmp]: http://en.wikipedia.org/wiki/Setjmp.h
+
+## Core tools
+
+### Ruby
+
+[Ruby] is a handy scripting language like Perl or Python. It's a modern, 
+full featured language that happens to be quite handy for accomplishing 
+tasks like code generation or automating one's workflow while developing 
+in a compiled language such as C.
+
+[Ruby]: http://www.ruby-lang.org/en/
+
+### Rake
+
+!!! warning "Migrating away from Rake"
+    Ceedling would not exist today if not for the help Rake provided to
+    get off the ground. As Ceedling matured it became apparent that 
+    Rake had become a limitation. The project is slowly removing its
+    dependency on Rake.
+
+[Rake] is a utility written in Ruby for accomplishing dependency 
+tracking and task automation common to building software. It's a modern, 
+more flexible replacement for [Make].
+
+Rakefiles are Ruby files, but they contain build targets similar
+in nature to that of Makefiles (but you can also run Ruby code in
+your Rakefile).
+
+[Rake]: http://rubyrake.org/
+[Make]: http://en.wikipedia.org/wiki/Make_(software)
+
+### YAML
+
+[YAML] is a "human friendly data serialization standard for all
+programming languages." It's kinda like a markup language but don't
+call it that. With a YAML library, you can [serialize] data structures
+to and from the file system in a textual, human readable form. Ceedling
+uses a serialized data structure as its configuration input.
+
+YAML has some advanced features that can greatly 
+[reduce duplication][yaml-anchors-aliases] in a configuration file 
+needed in complex projects. YAML anchors and aliases are beyond the scope
+of this document but may be of use to advanced Ceedling users. Note that 
+Ceedling does anticipate the use of YAML aliases. It proactively flattens 
+YAML lists to remove any list nesting that results from the convenience of
+aliasing one list inside another.
+
+[YAML]: http://en.wikipedia.org/wiki/Yaml
+[serialize]: http://en.wikipedia.org/wiki/Serialization
+[yaml-anchors-aliases]: https://blog.daemonl.com/2016/02/yaml.html
+
+---
+
+## Dependencies and Bundled Tools
+
+* By using the preferred installation options of the Ruby Ceedling gem or 
+  the prepackaged Docker images, all Ceedling dependencies will be installed 
+  for you. (See [installation section](../getting-started/installation.md).)
+
+* Regardless of installation method, Unity, CMock, and CException are bundled 
+  with Ceedling. Ceedling is designed to glue them all together for your 
+  project as seamlessly as possible.
+
+* YAML support is included with Ruby. It requires no special installation
+  or configuration. If your project file contains properly formatted YAML
+  with the recognized names and options (see later sections), you are good 
+  to go.
+
+<br/><br/>

data/docs/mkdocs/plugins/beep.md

@@ -0,0 +1,134 @@
+# Beep
+
+Hear a useful beep at the end of a build.
+
+## Plugin Overview
+
+Are you getting too distracted surfing the internet, chatting with coworkers, or swordfighting while a long build runs? A friendly beep will let you know
+it's time to pay attention again.
+
+## Setup
+
+To use this plugin, it must be enabled:
+
+```yaml
+:plugins:
+  :enabled:
+    - beep
+```
+
+## Configuration
+
+Beep includes a default configuration. By just enabling the plugin, the simplest cross-platform sound mechanism (`:bell` below) is automatically enabled for both
+build completion and build error events.
+
+If you would like to customize your beeps, the following explains your options.
+
+### Events
+
+When this plugin is enabled, a beep is sounded when:
+
+* A test build or release build finish successfully.
+* An error condition breaks a build.
+
+To change the default sound for each event, define `:on_done` and `:on_error` beneath a top-level `:beep` entry in your configuration file. See example below.
+
+### Sound options
+
+The following options are fixed. At present, this plugin does not expose customization settings.
+
+* `:bell`
+
+  `:bell` is the simplest and most widely available option for beeping. This option simply `echo`s the unprintable [ASCII bell character][ascii-bel-character] to a command terminal. This option is generally available on all platforms, including Windows.
+
+  [ascii-bel-character]: https://en.wikipedia.org/wiki/Bell_character
+
+* `:tput`
+
+  [`tput`][tput] is a command line utility widely availble among Unix derivatives, including Linux and macOS. The `tput` utility uses the terminfo database to make the values of terminal-dependent capabilities (including the [ASCII bell character][ascii-bel-character]) and terminal information available to the shell.
+
+  If the `echo`-based method used by the `:bell` option is not successful, `:tput` is a good backup option (except on Windows).
+
+  [tput]: https://linux.die.net/man/1/tput
+
+* `:beep`
+
+  [`beep`][beep] is an old but widely available Linux package for tone generation using the PC speaker.
+
+  `beep` requires isntallation and the possibility of a complementary kernel module.
+
+  The original audio device in a PC before sound cards was a simple and limited speaker directly wired to a motherboard. Rarely, modern systems still have this device. More commonly, its functions are routed to a default mode of modern audio hardware. `beep` may not work on modern Linux systems. If it is a viable option, this utility is typically dependent on a PC speaker kernel module and related configuration.
+
+  [beep]: https://linux.die.net/man/1/beep
+
+* `:speaker_test`
+
+  [`speaker-test`][speaker-test] is a Linux package commonly available for tone generation using a system's audio features.
+
+  `speaker-test` requires installation as well as audio subsystem configuration.
+
+  _Note:_ `speaker-test` typically mandates a 4 second minimum run, even if the configured sound plays for less than this minimum. Options to limit `speaker-test`'s minimum time are likely possible but would require combining advanced Ceedling features.
+
+  [speaker-test]: https://linux.die.net/man/1/speaker-test
+
+* `:say`
+
+  macOS includes a built-in text-to-speech command line application, [`say`][say]. When Ceedling is running on macOS and this beep option is selected, Ceedling events will be verbally announced.
+
+  [say]: https://ss64.com/mac/say.html
+
+### Adding arguments to a beep tool
+
+Each of the sound options above map to a command line tool that Ceedling executes.
+
+The `:beep`, `:speaker_test`, and `:say` tools can accept additional command line arguments to modify their behavior and sound ouput.
+
+The `:speaker_test` tool is preconfigured with its `-t`, `-f`, and `-l` arguments to generate a 1 second 1000 Hz sine wave. Any additional arguments added through configuration will follow these (and could conflict).
+
+To add additional arguments, a feature of Ceedling's project file handling allows you to merge a partial tool definition with tools already fully defined.
+
+```yaml
+:tools_beep_<sound option>: # Fill in <sound option> as from the list above
+  :arguments:
+    - ...                   # Add any aguments as a list of strings
+```
+
+### Example beep configurations in YAML
+
+Enabling the plugin and event handlers with beep tool selections:
+
+```yaml
+:plugins:
+  :enabled:
+    - beep
+
+# The following is the default configuration.
+# It is shown for completeness, but it need not be duplicated in your project file 
+# if the default settings work for you.
+:beep:
+  :on_done: :bell
+  :on_error: :bell
+```
+
+Adding an argument to a beep tool:
+
+```yaml
+:plugins:
+  :enabled:
+    - beep
+
+:beep:
+  :on_done: :say # Choose the macOS `say` tool for build done events
+                 # `:bell` remains the default for :on_error:
+
+:tools_beep_say:
+  :arguments:
+    - -v daniel  # Change `say` command line to use Daniel voice
+
+```
+
+## Notes
+
+* Some terminal emulators intercept and/or silence beeps. Remote terminal sessions can add further complication. Be sure to check relevant configuration options to accomplish what you want.
+
+<br/><br/>

data/docs/mkdocs/plugins/bullseye.md

@@ -0,0 +1,77 @@
+# Bullseye
+
+Plugin for integrating Bullseye code coverage tool into Ceedling projects.
+This plugin requires a working license to Bullseye code coverage tools. The tools
+must be within the path or the path should be added to the environment in the 
+project configuration.
+
+!!! warning "Bullseye Plugin Disabled"
+    [June 1, 2024] Until the Bullseye Plugin can be updated for compatibility 
+    with Ceedling >= 1.0.0, it has been disabled.
+
+## Configuration
+
+The bullseye plugin supports configuration options via your `project.yml` provided
+by Ceedling. The following is a typical configuration example:
+
+```
+:bullseye:
+  :auto_license: TRUE
+:plugins:
+  :bullseye_lib_path: []
+:paths:
+  :bullseye_toolchain_include: []
+
+:tools:
+  :bullseye_instrumentation:
+    :executable: covc
+    :arguments:
+      - '--file $': ENVIRONMENT_COVFILE
+      - -q
+      - ${1}
+  :bullseye_compiler:
+    :executable: gcc
+    :arguments:
+      - -g
+      - -I"$": COLLECTION_PATHS_TEST_SUPPORT_SOURCE_INCLUDE_VENDOR
+      - -I"$": COLLECTION_PATHS_BULLSEYE_TOOLCHAIN_INCLUDE
+      - -D$: COLLECTION_DEFINES_TEST_AND_VENDOR
+      - -DBULLSEYE_COMPILER
+      - -c "${1}"
+      - -o "${2}"
+  :bullseye_linker:
+    :executable: gcc
+    :arguments:
+      - ${1}
+      - -o ${2}
+      - -L$: PLUGINS_BULLSEYE_LIB_PATH
+      - -lcov
+  :bullseye_fixture:
+    :executable: ${1}
+  :bullseye_report_covsrc:
+    :executable: covsrc
+    :arguments:
+      - '--file $': ENVIRONMENT_COVFILE
+      - -q
+      - -w140
+  :bullseye_report_covfn:
+    :executable: covfn
+    :arguments:
+      - '--file $': ENVIRONMENT_COVFILE
+      - --width 120
+      - --no-source
+      - '"${1}"'
+  :bullseye_browser:
+    :executable: CoverageBrowser
+    :optional: TRUE
+    :arguments:
+      - '"$"': ENVIRONMENT_COVFILE
+```
+
+## Example Usage
+
+```sh
+ceedling bullseye:all utils:bullseye
+```
+
+<br/><br/>

data/docs/mkdocs/plugins/command-hooks.md

@@ -0,0 +1,263 @@
+# Command Hooks
+
+Easily run command line tools and scripts at various points in a Ceedling build.
+
+## Plugin Overview
+
+This plugin allows you to skip creating a full Ceedling plugin for many common use cases. It links Ceedling's programmatic `Plugin` code hooks to easily managed tool definitions. 
+
+## Setup
+
+To use this plugin, it must be enabled:
+
+```yaml
+:plugins:
+  :enabled:
+    - command_hooks
+```
+
+## Configuration
+
+### Overview
+
+To connect utilties or scripts to build step hooks, Ceedling tools must be defined.
+
+A Ceedling tool is just a YAML blob that gathers together a handful of settings and values that tell Ceedling how to build and execute a command line. Your tool can be a command line utility, a script, etc.
+
+Example Ceedling tools follow. When enabled, this plugin ensures any tools you define are executed by the corresponding build step hook they are organized beneath. The configurtion of enabled hooks and tools happens in a top-level `:command_hooks:` block within your project configuration. One or more tools can be attached to a build step hook.
+
+### Tool lists
+
+A command hook can execute one or more tools.
+
+If only a single tool is needed, its hash keys and value can be organized as a YAML sub-hash beneath the hook key. Alternatively, a single tool can exist as the only entry in a YAML list.
+
+If multiple tools are needed, they must be organized as entries in a YAML list.
+
+See the commented examples below.
+
+### Tool definitions
+
+Each Ceedling tool requires an `:executable` string and an optional `:arguments` list. See the [`:tools` configuration reference][tools-doc] to understand how to craft your argument list and other tool options.
+
+This plugin passes one or two runtime parameters for use in a hook's tool argument list depending on the hook. These parameters are referenced with Ceedling tool argument expansion identifiers `${1}`, `${2}`, etc. Wherever you place `${1}` or `${2}` in your tool argument list, they expand in the command line Ceedling constructs with the parameters this plugin provides for that build step hook. The list of build step hooks below documents which parameters are available for each hook.
+
+[tools-doc]: ../configuration/reference/tools.md
+
+### Hook logging
+
+In addition to the standard Ceedling tool definition elements, a hook configuration entry may optionally include a `:logging` setting.
+
+`:logging` may be set to `TRUE` or `FALSE`. An omitted setting is equivalent to `FALSE`.
+
+When logging is enabled and logging conditions are appropriate, any output from the hook tool will be logged to the console with a brief header identifying the hook.
+
+* Explicit command hook output logging only occurs at verbosity levels Normal and Obnoxious.
+* Debug logging naturally displays hook output as part of normal tool execution logging. It is not duplicated by hook logging.
+* At Normal verbosity, blank hook output is not logged at all; Obnoxious verbosity will display blank output as `<empty>`.
+
+### Command Hooks example configuration YAML
+
+```yaml
+:command_hooks:
+  # Hook called every time a mock is generated
+  # Who knows what my_script.py does -- sky is the limit
+  :pre_mock_generate:
+    # This tool is organized as a sub-hash beneath the command hook key
+    :executable: python
+    :arguments:
+      - my_script.py
+      - --some-arg
+      - ${1} # Replaced with the filepath of the header file that will be mocked
+    :logging: TRUE # Log any tool output to console
+      
+  # Hook called for each linking operation
+  # Here, we are performing two tasks for the same build step hook, converting a
+  # binary executable to S-record format and, then, archiving with other artifacts.
+  :post_link_execute:
+    # These tools are organized in a YAML list beneath the command hook key
+    - :executable: objcopy.exe
+      :arguments:
+        - ${1} # Replaced with the filepath to the linker's binary artifact output
+        - output.srec
+        - --strip-all
+    - :executable: 
+      :arguments: tar.exe
+        - -acf
+        - awesome_build.zip
+        - ${1} # Replaced with the filepath to the linker's binary artifact output
+        - memory_report.txt
+```
+
+## Available Build Step Hooks
+
+Define any of the following entries within a top-level `:command_hooks:` section of your Ceedling project file to automagically connect utilities or scripts to build process steps.
+
+Some hooks are called for every file-related operation for which the hook is named. Other hooks are triggered by the single build step for which the hook is named.
+
+As an example, consider a Ceedling project with ten test files and seventeen mocks. The command line `ceedling test:all` would trigger:
+
+* 1 occurrence of the `:pre_build` hook.
+* 1 occurrence of the `:pre_test_build` hook.
+* 10 occurrences of the `:pre_test` and `:post_test` hooks.
+* 17 occurrences of the `:pre_mock_generate` and `:post_mock_generate` hooks.
+* 10 occurrences of the `:pre_test_runner_generate` and `:post_test_runner_generate` hooks.
+* 27(+) occurrences of the `:pre_compile` and `:post_compile` hooks. These hooks would be called 27 times for test file and mock file compilation. A test suite build will also include compilation of the source files under tests, Unity's source, CMock's source, and generated test runner C files -- easily more than another two dozen compilation hook calls.
+* 10 occurrences of the `:pre_link` and `:post_link` hooks for test executable creation.
+* 10 occurrences of the `:pre_test_fixture_execute` and `:post_test_fixture_execute` hooks for running test executables and gathering the results of the tests cases they contain.
+* 1 occurrence of the `:post_test_build` hook.
+* 1 occurrence of the `:post_build` hook unless a build error occurred (`:post_error` would be called instead).
+
+### `:pre_build`
+
+Called once just before Ceedling executes any tasks.
+
+The parameter available to a tool (`${1}`) when the hook is called is a floating-point stopwatch value in seconds. This value and the corresponding `post_build` value can be used to compute the total build duration.
+
+### `:post_build`
+
+Called once just before Ceedling terminates after a successful build.
+
+The parameter available to a tool (`${1}`) when the hook is called is a floating-point stopwatch value in seconds. This value and the corresponding `pre_build` value can be used to compute the total build duration.
+
+### `:post_error`
+
+Called once just after any build failure and just before Ceedling terminates.
+
+The parameter available to a tool (`${1}`) when the hook is called is a floating-point stopwatch value in seconds at the moment the error is handled.
+
+### `:pre_test`
+
+Called just before each test begins its build pipeline and just after all context for that build has been gathered.
+
+The parameter available to a tool (`${1}`) when the hook is called is the test's filepath.
+
+### `:post_test`
+
+Called just after each test completes its build and execution.
+
+The parameter available to a tool (`${1}`) when the hook is called is the test's filepath.
+
+### `:pre_test_build`
+
+Called once just before the full test build pipeline begins (before any individual test's configure, preprocess, compile, link, or execute steps).
+
+Two parameters are available to a tool when the hook is called:
+
+* `${1}` — the build context as a string (e.g. `"test"`, `"gcov"`).
+* `${2}` — a floating-point stopwatch value in seconds. This value and the corresponding `post_test_build` value can be used to compute the total test build duration.
+
+### `:post_test_build`
+
+Called once just after the full test build pipeline completes or terminates (including on error).
+
+Two parameters are available to a tool when the hook is called:
+
+* `${1}` — the build context as a string (e.g. `"test"`, `"gcov"`).
+* `${2}` — a floating-point stopwatch value in seconds. This value and the corresponding `pre_test_build` value can be used to compute the total test build duration.
+
+### `:pre_release_build`
+
+Called once just before a release build begins.
+
+The parameter available to a tool (`${1}`) when the hook is called is a floating-point stopwatch value in seconds. This value and the corresponding `post_release_build` value can be used to compute the total release build duration.
+
+### `:post_release_build`
+
+Called once just after a release build finishes or terminates (including on error).
+
+The parameter available to a tool (`${1}`) when the hook is called is a floating-point stopwatch value in seconds. This value and the corresponding `pre_release_build` value can be used to compute the total release build duration.
+
+### `:pre_mock_preprocess`
+
+If mocks are enabled and preprocessing is in use, this is called just before each header file to be mocked is preprocessed.
+
+The parameter available to a tool (`${1}`) when the hook is called is the filepath of the header file to be mocked.
+
+See [_Conventions & Behaviors_][preprocessing] for details on how Ceedling preprocessing operates.
+
+[preprocessing]: ../testing-guide/conventions.md#test-preprocessing
+
+### `:post_mock_preprocess`
+
+If mocks are enabled and preprocessing is in use, this is called just after each header file to be mocked is preprocessed.
+
+The parameter available to a tool (`${1}`) when the hook is called is the filepath of the header file to be mocked.
+
+### `:pre_mock_generate`
+
+If mocks are enabled, this is called just before each header file to be mocked is processed by mock generation.
+
+The parameter available to a tool (`${1}`) when the hook is called is the filepath of the header file to be mocked.
+
+### `:post_mock_generate`
+
+If mocks are enabled, this is called just after each mock generation.
+
+The parameter available to a tool (`${1}`) when the hook is called is the filepath of the header file to be mocked.
+
+### `:pre_test_preprocess`
+
+If preprocessing is in use, this is called just before each test file is preprocessed before runner generation.
+
+The parameter available to a tool (`${1}`) when the hook is called is the test's filepath.
+
+See [_Conventions & Behaviors_][preprocessing] for details on how Ceedling preprocessing operates.
+
+### `:post_test_preprocess`
+
+If preprocessing is in use, this is called just after each test file is preprocessed.
+
+The parameter available to a tool (`${1}`) when the hook is called is the test's filepath.
+
+See [_Conventions & Behaviors_][preprocessing] for details on how Ceedling preprocessing operates.
+
+### `:pre_runner_generate`
+
+Called just before each test file is processed by test runner generation.
+
+The parameter available to a tool (`${1}`) when the hook is called is the test's filepath.
+
+### `:post_runner_generate`
+
+Called just after each test runner is generated.
+
+The parameter available to a tool (`${1}`) when the hook is called is the test's filepath.
+
+### `:pre_compile_execute`
+
+Called just before each C or assembly file is compiled.
+
+The parameter available to a tool (`${1}`) when the hook is called is the filepath of the file to be compiled.
+
+### `:post_compile_execute`
+
+Called just after each file compilation.
+
+The parameter available to a tool (`${1}`) when the hook is called is the filepath of the input file that was compiled.
+
+### `:pre_link_execute`
+
+Called just before any binary artifact—test or release—is linked.
+
+The parameter available to a tool (`${1}`) when the hook is called is the binary output artifact's filepath.
+
+### `:post_link_execute`
+
+Called just after a binary artifact is linked.
+
+The parameter available to a tool (`${1}`) when the hook is called is the binary output artifact's filepath.
+
+### `:pre_test_fixture_execute`
+
+Called just before each test is executed in its corresponding test fixture.
+
+The parameter available to a tool (`${1}`) when the hook is called is the filepath of the binary artifact to be executed by the fixture.
+
+### `:post_test_fixture_execute`
+
+Called just after each test's fixture is executed and test results are collected.
+
+The parameter available to a tool (`${1}`) when the hook is called is the filepath of the binary artifact that was executed by the fixture.
+
+<br/><br/>

data/docs/mkdocs/plugins/compile-commands-json-db.md

@@ -0,0 +1,42 @@
+# JSON Compilation Database
+
+Language Server Protocol (LSP) support for Clang tooling.
+
+## Background
+
+Syntax highlighting and code completion are hard. Historically each editor or IDE has implemented their own and then competed amongst themselves to offer the best experience for developers. Good syntax highlighting can be so valuable as to outweigh the consideration of alternate editors. If implementing sytnax highlighting and related features in a tool is hard for one language — and it is — imagine doing it for dozens of them. Further, on the flip side, imagine the complexities involved for a developer working with multiple languages at once.
+
+In June of 2016, Microsoft with Red Hat and Codenvy got together to create the [Language Server Protocol (LSP)][lsp-microsoft] ([community site][lsp-community]). The idea was simple. By standardizing, any conforming IDE or editor would only need to support LSP instead of custom plugins for each language. In turn, the backend code that performs syntax highlighting and similar features can be written once and used by any IDE that supports LSP. Today, [Many editors support LSP][lsp-tools].
+
+[lsp-microsoft]: https://microsoft.github.io/language-server-protocol/
+[lsp-community]: https://langserver.org/
+[lsp-tools]: https://microsoft.github.io/language-server-protocol/implementors/tools/
+
+## Plugin Overview
+
+For C and C++ projects, perhaps the most popular LSP server is the [`clangd`][clangd] backend. In order to provide features like _go to definition_, `clangd` needs to understand how to build a project so that it can discover all the pieces to the puzzle. Because of the various flavors of builds Ceedling supports and especially because of the complexities of test suite builds, components of a build can easily go missing from the view of `clangd`.
+
+This plugin gives `clangd` — or any tool that understands a [JSON compilation database][json-compilation-database] — full visibility into a Ceedling build.
+
+Once enabled, this plugin generates the database as `<build root>/artifacts/compile_commands.json` for each new build. Tools that understand JSON Compilation Database files can then process it to make their features fully available to you.
+
+[clangd]: https://clangd.llvm.org
+[json-compilation-database]: https://clang.llvm.org/docs/JSONCompilationDatabase.html
+
+## Setup
+
+Enable the plugin in your Ceedling project file by adding `compile_commands_json_db` to the list of enabled plugins.
+
+``` YAML
+:plugins:
+  :enabled:
+    - compile_commands_json_db
+```
+
+## Configuration
+
+There is no additional configuration necessary to run this plugin.
+
+`clangd` will search your build directory for the JSON compilation database, but in some instances on Unix-asbed platforms it can be easier and necessary to symlink the file into the root directory of your project (e.g. `ln -s ./build/artifacts/compile_commands.json .`).
+
+<br/><br/>