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 <optional> 30 #include <string> 31 32 namespace clang { 33 class CompilerInvocation; 34 class LangOptions; 35 class HeaderSearch; 36 namespace clangd { 37 38 // The filesystem location where a standard library was found. 39 // 40 // This is the directory containing <vector> or <stdio.h>. 41 // It's used to ensure we only index files that are in the standard library. 42 // 43 // The paths are canonicalized (FS "real path" with symlinks resolved). 44 // This allows them to be easily compared against paths the indexer returns. 45 struct StdLibLocation { 46 llvm::SmallVector<std::string> Paths; 47 }; 48 49 // Tracks the state of standard library indexing within a particular index. 50 // 51 // In general, we don't want to index the standard library multiple times. 52 // In most cases, this class just acts as a flag to ensure we only do it once. 53 // 54 // However, if we first open a C++11 file, and then a C++20 file, we *do* 55 // want the index to be upgraded to include the extra symbols. 56 // Similarly, the C and C++ standard library can coexist. 57 class StdLibSet { 58 std::atomic<int> Best[2] = {{-1}, {-1}}; 59 60 public: 61 // Determines if we should index the standard library in a configuration. 62 // 63 // This is true if: 64 // - standard library indexing is enabled for the file 65 // - the language version is higher than any previous add() for the language 66 // - the standard library headers exist on the search path 67 // Returns the location where the standard library was found. 68 // 69 // This function is threadsafe. 70 std::optional<StdLibLocation> add(const LangOptions &, const HeaderSearch &); 71 72 // Indicates whether a built index should be used. 73 // It should not be used if a newer version has subsequently been added. 74 // 75 // Intended pattern is: 76 // if (add()) { 77 // symbols = indexStandardLibrary(); 78 // if (isBest()) 79 // index.update(symbols); 80 // } 81 // 82 // This is still technically racy: we could return true here, then another 83 // thread could add->index->update a better library before we can update. 84 // We'd then overwrite it with the older version. 85 // However, it's very unlikely: indexing takes a long time. 86 bool isBest(const LangOptions &) const; 87 }; 88 89 // Index a standard library and return the discovered symbols. 90 // 91 // The compiler invocation should describe the file whose config we're reusing. 92 // We overwrite its virtual buffer with a lot of #include statements. 93 SymbolSlab indexStandardLibrary(std::unique_ptr<CompilerInvocation> Invocation, 94 const StdLibLocation &Loc, 95 const ThreadsafeFS &TFS); 96 97 // Variant that allows the umbrella header source to be specified. 98 // Exposed for testing. 99 SymbolSlab indexStandardLibrary(llvm::StringRef HeaderSources, 100 std::unique_ptr<CompilerInvocation> CI, 101 const StdLibLocation &Loc, 102 const ThreadsafeFS &TFS); 103 104 // Generate header containing #includes for all standard library headers. 105 // Exposed for testing. 106 llvm::StringRef getStdlibUmbrellaHeader(const LangOptions &); 107 108 } // namespace clangd 109 } // namespace clang 110 111 #endif // LLVM_CLANG_TOOLS_EXTRA_CLANGD_INDEX_STDLIB_H 112