clang-tools  15.0.0git
StdLib.h
Go to the documentation of this file.
1 //===--- StdLib.h - Index the C and C++ standard library ---------*- 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 // Eagerly indexing the standard library gives a much friendlier "warm start"
9 // with working code completion in a standalone file or small project.
10 //
11 // We act as if we saw a file which included the whole standard library:
12 // #include <array>
13 // #include <bitset>
14 // #include <chrono>
15 // ...
16 // We index this TU and feed the result into the dynamic index.
17 //
18 // This happens within the context of some particular open file, and we reuse
19 // its CompilerInvocation. Matching its include path, LangOpts etc ensures that
20 // we see the standard library and configuration that matches the project.
21 //===----------------------------------------------------------------------===//
22 
23 #ifndef LLVM_CLANG_TOOLS_EXTRA_CLANGD_INDEX_STDLIB_H
24 #define LLVM_CLANG_TOOLS_EXTRA_CLANGD_INDEX_STDLIB_H
25 
26 #include "index/Symbol.h"
27 #include "support/ThreadsafeFS.h"
28 #include "llvm/ADT/StringRef.h"
29 #include <string>
30 
31 namespace clang {
32 class CompilerInvocation;
33 class LangOptions;
34 class HeaderSearch;
35 namespace clangd {
36 
37 // The filesystem location where a standard library was found.
38 //
39 // This is the directory containing <vector> or <stdio.h>.
40 // It's used to ensure we only index files that are in the standard library.
41 //
42 // The paths are canonicalized (FS "real path" with symlinks resolved).
43 // This allows them to be easily compared against paths the indexer returns.
45  llvm::SmallVector<std::string> Paths;
46 };
47 
48 // Tracks the state of standard library indexing within a particular index.
49 //
50 // In general, we don't want to index the standard library multiple times.
51 // In most cases, this class just acts as a flag to ensure we only do it once.
52 //
53 // However, if we first open a C++11 file, and then a C++20 file, we *do*
54 // want the index to be upgraded to include the extra symbols.
55 // Similarly, the C and C++ standard library can coexist.
56 class StdLibSet {
57  std::atomic<int> Best[2] = {{-1}, {-1}};
58 
59 public:
60  // Determines if we should index the standard library in a configuration.
61  //
62  // This is true if:
63  // - standard library indexing is enabled for the file
64  // - the language version is higher than any previous add() for the language
65  // - the standard library headers exist on the search path
66  // Returns the location where the standard library was found.
67  //
68  // This function is threadsafe.
69  llvm::Optional<StdLibLocation> add(const LangOptions &, const HeaderSearch &);
70 
71  // Indicates whether a built index should be used.
72  // It should not be used if a newer version has subsequently been added.
73  //
74  // Intended pattern is:
75  // if (add()) {
76  // symbols = indexStandardLibrary();
77  // if (isBest())
78  // index.update(symbols);
79  // }
80  //
81  // This is still technically racy: we could return true here, then another
82  // thread could add->index->update a better library before we can update.
83  // We'd then overwrite it with the older version.
84  // However, it's very unlikely: indexing takes a long time.
85  bool isBest(const LangOptions &) const;
86 };
87 
88 // Index a standard library and return the discovered symbols.
89 //
90 // The compiler invocation should describe the file whose config we're reusing.
91 // We overwrite its virtual buffer with a lot of #include statements.
92 SymbolSlab indexStandardLibrary(std::unique_ptr<CompilerInvocation> Invocation,
93  const StdLibLocation &Loc,
94  const ThreadsafeFS &TFS);
95 
96 // Variant that allows the umbrella header source to be specified.
97 // Exposed for testing.
98 SymbolSlab indexStandardLibrary(llvm::StringRef HeaderSources,
99  std::unique_ptr<CompilerInvocation> CI,
100  const StdLibLocation &Loc,
101  const ThreadsafeFS &TFS);
102 
103 // Generate header containing #includes for all standard library headers.
104 // Exposed for testing.
105 llvm::StringRef getStdlibUmbrellaHeader(const LangOptions &);
106 
107 } // namespace clangd
108 } // namespace clang
109 
110 #endif // LLVM_CLANG_TOOLS_EXTRA_CLANGD_INDEX_STDLIB_H
Loc
SourceLocation Loc
Definition: KernelNameRestrictionCheck.cpp:45
CI
std::unique_ptr< CompilerInvocation > CI
Definition: TUScheduler.cpp:491
clang::clangd::StdLibLocation
Definition: StdLib.h:44
ThreadsafeFS.h
clang::clangd::getStdlibUmbrellaHeader
llvm::StringRef getStdlibUmbrellaHeader(const LangOptions &LO)
Definition: StdLib.cpp:97
clang::clangd::StdLibSet::isBest
bool isBest(const LangOptions &) const
Definition: StdLib.cpp:284
clang::clangd::indexStandardLibrary
SymbolSlab indexStandardLibrary(llvm::StringRef HeaderSources, std::unique_ptr< CompilerInvocation > CI, const StdLibLocation &Loc, const ThreadsafeFS &TFS)
Definition: StdLib.cpp:208
Symbol.h
clang::clangd::StdLibSet
Definition: StdLib.h:56
clang::clangd::ThreadsafeFS
Wrapper for vfs::FileSystem for use in multithreaded programs like clangd.
Definition: ThreadsafeFS.h:27
clang::clangd::StdLibSet::add
llvm::Optional< StdLibLocation > add(const LangOptions &, const HeaderSearch &)
Definition: StdLib.cpp:289
clang
===– Representation.cpp - ClangDoc Representation --------—*- C++ -*-===//
Definition: ApplyReplacements.h:27
clang::clangd::SymbolSlab
An immutable symbol container that stores a set of symbols.
Definition: Symbol.h:177
clang::clangd::StdLibLocation::Paths
llvm::SmallVector< std::string > Paths
Definition: StdLib.h:45