xref: /freebsd-src/contrib/llvm-project/lld/docs/missingkeyfunction.rst (revision 0b57cec536236d46e3dba9bd041533462f33dbb7)
1*0b57cec5SDimitry AndricMissing Key Function
2*0b57cec5SDimitry Andric====================
3*0b57cec5SDimitry Andric
4*0b57cec5SDimitry AndricIf your build failed with a linker error something like this::
5*0b57cec5SDimitry Andric
6*0b57cec5SDimitry Andric  foo.cc:28: error: undefined reference to 'vtable for C'
7*0b57cec5SDimitry Andric  the vtable symbol may be undefined because the class is missing its key function
8*0b57cec5SDimitry Andric  (see https://lld.llvm.org/missingkeyfunction)
9*0b57cec5SDimitry Andric
10*0b57cec5SDimitry Andricit's likely that your class C has a key function (defined by the ABI as the first
11*0b57cec5SDimitry Andricnon-pure, non-inline, virtual function), but you haven't actually defined it.
12*0b57cec5SDimitry Andric
13*0b57cec5SDimitry AndricWhen a class has a key function, the compiler emits the vtable (and some other
14*0b57cec5SDimitry Andricthings as well) only in the translation unit that defines that key function. Thus,
15*0b57cec5SDimitry Andricif you're missing the key function, you'll also be missing the vtable. If no other
16*0b57cec5SDimitry Andricfunction calls your missing function, you won't see any undefined reference errors
17*0b57cec5SDimitry Andricfor it, but you will see undefined references to the vtable symbol.
18*0b57cec5SDimitry Andric
19*0b57cec5SDimitry AndricWhen a class has no non-pure, non-inline, virtual functions, there is no key
20*0b57cec5SDimitry Andricfunction, and the compiler is forced to emit the vtable in every translation unit
21*0b57cec5SDimitry Andricthat references the class. In this case, it is emitted in a COMDAT section,
22*0b57cec5SDimitry Andricwhich allows the linker to eliminate all duplicate copies. This is still
23*0b57cec5SDimitry Andricwasteful in terms of object file size and link time, so it's always advisable to
24*0b57cec5SDimitry Andricensure there is at least one eligible function that can serve as the key function.
25*0b57cec5SDimitry Andric
26*0b57cec5SDimitry AndricHere are the most common mistakes that lead to this error:
27*0b57cec5SDimitry Andric
28*0b57cec5SDimitry AndricFailing to define a virtual destructor
29*0b57cec5SDimitry Andric--------------------------------------
30*0b57cec5SDimitry Andric
31*0b57cec5SDimitry AndricSay you have a base class declared in a header file::
32*0b57cec5SDimitry Andric
33*0b57cec5SDimitry Andric  class B {
34*0b57cec5SDimitry Andric  public:
35*0b57cec5SDimitry Andric    B();
36*0b57cec5SDimitry Andric    virtual ~B();
37*0b57cec5SDimitry Andric    ...
38*0b57cec5SDimitry Andric  };
39*0b57cec5SDimitry Andric
40*0b57cec5SDimitry AndricHere, ``~B`` is the first non-pure, non-inline, virtual function, so it is the key
41*0b57cec5SDimitry Andricfunction. If you forget to define ``B::~B`` in your source file, the compiler will
42*0b57cec5SDimitry Andricnot emit the vtable for ``B``, and you'll get an undefined reference to "vtable
43*0b57cec5SDimitry Andricfor B".
44*0b57cec5SDimitry Andric
45*0b57cec5SDimitry AndricThis is just an example of the more general mistake of forgetting to define the
46*0b57cec5SDimitry Andrickey function, but it's quite common because virtual destructors are likely to be
47*0b57cec5SDimitry Andricthe first eligible key function and it's easy to forget to implement them. It's
48*0b57cec5SDimitry Andricalso more likely that you won't have any direct references to the destructor, so
49*0b57cec5SDimitry Andricyou won't see any undefined reference errors that point directly to the problem.
50*0b57cec5SDimitry Andric
51*0b57cec5SDimitry AndricThe solution in this case is to implement the missing function.
52*0b57cec5SDimitry Andric
53*0b57cec5SDimitry AndricForgetting to declare a virtual function in an abstract class as pure
54*0b57cec5SDimitry Andric---------------------------------------------------------------------
55*0b57cec5SDimitry Andric
56*0b57cec5SDimitry AndricSay you have an abstract base class declared in a header file::
57*0b57cec5SDimitry Andric
58*0b57cec5SDimitry Andric  class A {
59*0b57cec5SDimitry Andric  public:
60*0b57cec5SDimitry Andric    A();
61*0b57cec5SDimitry Andric    virtual ~A() {}
62*0b57cec5SDimitry Andric    virtual int foo() = 0;
63*0b57cec5SDimitry Andric    ...
64*0b57cec5SDimitry Andric    virtual int bar();
65*0b57cec5SDimitry Andric    ...
66*0b57cec5SDimitry Andric  };
67*0b57cec5SDimitry Andric
68*0b57cec5SDimitry AndricThis base class is intended to be abstract, but you forgot to mark one of the
69*0b57cec5SDimitry Andricfunctions pure. Here, ``A::bar``, being non-pure, is nominated as the key function,
70*0b57cec5SDimitry Andricand as a result, the vtable for ``A`` is not emitted, because the compiler is
71*0b57cec5SDimitry Andricwaiting for a translation unit that defines ``A::bar``.
72*0b57cec5SDimitry Andric
73*0b57cec5SDimitry AndricThe solution in this case is to add the missing ``= 0`` to the declaration of
74*0b57cec5SDimitry Andric``A::bar``.
75*0b57cec5SDimitry Andric
76*0b57cec5SDimitry AndricKey function is defined, but the linker doesn't see it
77*0b57cec5SDimitry Andric------------------------------------------------------
78*0b57cec5SDimitry Andric
79*0b57cec5SDimitry AndricIt's also possible that you have defined the key function somewhere, but the
80*0b57cec5SDimitry Andricobject file containing the definition of that function isn't being linked into
81*0b57cec5SDimitry Andricyour application.
82*0b57cec5SDimitry Andric
83*0b57cec5SDimitry AndricThe solution in this case is to check your dependencies to make sure that
84*0b57cec5SDimitry Andricthe object file or the library file containing the key function is given to
85*0b57cec5SDimitry Andricthe linker.
86