Multiple Definition Error Including C++ Header File with Inline Code from Multiple Sources

multiple definition error including c++ header file with inline code from multiple sources

These are not equivalent. The second example given has an implicit 'inline' modifier on the method and so the compiler will reconcile multiple definitions itself (most likely with internal linkage of the method if it isn't inlineable).

The first example isn't inline and so if this header is included in multiple translation units then you will have multiple definitions and linker errors.

Also, headers should really always be guarded to prevent multiple definition errors in the same translation unit. That should convert your header to:

#ifndef EXAMPLE_H
#define EXAMPLE_H

//define your class here

#endif

Compiling error with errors like multiple definition

Inside your header file, you should declare your variable like:

extern const int khStrInt;

Then in a .c file, you should define it like:

const int khStrInt = 33;

This means the variable definition is only generated once by the compiler when compiling the .c file and so the linker doesn't see multiple definitions. Also, having the declaration in the header file allows other files which include the header to be able to use the variable.

multiple definition error c++

Since I could not find any complete (in my view) duplicate for this question, I am going to write a (hopefully) authoritive and complete answer.

What is One Definition Rule and why should I care

A One Definition Rule, usually dubbed ODR, is a rule which states (simplified) that any entity (informal term) used in the program should be defined once, and only once. An entity which is defined more than once is often causing a compilation or linker error, but sometimes can be left undetected by the compiler and lead to very hard-to-trace bugs.

I am not going to formally define entity here, but one can think of it as a function, variable or class. Before going further, one should very clear understand the difference between definition and declaration in C++, since while double definition is prohibited, double declaration is usually unavoidable.

Definition vs. declaration

Every entity used in the code should be declared in the given translation unit (translation unit is usually a cpp source file together with all header files included in it, directly or indirectly through other header files). The way an entitty is declared differes based on the entity itself. See below on how to declare different types of entities. Entities are often declared in header files. Since most complex application has more than one translation unit in it (more than one cpp file), and different cpp files often include the same headers, an application is likely to have multiple declarations for many entities used. Like I said above, this is not a problem.

Every entity used in the application, must be defined once and only once. The term 'application' is used a bit loosely here - for example, libraries (both static and dynamic) can have entities (at this point usually called symbols) left undefined within them, and an executable which was linked to use a dynamic library can have a symbol undefined as well. Instead, I refer to the application is an ultimate running something, after all the libraries have been statically or dynamically linked into it, and symbols resolved.

It is also worth noting that every definition serves as a declaration as well, meaning, that whenever you define something, you are also declaring the same thing.

As with declaration, the way to define an entity differes by the type of entity. Here is how one can declare/define 3 basic types of entities - variables, classes and functions - based on it's type.

Variables

Variables are declared using following construct:

extern int x;

This declares a variable x. It does not define it! A following piece of code will be compiled OK, but an attempt to link it without any other input files (for example, with g++ main.cpp) will produce a link-time error due to undefined symbols:

extern int x;
int main() {
    return x;
}

The following piece of code defines variable x:

int x;

If this single line were to be put into file x.cpp, and this file compiled/linked together with main.cpp from above with g++ x.cpp main.cpp -o test it would compile and link without problems. You could even run resulting executable, and if you are to check exit code after the executable was run, you'd notice it is 0. (Since global variable x would be default-initialized to 0).

Functions

Functions are declared by providing their prototypes. A typical function declaration looks like following:

double foo(int x, double y);

This construct declares a function foo, returning double and accepting two arguments - one of type int, another of type double. This declaration can appear multiple times.

Following code defines above mentioned foo:

void foo(int x, double y) {
    return x * y;
}

This definition can only appear once in the whole application.

Function definition has an additional quirk to variable definition. If above definition of foo were to put into header file foo.h, which in turn would be included by two cpp files 1.cpp and 2.cpp, which are compiled/linked together with g++ 1.cpp 2.cpp -o test you would have a linker error, saying that foo() is defined twice. This might be prevented by using following form of foo declaration:

inline void foo(int x, double y) {
    return x * y;
}

Note inline there. What it tells compiler is that foo can be included by multiple .cpp files, and this inclusion should not produce linker error. Compiler have several options on how to make this happen, but it can be relied upon to do it's job. Note, it would still be an error to have this definition twice in the same translation unit! For example, following code will produce a compiler error

inline void foo() { }
inline void foo() { }

It is worth noting, that any class method defined within the class is implictly inline, for example:

class A {
public:
    int foo() { return 42; }
};

Here A::foo() is defined inline.

Classess

Classess are declared by following construct:

class X;

Above declaration declares class X (and at this point X is formally called an incomplete type), so that it can be used when information about it contents, such as it's size or it's members is not needed. For example:

X* p; // OK - no information about class X is actually required to define a pointer to it
p->y = 42; // Error - compiler has no idea if X has any member named `y`

void foo(X x); // OK - compiler does not need to generated any code for this

void foo(X x) { } // Error - compiler needs to know the size of X to generate code for foo to properly read it's argument
void bar(X* x) { } // OK - compiler needs not to know specifics of X for this

A definition of class is well-known to everybody, and follows this construct:

class X {
   public:
   int y;
};

This makes a class X defined, and now it can be used in any context. An important note - class definition has to be unique per tralnlation unit, but does not have to be unique per application. That is, you can have X defined only once per translation unit, but it can be used in multiple files linked together.

How to properly follow ODR rules

Whenever a same entity is defined more than once in the resulting application, so-called ODR violation happenes. Most of the time, a linker will see the violation and will complain. However, there are cases when ODR violation does not break linking and instead causes bugs. This might happen, for example, when the same .cpp file defining a global variable X is put into both application and dynamic library, which is loaded on demand (with dlopen). (Yours trully spent a couple of days trying to trace a bug happened because of that.)

A more conventional causes of ODR violations are:

Same entity defined twice in the same file in the same scope

int x;
int x; // ODR violation

void foo() {
   int x;
} // No ODR violation, foo::x is different from x in the global scope

Prevention: don't do this.

Same entity defined twice, when it was supposed to be declared

(in x.h)
int x;

(in 1.cpp)
#include <x.h>
void set_x(int y) {
   x = y;
}

(in 2.cpp)
#include <x.h>
int get_x() {
    return x;
}

While the wisdom of above code is questionable at best, in serves a point of illustrating ODR rule. In the code above, variable x is supposed to be shared between two files, 1.cpp and 2.cpp, but was coded incorrectly. Instead, the code should be following:

(in x.h)
extern int x; //declare x

(in x.xpp)
int x; // define x

// 1.cpp and 2.cpp remain the same

Prevention
Know what you are doing. Declare entities when you want them declared, do not define them.
If in the example above we'd use function instead of the variable, like following:

(in x.h)
int x_func() { return 42; }

We would have a problem which could be solved in two ways (as mentioned above). We could use inline function, or we could move definition to the cpp file:

(in x.h)
int x_func();

(in x.cpp)
int x_func() { return 42; } 

Same header file included twice, causing the same class defined twice
This is a funny one. Imagine, you have a following code:

(in a.h)
class A { };

(in main.cpp)
#include <a.h>
#include <a.h> // compilation error!

The above code is seldom appearing as written, but it is quite easy to have the same file included twice through the intermediate:

(in foo.h)
#include <a.h>

(in main.cpp)
#include <a.h>
#include <foo.h>

Prevention Traditional solution to this is to use so-called include guards, that is, a special preprocessor definitions which would prevent the double-inclusion. In this regard, a.h should be redone as following:

(in a.h)
#ifndef INCLUDED_A_H
#define INCLUDED_A_H

class A { };

#endif

The code above will prevent inclusion of a.h into the same translation unit more than once, since INCLUDED_A_H will become defined after first inclusion, and will fail #ifndef on all subsequent ones.

Some compilers expose other ways to control inclusion, but to date include guards remain the way to do it uniformely across different compilers.

Multiple definition error on variable that is declared and defined in header file and used only in its cpp file

If you declare your variable in the header file:

#ifndef GLOBAL_H
#define GLOBAL_H

int foo = 0;

#endif

In every include of your header file or translation unit, a new instance of your integer is created. As you mentioned, to avoid this, you need to declare the item as "extern" in the header file and initialize it in the implementation file:

// .h
extern int foo;

// .cpp
int foo = 0

A more C++ way to do that can be something like this:

#ifndef GLOBAL_H
#define GLOBAL_H

struct Global {
    static int foo;
};
#endif

And in your cpp file:

#include "variables.h"

int Global::foo = 0;

C++17 fixes this problem with inline variables, so you can do:

#ifndef GLOBAL_H
#define GLOBAL_H

inline int foo = 0;

#endif

See How do inline variables work? for more information.

Why does defining functions in header files create multiple definition errors, but not classes?

Generally when you compile a definition that is namespace scoped (like functions or global variables), your compiler will emit a global symbol for it. If this appears in multiple translation units, there will be a conflict during link-time since there are multiple definitions (which happen to be equivalent, but the linker can't check this).

This is part of the one definition rule: Exactly one definition of a function or variable is allowed in the entire program, in one of the translation units.

There are some exceptions to this, for example, class definitions and inline functions/variables. However, definitions must be the exact same (textually) in all the translation units they appear in. Class definitions are meant to be #included, so it makes sense to allow them to appear in multiple translation units.

If you define a member function inside the class body they are implicitly inline because otherwise you would not be able to include the class definition with the member function definition without breaking ODR. For example, these three are functionally equivalent:

struct TestStruct {
    int x;
    int test() { return 10; }
};

// Could have been written

struct TestStruct {
    int x;
    inline int test() { return 10; }
};

// Or as

struct TestStruct {
    int x;
    int test();  // The `inline` specifier could also be here
};

inline int TestStruct::test() { return 10; }

You can do this to your namespace scoped functions/variables too: inline int test() { return 5; } and inline int x = 20; would have compiled with no further issue.

This is implemented by the compiler emitting "specially marked" symbols for inline entities, and the linker picking one arbitrarily since they should all be the same.

The same exception to ODR also exists for templated functions / variables and enum declarations, since they are also meant to live in header files.

One header file in multipe cpp files: Multiple definition

There are 2 solutions to this problem.

Solution 1

You can add the keyword inline infront of the function like:

myfile.h

#ifndef UTILS
#define UTILS

inline void toUpper(string &str) {
    for(unsigned int i=0; i<str.length(); i++) {
            str.at(i) = toupper(str.at(i));
    }
}

inline void toLower(string &str) {
    for(unsigned int i=0; i<str.length(); i++) {
            str.at(i) = tolower(str.at(i));
    }
}

#endif // UTILS

Now you can include this header in different files without getting the mentioned error.

Solution 2

You can create a separate .cpp file and put the definition there. This would look like:

myfile.h

#ifndef UTILS
#define UTILS

//just declarations here
void toUpper(string &str);    //note no inline keyword needed here

void toLower(string &str);    //note no inline keyword needed here

#endif // UTILS

myfile.cpp

#include "myheader.h"
void toUpper(string &str) {
    for(unsigned int i=0; i<str.length(); i++) {
            str.at(i) = toupper(str.at(i));
    }
}

void toLower(string &str) {
    for(unsigned int i=0; i<str.length(); i++) {
            str.at(i) = tolower(str.at(i));
    }
}

C++ include guards and multiple definition errors

There are multiple definition errors because stack.cpp does:

stack<int> s;

and main.cpp also defines a stack:

stack<int> s;

You have two different global objects defined with the same name which causes undefined behaviour (luckily your linker diagnoses it).

Instead, what you probably intended to do was to have a single stack that is referred to by several different units. To accomplish that you can only have the line that defines a stack appear once. (Remember that #include is just a straight text replacement; your code behaves the same as if you copy-pasted the contents of stack.h into the body of each .cpp file).

The other units need to have a line which says "There is a stack<int> called s defined somewhere (but not here)" and the code for that is:

extern stack<int> s;

So you should put that line in your header file, and put stack<int> s; in exactly one .cpp file - doesn't matter which.

---

In the case of the functions, you do not define any functions in the header, only declare. If you defined a function in the header (e.g. void print() { }) then you would have the same multiple definition error causing undefined behaviour.

Multple c++ files causes multiple definition error?

You have two options to solve this multiple definition problem: Mark the method inline, or put the definition in a .cpp file.

1) Mark the method inline:

// Foo.h

inline bool foo(int i) { return i = 42; }

2) Put the definition in a .cpp file:

// Foo.h

inline bool foo(int i); // declaration

// Foo.cpp
bool foo(int i) { return i = 42; } // definition

Whether the method is actually inlined by the compiler in the first case is irrelevant here: inline allows you to define a non-member function in a header file without breaking the one definition rule.

Why am I getting a 'multiple definition' error? how do i fix it?

The header test.hpp is included in two compilation units. The first one is the compilation unit main.cpp and the second one is the compilation unit test.cpp.

Functions by default have external linkage. This means that functions with the same name and signature denote the same function in different compilation units. They shall be defined once. However in your program the definition of the function test2 is found in two compilation units and the linker does not know what definition of the function to use.

You could declare the function as an inline function. For example

inline void test2() { std::cerr << "test2" << std::endl; }

In this case it may be defined in each compilation unit.

Or you can place in the header only the function declaration as you made with the function test and define it for example in test.cpp.

Another way is to declare the function as having internal linkage. To do this you can define the function in the header either with the keyword static

static void test2() { std::cerr << "test2" << std::endl; }

or place it in unnamed name space

namespace
{
    void test2() { std::cerr << "test2" << std::endl; }
}

In this case each compilation unit will have its own function test2.

---

Related Topics