481 lines
16KB

  1. Error: Linking a runtime binary failed
  2. ######################################
  3. .. contents::
  4. .. highlight:: c++
  5. This error indicates that the final phases of the build pipeline, the link
  6. phases, failed.
  7. The end result of the software development process is to produce applications
  8. and programs that can be executed by users. In the traditional compilation and
  9. linking model, which we still use to this day, multiple *translation units*
  10. (which can be thought of as "source files") are combined together in a process
  11. known as *linking*. The result of linking is an actual executable.
  12. .. note::
  13. Linking is also used to generate executables that are used as tests.
  14. Refer: :ref:`pkgs.apps-tests`.
  15. What is "Linking"?
  16. ******************
  17. The *phases of translation* define the steps taken by a compiler (and linker)
  18. to map from the input human-readable source code to the code that can be
  19. executed by a machine. The first few phases are collected bundled together in
  20. a phase known as "compilation," while the later phases are known as "linking."
  21. The output of the compilation phases is often generated by a *compiler* and
  22. then written to the filesystem. The resulting files, known as *object files*
  23. are then fed into another tool known as a *linker*.
  24. .. note::
  25. "Object files" are just one possible intermediate product. Compilers and
  26. linkers may deal with different intermediate products depending on compiler
  27. and linker options.
  28. Symbol Reference Resolution
  29. ***************************
  30. When code within a translation unit uses a function, variable, or member of a
  31. class that is declared **but not defined** in that translation unit, that
  32. usage is stored as an "unresolved" reference to an external symbol within the
  33. resulting object file.
  34. Each translation unit may also contain the *definitions* of any number of
  35. symbols. It is possible that other translation units may contain unresolved
  36. references to the symbol that the translation unit defines.
  37. It is the job of the linker to fill in these unresolved references when it
  38. combines translation units together.
  39. Failure Modes
  40. *************
  41. There are two very common types of linker errors that may be seen:
  42. Multiple Definitions Found
  43. ==========================
  44. When translation units are combined together, the symbols within them are
  45. combined together into a final binary. If two or more translation units contain
  46. the *definition* of a single symbol, then the linker must make a decision:
  47. #. If the symbol is marked properly, then the linker can discard all except one
  48. of the definitions and choose one to keep in the final binary. For example:
  49. This is allowed if the associated symbol has been declared with the
  50. ``inline`` keyword, or is a symbol in any context that is "implicitly
  51. ``inline``," which includes member functions and static variables which are
  52. defined within their class's body, and any function template.
  53. #. **Fail**
  54. If the linker is not allowed to discard all-but-one of the multiple
  55. definitions, this is a hard-error. This can happen if multiple translation
  56. units defined the same variable or function at the same namespace.
  57. Issue: A non-``inline`` function is defined in a header file
  58. ------------------------------------------------------------
  59. A likely case is that of defining a function in a header file without
  60. marking it as ``inline``:
  61. .. code-block::
  62. :caption: ``hello.hpp``
  63. #ifndef MY_HEADER_INC
  64. #define MY_HEADER_INC
  65. #include <cstdio>
  66. void say_hello() {
  67. std::puts("Hello!\n");
  68. }
  69. #endif
  70. and then that header is ``#include``-ed in multiple source files:
  71. .. code-block::
  72. :caption: ``a.cpp``
  73. #include "hello.hpp"
  74. // ... stuff ...
  75. .. code-block::
  76. :caption: ``b.cpp``
  77. #include "hello.hpp"
  78. // .. different stuff ...
  79. .. note::
  80. ``template`` functions and member functions *defined within the class body*
  81. are implicitly ``inline``, and using the ``inline`` keyword is then
  82. redundant.
  83. In the above configuration, the linker will generate an error about multiple
  84. definitions of the ``say_hello`` function. Possibly confusingly, it will point
  85. to ``a.cpp`` and ``b.cpp`` as the "definers" of ``say_hello``, even though it
  86. is actually defined in the header. The issue is that no tools are currently
  87. able to understand this structure in a way that they can clearly issue
  88. appropriate instruction on how to fix this. There are two ways to fix this:
  89. #. Add the ``inline`` keyword to the definition of ``say_hello``::
  90. #ifndef MY_HEADER_INC
  91. #define MY_HEADER_INC
  92. #include <cstdio>
  93. inline void say_hello() {
  94. std::puts("Hello!\n");
  95. }
  96. #endif
  97. This activates the rule that permits the linker to disregard the multiple
  98. definitions and choose one to keep arbitrarily.
  99. .. note::
  100. Only use ``inline`` in headers!
  101. #. Change the definition of ``say_hello`` to be a *declaration*, and move the
  102. *definition* to a separate source file:
  103. .. code-block::
  104. :caption: ``hello.hpp``
  105. #ifndef MY_HEADER_INC
  106. #define MY_HEADER_INC
  107. #include <cstdio>
  108. void say_hello() {
  109. std::puts("Hello!\n");
  110. }
  111. #endif
  112. .. code-block::
  113. :caption: ``hello.cpp``
  114. #include "hello.hpp"
  115. void say_hello() {
  116. std::puts("Hello!\n");
  117. }
  118. This will place the sole location of the ``say_hello`` definition within
  119. ``hello.cpp``.
  120. Issue: There are two colliding and distinct definitions
  121. -------------------------------------------------------
  122. Suppose you have two different source files:
  123. .. code-block::
  124. :caption: ``a.cpp``
  125. #include "a.hpp"
  126. void error(string message) {
  127. cerr << "An error occured: " << msg << '\n';
  128. }
  129. void a_func() {
  130. bool had_error = first_a();
  131. if (err) {
  132. error(*err);
  133. }
  134. err = second_a();
  135. if (err) {
  136. error(*err);
  137. }
  138. }
  139. .. code-block::
  140. :caption: ``b.cpp``
  141. void error(string message) {
  142. throw runtime_error(msg);
  143. }
  144. void b_func() {
  145. bool had_error = first_b();
  146. if (had_error) {
  147. error("The first step failed!");
  148. }
  149. had_error = second_b();
  150. if (had_error) {
  151. error("The second step failed!");
  152. }
  153. }
  154. The two functions, ``a_func`` and ``b_func``, despite having a similar
  155. structure, are *completely different* because of the behavior of ``error``:
  156. - In ``a.cpp``:
  157. - ``error()`` will simply log a message but let execution continue.
  158. - If ``first_a()`` fails, execution will continue into ``second_a()``.
  159. - In ``b.cpp``:
  160. - ``error()`` will throw an exception.
  161. - If ``first_b()`` fails, execution will never reach ``second_b()``
  162. Nevertheless, the linker will produce an error that there are multiple visible
  163. definitions of ``error()``, even though the translation units individually have
  164. no ambiguity.
  165. The issue is that both of the definitions have *external linkage* and must be
  166. visible to all other translation units.
  167. It may be tempting to fix this issue in the same way that we did in the prior
  168. example: to declare them ``inline``, and it will *seem* to have worked, but
  169. **this will not work correctly!!**
  170. Remember what the linker does in the presence of ``inline`` on multiple
  171. definitions between different translation units: It will *pick one* and
  172. *discard the others*. This means that either ``error`` function may replace the
  173. other across translation units, and the resulting code will have wildly
  174. different behavior.
  175. The *correct* solution is to give the ``error`` function *internal linkage*,
  176. which means that its definition is not visible across translation units. This
  177. will allow both definitions of ``error`` to live together in the linked binary
  178. without ambiguity. The classic way of doing this is through the usage of the
  179. global-scope ``static`` keyword which is present in C::
  180. static void error(string s) {
  181. // ...
  182. }
  183. C++ presents another way it can be done: via an *unnamed namespace*::
  184. namespace {
  185. void error(string s) {
  186. // ...
  187. }
  188. } // close namespace
  189. The benefit of the unnamed namespace is it can be used to mark an entire
  190. section of declarations to be *internal*, and it can also be used to mark a
  191. class definition to have *internal linkage* (There is no way to declare a
  192. "``static class``").
  193. Unresolved External Symbol / Undefined Reference
  194. ================================================
  195. Another common error seen while linking is that of the *unresolved external
  196. symbol* (Visual C++) or *undefined reference* (GCC and Clang). Both have the
  197. same underlying cause, and both have the same solutions.
  198. When a translation unit makes use of a symbol which has been declared *but not
  199. defined within that translation unit*, it is up to the linker to resolve that
  200. reference to another translation unit that contains the definition.
  201. If the linker is unable to find the definition of the referenced entity, it
  202. will emit this error.
  203. Issue: An external library is not being included in the link
  204. ------------------------------------------------------------
  205. If the unresolved reference is to an entity belonging to an external library,
  206. you may be missing the linker inputs to actually use that library.
  207. If your project makes use of a declared entity from a third party (even if that
  208. usage is transitive through a dependency), it is required that the definitions
  209. from that third party library are included in the link step. This usually comes
  210. in the form of a static library, shared library/DLL, or even plain object
  211. files.
  212. If the external library containing the definition in question is managed by
  213. ``dds``, this issue should never occur. If the library exists outside of
  214. ``dds`` (e.g. a system library), then that library will need to be manually
  215. added as a linker input using a toolchain file using the ``Link-Flags`` option.
  216. See: :ref:`toolchains.opt-ref`.
  217. If the name of the unresolved symbol appears unfamiliar or you do not believe
  218. that you are making use of it, it is possible that one of your dependencies is
  219. making use of a system library symbol that needs to be part of the link. The
  220. link error will refer to the object/source file that is actually making the
  221. unresolvable reference. Seeing this filepath will be a reliable way to discover
  222. who would be making the reference, and therefore a good way to track down the
  223. dependency that needs an additional linker input. Refer to the documentation
  224. of the dependency in question to see if it requires additional linker inputs
  225. in order to be used.
  226. If the library that should contain the unresolved reference is a dependency
  227. managed by ``dds``, it is possible that the library author has mistakenly
  228. declared a symbol without providing a definition. If the definition *is*
  229. present in the ``dds``-provided dependency library, then the failure to resolve
  230. the reference would be a ``dds`` bug.
  231. Issue: The definition is simply missing
  232. ---------------------------------------
  233. C and C++ allow for an entity to be *declared* and *defined* separately. If you
  234. *declare* and entity but do not *define* that entity, your code will work as
  235. long as no one attempts to refer to that entity.
  236. Ensure that the entity that is "missing" exists.
  237. Issue: Missing ``virtual`` method implementations
  238. -------------------------------------------------
  239. If the error refers to a missing ``vtable for class``, or if the error refers
  240. to a missing definition of a ``virtual`` function, it means that one or more
  241. ``virtual`` functions are not defined.
  242. Note that ``virtual`` functions are slightly different in this regard: It is
  243. not required that someone actually make a call to the ``virtual`` function for
  244. the definition to be required. The metadata that the compiler generates for
  245. the class containing the ``virtual`` functions will implicitly form a reference
  246. to every ``virtual`` function, so they must all be defined if someone attempts
  247. to instantiate the class, as instantiating the class will form a reference to
  248. that metadata.
  249. Issue: Mismatched declarations and definitions
  250. ----------------------------------------------
  251. Suppose you have a header file and a corresponding source file:
  252. .. code-block::
  253. :caption: ``a.hpp``
  254. namespace foo {
  255. size_t string_length(const string& str);
  256. }
  257. .. code-block::
  258. :caption: ``a.cpp``
  259. #include "a.hpp"
  260. using namespace foo;
  261. size_t string_length(const string& str) {
  262. // ... implementation goes here ...
  263. }
  264. The above code will link correctly, as the definition of ``foo::string_length``,
  265. is available from ``a.cpp``, while the declaration exists in ``a.hpp``.
  266. However, if we modify *only the declaration* to use ``string_view`` instead of
  267. ``const string&``, something different occurs::
  268. namespace foo {
  269. size_t string_length(string_view str);
  270. }
  271. It may be tempting to say that "our declaration and definition do not match,"
  272. but that is semantically incorrect: We have declared a function
  273. ``size_t foo::string_length(string_view)``, but we have defined *and declared*
  274. a **completely different function** ``size_t string_length(const string&)``!
  275. The compiler will not warn about this: There is nothing semantically incorrect
  276. about this code.
  277. The linker, however, will not find any definition of ``foo::string_length``.
  278. The function ``::string_length(const string&)`` isn't even in the ``foo``
  279. ``namespace``: It was declared and defined at the global scope within
  280. ``a.cpp``.
  281. If you are seeing an error about an unresolved reference to a function that is
  282. declared and defined separately, and you are *sure* is being compiled, check
  283. that the signature (and name) of the definition and declaration match
  284. *exactly*.
  285. .. tip::
  286. In essence, the error originates from relying on the
  287. ``using namespace foo`` directive to cause the definition of
  288. ``string_length`` to incidentally hit the name lookup of the prior
  289. declaration.
  290. In C++, using a *qualified name* at the definition site can prevent this
  291. error from slipping through::
  292. #include "a.hpp"
  293. using namespace foo;
  294. size_t foo::string_length(const string& str) {
  295. // ... implementation goes here ...
  296. }
  297. By using the qualified name ``foo::string_length`` at the definition site,
  298. the compiler will validate that the function being defined has a prior
  299. declaration that matches *exactly* to the signature of the definition.
  300. Note that this *is not* the same as defining the function within a
  301. ``namespace`` block::
  302. #include "a.hpp"
  303. // NOT HELPFUL!
  304. namespace foo {
  305. size_t string_length(const string& str) {
  306. // ... implementation goes here ...
  307. }
  308. }
  309. This will suffer the same potential mistake as defining it with an
  310. unqualified name.
  311. Note that within the scope of a function that has been declared within the
  312. namespace, that namespace is currently within scope even if the definition
  313. itself is not wrapped in a ``namespace`` block. It may be a good option to
  314. simply remove the ``using namespace`` directive altogether.
  315. .. note::
  316. This trick cannot be applied to names that are declared at the global
  317. scope, since you cannot use the global-namespace qualifier at a
  318. function definition (it is not valid syntax)::
  319. // Declaration at global scope
  320. void some_function();
  321. // Definition? No: Invalid syntax!
  322. void ::some_function() {
  323. // ... stuff ...
  324. }
  325. Issue: The source file containing definition is not being included in the link
  326. ------------------------------------------------------------------------------
  327. If the translation unit that contains the definition of an entity is not being
  328. passed to the linker, the linker will not be able to find it!
  329. If you are using ``dds`` correctly, and the compiled source file containing the
  330. definition is placed as a (direct or indirect) descendent of the ``src/``
  331. directory, then ``dds`` will always include that source file as part of the
  332. link for the enclosing library.
  333. Build systems that require you to enumerate your source files explicitly will
  334. not automatically see a source file unless it has been added to the source
  335. list. Even build systems that allow directory-globbing (like CMake) will need
  336. to have the globbing pattern match the path to the source file.