One Definition Rule

The One Definition Rule (ODR) is an important rule of the C++ programming language that prescribes that classes/structs and non-inline functions cannot have more than one definition in the entire program and templates and types cannot have more than one definition by translation unit. It is defined in the ISO C++ Standard (ISO/IEC 14882) 2003, at section 3.2. Some other programming languages have similar but differently defined rules towards the same objective.

Summary

In short, the ODR states that:

1. In any translation unit, a template, type, function, or object can have no more than one definition. Some of these can have any number of declarations. A definition provides an instance.
2. In the entire program, an object or non-inline function cannot have more than one definition; if an object or function is used, it must have exactly one definition. You can declare an object or function that is never used, in which case you don't have to provide a definition. In no event can there be more than one definition.
3. Some things, like types, templates, and extern inline functions, can be defined in more than one translation unit. For a given entity, each definition must have the same sequence of tokens. Non-extern objects and functions in different translation units are different entities, even if their names and types are the same.

Some violations of the ODR must be diagnosed by the compiler. Other violations, particularly those that span translation units, are not required to be diagnosed.^[1]

Examples

In general, a translation unit shall contain no more than one definition of any class type. In this example, two definitions of the class type MyClass occur in the same translation unit. This typically occurs if a header file is included twice by the same source file without appropriate header guards.

class MyClass {}; // first definition of MyClass
class MyClass {}; // error, second definition of MyClass

In the following, forming a pointer to MyStruct or defining a function taking a reference to MyStruct are examples of legal constructs, because they do not require the type of MyStruct to be complete. Therefore, a definition is not required.^[2]

Defining an object of type MyStruct, a function taking an argument of type MyStruct, or using MyStruct in a sizeof expression are examples of contexts where S must be complete, and therefore require a definition.^[2]

struct MyStruct;     // declaration of MyStruct
MyStruct* p;         // ok, no definition required
void f(MyStruct&);   // ok, no definition required
void f(MyStruct*);   // ok, no definition required 
MyStruct f();        // ok, no definition required - this is a function declaration only!

MyStruct s;          // error, definition required
sizeof(MyStruct);    // error, definition required

More than one definition

In certain cases, there can be more than one definition of a type or a template. A program consisting of multiple header files and source files will typically have more than one definition of a type, but not more than one definition per translation unit.

If a program contains more than one definition of a type, then each definition must be equivalent.^[3]

Definitions of static const data members

In pre-standard C++, all static data members required a definition outside of their class. However, during the C++ standardization process it was decided to lift this requirement for static const integral members. The intent was to allow uses such as:

struct MyClass {
    static const int N = 10;
};
char data[MyClass::N]; // N "used" without out-of-class definition

without a namespace scope definition for N.

Nevertheless, the wording of the 1998 C++ standard still required a definition if the member was used in the program.^[4] This included the member appearing anywhere except as the operand to sizeof or typeid, effectively making the above ill-formed.^[5]

This was identified as a defect, and the wording was adjusted to allow such a member to appear anywhere a constant expression is required, without requiring an out-of-class definition. This includes array bounds, case expressions, static member initializers, and nontype template arguments.^[6]

struct MyClass1 {
    static const int N = 10;
    static const int U = N; // Legal per C++03
};

char data[Class1::N]; // Legal per C++03

template <int> 
struct MyClass2;

template <> 
struct MyClass2<Class1::N> {}; // Legal per C++03

However, using a static const integral member anywhere except where an integral constant-expression is required, requires a definition:^[7]

struct MyClass {
    static const int N = 10;
};

int main() {
    int i = MyClass::N; // Ill-formed in C++03. Definition of MyClass::N required.
}

This requirement was relaxed in a later standard, C++11.^[7]

Example showing unexpected side effects

We need 4 files: "Base.cppm", "Dummy1.cppm", "Dummy2.cppm", "Main.cpp".

Base.cppm:

module;

export org.wikipedia.examples.Base;

export import org.wikipedia.examples.Dummy1;
export import org.wikipedia.examples.Dummy2;

export namespace org::wikipedia::examples {

// abstract base class
class Base {
public:
	virtual void myFunc() = 0;
	virtual ~Base() = default;
};

}

Dummy1.cppm

module;

export module org.wikipedia.examples.Dummy2;

import std;

import org.wikipedia.examples.Base;

export namespace org::wikipedia::examples {

class Dummy : public Base {
public:
	void myFunc() override {
		std::println("odr ONE dummy: Hello");
	}
};

Base* odr1Create() {
	return new Dummy();
}

}

Dummy2.cppm:

module;

export module org.wikipedia.examples.Dummy2;

import std;

import org.wikipedia.examples.Base;

export org::wikipedia::examples {

class Dummy : public Base {
public:
	void myFunc() override {
		std::println("odr TWO dummy: World");
	}
};

Base* odr2Create() {
	return new Dummy();
}

}

Main.cpp:

import org.wikipedia.examples.Base;

using namespace org::wikipedia::examples;

int main(int argc, char* argv[]) {
	Base* o1 = odr1Create();
	Base* o2 = odr2Create();
	o1->myFunc();
	o2->myFunc();

    delete o1;
    delete o2;
}

When executed the expected output is:

odr ONE dummy: Hello
odr TWO dummy: World

But the likely output is:

odr ONE dummy: Hello
odr ONE dummy: Hello

The problem is, that the C++ linker has to figure out how to build the virtual method table for the (two different) Dummy classes, and that only works if the class names are different.

See also

• Include directive
• Include guard