Updated compile_commands_json plugin

- Added `ouput` key to database entries to allow tools to distinguish compilation output now that the same code file can be compiled multiple times with different command line options.
- Documentation revised to be more useful and clear.

plugins/compile_commands_json/README.md

@@ -1,29 +1,38 @@
-compile_commands_json
-=====================
+# Ceedling Plugin: JSON Compilation Database
 
-## Overview
+**Language Server Protocol (LSP) support for Clang tooling**
 
-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. Often developers would still to an IDE that felt cumbersome and slow just because it had the best syntax highlighting on the market. If doing it for one language is hard (and it is) imagine doing it for dozens of them. Imagine a full stack developer who has to work with CSS, HTML, JavaScript and some Ruby - they need excellent support in all those languages which just made things even harder.
+# Background
 
-In June of 2016, Microsoft with Red Hat and Codenvy got together to create a standard called the Language Server Protocol (LSP). The idea was simple, by standardising on one protocol, all the IDEs and editors out there would only have to support LSP, and not have custom plugins for each language. In turn, the backend code that actually does the highlighting can be written once and used by any IDE that supports LSP. Many editors already support it such as Sublime Text, vim and emacs. This means that if you're using a crufty old IDE or worse, you're using a shiny new editor without code completion, then this could be just the upgrade you're looking for!
+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 highlight and related features is hard for one language — and it is — imagine doing it for dozens of them. Further imagine the complexities involved for a developer working with multiple languages at once.
 
-For C and C++ projects, many people use the `clangd` backend. So that it can do things like "go to definition", `clangd` needs to know how to build the project so that it can figure out all the pieces to the puzzle. There are manual tools such as `bear` which can be run with `gcc` or `clang` to extract this information it has a big limitation in that if run with `ceedling release` you won't get any auto completion for Unity and you'll also get error messages reported by your IDE because of what it perceives as missing headers. If you do the same with `ceedling test` now you get Unity but you might miss things that are only seen in the release build.
+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].
 
-This plugin resolves that issue. As it is run by Ceedling, it has access to all the build information it needs to create the perfect `compile_commands.json`. Once enabled, this plugin will generate that file and place it in `./build/artifacts/compile_commands.json`. `clangd` will search your project for this file, but it is easier to symlink it into the root directory (for example `ln -s ./build/artifacts/compile_commands.json`. 
+[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/
 
-For more information on LSP and to find out if your editor supports it, check out https://langserver.org/
+# Plugin Overview
 
-## Setup
+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 (e.g. release plus multiple variants of test suite builds), components of the build can easily go missing from the view of `clangd`.
 
-Enable the plugin in your project.yml by adding `compile_commands_json` to the list
-of enabled plugins.
+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`.
+
+[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` to the list of enabled plugins.
 
 ``` YAML
 :plugins:
   :enabled:
     - compile_commands_json
 ```
 
-## Configuration
+# 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 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 .`).

plugins/compile_commands_json/lib/compile_commands_json.rb

@@ -5,20 +5,20 @@
 class CompileCommandsJson < Plugin
   def setup
     @fullpath = File.join(PROJECT_BUILD_ARTIFACTS_ROOT, "compile_commands.json")
-    @database = if (File.exist?(@fullpath) && File.size(@fullpath) > 0)
-                  JSON.parse( File.read(@fullpath) )
-                else
-                  []
-                end
+    @database = []
+    if (File.exist?(@fullpath) && File.size(@fullpath) > 0)
+      @database = JSON.parse( File.read(@fullpath) )
+    end
   end
 
   def post_compile_execute(arg_hash)
 
-    # Create the new Entry
+    # Create new Entry from compilation
     value = {
-      "directory" => Dir.pwd,
+      "directory" => Dir.pwd, # TODO: Replace with Ceedling project root when it exists
+      "file" => arg_hash[:source],
       "command" => arg_hash[:shell_command],
-      "file" => arg_hash[:source]
+      "output" => arg_hash[:object]
     }
 
     # Determine if we're updating an existing file description or adding a new one
@@ -29,7 +29,7 @@ def post_compile_execute(arg_hash)
       @database << value
     end
 
-    # Update the Actual compile_commands.json file
+    # Rewrite the compile_commands.json file
     File.open(@fullpath,'w') {|f| f << JSON.pretty_generate(@database)}
   end
 end