Kompilierfehler vs Linkerfehler

1. Wichtig: compile error nicht mit link error verwechseln

Wenn man gerade erst zu programmieren beginnt, wirkt der Button „Build/Run“ in der IDE wie ein „magischer Knopf, um das Programm zu machen“. Und das ist normal: das Gehirn spart Energie. Aber diese Ersparnis hat ihren Preis: man sieht roten Text und beginnt, alles Mögliche zu reparieren — so als wäre Ihr Auto kaputt und Sie würden anfänglich die Scheibenwischer wechseln, weil „sie näher sind“.

In C++ sind Kompilierfehler und Linkerfehler zwei verschiedene „Pannen“ in zwei verschiedenen Phasen. Wenn man sie verwechselt, wird man fast garantiert am falschen Ort und am falschen Objekt herumdoktern. Die gute Nachricht: man kann sie sehr schnell unterscheiden — an charakteristischen Wörtern und danach, worauf genau die Meldung sich bezieht.

Prozesskarte: Compiler und Linker

Wenn man es ganz menschlich erklärt: der Compiler ist wie ein strenger Lehrer der Grammatik — er prüft, dass in jeder Datei die Sätze grammatisch korrekt gebaut sind, Wörter existieren und Formen übereinstimmen. Der Linker hingegen ist wie der Organisator einer Hochzeit: er nimmt die „Teile der Zeremonie“ aus verschiedenen Dateien und versucht, ein einheitliches Ereignis zu bauen, bei dem „der Bräutigam wirklich der Braut begegnet“, also bei dem jeder Funktionsaufruf seine Implementierung findet.

Wichtig: der Compiler arbeitet pro einzelne .cpp (pro Translation Unit). Der Linker arbeitet auf Basis der Kompilationsergebnisse aller .cpp und versucht, sie zu einer ausführbaren Datei zu verbinden. Deshalb sind manche Probleme „sofort sichtbar“ (während der Kompilierung), andere tauchen erst „am Ende“ (während der Linker-Phase) auf.

Unten steht eine kurze Tabelle, die unser Anker während der gesamten Vorlesung sein wird.

2. Kompilierfehler: „ich verstehe diese Datei nicht“

Ein Kompilierfehler ist die Situation „eine konkrete .cpp konnte nicht in ein Objektfile übersetzt werden“. Normalerweise (fast immer) enthält die Compiler-Meldung Koordinaten: Datei → Zeile → Spalte und zeigt an, wo der Compiler „gestolpert“ ist. Das ist wie bei einer Diktatkontrolle: die Stelle wird markiert, an der ein Wort falsch geschrieben ist.

Damit die Beispiele nicht abstrakt bleiben, arbeiten wir weiter mit unserer Konsolenanwendung TaskBox — einem einfachen Aufgabenmanager. Wir machen bewusst kleine Funktionen und verteilen sie auf mehrere Dateien, um verschiedene Fehlertypen anschaulich zu demonstrieren.

Syntaxfehler: „kann das nicht lesen“

Ein Syntaxfehler ist klassisch. Das ist, wenn ein ; fehlt, eine schließende } fehlt oder man versehentlich etwas geschrieben hat, das „nicht der C++-Grammatik entspricht“.

#include <iostream>

int main() {
    std::cout << "TaskBox started\n"   // <- ';' vergessen
    return 0;
}

Hier wird der Compiler normalerweise so etwas wie expected ‘;’ oder expected ... ausgeben. Wichtig zu verstehen: solange die Syntax nicht repariert ist, macht es keinen Sinn weiterzumachen — der Compiler kann die Datei nicht korrekt parsen, und ein Teil der folgenden Meldungen kann einfach ein Echo des ersten Fehlers sein.

Name nicht gefunden: „ich weiß nicht, was das ist“

Die zweithäufigste Kategorie: Sie benutzen eine Funktion/Variable/Typ, über die der Compiler an dieser Stelle nichts weiß. Und ja, das passiert besonders oft in mehrdateiigen Projekten, wenn Sie vergessen haben, den passenden Header zu includen.

#include <iostream>

int main() {
    std::cout << addTask("buy milk") << '\n';
    return 0;
}

