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