1 //===- ErrorHandler.h -------------------------------------------*- C++ -*-===//
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
7 //===----------------------------------------------------------------------===//
9 // We designed lld's error handlers with the following goals in mind:
11 // - Errors can occur at any place where we handle user input, but we don't
12 // want them to affect the normal execution path too much. Ideally,
13 // handling errors should be as simple as reporting them and exit (but
14 // without actually doing exit).
16 // In particular, the design to wrap all functions that could fail with
17 // ErrorOr<T> is rejected because otherwise we would have to wrap a large
18 // number of functions in lld with ErrorOr. With that approach, if some
19 // function F can fail, not only F but all functions that transitively call
20 // F have to be wrapped with ErrorOr. That seemed too much.
22 // - Finding only one error at a time is not sufficient. We want to find as
23 // many errors as possible with one execution of the linker. That means the
24 // linker needs to keep running after a first error and give up at some
25 // checkpoint (beyond which it would find cascading, false errors caused by
26 // the previous errors).
28 // - We want a simple interface to report errors. Unlike Clang, the data we
29 // handle is compiled binary, so we don't need an error reporting mechanism
30 // that's as sophisticated as the one that Clang has.
32 // The current lld's error handling mechanism is simple:
34 // - When you find an error, report it using error() and continue as far as
35 // you can. An internal error counter is incremented by one every time you
38 // A common idiom to handle an error is calling error() and then returning
39 // a reasonable default value. For example, if your function handles a
40 // user-supplied alignment value, and if you find an invalid alignment
41 // (e.g. 17 which is not 2^n), you may report it using error() and continue
42 // as if it were alignment 1 (which is the simplest reasonable value).
44 // Note that you should not continue with an invalid value; that breaks the
45 // internal consistency. You need to maintain all variables have some sane
46 // value even after an error occurred. So, when you have to continue with
47 // some value, always use a dummy value.
49 // - Find a reasonable checkpoint at where you want to stop the linker, and
50 // add code to return from the function if errorCount() > 0. In most cases,
51 // a checkpoint already exists, so you don't need to do anything for this.
53 // This interface satisfies all the goals that we mentioned above.
55 // You should never call fatal() except for reporting a corrupted input file.
56 // fatal() immediately terminates the linker, so the function is not desirable
57 // if you are using lld as a subroutine in other program, and with that you
58 // can find only one error at a time.
60 // warn() doesn't do anything but printing out a given message.
62 // It is not recommended to use llvm::outs() or llvm::errs() directly in lld
63 // because they are not thread-safe. The functions declared in this file are
66 //===----------------------------------------------------------------------===//
68 #ifndef LLD_COMMON_ERRORHANDLER_H
69 #define LLD_COMMON_ERRORHANDLER_H
71 #include "lld/Common/LLVM.h"
73 #include "llvm/ADT/STLExtras.h"
74 #include "llvm/Support/Error.h"
75 #include "llvm/Support/FileOutputBuffer.h"
85 uint64_t errorCount = 0;
86 uint64_t errorLimit = 20;
87 StringRef errorLimitExceededMsg = "too many errors emitted, stopping now";
88 StringRef logName = "lld";
89 llvm::raw_ostream *errorOS = &llvm::errs();
90 bool colorDiagnostics = llvm::errs().has_colors();
91 bool exitEarly = true;
92 bool fatalWarnings = false;
94 bool vsDiagnostics = false;
96 void error(const Twine &msg);
97 LLVM_ATTRIBUTE_NORETURN void fatal(const Twine &msg);
98 void log(const Twine &msg);
99 void message(const Twine &msg);
100 void warn(const Twine &msg);
102 std::unique_ptr<llvm::FileOutputBuffer> outputBuffer;
105 void printHeader(StringRef s, raw_ostream::Colors c, const Twine &msg);
108 /// Returns the default error handler.
109 ErrorHandler &errorHandler();
111 inline void error(const Twine &msg) { errorHandler().error(msg); }
112 inline LLVM_ATTRIBUTE_NORETURN void fatal(const Twine &msg) {
113 errorHandler().fatal(msg);
115 inline void log(const Twine &msg) { errorHandler().log(msg); }
116 inline void message(const Twine &msg) { errorHandler().message(msg); }
117 inline void warn(const Twine &msg) { errorHandler().warn(msg); }
118 inline uint64_t errorCount() { return errorHandler().errorCount; }
120 LLVM_ATTRIBUTE_NORETURN void exitLld(int val);
122 void diagnosticHandler(const llvm::DiagnosticInfo &di);
123 void checkError(Error e);
125 // check functions are convenient functions to strip errors
126 // from error-or-value objects.
127 template <class T> T check(ErrorOr<T> e) {
128 if (auto ec = e.getError())
130 return std::move(*e);
133 template <class T> T check(Expected<T> e) {
135 fatal(llvm::toString(e.takeError()));
136 return std::move(*e);
140 T check2(ErrorOr<T> e, llvm::function_ref<std::string()> prefix) {
141 if (auto ec = e.getError())
142 fatal(prefix() + ": " + ec.message());
143 return std::move(*e);
147 T check2(Expected<T> e, llvm::function_ref<std::string()> prefix) {
149 fatal(prefix() + ": " + toString(e.takeError()));
150 return std::move(*e);
153 inline std::string toString(const Twine &s) { return s.str(); }
155 // To evaluate the second argument lazily, we use C macro.
156 #define CHECK(E, S) check2((E), [&] { return toString(S); })