Wenn addTask an keiner sichtbaren Stelle deklariert ist (z. B. weil Sie #include "task.hpp" vergessen haben), wird der Compiler was not declared in this scope oder identifier not found melden. Das ist ein Kompilierfehler, weil der Compiler nicht einmal beschreiben kann, was addTask ist.

Header nicht gefunden: „man hat mir die Datei nicht gegeben“

Manchmal liegt das Problem gar nicht an C++ als Sprache, sondern daran, dass der Compiler die Datei nicht finden kann.

#include "task.hpp"
#include "missing.hpp" // Datei fehlt

int main() {}

Die Meldung wird so ähnlich sein wie No such file or directory. Das ist ebenfalls ein compile error, weil der Compiler die Translation Unit nicht erstellen kann: ihm fehlt der Text, den Sie zu inkludieren verlangen.

4. Linkerfehler: „ich habe Teile gebaut, aber kann sie nicht verbinden“

Ein Linkerfehler ist sehr charakteristisch: die Kompilierung schien erfolgreich, aber im letzten Build-Schritt wird das Programm nicht erzeugt. Für Neulinge ist das besonders verwirrend, weil „der Compiler hat doch schon alles geprüft“. Er hat nicht alles geprüft — er hat nur das geprüft, was er in jeder einzelnen .cpp sehen konnte.

Wenn der Compiler die Grammatik prüft, dann prüft der Linker, ob jede „Erwähnung einer Figur“ im Skript wirklich einen Schauspieler auf der Bühne hat.

Link error: undefined reference / unresolved external

Das ist der häufigste Linkerfehler: irgendwo haben Sie eine Funktion deklariert (oder den Header mit der Deklaration included), aber die Definition (Implementierung) ist nicht Teil des Builds.

Wir bauen jetzt die „richtige“ Struktur unseres TaskBox auf.

task.hpp (Deklaration):

#pragma once
#include <string>

int addTask(const std::string& title);

task.cpp (Implementierung):

#include "task.hpp"

int addTask(const std::string& title) {
    (void)title;
    return 1;
}

main.cpp:

#include <iostream>
#include "task.hpp"

int main() {
    std::cout << addTask("buy milk") << '\n'; // 1
}

Achten Sie nun auf eine typische Situation: task.cpp existiert im Projektordner, ist aber nicht am Build beteiligt (z. B. weil Sie die Datei nicht dem Projekt/Target hinzugefügt haben). Dann wird main.cpp erfolgreich kompilieren: es sah die Deklaration addTask(...) aus dem Header und „glaubte“, dass irgendwo eine Implementierung existiert.

Der Linker wird aber melden: „Definition nicht gefunden“ (undefined reference, unresolved external symbol) — das ist der Moment, in dem er versucht hat, den Aufruf mit der Implementierung zu verknüpfen, es aber nicht geschafft hat.

Link error: multiple definition

Die zweite Klassiker: Sie haben versehentlich dafür gesorgt, dass die gleiche Definition zweimal im Build landet. Sehr oft passiert das, wenn Sie eine globale Variable im Header definieren und den Header in zwei .cpp includen.

Schlechtes Beispiel:

// config.hpp
#pragma once

int g_nextId = 1; // <- DEFINITION im Header (Risiko!)

task.cpp:

#include "config.hpp"

int getNextIdForTask() {
    return g_nextId++;
}

main.cpp:

#include "config.hpp"
#include <iostream>

int main() {
    std::cout << g_nextId << '\n'; // 1
}

Beide .cpp-Dateien included config.hpp, und jede bekam ihre eigene Definition von g_nextId. Beim Linken wird das zu multiple definition. Das hängt direkt damit zusammen, dass eine Entität idealerweise genau eine Definition haben sollte (Hallo ODR).

5. Wie die Kompilierung „glaubt“ und der Linker „prüft“

Hier ist es wichtig, innezuhalten und die Kernidee ruhig zu formulieren, damit später keine Magie im Spiel zu sein scheint. Wenn der Compiler einen Aufruf wie addTask("buy milk") sieht, möchte er zwei Dinge wissen: ob eine solche Funktion in Form existiert und ob die Argumente korrekt übergeben werden können.

Dafür reicht ihm eine Deklaration:

int addTask(const std::string& title);

Das ist wie ein Schild „In diesem Haus arbeitet ein Notar“: Sie können schon kommen, die Tür öffnen und sagen „ich brauche den Service“, auch wenn der Notar noch nicht sichtbar ist. Der Linker ist dagegen die Bezahl- und Unterschriftsphase: der Notar muss tatsächlich vorhanden sein, im Büro sitzen und das Siegel setzen können.

Deshalb führt das Szenario „deklariert, aber nicht definiert“ zu einem link error, nicht zu einem compile error. Der Compiler muss nicht erraten, dass die Implementierung fehlt — er geht davon aus, dass Sie nicht lügen (Spoiler: wir lügen ständig, aber meist aus Versehen).

Praktischer Detektor: 5 Signale, um den Fehlertyp zu erkennen

Jetzt kommt ein sehr praxisorientierter Abschnitt. Das ist der Moment, an dem Sie in Zukunft ein rotes Log sehen und in 10 Sekunden feststellen: „Aha, das ist Linken. Also suche ich die Implementierung, die Beteiligung der Datei am Build oder Duplikate“.

Ich beschreibe die Signale in zusammenhängendem Text, nicht als bloße Liste, weil es hilfreich ist, „wie man die Meldung liest“ mit „wo man repariert“ zu verknüpfen.

Signal eins — die Meldung enthält einen klaren Ort im Quelltext: main.cpp:12:5: error: .... Das ist fast immer Kompilierung. Der Linker nennt auch manchmal Dateien, aber das sind normalerweise Objektdateien/Bibliotheken, keine genaue Zeile Ihrer main.cpp.

Signal zwei — Wörter wie „expected“ oder „kann nicht parsen“ und jegliche Syntaxbeschwerden. Der Linker sieht keine Syntax: er arbeitet mit Kompilatergebnissen. Also ist expected ';' ein hundertprozentiger compile error.

Signal drei — Phrasen wie „Datei nicht gefunden“ (No such file or directory) in Verbindung mit #include. Das ist ein compile error: der Compiler kann die Translation Unit nicht bauen, weil ihm der Text fehlt.

Signal vier — Wörter wie undefined reference, unresolved external, LNK2019 (in MSVC) oder ld: .... Das ist Linken: es geht um Symbole, die irgendwo definiert sein sollten, aber nicht gefunden wurden.

Signal fünf — multiple definition (oder MSVC-Äquivalente). Das ist Linken: Definitionen sind bereits im Build angekommen, und der Linker stellt fest, dass zwei identische Personen mit demselben Ausweis erschienen sind.

6. Praxis mit TaskBox: ein Problem — zwei Phasen

Jetzt machen wir eine wichtige Übung für das Gehirn: wir schauen, wie ein inhaltlich ähnliches Problem als compile error und als link error erscheint. Das hilft, „nicht sehen“ und „nicht finden“ auseinanderzuhalten.

Compiler sieht die Deklaration nicht

main.cpp:

#include <iostream>

int main() {
    std::cout << addTask("buy milk") << '\n';
}

Hier fehlt das #include von "task.hpp", deshalb weiß der Compiler überhaupt nicht, was addTask ist. Das ist ein compile error.

Compiler sieht die Deklaration, Linker findet die Definition nicht

main.cpp:

#include <iostream>
#include "task.hpp"

int main() {
    std::cout << addTask("buy milk") << '\n';
}

task.hpp ist vorhanden, die Deklaration ist da, die Kompilierung wird durchlaufen. Wenn aber task.cpp nicht am Build teilnimmt oder in ihm keine Definition von addTask existiert, stürzt der Build beim Linken mit undefined reference ab.

Die inhaltliche Schlussfolgerung ist einfach: der Fehler ist nicht „mystisch verschoben“. Er tritt einfach dort zutage, wo er überprüfbar wird.

Sehr häufiger Grund für Linkerfehler: „Signaturen sind auseinandergegangen“

Dieser Punkt ist eine typische Falle: Sie denken, die Definition existiert, aber der Linker sagt trotzdem undefined reference.

In der Praxis ist die Ursache oft profaner: Sie haben eine Funktion deklariert, aber eine „ähnliche, aber andere“ Funktion definiert. Der Linker sucht nach einer genauen Übereinstimmung von Namen und Parametern.

task.hpp:

#pragma once
#include <string>

int addTask(const std::string& title);

task.cpp (Fehler):

#include "task.hpp"

int addTask(std::string title) { // <- kein const&, anderer Parameter
    (void)title;
    return 1;
}

Für den Compiler kann das durchgehen (besonders wenn Sie versehentlich task.hpp nicht in task.cpp includen — was selbst eine schlechte Praxis ist). Der Linker sucht jedoch nach addTask(const std::string&) und findet addTask(std::string). Für ihn sind das zwei verschiedene Funktionen.

Eine praktische Gewohnheit, die solche Fälle stark reduziert: die .cpp includet immer sein eigenes .hpp. Dann fängt der Compiler Signaturabweichungen noch vor dem Linken ab.

7. Mini-Algorithmus zum Lesen des Build-Logs

Ich möchte Ihnen keine Philosophie, sondern eine Arbeitsmechanik mitgeben. Stellen Sie sich vor, Sie haben auf Build geklickt und 200 Zeilen Log erhalten. Sie müssen das nicht wie einen Roman lesen (auch wenn die Dramaturgie manchmal oscarreif ist). Man sollte jedes Mal gleich vorgehen.

Zuerst bestimmen Sie, ob es Kompilierung oder Linken ist, anhand von Schlüsselwörtern und Stil der Meldung. Dann finden Sie die erste substanzielle Fehlermeldung, denn der Rest erfolgt oft als Kaskade. Danach entscheiden Sie, wo Sie suchen: im Code einer konkreten .cpp, in den Header-Includes oder bei den Dateien, die am Build teilnehmen und wo die Definitionen liegen.

Unten eine einfache Ablaufgrafik, die Sie im Kopf behalten können:

flowchart TD
    A["Build ist fehlgeschlagen"] --> B{"Enthält die Meldung undefined reference / multiple definition / LNK... ?"}
    B -- Ja --> L["Das ist ein link error. Suche: wo ist die Definition? Gibt es Duplikate? Nehmen alle .cpp am Build teil?"]
    B -- Nein --> C{"Enthält die Meldung file:line:col und 'error:' ?"}
    C -- Ja --> D["Das ist ein compile error. Suche: Syntax/Typen/Namen/#include/Sichtbarkeit von Deklarationen"]
    C -- Nein --> E["Schau weiter oben im Log: manchmal versteckt die IDE die eigentliche Phase"]

8. Typische Fehler: warum sie sich wiederholen

Fehler Nr.1: an der falschen Phase herumdoktern.
Das häufigste Szenario: Sie sehen undefined reference, fangen aber an, if/else in main zu ändern, weil „vielleicht ist die Logik falsch“. Dem Linker ist die Logik egal: er kann die Definition nicht finden. Die Lösung ist die Gewohnheit, zuerst den Fehlertyp zu klassifizieren und dann zu handeln.

Fehler Nr.2: „die Datei existiert — also ist sie am Build beteiligt“.
Psychologisch verständlich: wenn task.cpp neben den anderen Dateien liegt, glaubt man, sie ist automatisch berücksichtigt. Build ist jedoch eine Liste von Dateien, die tatsächlich kompiliert und gelinkt werden. Wenn task.cpp nicht dem Projekt/Target hinzugefügt wurde, ist sie faktisch nicht vorhanden. Das führt zu undefined reference und dem Gefühl, die Realität würde einen gaslighten.

Fehler Nr.3: Variablen in Headern definieren.
Der Anfänger denkt: „Ich will, dass alle g_nextId sehen, also packe ich sie ins .hpp“. Das führt zu multiple definition, weil der Header in mehreren Translation Units inkludiert wird und jede ihre eigene Definition erhält. Das ist wie denselben „Pass“ in zwei Ämtern auszudrucken und zu versuchen, die Kontrolle zu passieren. Solche Konflikte verletzen die Regel der einen Definition (ODR).

Fehler Nr.4: Deklaration und Definition sind auseinandergeraten, und die .cpp includet nicht das eigene .hpp.
Das ist eine stille Mine. Sie haben die Signatur im .hpp geändert, vergessen, sie in der .cpp anzupassen, und wundern sich über undefined reference. Wenn die .cpp ihr eigenes .hpp includet hätte, hätte der Compiler das Problem sofort gefunden. Daher ist „include dein Header“ keine Stilfrage, sondern ein praktischer Schutz gegen Build-Bugs.

Fehler Nr.5: versuchen, das Linken mit mehr #include zu „lösen“.
Manchmal denkt jemand bei undefined reference: „vielleicht habe ich den falschen Header included“. Aber #include wirkt auf die Kompilierung, nicht auf die Existenz einer Definition im Build. Ein Header liefert eine Deklaration; der Linker verlangt eine Implementierung. Man kann den Header zehnmal includen — die Definition erscheint dadurch nicht (und oft werden die Probleme sogar größer).