1//===----------------------------------------------------------------------===//
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#include "clang-tidy/ClangTidyCheck.h"
10#include "clang-tidy/ClangTidyModuleRegistry.h"
11
12#include "llvm/ADT/ArrayRef.h"
13
14#include "header_exportable_declarations.hpp"
15
16#include <iostream>
17#include <iterator>
18#include <ranges>
19#include <algorithm>
20
21template <>
22struct clang::tidy::OptionEnumMapping<libcpp::header_exportable_declarations::FileType> {
23 static llvm::ArrayRef<std::pair<libcpp::header_exportable_declarations::FileType, llvm::StringRef>> getEnumMapping() {
24 static constexpr std::pair<libcpp::header_exportable_declarations::FileType, llvm::StringRef> Mapping[] = {
25 {libcpp::header_exportable_declarations::FileType::Header, "Header"},
26 {libcpp::header_exportable_declarations::FileType::ModulePartition, "ModulePartition"},
27 {libcpp::header_exportable_declarations::FileType::Module, "Module"},
28 {libcpp::header_exportable_declarations::FileType::CHeader, "CHeader"},
29 {libcpp::header_exportable_declarations::FileType::CompatModulePartition, "CompatModulePartition"},
30 {libcpp::header_exportable_declarations::FileType::CompatModule, "CompatModule"}};
31 return ArrayRef(Mapping);
32 }
33};
34
35namespace libcpp {
36header_exportable_declarations::header_exportable_declarations(
37 llvm::StringRef name, clang::tidy::ClangTidyContext* context)
38 : clang::tidy::ClangTidyCheck(name, context),
39 filename_(Options.get("Filename", "")),
40 file_type_(Options.get("FileType", header_exportable_declarations::FileType::Unknown)),
41 extra_header_(Options.get("ExtraHeader", "")) {
42 switch (file_type_) {
43 case header_exportable_declarations::FileType::CHeader:
44 case header_exportable_declarations::FileType::Header:
45 if (filename_.empty())
46 llvm::errs() << "No filename is provided.\n";
47 if (extra_header_.empty())
48 extra_header_ = "$^"; // Use a never matching regex to silence an error message.
49 break;
50 case header_exportable_declarations::FileType::ModulePartition:
51 case header_exportable_declarations::FileType::CompatModulePartition:
52 if (filename_.empty())
53 llvm::errs() << "No filename is provided.\n";
54 [[fallthrough]];
55 case header_exportable_declarations::FileType::Module:
56 case header_exportable_declarations::FileType::CompatModule:
57 if (!extra_header_.empty())
58 llvm::errs() << "Extra headers are not allowed for modules.\n";
59 if (Options.get("SkipDeclarations"))
60 llvm::errs() << "Modules may not skip declarations.\n";
61 if (Options.get("ExtraDeclarations"))
62 llvm::errs() << "Modules may not have extra declarations.\n";
63 break;
64 case header_exportable_declarations::FileType::Unknown:
65 llvm::errs() << "No file type is provided.\n";
66 break;
67 }
68
69 std::optional<llvm::StringRef> list = Options.get("SkipDeclarations");
70 if (list)
71 for (auto decl : std::views::split(*list, ' ')) {
72 std::string s;
73 std::ranges::copy(decl, std::back_inserter(s)); // use range based constructor
74 skip_decls_.emplace(std::move(s));
75 }
76 decls_ = skip_decls_;
77
78 list = Options.get("ExtraDeclarations");
79 if (list)
80 for (auto decl : std::views::split(*list, ' ')) {
81 auto common = decl | std::views::common;
82 std::cout << "using ::" << std::string{common.begin(), common.end()} << ";\n";
83 }
84}
85
86header_exportable_declarations::~header_exportable_declarations() {
87 for (const auto& name : global_decls_)
88 if (!skip_decls_.contains("std::" + name) && decls_.contains("std::" + name))
89 std::cout << "using ::" << name << ";\n";
90}
91
92void header_exportable_declarations::registerMatchers(clang::ast_matchers::MatchFinder* finder) {
93 // there are no public names in the Standard starting with an underscore, so
94 // no need to check the strict rules.
95 using namespace clang::ast_matchers;
96
97 switch (file_type_) {
98 case FileType::Header:
99 finder->addMatcher(
100 namedDecl(
101 // Looks at the common locations where headers store their data
102 // * header
103 // * __header/*.h
104 // * __header_dir/*.h // Used for transitioning from __header
105 // * __fwd/header.h
106 anyOf(isExpansionInFileMatching(("v1/__" + filename_ + "/").str()),
107 isExpansionInFileMatching(("v1/__" + filename_ + "_dir/").str()),
108 isExpansionInFileMatching(extra_header_),
109 isExpansionInFileMatching(("v1/__fwd/" + filename_ + "\\.h$").str()),
110 isExpansionInFileMatching(("v1/" + filename_ + "$").str())),
111 unless(hasAncestor(friendDecl())))
112 .bind("header_exportable_declarations"),
113 this);
114 break;
115 case FileType::CHeader:
116 // For C headers of the std.compat two matchers are used
117 // - The cheader matcher; in libc++ these are never split in multiple
118 // headers so limiting the declarations to that header works.
119 // - The header.h; where the declarations of this header are provided
120 // is not specified and depends on the libc used. Therefore it is not
121 // possible to restrict the location in a portable way.
122 finder->addMatcher(namedDecl().bind("cheader_exportable_declarations"), this);
123
124 [[fallthrough]];
125 case FileType::ModulePartition:
126 case FileType::CompatModulePartition:
127 finder->addMatcher(namedDecl(anyOf(isExpansionInFileMatching(filename_), isExpansionInFileMatching(extra_header_)))
128 .bind("header_exportable_declarations"),
129 this);
130 break;
131 case FileType::Module:
132 case FileType::CompatModule:
133 finder->addMatcher(namedDecl().bind("header_exportable_declarations"), this);
134 break;
135 case header_exportable_declarations::FileType::Unknown:
136 llvm::errs() << "This should be unreachable.\n";
137 break;
138 }
139}
140
141/// Returns the qualified name of a public declaration.
142///
143/// There is a small issue with qualified names. Typically the name returned is
144/// in the namespace \c std instead of the namespace \c std::__1. Except when a
145/// name is declared both in the namespace \c std and in the namespace
146/// \c std::__1. In that case the returned value will adjust the name to use
147/// the namespace \c std.
148///
149/// The reason this happens is due to some parts of libc++ using
150/// \code namespace std \endcode instead of
151/// \code _LIBCPP_BEGIN_NAMESPACE_STD \endcode
152/// Some examples
153/// * cstddef has bitwise operators for the type \c byte
154/// * exception has equality operators for the type \c exception_ptr
155/// * initializer_list has the functions \c begin and \c end
156///
157/// When the named declaration uses a reserved name the result is an
158/// empty string.
159static std::string get_qualified_name(const clang::NamedDecl& decl) {
160 std::string result = decl.getNameAsString();
161 // Reject reserved names (ignoring _ in global namespace).
162 if (result.size() >= 2 && result[0] == '_')
163 if (result[1] == '_' || std::isupper(result[1]))
164 if (result != "_Exit")
165 return "";
166
167 for (auto* context = llvm::dyn_cast_or_null<clang::NamespaceDecl>(decl.getDeclContext()); //
168 context;
169 context = llvm::dyn_cast_or_null<clang::NamespaceDecl>(context->getDeclContext())) {
170 std::string ns = std::string(context->getName());
171
172 if (ns.starts_with("__")) {
173 // When the reserved name is an inline namespace the namespace is
174 // not added to the qualified name instead of removed. Libc++ uses
175 // several inline namespace with reserved names. For example,
176 // __1 for every declaration, __cpo in range-based algorithms.
177 //
178 // Note other inline namespaces are expanded. This resolves
179 // ambiguity when two named declarations have the same name but in
180 // different inline namespaces. These typically are the literal
181 // conversion operators like operator""s which can be a
182 // std::string or std::chrono::seconds.
183 if (!context->isInline())
184 return "";
185 } else
186 result = ns + "::" + result;
187 }
188 return result;
189}
190
191static bool is_viable_declaration(const clang::NamedDecl* decl) {
192 // Declarations that are a subobject of a friend Declaration are automatically exported with the record itself.
193 if (decl->getFriendObjectKind() != clang::Decl::FOK_None)
194 return false;
195
196 // *** Function declarations ***
197
198 if (clang::CXXMethodDecl::classof(decl))
199 return false;
200
201 if (clang::CXXDeductionGuideDecl::classof(decl))
202 return false;
203
204 if (clang::FunctionDecl::classof(decl))
205 return true;
206
207 if (clang::CXXConstructorDecl::classof(decl))
208 return false;
209
210 // implicit constructors disallowed
211 if (const auto* r = llvm::dyn_cast_or_null<clang::RecordDecl>(decl))
212 return !r->isLambda() && !r->isImplicit();
213
214 // *** Unconditionally accepted declarations ***
215 return llvm::isa<clang::EnumDecl, clang::VarDecl, clang::ConceptDecl, clang::TypedefNameDecl, clang::UsingDecl>(decl);
216}
217
218/// Some declarations in the global namespace are exported from the std module.
219static bool is_global_name_exported_by_std_module(std::string_view name) {
220 static const std::set<std::string_view> valid{
221 "operator delete", "operator delete[]", "operator new", "operator new[]"};
222 return valid.contains(name);
223}
224
225static bool is_valid_declaration_context(
226 const clang::NamedDecl& decl, std::string_view name, header_exportable_declarations::FileType file_type) {
227 const clang::DeclContext& context = *decl.getDeclContext();
228 if (context.isNamespace())
229 return true;
230
231 if (context.isFunctionOrMethod() || context.isRecord())
232 return false;
233
234 if (is_global_name_exported_by_std_module(name))
235 return true;
236
237 return file_type != header_exportable_declarations::FileType::Header;
238}
239
240static bool is_module(header_exportable_declarations::FileType file_type) {
241 switch (file_type) {
242 case header_exportable_declarations::FileType::Module:
243 case header_exportable_declarations::FileType::ModulePartition:
244 case header_exportable_declarations::FileType::CompatModule:
245 case header_exportable_declarations::FileType::CompatModulePartition:
246 return true;
247
248 case header_exportable_declarations::FileType::Header:
249 case header_exportable_declarations::FileType::CHeader:
250 return false;
251
252 case header_exportable_declarations::FileType::Unknown:
253 llvm::errs() << "This should be unreachable.\n";
254 return false;
255 }
256}
257
258void header_exportable_declarations::check(const clang::ast_matchers::MatchFinder::MatchResult& result) {
259 if (const auto* decl = result.Nodes.getNodeAs<clang::NamedDecl>("header_exportable_declarations"); decl != nullptr) {
260 if (!is_viable_declaration(decl))
261 return;
262
263 std::string name = get_qualified_name(*decl);
264 if (name.empty())
265 return;
266
267 // For modules only take the declarations exported.
268 if (is_module(file_type: file_type_))
269 if (decl->getModuleOwnershipKind() != clang::Decl::ModuleOwnershipKind::VisibleWhenImported)
270 return;
271
272 if (!is_valid_declaration_context(*decl, name, file_type_))
273 return;
274
275 if (decls_.contains(name)) {
276 // For modules avoid exporting the same named declaration twice. For
277 // header files this is common and valid.
278 if (file_type_ == FileType::ModulePartition || file_type_ == FileType::CompatModulePartition)
279 // After the warning the script continues.
280 // The test will fail since modules have duplicated entries and headers not.
281 llvm::errs() << "Duplicated export of '" << name << "'.\n";
282 else
283 return;
284 }
285
286 // For named declarations in std this is valid
287 // using std::foo;
288 // for named declarations it is invalid to use
289 // using bar;
290 // Since fully qualifying named declarations in the std namespace is valid
291 // using fully qualified names unconditionally.
292 std::cout << "using ::" << std::string{name} << ";\n";
293 decls_.insert(x: name);
294 } else if (const auto* decl = result.Nodes.getNodeAs<clang::NamedDecl>("cheader_exportable_declarations");
295 decl != nullptr) {
296 if (decl->getDeclContext()->isNamespace())
297 return;
298
299 if (!is_viable_declaration(decl))
300 return;
301
302 std::string name = get_qualified_name(*decl);
303 if (name.empty())
304 return;
305
306 if (global_decls_.contains(name))
307 return;
308
309 global_decls_.insert(x: name);
310 }
311}
312
313} // namespace libcpp
314

source code of libcxx/test/tools/clang_tidy_checks/header_exportable_declarations.cpp