MSVC cl.exe trying to use C++ header paradigm (definition vs declaration)

Question

I'm trying to implement a library that uses the rather popular C++ header paradigm (separating definition and declaration in a .h / .hpp and a .cpp file). I'm using the MSVC cl.exe compiler to target the Windows operating system.

I explicitly use the #include directive targeting the header file abc.hpp where the definition is expressed. I expect the compiler to automatically look for the corresponding abc.cpp file and redirect calls to abc.hpp::abc() towards abc.cpp::abc().

(I know I could directly #include "abc.cpp" in the example but remember I'm trying to solve a bigger problem that is include an entire library from it's header files.)

(I also tried to use the /I compiler option but after both testing and reading the documentation it's not of much use.) https://learn.microsoft.com/en-us/cpp/build/reference/i-additional-include-directories

I described the test I run bellow and the compiler error I get:

######## main.cpp ######## 
#include <stdio.h> // printf_s
#include "abc.hpp"
int main(int argc, char *argv[]) {
    abc();
    return(0);
}

######## abc.hpp ######## 
void abc();

######## abc.cpp ######## 
#include "abc.hpp"

void abc() {
    printf("ABC!\n");
}

######## command line ########
> cl main.cpp
Microsoft (R) C/C++ Optimizing Compiler Version 19.X for x64
Copyright (C) Microsoft Corporation.  All rights reserved.

main.cpp
Microsoft (R) Incremental Linker Version 14.X
Copyright (C) Microsoft Corporation.  All rights reserved.

/out:main.exe
main.obj
main.obj : error LNK2019: unresolved external symbol "void __cdecl abc(void)" (?abc@@YAXXZ) referenced in function main
main.exe : fatal error LNK1120: 1 unresolved externals

Is my expectation about the compiler automatically remapping abc.hpp::abc() towards abc.cpp::abc() off the mark? Am I forced to have the .cpp code be compiler as a separate .lib to be able to /link /LIBPATH: it to the compiler?

I'd be pleased to hear your insight about this matter.

Answer 1

You have a ... let's say more reasonable opinion on how C++ compile and linking should work. But the truth is that the C++ include compile and link model is ancient and seems alien to any modern modular builds in modern languages. However it is so encarved into C++, that is the way it goes with C++ and that was the way since the beginning. Things are about to change (slowly) with modules being introduced into the standard in C++20 (really a great and arduous achievement considering C++'s legacy and backwards-compatibility).

---

So the classical way is this: You include headers that contain the declaration you need. #include is a preprocessor directive and it is more-or-less just a dumb copy-paste of the contents of the header. This lets you compile each "compilation unit" individually. Then you link all of the compilation units into your final binary (bee it a library or an executable).

Let's say you have a foo.cpp with the definition of the function foo.

foo.cpp

int foo(int a)
{
     return a * a;
}

If you need to call foo from another compilation unit you first need to make the declaration of foo visible in that compilation unit. You can do that easily just by writing the declaration:

bar.cpp

int foo(int);

void bar()
{
    int r = foo(24);
}

Before using foo the compiler need to know what foo is. Aka it needs to know it is a function taking an int parameter and returning an int. That is what I did in the example above when I wrote int foo(int). Hower you shouldn't write each declaration. You can write the declaration of foo once in foo.hpp and then include that header:

foo.hpp

#pragma once // or standard-compliant guard

int foo(int);

bar.cpp

#include "foo.hpp"

void bar()
{
    int r = foo(24);
}

The preprocessor wil textually replace #include "foo.hpp" with the contents of the file before feeding it to the compiler.

Now you can compile bar.cpp into an object file. The compiler just writes a call to a symbol foo known to name a function taking an int parameter and returning an int. However the definition of foo is not visible. Aka. the compiler doesn't have the "source code" of foo.

So the next step is to link together all the compilation units.

You can do the compilation and linking in two separate stages (I use g++ in the examples because I am more familiar with the parameters, but the principles are the same for cl.exe):

# compile each compilation unit
g++ bar.cpp -o bar.o
g++ foo.cpp -o foo.o

# link all into the final executable
g++ bar.o foo.o -o my_executable

Or you can do it all in one go:

g++ foo.cpp bar.cpp -o my_executable

Because cl.exe (and clang and gcc) is neither the compiler nor the linker. It's a front end that calls the preprocessor, compiler and/or linker on your behalf.

---

You need to know these details to understand what is happening under the hood so you can solve issues when they appear, but you shouldn't manually invoke the compiler. Use a build system that will take care of all this for you. Let VS do this for you or use make / cmake.