| # Copyright 2022 The Pigweed Authors |
| # |
| # Licensed under the Apache License, Version 2.0 (the "License"); you may not |
| # use this file except in compliance with the License. You may obtain a copy of |
| # the License at |
| # |
| # https://www.apache.org/licenses/LICENSE-2.0 |
| # |
| # Unless required by applicable law or agreed to in writing, software |
| # distributed under the License is distributed on an "AS IS" BASIS, WITHOUT |
| # WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the |
| # License for the specific language governing permissions and limitations under |
| # the License. |
| """Configure C/C++ IDE support for Pigweed projects. |
| |
| We support C/C++ code analysis via ``clangd``, or other language servers that |
| are compatible with the ``clangd`` compilation database format. |
| |
| While clangd can work well out of the box for typical C++ codebases, some work |
| is required to coax it to work for embedded projects. In particular, Pigweed |
| projects use multiple toolchains within a distinct environment, and almost |
| always define multiple targets. This means compilation units are likely have |
| multiple compile commands and the toolchain executables are unlikely to be in |
| your path. ``clangd`` is not equipped to deal with this out of the box. We |
| handle this by: |
| |
| - Processing the compilation database produced by the build system into |
| multiple internally-consistent compilation databases, one for each target |
| (where a "target" is a particular build for a particular system using a |
| particular toolchain). |
| |
| - Creating unambiguous paths to toolchain drivers to ensure the right toolchain |
| is used and that clangd knows where to find that toolchain's system headers. |
| |
| - Providing tools for working with several compilation databases that are |
| spiritually similar to tools like ``pyenv``, ``rbenv``, etc. |
| |
| In short, we take the probably-broken compilation database that the build system |
| generates, process it into several not-broken compilation databases in the |
| ``pw_ide`` working directory, and provide a stable symlink that points to the |
| selected active target's compliation database. If ``clangd`` is configured to |
| point at the symlink and is set up with the right paths, you'll get code |
| intelligence. |
| """ |
| |
| from collections import defaultdict |
| from dataclasses import dataclass |
| import glob |
| from io import TextIOBase |
| import json |
| import os |
| from pathlib import Path |
| import platform |
| from typing import ( |
| Any, |
| cast, |
| Callable, |
| Dict, |
| Generator, |
| List, |
| Optional, |
| Tuple, |
| TypedDict, |
| Union, |
| ) |
| |
| from pw_ide.exceptions import ( |
| BadCompDbException, |
| InvalidTargetException, |
| MissingCompDbException, |
| UnresolvablePathException, |
| ) |
| |
| from pw_ide.settings import PigweedIdeSettings, PW_PIGWEED_CIPD_INSTALL_DIR |
| from pw_ide.symlinks import set_symlink |
| |
| _COMPDB_FILE_PREFIX = 'compile_commands' |
| _COMPDB_FILE_SEPARATOR = '_' |
| _COMPDB_FILE_EXTENSION = '.json' |
| |
| _COMPDB_CACHE_DIR_PREFIX = '.cache' |
| _COMPDB_CACHE_DIR_SEPARATOR = '_' |
| |
| COMPDB_FILE_GLOB = f'{_COMPDB_FILE_PREFIX}*{_COMPDB_FILE_EXTENSION}' |
| COMPDB_CACHE_DIR_GLOB = f'{_COMPDB_CACHE_DIR_PREFIX}*' |
| |
| MAX_COMMANDS_TARGET_FILENAME = 'max_commands_target' |
| |
| _SUPPORTED_TOOLCHAIN_EXECUTABLES = ('clang', 'gcc', 'g++') |
| |
| |
| def compdb_generate_file_path(target: str = '') -> Path: |
| """Generate a compilation database file path.""" |
| |
| path = Path(f'{_COMPDB_FILE_PREFIX}{_COMPDB_FILE_EXTENSION}') |
| |
| if target: |
| path = path.with_name( |
| f'{_COMPDB_FILE_PREFIX}' |
| f'{_COMPDB_FILE_SEPARATOR}{target}' |
| f'{_COMPDB_FILE_EXTENSION}' |
| ) |
| |
| return path |
| |
| |
| def compdb_generate_cache_path(target: str = '') -> Path: |
| """Generate a compilation database cache directory path.""" |
| |
| path = Path(f'{_COMPDB_CACHE_DIR_PREFIX}') |
| |
| if target: |
| path = path.with_name( |
| f'{_COMPDB_CACHE_DIR_PREFIX}' |
| f'{_COMPDB_CACHE_DIR_SEPARATOR}{target}' |
| ) |
| |
| return path |
| |
| |
| def compdb_target_from_path(filename: Path) -> Optional[str]: |
| """Get a target name from a compilation database path.""" |
| |
| # The length of the common compilation database file name prefix |
| prefix_length = len(_COMPDB_FILE_PREFIX) + len(_COMPDB_FILE_SEPARATOR) |
| |
| if len(filename.stem) <= prefix_length: |
| # This will return None for the symlink filename, and any filename that |
| # is too short to be a compilation database. |
| return None |
| |
| if filename.stem[:prefix_length] != ( |
| _COMPDB_FILE_PREFIX + _COMPDB_FILE_SEPARATOR |
| ): |
| # This will return None for any files that don't have the common prefix. |
| return None |
| |
| return filename.stem[prefix_length:] |
| |
| |
| def _none_to_empty_str(value: Optional[str]) -> str: |
| return value if value is not None else '' |
| |
| |
| def _none_if_not_exists(path: Path) -> Optional[Path]: |
| return path if path.exists() else None |
| |
| |
| def compdb_cache_path_if_exists( |
| working_dir: Path, target: Optional[str] |
| ) -> Optional[Path]: |
| return _none_if_not_exists( |
| working_dir / compdb_generate_cache_path(_none_to_empty_str(target)) |
| ) |
| |
| |
| def target_is_enabled( |
| target: Optional[str], settings: PigweedIdeSettings |
| ) -> bool: |
| """Determine if a target is enabled. |
| |
| By default, all targets are enabled. If specific targets are defined in a |
| settings file, only those targets will be enabled. |
| """ |
| |
| if target is None: |
| return False |
| |
| if len(settings.targets) == 0: |
| return True |
| |
| return target in settings.targets |
| |
| |
| def path_to_executable( |
| exe: str, |
| *, |
| default_path: Optional[Path] = None, |
| path_globs: Optional[List[str]] = None, |
| strict: bool = False, |
| ) -> Optional[Path]: |
| """Return the path to a compiler executable. |
| |
| In a ``clang`` compile command, the executable may or may not include a |
| path. For example: |
| |
| .. code-block:: none |
| |
| /usr/bin/clang <- includes a path |
| ../path/to/my/clang <- includes a path |
| clang <- doesn't include a path |
| |
| If it includes a path, then ``clangd`` will have no problem finding the |
| driver, so we can simply return the path. If the executable *doesn't* |
| include a path, then ``clangd`` will search ``$PATH``, and may not find the |
| intended driver unless you actually want the default system toolchain or |
| Pigweed paths have been added to ``$PATH``. So this function provides two |
| options for resolving those ambiguous paths: |
| |
| - Provide a default path, and all executables without a path will be |
| re-written with a path within the default path. |
| - Provide the a set of globs that will be used to search for the executable, |
| which will normally be the query driver globs used with clangd. |
| |
| By default, if neither of these options is chosen, or if the executable |
| cannot be found within the provided globs, the pathless executable that was |
| provided will be returned, and clangd will resort to searching $PATH. If you |
| instead pass ``strict=True``, this will raise an exception if an unambiguous |
| path cannot be constructed. |
| |
| This function only tries to ensure that all executables have a path to |
| eliminate ambiguity. A couple of important things to keep in mind: |
| |
| - This doesn't guarantee that the path exists or an executable actually |
| exists at the path. It only ensures that some path is provided to an |
| executable. |
| - An executable being present at the indicated path doesn't guarantee that |
| it will work flawlessly for clangd code analysis. The clangd |
| ``--query-driver`` argument needs to include a path to this executable in |
| order for its bundled headers to be resolved correctly. |
| |
| This function also filters out invalid or unsupported drivers. For example, |
| build systems will sometimes naively include build steps for Python or other |
| languages in the compilation database, which are not usable with clangd. |
| As a result, this function has four possible end states: |
| |
| - It returns a path with an executable that can be used as a ``clangd`` |
| driver. |
| - It returns ``None``, meaning the compile command was invalid. |
| - It returns the same string that was provided (as a ``Path``), if a path |
| couldn't be resolved and ``strict=False``. |
| - It raises an ``UnresolvablePathException`` if the executable cannot be |
| placed in an unambiguous path and ``strict=True``. |
| """ |
| maybe_path = Path(exe) |
| |
| # We were give an empty string, not a path. Not a valid command. |
| if len(maybe_path.parts) == 0: |
| return None |
| |
| # Determine if the executable name matches supported drivers. |
| is_supported_driver = False |
| |
| for supported_executable in _SUPPORTED_TOOLCHAIN_EXECUTABLES: |
| if supported_executable in maybe_path.name: |
| is_supported_driver = True |
| |
| if not is_supported_driver: |
| return None |
| |
| # Now, ensure the executable has a path. |
| |
| # This is either a relative or absolute path -- return it. |
| if len(maybe_path.parts) > 1: |
| return maybe_path |
| |
| # If we got here, there's only one "part", so we assume it's an executable |
| # without a path. This logic doesn't work with a path like `./exe` since |
| # that also yields only one part. So currently this breaks if you actually |
| # have your compiler executable in your root build directory, which is |
| # (hopefully) very rare. |
| |
| # If we got a default path, use it. |
| if default_path is not None: |
| return default_path / maybe_path |
| |
| # Otherwise, try to find the executable within the query driver globs. |
| # Note that unlike the previous paths, this path will only succeed if an |
| # executable actually exists somewhere in the query driver globs. |
| if path_globs is not None: |
| for path_glob in path_globs: |
| for path_str in glob.iglob(path_glob): |
| path = Path(path_str) |
| if path.name == maybe_path.name: |
| return path.absolute() |
| |
| if strict: |
| raise UnresolvablePathException( |
| f'Cannot place {exe} in an unambiguous path!' |
| ) |
| |
| return maybe_path |
| |
| |
| def command_parts(command: str) -> Tuple[str, List[str]]: |
| """Return the executable string and the rest of the command tokens.""" |
| parts = command.split() |
| head = parts[0] if len(parts) > 0 else '' |
| tail = parts[1:] if len(parts) > 1 else [] |
| return head, tail |
| |
| |
| # This is a clumsy way to express optional keys, which is not directly |
| # supported in TypedDicts right now. |
| class BaseCppCompileCommandDict(TypedDict): |
| file: str |
| directory: str |
| output: Optional[str] |
| |
| |
| class CppCompileCommandDictWithCommand(BaseCppCompileCommandDict): |
| command: str |
| |
| |
| class CppCompileCommandDictWithArguments(BaseCppCompileCommandDict): |
| arguments: List[str] |
| |
| |
| CppCompileCommandDict = Union[ |
| CppCompileCommandDictWithCommand, CppCompileCommandDictWithArguments |
| ] |
| |
| |
| class CppCompileCommand: |
| """A representation of a clang compilation database compile command. |
| |
| See: https://clang.llvm.org/docs/JSONCompilationDatabase.html |
| """ |
| |
| def __init__( |
| self, |
| file: str, |
| directory: str, |
| command: Optional[str] = None, |
| arguments: Optional[List[str]] = None, |
| output: Optional[str] = None, |
| ) -> None: |
| # Per the spec, either one of these two must be present. clangd seems |
| # to prefer "arguments" when both are present. |
| if command is None and arguments is None: |
| raise TypeError( |
| 'A compile command requires either \'command\' ' |
| 'or \'arguments\'.' |
| ) |
| |
| if command is None: |
| raise TypeError( |
| 'Compile commands without \'command\' ' 'are not supported yet.' |
| ) |
| |
| self._command = command |
| self._arguments = arguments |
| self._file = file |
| self._directory = directory |
| |
| executable, tokens = command_parts(command) |
| self._executable_path = Path(executable) |
| self._inferred_output: Optional[str] = None |
| |
| try: |
| # Find the output argument and grab its value. |
| output_flag_idx = tokens.index('-o') |
| self._inferred_output = tokens[output_flag_idx + 1] |
| except ValueError: |
| # No -o found, probably not a C/C++ compile command. |
| self._inferred_output = None |
| except IndexError: |
| # It has an -o but no argument after it. |
| raise TypeError( |
| 'Failed to load compile command with no output argument!' |
| ) |
| |
| self._provided_output = output |
| self.target: Optional[str] = None |
| |
| @property |
| def file(self) -> str: |
| return self._file |
| |
| @property |
| def directory(self) -> str: |
| return self._directory |
| |
| @property |
| def command(self) -> Optional[str]: |
| return self._command |
| |
| @property |
| def arguments(self) -> Optional[List[str]]: |
| return self._arguments |
| |
| @property |
| def output(self) -> Optional[str]: |
| # We're ignoring provided output values for now. |
| return self._inferred_output |
| |
| @property |
| def output_path(self) -> Optional[Path]: |
| if self.output is None: |
| return None |
| |
| return Path(self.directory) / Path(self.output) |
| |
| @property |
| def executable_path(self) -> Path: |
| return self._executable_path |
| |
| @property |
| def executable_name(self) -> str: |
| return self.executable_path.name |
| |
| @classmethod |
| def from_dict( |
| cls, compile_command_dict: Dict[str, Any] |
| ) -> 'CppCompileCommand': |
| return cls( |
| # We want to let possible Nones through to raise at runtime. |
| file=cast(str, compile_command_dict.get('file')), |
| directory=cast(str, compile_command_dict.get('directory')), |
| command=compile_command_dict.get('command'), |
| arguments=compile_command_dict.get('arguments'), |
| output=compile_command_dict.get('output'), |
| ) |
| |
| @classmethod |
| def try_from_dict( |
| cls, compile_command_dict: Dict[str, Any] |
| ) -> Optional['CppCompileCommand']: |
| try: |
| return cls.from_dict(compile_command_dict) |
| except TypeError: |
| return None |
| |
| def process( |
| self, |
| *, |
| default_path: Optional[Path] = None, |
| path_globs: Optional[List[str]] = None, |
| strict: bool = False, |
| ) -> Optional['CppCompileCommand']: |
| """Process a compile command. |
| |
| At minimum, a compile command from a clang compilation database needs to |
| be correlated with its target, and this method returns the target name |
| with the compile command. But it also cleans up other things we need for |
| reliable code intelligence: |
| |
| - Some targets may not be valid C/C++ compile commands. For example, |
| some build systems will naively include build steps for Python or for |
| linting commands. We want to filter those out. |
| |
| - Some compile commands don't provide a path to the compiler executable |
| (referred to by clang as the "driver"). In that case, clangd is very |
| unlikely to find the executable unless it happens to be in ``$PATH``. |
| The ``--query-driver`` argument to ``clangd`` allowlists |
| executables/drivers for use its use, but clangd doesn't use it to |
| resolve ambiguous paths. We bridge that gap here. Any executable |
| without a path will be either placed in the provided default path or |
| searched for in the query driver globs and be replaced with a path to |
| the executable. |
| """ |
| if self.command is None: |
| raise NotImplementedError( |
| 'Compile commands without \'command\' ' 'are not supported yet.' |
| ) |
| |
| executable_str, tokens = command_parts(self.command) |
| executable_path = path_to_executable( |
| executable_str, |
| default_path=default_path, |
| path_globs=path_globs, |
| strict=strict, |
| ) |
| |
| if executable_path is None or self.output is None: |
| return None |
| |
| # TODO(chadnorvell): Some commands include the executable multiple |
| # times. It's not clear if that affects clangd. |
| new_command = f'{str(executable_path)} {" ".join(tokens)}' |
| |
| return self.__class__( |
| file=self.file, |
| directory=self.directory, |
| command=new_command, |
| arguments=None, |
| output=self.output, |
| ) |
| |
| def as_dict(self) -> CppCompileCommandDict: |
| base_compile_command_dict: BaseCppCompileCommandDict = { |
| 'file': self.file, |
| 'directory': self.directory, |
| 'output': self.output, |
| } |
| |
| # TODO(chadnorvell): Support "arguments". The spec requires that a |
| # We don't support "arguments" at all right now. When we do, we should |
| # preferentially include "arguments" only, and only include "command" |
| # when "arguments" is not present. |
| if self.command is not None: |
| compile_command_dict: CppCompileCommandDictWithCommand = { |
| 'command': self.command, |
| # Unfortunately dict spreading doesn't work with mypy. |
| 'file': base_compile_command_dict['file'], |
| 'directory': base_compile_command_dict['directory'], |
| 'output': base_compile_command_dict['output'], |
| } |
| else: |
| raise NotImplementedError( |
| 'Compile commands without \'command\' ' 'are not supported yet.' |
| ) |
| |
| return compile_command_dict |
| |
| |
| def _infer_target_pos(target_glob: str) -> List[int]: |
| """Infer the position of the target in a compilation unit artifact path.""" |
| tokens = Path(target_glob).parts |
| positions = [] |
| |
| for pos, token in enumerate(tokens): |
| if token == '?': |
| positions.append(pos) |
| elif token == '*': |
| pass |
| else: |
| raise ValueError(f'Invalid target inference token: {token}') |
| |
| return positions |
| |
| |
| def infer_target( |
| target_glob: str, root: Path, output_path: Path |
| ) -> Optional[str]: |
| """Infer a target from a compilation unit artifact path. |
| |
| See the documentation for ``PigweedIdeSettings.target_inference``.""" |
| target_pos = _infer_target_pos(target_glob) |
| |
| if len(target_pos) == 0: |
| return None |
| |
| # Depending on the build system and project configuration, the target name |
| # may be in the "directory" or the "output" of the compile command. So we |
| # need to construct the full path that combines both and use that to search |
| # for the target. |
| subpath = output_path.relative_to(root) |
| return '_'.join([subpath.parts[pos] for pos in target_pos]) |
| |
| |
| LoadableToCppCompilationDatabase = Union[ |
| List[Dict[str, Any]], str, TextIOBase, Path |
| ] |
| |
| |
| class CppCompilationDatabase: |
| """A representation of a clang compilation database. |
| |
| See: https://clang.llvm.org/docs/JSONCompilationDatabase.html |
| """ |
| |
| def __init__(self, build_dir: Optional[Path] = None) -> None: |
| self._db: List[CppCompileCommand] = [] |
| |
| # Only compilation databases that are loaded will have this, and it |
| # contains the root directory of the build that the compilation |
| # database is based on. Processed compilation databases will not have |
| # a value here. |
| self._build_dir = build_dir |
| |
| def __len__(self) -> int: |
| return len(self._db) |
| |
| def __getitem__(self, index: int) -> CppCompileCommand: |
| return self._db[index] |
| |
| def __iter__(self) -> Generator[CppCompileCommand, None, None]: |
| return (compile_command for compile_command in self._db) |
| |
| def add(self, *commands: CppCompileCommand): |
| """Add compile commands to the compilation database.""" |
| self._db.extend(commands) |
| |
| def merge(self, other: 'CppCompilationDatabase') -> None: |
| """Merge values from another database into this one. |
| |
| This will not overwrite a compile command that already exists for a |
| particular file. |
| """ |
| self_dict = {c.file: c for c in self._db} |
| |
| for compile_command in other: |
| if compile_command.file not in self_dict: |
| self_dict[compile_command.file] = compile_command |
| |
| self._db = list(self_dict.values()) |
| |
| def as_dicts(self) -> List[CppCompileCommandDict]: |
| return [compile_command.as_dict() for compile_command in self._db] |
| |
| def to_json(self) -> str: |
| """Output the compilation database to a JSON string.""" |
| |
| return json.dumps(self.as_dicts(), indent=2, sort_keys=True) |
| |
| def to_file(self, path: Path): |
| """Write the compilation database to a JSON file.""" |
| |
| with open(path, 'w') as file: |
| json.dump(self.as_dicts(), file, indent=2, sort_keys=True) |
| |
| @classmethod |
| def load( |
| cls, compdb_to_load: LoadableToCppCompilationDatabase, build_dir: Path |
| ) -> 'CppCompilationDatabase': |
| """Load a compilation database. |
| |
| You can provide a JSON file handle or path, a JSON string, or a native |
| Python data structure that matches the format (list of dicts). |
| """ |
| db_as_dicts: List[Dict[str, Any]] |
| |
| if isinstance(compdb_to_load, list): |
| # The provided data is already in the format we want it to be in, |
| # probably, and if it isn't we'll find out when we try to |
| # instantiate the database. |
| db_as_dicts = compdb_to_load |
| else: |
| if isinstance(compdb_to_load, Path): |
| # The provided data is a path to a file, presumably JSON. |
| try: |
| compdb_data = compdb_to_load.read_text() |
| except FileNotFoundError: |
| raise MissingCompDbException() |
| elif isinstance(compdb_to_load, TextIOBase): |
| # The provided data is a file handle, presumably JSON. |
| compdb_data = compdb_to_load.read() |
| elif isinstance(compdb_to_load, str): |
| # The provided data is a a string, presumably JSON. |
| compdb_data = compdb_to_load |
| |
| db_as_dicts = json.loads(compdb_data) |
| |
| compdb = cls(build_dir=build_dir) |
| |
| try: |
| compdb.add( |
| *[ |
| compile_command |
| for compile_command_dict in db_as_dicts |
| if ( |
| compile_command := CppCompileCommand.try_from_dict( |
| compile_command_dict |
| ) |
| ) |
| is not None |
| ] |
| ) |
| except TypeError: |
| # This will arise if db_as_dicts is not actually a list of dicts |
| raise BadCompDbException() |
| |
| return compdb |
| |
| def process( |
| self, |
| settings: PigweedIdeSettings, |
| *, |
| default_path: Optional[Path] = None, |
| path_globs: Optional[List[str]] = None, |
| strict: bool = False, |
| ) -> 'CppCompilationDatabasesMap': |
| """Process a ``clangd`` compilation database file. |
| |
| Given a clang compilation database that may have commands for multiple |
| valid or invalid targets/toolchains, keep only the valid compile |
| commands and store them in target-specific compilation databases. |
| """ |
| if self._build_dir is None: |
| raise ValueError( |
| 'Can only process a compilation database that ' |
| 'contains a root build directory, usually ' |
| 'specified when loading the file. Are you ' |
| 'trying to process an already-processed ' |
| 'compilation database?' |
| ) |
| |
| clean_compdbs = CppCompilationDatabasesMap(settings) |
| |
| for compile_command in self: |
| processed_command = compile_command.process( |
| default_path=default_path, path_globs=path_globs, strict=strict |
| ) |
| |
| if ( |
| processed_command is not None |
| and processed_command.output_path is not None |
| ): |
| target = infer_target( |
| settings.target_inference, |
| self._build_dir, |
| processed_command.output_path, |
| ) |
| |
| if target_is_enabled(target, settings): |
| # This invariant is satisfied by target_is_enabled |
| target = cast(str, target) |
| processed_command.target = target |
| clean_compdbs[target].add(processed_command) |
| |
| return clean_compdbs |
| |
| |
| class CppCompilationDatabasesMap: |
| """Container for a map of target name to compilation database.""" |
| |
| def __init__(self, settings: PigweedIdeSettings): |
| self.settings = settings |
| self._dbs: Dict[str, CppCompilationDatabase] = defaultdict( |
| CppCompilationDatabase |
| ) |
| |
| def __len__(self) -> int: |
| return len(self._dbs) |
| |
| def __getitem__(self, key: str) -> CppCompilationDatabase: |
| return self._dbs[key] |
| |
| def __setitem__(self, key: str, item: CppCompilationDatabase) -> None: |
| self._dbs[key] = item |
| |
| @property |
| def targets(self) -> List[str]: |
| return list(self._dbs.keys()) |
| |
| def items( |
| self, |
| ) -> Generator[Tuple[str, CppCompilationDatabase], None, None]: |
| return ((key, value) for (key, value) in self._dbs.items()) |
| |
| def write(self) -> None: |
| """Write compilation databases to target-specific JSON files.""" |
| # This also writes out a file with the name of the target that has the |
| # largest number of commands, i.e., the target with the broadest |
| # compilation unit coverage. We can use this as a default target of |
| # last resort. |
| max_commands = 0 |
| max_commands_target = None |
| |
| for target, compdb in self.items(): |
| if max_commands_target is None or len(compdb) > max_commands: |
| max_commands_target = target |
| max_commands = len(compdb) |
| |
| compdb.to_file( |
| self.settings.working_dir / compdb_generate_file_path(target) |
| ) |
| |
| max_commands_target_path = ( |
| self.settings.working_dir / MAX_COMMANDS_TARGET_FILENAME |
| ) |
| |
| if max_commands_target is not None: |
| if max_commands_target_path.exists(): |
| max_commands_target_path.unlink() |
| |
| with open( |
| max_commands_target_path, 'x' |
| ) as max_commands_target_file: |
| max_commands_target_file.write(max_commands_target) |
| |
| @classmethod |
| def merge( |
| cls, *db_sets: 'CppCompilationDatabasesMap' |
| ) -> 'CppCompilationDatabasesMap': |
| """Merge several sets of processed compilation databases. |
| |
| If you process N compilation databases produced by a build system, |
| you'll end up with N sets of processed compilation databases, |
| containing databases for one or more targets each. This method |
| merges them into one set of databases with one database per target. |
| |
| The expectation is that the vast majority of the time, each of the |
| raw compilation databases that are processed will contain distinct |
| targets, meaning that the keys of each ``CppCompilationDatabases`` |
| object that's merged will be unique to each object, and this operation |
| is nothing more than a shallow merge. |
| |
| However, this also supports the case where targets may overlap between |
| ``CppCompilationDatabases`` objects. In that case, we prioritize |
| correctness, ensuring that the resulting compilation databases will |
| work correctly with clangd. This means not including duplicate compile |
| commands for the same file in the same target's database. The choice |
| of which duplicate compile command ends up in the final database is |
| unspecified and subject to change. Note also that this method expects |
| the ``settings`` value to be the same between all of the provided |
| ``CppCompilationDatabases`` objects. |
| """ |
| if len(db_sets) == 0: |
| raise ValueError( |
| 'At least one set of compilation databases is ' 'required.' |
| ) |
| |
| # Shortcut for the most common case. |
| if len(db_sets) == 1: |
| return db_sets[0] |
| |
| merged = cls(db_sets[0].settings) |
| |
| for dbs in db_sets: |
| for target, db in dbs.items(): |
| merged[target].merge(db) |
| |
| return merged |
| |
| |
| @dataclass(frozen=True) |
| class CppIdeFeaturesTarget: |
| """Data pertaining to a C++ code analysis target.""" |
| |
| name: str |
| compdb_file_path: Path |
| compdb_cache_path: Optional[Path] |
| is_enabled: bool |
| |
| |
| class CppIdeFeaturesState: |
| """The state of the C++ analysis targets in the working directory. |
| |
| Targets can be: |
| |
| - **Available**: A compilation database is present for this target. |
| - **Enabled**: Any targets are enabled by default, but a subset can be |
| enabled instead in the pw_ide settings. Enabled targets need |
| not be available if they haven't had a compilation database |
| created through processing yet. |
| - **Valid**: Is both available and enabled. |
| - **Current**: The one currently activated target that is exposed to clangd. |
| """ |
| |
| def __init__(self, settings: PigweedIdeSettings) -> None: |
| self.settings = settings |
| |
| # We filter out Nones below, so we can assume its a str |
| target: Callable[[Path], str] = lambda path: cast( |
| str, compdb_target_from_path(path) |
| ) |
| |
| # Contains every compilation database that's present in the working dir. |
| # This dict comprehension looks monstrous, but it just finds targets and |
| # associates the target names with their CppIdeFeaturesTarget objects. |
| self.targets: Dict[str, CppIdeFeaturesTarget] = { |
| target(file_path): CppIdeFeaturesTarget( |
| name=target(file_path), |
| compdb_file_path=file_path, |
| compdb_cache_path=compdb_cache_path_if_exists( |
| settings.working_dir, compdb_target_from_path(file_path) |
| ), |
| is_enabled=target_is_enabled(target(file_path), settings), |
| ) |
| for file_path in settings.working_dir.iterdir() |
| if file_path.match( |
| f'{_COMPDB_FILE_PREFIX}*{_COMPDB_FILE_EXTENSION}' |
| ) |
| # This filters out the symlink |
| and compdb_target_from_path(file_path) is not None |
| } |
| |
| # Contains the currently selected target. |
| self._current_target: Optional[CppIdeFeaturesTarget] = None |
| |
| # This is diagnostic data; it tells us what the current target should |
| # be, even if the state of the working directory is corrupted and the |
| # compilation database for the target isn't actually present. Anything |
| # that requires a compilation database to be definitely present should |
| # use `current_target` instead of these values. |
| self.current_target_name: Optional[str] = None |
| self.current_target_file_path: Optional[Path] = None |
| self.current_target_exists: Optional[bool] = None |
| |
| # Contains the name of the target that has the most compile commands, |
| # i.e., the target with the most file coverage in the project. |
| self._max_commands_target: Optional[str] = None |
| |
| try: |
| src_file = Path( |
| os.readlink( |
| (settings.working_dir / compdb_generate_file_path()) |
| ) |
| ) |
| |
| self.current_target_file_path = src_file |
| self.current_target_name = compdb_target_from_path(src_file) |
| |
| if not self.current_target_file_path.exists(): |
| self.current_target_exists = False |
| |
| else: |
| self.current_target_exists = True |
| self._current_target = CppIdeFeaturesTarget( |
| name=target(src_file), |
| compdb_file_path=src_file, |
| compdb_cache_path=compdb_cache_path_if_exists( |
| settings.working_dir, target(src_file) |
| ), |
| is_enabled=target_is_enabled(target(src_file), settings), |
| ) |
| except (FileNotFoundError, OSError): |
| # If the symlink doesn't exist, there is no current target. |
| pass |
| |
| try: |
| with open( |
| settings.working_dir / MAX_COMMANDS_TARGET_FILENAME |
| ) as max_commands_target_file: |
| self._max_commands_target = max_commands_target_file.readline() |
| except FileNotFoundError: |
| # If the file doesn't exist, a compilation database probably |
| # hasn't been processed yet. |
| pass |
| |
| def __len__(self) -> int: |
| return len(self.targets) |
| |
| def __getitem__(self, index: str) -> CppIdeFeaturesTarget: |
| return self.targets[index] |
| |
| def __iter__(self) -> Generator[CppIdeFeaturesTarget, None, None]: |
| return (target for target in self.targets.values()) |
| |
| @property |
| def current_target(self) -> Optional[str]: |
| """The name of current target used for code analysis. |
| |
| The presence of a symlink with the expected filename pointing to a |
| compilation database matching the expected filename format is the source |
| of truth on what the current target is. |
| """ |
| return ( |
| self._current_target.name |
| if self._current_target is not None |
| else None |
| ) |
| |
| @current_target.setter |
| def current_target(self, target: Optional[str]) -> None: |
| settings = self.settings |
| |
| if not self.is_valid_target(target): |
| raise InvalidTargetException() |
| |
| # The check above rules out None. |
| target = cast(str, target) |
| |
| compdb_symlink_path = settings.working_dir / compdb_generate_file_path() |
| |
| compdb_target_path = settings.working_dir / compdb_generate_file_path( |
| target |
| ) |
| |
| if not compdb_target_path.exists(): |
| raise MissingCompDbException() |
| |
| set_symlink(compdb_target_path, compdb_symlink_path) |
| |
| cache_symlink_path = settings.working_dir / compdb_generate_cache_path() |
| |
| cache_target_path = settings.working_dir / compdb_generate_cache_path( |
| target |
| ) |
| |
| if not cache_target_path.exists(): |
| os.mkdir(cache_target_path) |
| |
| set_symlink(cache_target_path, cache_symlink_path) |
| |
| @property |
| def max_commands_target(self) -> Optional[str]: |
| """The target with the most compile commands. |
| |
| The return value is the name of the target with the largest number of |
| compile commands (i.e., the largest coverage across the files in the |
| project). This can be a useful "default target of last resort". |
| """ |
| return self._max_commands_target |
| |
| @property |
| def available_targets(self) -> List[str]: |
| return list(self.targets.keys()) |
| |
| @property |
| def enabled_available_targets(self) -> Generator[str, None, None]: |
| return ( |
| name for name, target in self.targets.items() if target.is_enabled |
| ) |
| |
| def is_valid_target(self, target: Optional[str]) -> bool: |
| if target is None or (data := self.targets.get(target, None)) is None: |
| return False |
| |
| return data.is_enabled |
| |
| |
| def aggregate_compilation_database_targets( |
| compdb_file: LoadableToCppCompilationDatabase, |
| settings: PigweedIdeSettings, |
| build_dir: Path, |
| *, |
| default_path: Optional[Path] = None, |
| path_globs: Optional[List[str]] = None, |
| ) -> List[str]: |
| """Return all valid unique targets from a ``clang`` compilation database.""" |
| compdbs_map = CppCompilationDatabase.load(compdb_file, build_dir).process( |
| settings, default_path=default_path, path_globs=path_globs |
| ) |
| |
| return compdbs_map.targets |
| |
| |
| def delete_compilation_databases(settings: PigweedIdeSettings) -> None: |
| """Delete all compilation databases in the working directory. |
| |
| This leaves cache directories in place. |
| """ |
| if settings.working_dir.exists(): |
| for path in settings.working_dir.iterdir(): |
| if path.name.startswith(_COMPDB_FILE_PREFIX): |
| try: |
| path.unlink() |
| except FileNotFoundError: |
| pass |
| |
| |
| def delete_compilation_database_caches(settings: PigweedIdeSettings) -> None: |
| """Delete all compilation database caches in the working directory. |
| |
| This leaves all compilation databases in place. |
| """ |
| if settings.working_dir.exists(): |
| for path in settings.working_dir.iterdir(): |
| if path.name.startswith(_COMPDB_CACHE_DIR_PREFIX): |
| try: |
| path.unlink() |
| except FileNotFoundError: |
| pass |
| |
| |
| class ClangdSettings: |
| """Makes system-specific settings for running ``clangd`` with Pigweed.""" |
| |
| def __init__(self, settings: PigweedIdeSettings): |
| self.compile_commands_dir: Path = PigweedIdeSettings().working_dir |
| self.clangd_path: Path = ( |
| Path(PW_PIGWEED_CIPD_INSTALL_DIR) / 'bin' / 'clangd' |
| ) |
| |
| self.arguments: List[str] = [ |
| f'--compile-commands-dir={self.compile_commands_dir}', |
| f'--query-driver={settings.clangd_query_driver_str()}', |
| '--background-index', |
| '--clang-tidy', |
| ] |
| |
| def command(self, system: str = platform.system()) -> str: |
| """Return the command that runs clangd with Pigweed paths.""" |
| |
| def make_command(line_continuation: str): |
| arguments = f' {line_continuation}\n'.join( |
| f' {arg}' for arg in self.arguments |
| ) |
| return f'\n{self.clangd_path} {line_continuation}\n{arguments}' |
| |
| if system.lower() == 'json': |
| return '\n' + json.dumps( |
| [str(self.clangd_path), *self.arguments], indent=2 |
| ) |
| |
| if system.lower() in ['cmd', 'batch']: |
| return make_command('`') |
| |
| if system.lower() in ['powershell', 'pwsh']: |
| return make_command('^') |
| |
| if system.lower() == 'windows': |
| return ( |
| f'\nIn PowerShell:\n{make_command("`")}' |
| f'\n\nIn Command Prompt:\n{make_command("^")}' |
| ) |
| |
| # Default case for *sh-like shells. |
| return make_command('\\') |
