1//===- ErrorHandler.h -------------------------------------------*- 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// We designed lld's error handlers with the following goals in mind:
10//
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).
15//
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.
21//
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).
27//
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.
31//
32// The current lld's error handling mechanism is simple:
33//
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
36//    call error().
37//
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).
43//
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.
48//
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.
52//
53// This interface satisfies all the goals that we mentioned above.
54//
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.
59//
60// warn() doesn't do anything but printing out a given message.
61//
62// It is not recommended to use llvm::outs() or lld::errs() directly in lld
63// because they are not thread-safe. The functions declared in this file are
64// thread-safe.
65//
66//===----------------------------------------------------------------------===//
67
68#ifndef LLD_COMMON_ERRORHANDLER_H
69#define LLD_COMMON_ERRORHANDLER_H
70
71#include "lld/Common/LLVM.h"
72
73#include "llvm/ADT/STLExtras.h"
74#include "llvm/Support/Error.h"
75#include "llvm/Support/FileOutputBuffer.h"
76
77namespace llvm {
78class DiagnosticInfo;
79class raw_ostream;
80}
81
82namespace lld {
83
84// We wrap stdout and stderr so that you can pass alternative stdout/stderr as
85// arguments to lld::*::link() functions.
86extern llvm::raw_ostream *stdoutOS;
87extern llvm::raw_ostream *stderrOS;
88
89llvm::raw_ostream &outs();
90llvm::raw_ostream &errs();
91
92class ErrorHandler {
93public:
94  uint64_t errorCount = 0;
95  uint64_t errorLimit = 20;
96  StringRef errorLimitExceededMsg = "too many errors emitted, stopping now";
97  StringRef logName = "lld";
98  bool exitEarly = true;
99  bool fatalWarnings = false;
100  bool verbose = false;
101  bool vsDiagnostics = false;
102
103  void error(const Twine &msg);
104  LLVM_ATTRIBUTE_NORETURN void fatal(const Twine &msg);
105  void log(const Twine &msg);
106  void message(const Twine &msg);
107  void warn(const Twine &msg);
108
109  std::unique_ptr<llvm::FileOutputBuffer> outputBuffer;
110
111private:
112  using Colors = raw_ostream::Colors;
113
114  std::string getLocation(const Twine &msg);
115};
116
117/// Returns the default error handler.
118ErrorHandler &errorHandler();
119
120inline void error(const Twine &msg) { errorHandler().error(msg); }
121inline LLVM_ATTRIBUTE_NORETURN void fatal(const Twine &msg) {
122  errorHandler().fatal(msg);
123}
124inline void log(const Twine &msg) { errorHandler().log(msg); }
125inline void message(const Twine &msg) { errorHandler().message(msg); }
126inline void warn(const Twine &msg) { errorHandler().warn(msg); }
127inline uint64_t errorCount() { return errorHandler().errorCount; }
128
129LLVM_ATTRIBUTE_NORETURN void exitLld(int val);
130
131void diagnosticHandler(const llvm::DiagnosticInfo &di);
132void checkError(Error e);
133
134// check functions are convenient functions to strip errors
135// from error-or-value objects.
136template <class T> T check(ErrorOr<T> e) {
137  if (auto ec = e.getError())
138    fatal(ec.message());
139  return std::move(*e);
140}
141
142template <class T> T check(Expected<T> e) {
143  if (!e)
144    fatal(llvm::toString(e.takeError()));
145  return std::move(*e);
146}
147
148template <class T>
149T check2(ErrorOr<T> e, llvm::function_ref<std::string()> prefix) {
150  if (auto ec = e.getError())
151    fatal(prefix() + ": " + ec.message());
152  return std::move(*e);
153}
154
155template <class T>
156T check2(Expected<T> e, llvm::function_ref<std::string()> prefix) {
157  if (!e)
158    fatal(prefix() + ": " + toString(e.takeError()));
159  return std::move(*e);
160}
161
162inline std::string toString(const Twine &s) { return s.str(); }
163
164// To evaluate the second argument lazily, we use C macro.
165#define CHECK(E, S) check2((E), [&] { return toString(S); })
166
167} // namespace lld
168
169#endif
170