See also: #680

Overview

This file provides an attempt to heuristically provide compiler flags for
c-family languages. It does this by interrogating a compilation database.
A compilation database can be generated by tools such as cmake, bear, etc. It
contains the compiler flags (actually, a compiler invocation) for each source
file in the project, generated by the make system. If no compilation database
is found, no flags are generated.

The file is deliberately heavy on comments. This is to allow it to be adapted
to individual use cases by copying it to a known directory, configuring it
as the 'global_extra_conf' and customising it to your particular
environment. Note that the comments in this file are not a replacement for the
ycmd or YouCompleteMe documentation, nor is is meant to be a replacement for
the comments/examples found in ycmd's own C++ source location
(../cpp/ycm/.ycm_extra_conf.py).

Finding the compilation database

While there is no standard, and using something like cmake typically involves
an out-of-tree build, we attempt to find a compilation database by walking the
directory hierarchy looking for a file named compile_commands.json, starting
at the path of the file for which flags were requested (i.e. the file being
edited).

If a compilation database is found, it is cached against the directory it is
found in, to prevent re-parsing the entire database for every file, while
allowing a single instance ycmd to operate on multiple "projects" at once.

Guessing flags

The compilation database typically only contains flags (compiler invocations)
for source files known to the make system and/or makefile generator, as these
form the translation units for which calls to the compiler (typically with the
-c flag) are actually made. It does not contain:

• new files, not yet run through the make generator system
• header files

So the logic in this file applies some simple heuristics to guess the flags in
those cases:

• If the file is a header file (according to HEADER_EXTENSIONS)
  above, see if there is an entry in the database with the same root, but
  with any of the extensions in SOURCE_EXTENSIONS. If so, return those
  flags.
• Otherwise, if there is an entry in the database for the requested file,
  return those flags.
• Otherwise, we really can't guess any flags, so return none (and thus a
  warning that we can't guess your flags).

General design

We reuse the extra conf file mechanism, rather than implementing it directly in, say flags.py. This is potentially controversial, so I will probably submit another PR with the alternative implementation so we can choose which is the best.

Comments on this design vs. flags.py:

• I think it is simpler, as it reuses the existing mechanism, though it did require more changes outside of the extra_conf_store as I fleshed it out.
• It can be disabled by adding a global-extra-conf file with an empty or trivial FlagsForFile method
• It provides yet-another-example extra conf file, with yet-more commentary. I don't know that this will really reduce the number of folk who just use ycmd's one, but you never know.
• (selfishly) it is the way i have been running it for months. I have an extended version which does more heuristics.
• (less selfishly) if we decide in the future that we want to support heuristics, I think this would be the way to go.
• It is public domain licensed, rather than GPLv3
• should we use ycm_extra_conf.py for other languages, we can add default implementations to this file without more code

Comments on flags.py:

• more strict design, in the sense that the functionality is clang-completer specific.
• very similar in terms of the actual code, so may well have most of the benefits of this approach
• I have thought about it less ;)

Other notable things in this change:

• We allow the extra conf file to raise NoExtraConfDetected. Primariy, this is so that the default file can raise it when it can't find a database, and the user must create her own conf file. This could be useful in other scenarios, where a given extra conf file is unable to provide flags for the requested file (e.g. in the case where it is an objective-c file and the extra conf module doesn't know what objective c is).

• Please ignore the number and history of commits, i'll tidy them if this option is selected.

• I have added basic set of tests. I think there are a few more cases to cover and probably things like ensuring the per-directory caches work correctly, etc. but I won't add them unless we're happy with the approach.

This change is