clang-tools  15.0.0git
CanonicalIncludes.h
Go to the documentation of this file.
1 //===-- CanonicalIncludes.h - remap #include header -------------*- C++ -*-===//
2 //
3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4 // See https://llvm.org/LICENSE.txt for license information.
5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6 //
7 //===----------------------------------------------------------------------===//
8 //
9 // At indexing time, we decide which file to #included for a symbol.
10 // Usually this is the file with the canonical decl, but there are exceptions:
11 // - private headers may have pragmas pointing to the matching public header.
12 // (These are "IWYU" pragmas, named after the include-what-you-use tool).
13 // - the standard library is implemented in many files, without any pragmas.
14 // We have a lookup table for common standard library implementations.
15 // libstdc++ puts char_traits in bits/char_traits.h, but we #include <string>.
16 //
17 //===----------------------------------------------------------------------===//
18 
19 #ifndef LLVM_CLANG_TOOLS_EXTRA_CLANGD_INDEX_CANONICALINCLUDES_H
20 #define LLVM_CLANG_TOOLS_EXTRA_CLANGD_INDEX_CANONICALINCLUDES_H
21 
22 #include "clang/Basic/FileEntry.h"
23 #include "clang/Lex/Preprocessor.h"
24 #include "llvm/ADT/StringMap.h"
25 #include "llvm/ADT/StringRef.h"
26 #include "llvm/Support/FileSystem/UniqueID.h"
27 #include <mutex>
28 #include <string>
29 #include <vector>
30 
31 namespace clang {
32 namespace clangd {
33 
34 /// Maps a definition location onto an #include file, based on a set of filename
35 /// rules.
36 /// Only const methods (i.e. mapHeader) in this class are thread safe.
38 public:
39  /// Adds a file-to-string mapping from \p ID to \p CanonicalPath.
40  void addMapping(FileEntryRef Header, llvm::StringRef CanonicalPath);
41 
42  /// Returns the overridden include for symbol with \p QualifiedName, or "".
43  llvm::StringRef mapSymbol(llvm::StringRef QualifiedName) const;
44 
45  /// Returns the overridden include for for files in \p Header, or "".
46  llvm::StringRef mapHeader(FileEntryRef Header) const;
47 
48  /// Adds mapping for system headers and some special symbols (e.g. STL symbols
49  /// in <iosfwd> need to be mapped individually). Approximately, the following
50  /// system headers are handled:
51  /// - C++ standard library e.g. bits/basic_string.h$ -> <string>
52  /// - Posix library e.g. bits/pthreadtypes.h$ -> <pthread.h>
53  /// - Compiler extensions, e.g. include/avx512bwintrin.h$ -> <immintrin.h>
54  /// The mapping is hardcoded and hand-maintained, so it might not cover all
55  /// headers.
56  void addSystemHeadersMapping(const LangOptions &Language);
57 
58 private:
59  /// A map from the private header to a canonical include path.
60  llvm::DenseMap<llvm::sys::fs::UniqueID, std::string> FullPathMapping;
61  /// A map from a suffix (one or components of a path) to a canonical path.
62  /// Used only for mapping standard headers.
63  const llvm::StringMap<llvm::StringRef> *StdSuffixHeaderMapping = nullptr;
64  /// A map from fully qualified symbol names to header names.
65  /// Used only for mapping standard symbols.
66  const llvm::StringMap<llvm::StringRef> *StdSymbolMapping = nullptr;
67 };
68 
69 /// Returns a CommentHandler that parses pragma comment on include files to
70 /// determine when we should include a different header from the header that
71 /// directly defines a symbol. Mappinps are registered with \p Includes.
72 ///
73 /// Currently it only supports IWYU private pragma:
74 /// https://github.com/include-what-you-use/include-what-you-use/blob/master/docs/IWYUPragmas.md#iwyu-pragma-private
75 ///
76 /// We ignore other pragmas:
77 /// - keep: this is common but irrelevant: we do not currently remove includes
78 /// - export: this is common and potentially interesting, there are three cases:
79 /// * Points to a public header (common): we can suppress include2 if you
80 /// already have include1. Only marginally useful.
81 /// * Points to a private header annotated with `private` (somewhat commmon):
82 /// Not incrementally useful as we support private.
83 /// * Points to a private header without pragmas (rare). This is a reversed
84 /// private pragma, and is valuable but too rare to be worthwhile.
85 /// - no_include: this is about as common as private, but only affects the
86 /// current file, so the value is smaller. We could add support.
87 /// - friend: this is less common than private, has implementation difficulties,
88 /// and affects behavior in a limited scope.
89 /// - associated: extremely rare
90 std::unique_ptr<CommentHandler>
92 
93 } // namespace clangd
94 } // namespace clang
95 
96 #endif // LLVM_CLANG_TOOLS_EXTRA_CLANGD_INDEX_CANONICALINCLUDES_H
clang::clangd::CanonicalIncludes::addSystemHeadersMapping
void addSystemHeadersMapping(const LangOptions &Language)
Adds mapping for system headers and some special symbols (e.g.
Definition: CanonicalIncludes.cpp:735
clang::clangd::collectIWYUHeaderMaps
std::unique_ptr< CommentHandler > collectIWYUHeaderMaps(CanonicalIncludes *Includes)
Returns a CommentHandler that parses pragma comment on include files to determine when we should incl...
Definition: CanonicalIncludes.cpp:709
clang::clangd::CanonicalIncludes
Maps a definition location onto an #include file, based on a set of filename rules.
Definition: CanonicalIncludes.h:37
clang::clangd::CanonicalIncludes::mapHeader
llvm::StringRef mapHeader(FileEntryRef Header) const
Returns the overridden include for for files in Header, or "".
Definition: CanonicalIncludes.cpp:681
clang::clangd::CanonicalIncludes::addMapping
void addMapping(FileEntryRef Header, llvm::StringRef CanonicalPath)
Adds a file-to-string mapping from ID to CanonicalPath.
Definition: CanonicalIncludes.cpp:672
clang::clangd::CanonicalIncludes::mapSymbol
llvm::StringRef mapSymbol(llvm::StringRef QualifiedName) const
Returns the overridden include for symbol with QualifiedName, or "".
Definition: CanonicalIncludes.cpp:704
clang
===– Representation.cpp - ClangDoc Representation --------—*- C++ -*-===//
Definition: ApplyReplacements.h:27