A GitLab upgrade is scheduled for Monday, June 30, 2025. The service will be unavailable for a few minutes in the morning. We'll keep you posted on the progress of the upgrade on the Mattermost channel: https://mattermost.inria.fr/devel/channels/gitlab. We recommend that you do not work on the platform until an announcement indicates that maintenance is complete.
"This is especially true after very usual mistakes such as missing ')', '}' or ';'.\n",
"This is especially true after very usual mistakes such as missing ')', '}' or ';'.\n",
"\n",
"\n",
"So what I (Sébastien) do is almost always begin at the top of the errors and see if solving this one explain the following errors or not.\n",
"So what I (Sébastien) do is almost always begin at the top of the errors and see if solving this one explains the following errors or not.\n",
"\n",
"\n",
"I sometimes even redirect the output of the compilation into a file so that I can easily access the top. To my knowledge there's no clean way to do it more properly with the build tool directly; I would be delighted if someone proved me wrong on this one because the following sequence is not entirely satisfactory:\n"
"I sometimes even redirect the output of the compilation into a file so that I can easily access the top. To my knowledge there's no clean way to do it more properly with the build tool directly; I would be delighted if someone proved me wrong on this one because the following sequence is not entirely satisfactory:\n"
]
]
...
@@ -97,7 +97,7 @@
...
@@ -97,7 +97,7 @@
"id": "9",
"id": "9",
"metadata": {},
"metadata": {},
"source": [
"source": [
"It's especially useful when you modified an header file that is heavily used directly or indirectly in your program or your library - all files that depend on it will in this case be recompiled.\n",
"It's especially useful when you modified a header file that is heavily used directly or indirectly in your program or your library - all files that depend on it will in this case be recompiled.\n",
"\n",
"\n",
"But why talk about it here, in a notebook about compilation errors?\n",
"But why talk about it here, in a notebook about compilation errors?\n",
"\n",
"\n",
...
@@ -165,9 +165,9 @@
...
@@ -165,9 +165,9 @@
"source": [
"source": [
"## Read carefully the message\n",
"## Read carefully the message\n",
"\n",
"\n",
"As said in the introduction, compilers are now much more helpful now that what they used to be (see for instance in the example above: it even tries to tell me where exactly in the line the error occurs).\n",
"As said in the introduction, compilers are now much more helpful now than what they used to be (see for instance in the example above: it even tries to tell me where exactly in the line the error occurs).\n",
"\n",
"\n",
"Most of the error messages are now clear enough; when they're not you may find information on the Web as the question has surely be posted somewhere (StackOverflow or similar sites).\n",
"Most of the error messages are now clear enough; when they're not you may find information on the Web as the question has surely been posted somewhere (StackOverflow or similar sites).\n",
"\n",
"\n",
"c++filt (that we mentioned [here](../6-InRealEnvironment/3-Compilers.ipynb#c++filt)) may be of help if the mangling makes the name of your function / class / whatever too difficult to read."
"c++filt (that we mentioned [here](../6-InRealEnvironment/3-Compilers.ipynb#c++filt)) may be of help if the mangling makes the name of your function / class / whatever too difficult to read."
]
]
...
@@ -250,9 +250,9 @@
...
@@ -250,9 +250,9 @@
"\n",
"\n",
"In both the cases we covered in this notebook, we rejoiced that the compiler was rather helpful if you forgot to use properly one of the expected keyword... but for the `template` keyword (described [here](../4-Templates/3-Syntax.ipynb#Mandatory-template-keyword)) it is fairly recent (around 2022!) - so if you're using a not so recent compiler and get an error message about an unknown method whereas \n",
"In both the cases we covered in this notebook, we rejoiced that the compiler was rather helpful if you forgot to use properly one of the expected keyword... but for the `template` keyword (described [here](../4-Templates/3-Syntax.ipynb#Mandatory-template-keyword)) it is fairly recent (around 2022!) - so if you're using a not so recent compiler and get an error message about an unknown method whereas \n",
"\n",
"\n",
"- This method do exist\n",
"- The method does exist\n",
"- This method is properly declared at to calling site (it's not a missing include)\n",
"- The method is properly declared at to calling site (it's not a missing include)\n",
"- This method is a template method within a template class\n",
"- The method is a template method within a template class\n",
"\n",
"\n",
"then you should have a look at the explanation in the notebook about the `template` keyword.\n",
"then you should have a look at the explanation in the notebook about the `template` keyword.\n",
"\n"
"\n"
...
...
%% Cell type:markdown id:0 tags:
%% Cell type:markdown id:0 tags:
# [Getting started in C++](./) - [Appendix](./0-main.ipynb) - [Dealing with compilation errors](./CompilationErrors.ipynb)
# [Getting started in C++](./) - [Appendix](./0-main.ipynb) - [Dealing with compilation errors](./CompilationErrors.ipynb)
%% Cell type:markdown id:1 tags:
%% Cell type:markdown id:1 tags:
## Introduction
## Introduction
It is easy to be annoyed by the compilation process in C or C++: you write code, want to check how it goes, and that pesky compiler keeps preventing you to just do that by complaining about insignificant stuff as inadequate syntax, sometimes in a really confusing way (and it used to be much worse 20 years ago - compilers aim to be much more user-friendly now).
It is easy to be annoyed by the compilation process in C or C++: you write code, want to check how it goes, and that pesky compiler keeps preventing you to just do that by complaining about insignificant stuff as inadequate syntax, sometimes in a really confusing way (and it used to be much worse 20 years ago - compilers aim to be much more user-friendly now).
It is better though to adopt the opposite view: the compiler is not an opponent, but an _ally_ - and in the end you really benefit from identifying issues at compile time rather than at runtime.
It is better though to adopt the opposite view: the compiler is not an opponent, but an _ally_ - and in the end you really benefit from identifying issues at compile time rather than at runtime.
The purpose of this notebook is to provide hints how to use to your own advantage the compiler and your build tool.
The purpose of this notebook is to provide hints how to use to your own advantage the compiler and your build tool.
%% Cell type:markdown id:2 tags:
%% Cell type:markdown id:2 tags:
## Take error messages from top to bottom
## Take error messages from top to bottom
%% Cell type:markdown id:3 tags:
%% Cell type:markdown id:3 tags:
When compiling even a single file (more on that below), the compiler may lay out plenty of compilation errors, even if most of the time they stop at some points (typically after around 20 errors have been printed).
When compiling even a single file (more on that below), the compiler may lay out plenty of compilation errors, even if most of the time they stop at some points (typically after around 20 errors have been printed).
That doesn't mean there are really 20 (or more) locations in your source file that needs to be fixed: sometimes the compiler can be very confused and isn't able to parse correctly the file.
That doesn't mean there are really 20 (or more) locations in your source file that needs to be fixed: sometimes the compiler can be very confused and isn't able to parse correctly the file.
This is especially true after very usual mistakes such as missing ')', '}' or ';'.
This is especially true after very usual mistakes such as missing ')', '}' or ';'.
So what I (Sébastien) do is almost always begin at the top of the errors and see if solving this one explain the following errors or not.
So what I (Sébastien) do is almost always begin at the top of the errors and see if solving this one explains the following errors or not.
I sometimes even redirect the output of the compilation into a file so that I can easily access the top. To my knowledge there's no clean way to do it more properly with the build tool directly; I would be delighted if someone proved me wrong on this one because the following sequence is not entirely satisfactory:
I sometimes even redirect the output of the compilation into a file so that I can easily access the top. To my knowledge there's no clean way to do it more properly with the build tool directly; I would be delighted if someone proved me wrong on this one because the following sequence is not entirely satisfactory:
%% Cell type:markdown id:4 tags:
%% Cell type:markdown id:4 tags:
```shell
```shell
ninja -j 1 2>&1 | tee compilation_output.txt
ninja -j 1 2>&1 | tee compilation_output.txt
head-n 50 compilation_output.txt
head-n 50 compilation_output.txt
```
```
%% Cell type:markdown id:5 tags:
%% Cell type:markdown id:5 tags:
(we'll come to the `-j 1` just below)
(we'll come to the `-j 1` just below)
%% Cell type:markdown id:6 tags:
%% Cell type:markdown id:6 tags:
## Master when (not to) use parallel build
## Master when (not to) use parallel build
%% Cell type:markdown id:7 tags:
%% Cell type:markdown id:7 tags:
To leverage the multiple processors available in your computer, you should really take advantage of parallel build... (that we evoked briefly [here](http://localhost:8888/lab/tree/6-InRealEnvironment/1-SetUpEnvironment.ipynb#Build-system)) unless of course you have something better to do (courtesy [Xkcd](https://xkcd.com/303/))
To leverage the multiple processors available in your computer, you should really take advantage of parallel build... (that we evoked briefly [here](http://localhost:8888/lab/tree/6-InRealEnvironment/1-SetUpEnvironment.ipynb#Build-system)) unless of course you have something better to do (courtesy [Xkcd](https://xkcd.com/303/))
%% Cell type:markdown id:8 tags:
%% Cell type:markdown id:8 tags:
%% Cell type:markdown id:9 tags:
%% Cell type:markdown id:9 tags:
It's especially useful when you modified an header file that is heavily used directly or indirectly in your program or your library - all files that depend on it will in this case be recompiled.
It's especially useful when you modified a header file that is heavily used directly or indirectly in your program or your library - all files that depend on it will in this case be recompiled.
But why talk about it here, in a notebook about compilation errors?
But why talk about it here, in a notebook about compilation errors?
The reason is that for compilation errors, I would recommend doing exactly the opposite: once you know something is amiss, you should really strive to concentrate on one error and fix it.
The reason is that for compilation errors, I would recommend doing exactly the opposite: once you know something is amiss, you should really strive to concentrate on one error and fix it.
If you're using without much thoughts the output of a parallel build, you may end up providing a fix to a compilation error that is not correct, run a new compilation, and switch to an entirely other issue without realizing that your first fix doesn't work.
If you're using without much thoughts the output of a parallel build, you may end up providing a fix to a compilation error that is not correct, run a new compilation, and switch to an entirely other issue without realizing that your first fix doesn't work.
I (Sébastien) even go a step further: when I get an error message, I usually copy/paste the command line provided by my build tool (combo CMake / Ninja) until it compiles correctly. For instance if I get:
I (Sébastien) even go a step further: when I get an error message, I usually copy/paste the command line provided by my build tool (combo CMake / Ninja) until it compiles correctly. For instance if I get:
%% Cell type:markdown id:10 tags:
%% Cell type:markdown id:10 tags:
```shell
```shell
➜ ninja Sources/TestPetscMatrixOperations
➜ ninja Sources/TestPetscMatrixOperations
[1/2] Building CXX object Sources/CMakeFiles/TestPetscMatrixOperations.dir/Test/ThirdParty/PETSc/MatrixOperations/test.cpp.o
[1/2] Building CXX object Sources/CMakeFiles/TestPetscMatrixOperations.dir/Test/ThirdParty/PETSc/MatrixOperations/test.cpp.o
/Users/sgilles/Codes/MoReFEM/CoreLibrary/Sources/Test/ThirdParty/PETSc/MatrixOperations/test.cpp:96:20: error: no member named 'Fill'in'MoReFEM::GlobalMatrix'
/Users/sgilles/Codes/MoReFEM/CoreLibrary/Sources/Test/ThirdParty/PETSc/MatrixOperations/test.cpp:96:20: error: no member named 'Fill'in'MoReFEM::GlobalMatrix'
initial_matrix.Fill(1.);
initial_matrix.Fill(1.);
~~~~~~~~~~~~~~ ^
~~~~~~~~~~~~~~ ^
1 error generated.
1 error generated.
ninja: build stopped: subcommand failed.
ninja: build stopped: subcommand failed.
```
```
%% Cell type:markdown id:11 tags:
%% Cell type:markdown id:11 tags:
I copy/paste the command helpfully provided by CMake and work on it until the issue is fixed (in the case above it wouldn't take long of course!)
I copy/paste the command helpfully provided by CMake and work on it until the issue is fixed (in the case above it wouldn't take long of course!)
When doing refactoring, you might want to know exactly how many files are impacted and don't compile. Usually a build tool will stop as soon as there is a file that chokes (or in case of a parallel build until all the processors meet such a file).
When doing refactoring, you might want to know exactly how many files are impacted and don't compile. Usually a build tool will stop as soon as there is a file that chokes (or in case of a parallel build until all the processors meet such a file).
However, there are usually options to tell to compile all that can be compiled; it is for instance `ninja -k 0` for `ninja`.
However, there are usually options to tell to compile all that can be compiled; it is for instance `ninja -k 0` for `ninja`.
%% Cell type:markdown id:14 tags:
%% Cell type:markdown id:14 tags:
## Read carefully the message
## Read carefully the message
As said in the introduction, compilers are now much more helpful now that what they used to be (see for instance in the example above: it even tries to tell me where exactly in the line the error occurs).
As said in the introduction, compilers are now much more helpful now than what they used to be (see for instance in the example above: it even tries to tell me where exactly in the line the error occurs).
Most of the error messages are now clear enough; when they're not you may find information on the Web as the question has surely be posted somewhere (StackOverflow or similar sites).
Most of the error messages are now clear enough; when they're not you may find information on the Web as the question has surely been posted somewhere (StackOverflow or similar sites).
c++filt (that we mentioned [here](../6-InRealEnvironment/3-Compilers.ipynb#c++filt)) may be of help if the mangling makes the name of your function / class / whatever too difficult to read.
c++filt (that we mentioned [here](../6-InRealEnvironment/3-Compilers.ipynb#c++filt)) may be of help if the mangling makes the name of your function / class / whatever too difficult to read.
%% Cell type:markdown id:15 tags:
%% Cell type:markdown id:15 tags:
## Don't neglect warnings
## Don't neglect warnings
When the compilation fails, you may get a jungle of error and warning messages, with an emphasis on errors (that are typically in deep red, whereas warnings are in yellow or purple).
When the compilation fails, you may get a jungle of error and warning messages, with an emphasis on errors (that are typically in deep red, whereas warnings are in yellow or purple).
You should however at least read the warning - it might point the very reason for which something is amiss in your code.
You should however at least read the warning - it might point the very reason for which something is amiss in your code.
Personally I handle them almost exactly the same way as error - it's only when I know for sure that the warning bears no relationship to the following error message that I put it aside.
Personally I handle them almost exactly the same way as error - it's only when I know for sure that the warning bears no relationship to the following error message that I put it aside.
%% Cell type:markdown id:16 tags:
%% Cell type:markdown id:16 tags:
## Make sure you're correctly identifying which overload / constructor / etc... is involved
## Make sure you're correctly identifying which overload / constructor / etc... is involved
C++ gives you a lot of liberties with naming: same name might be used with a different signature (function overload or multiple constructors for a class for instance) or used in a different namespace.
C++ gives you a lot of liberties with naming: same name might be used with a different signature (function overload or multiple constructors for a class for instance) or used in a different namespace.
Make sure you connect the dots well!
Make sure you connect the dots well!
%% Cell type:markdown id:17 tags:
%% Cell type:markdown id:17 tags:
## Include-related potential issues
## Include-related potential issues
### Missing include
### Missing include
Sometimes a compilation error might just be due to a missing include!
Sometimes a compilation error might just be due to a missing include!
If the compiler complains about an unknown function, it might just be that the specific source file in which it happens doesn't provide properly the declaration.
If the compiler complains about an unknown function, it might just be that the specific source file in which it happens doesn't provide properly the declaration.
### Circular dependency
### Circular dependency
This is one of the worst compilation you might get, as the compiler won't be able to tell you clearly what happens.
This is one of the worst compilation you might get, as the compiler won't be able to tell you clearly what happens.
If the compiler complains that it doesn't know about a specific function (or class or method) whereas you're absolutely positive that it is already provided and that you didn't fall into the trap mentioned [just above](http://localhost:8888/lab/tree/7-Appendix/CompilationErrors.ipynb#Make-sure-you're-correctly-identifying-which-overload-/-constructor-/-etc...-is-involved), you might be in a case of circular dependency.
If the compiler complains that it doesn't know about a specific function (or class or method) whereas you're absolutely positive that it is already provided and that you didn't fall into the trap mentioned [just above](http://localhost:8888/lab/tree/7-Appendix/CompilationErrors.ipynb#Make-sure-you're-correctly-identifying-which-overload-/-constructor-/-etc...-is-involved), you might be in a case of circular dependency.
This happens when a file `A.hpp` is included in `B.hpp`, which itself is included in `A.hpp`. Said like that it seems trivial and easy to spot, but in a real code it is often definitely not - as it might be for instance that `B.hpp` includes other headers, which themselves include others, one of which at some point include `A.hpp`.
This happens when a file `A.hpp` is included in `B.hpp`, which itself is included in `A.hpp`. Said like that it seems trivial and easy to spot, but in a real code it is often definitely not - as it might be for instance that `B.hpp` includes other headers, which themselves include others, one of which at some point include `A.hpp`.
The way to avoid it is to carefully think your architecture: if there is a clear hierarchy between your components, you should be able to avoid it most of the time.
The way to avoid it is to carefully think your architecture: if there is a clear hierarchy between your components, you should be able to avoid it most of the time.
You should also strive to limit to the minimum the includes to provide in other header files; use [forward declaration](http://localhost:8888/lab/tree/6-InRealEnvironment/2-FileStructure.ipynb#Forward-declaration) when you can, and don't provide includes that are needed only for implementation if said implementation is in a compiled file (of course for `inline` functions `template` classes and functions you don't have the choice). Doing so will also help you limit compilation time anyway.
You should also strive to limit to the minimum the includes to provide in other header files; use [forward declaration](http://localhost:8888/lab/tree/6-InRealEnvironment/2-FileStructure.ipynb#Forward-declaration) when you can, and don't provide includes that are needed only for implementation if said implementation is in a compiled file (of course for `inline` functions `template` classes and functions you don't have the choice). Doing so will also help you limit compilation time anyway.
### Duplicate header guards
### Duplicate header guards
Another typical issue is if you provide the same [header guard](http://localhost:8888/lab/tree/6-InRealEnvironment/2-FileStructure.ipynb#Forward-declaration) in two different files.
Another typical issue is if you provide the same [header guard](http://localhost:8888/lab/tree/6-InRealEnvironment/2-FileStructure.ipynb#Forward-declaration) in two different files.
In this case, one of them will be simply ignored, and its content will probably be sorely missing somewhere along the line in the compilation process.
In this case, one of them will be simply ignored, and its content will probably be sorely missing somewhere along the line in the compilation process.
To avoid this, you should either use `#pragma once` instead, or automate one way or the other the header guard names in the file to ensure unicity.
To avoid this, you should either use `#pragma once` instead, or automate one way or the other the header guard names in the file to ensure unicity.
%% Cell type:markdown id:18 tags:
%% Cell type:markdown id:18 tags:
## Template keyword
## Template keyword
%% Cell type:markdown id:19 tags:
%% Cell type:markdown id:19 tags:
We dedicated a [notebook](../4-Templates/3-Syntax.ipynb) to the specific syntax that might be required to help the compiler understand what is the intention with some specific template tricks.
We dedicated a [notebook](../4-Templates/3-Syntax.ipynb) to the specific syntax that might be required to help the compiler understand what is the intention with some specific template tricks.
In both the cases we covered in this notebook, we rejoiced that the compiler was rather helpful if you forgot to use properly one of the expected keyword... but for the `template` keyword (described [here](../4-Templates/3-Syntax.ipynb#Mandatory-template-keyword)) it is fairly recent (around 2022!) - so if you're using a not so recent compiler and get an error message about an unknown method whereas
In both the cases we covered in this notebook, we rejoiced that the compiler was rather helpful if you forgot to use properly one of the expected keyword... but for the `template` keyword (described [here](../4-Templates/3-Syntax.ipynb#Mandatory-template-keyword)) it is fairly recent (around 2022!) - so if you're using a not so recent compiler and get an error message about an unknown method whereas
- This method do exist
- The method does exist
- This method is properly declared at to calling site (it's not a missing include)
- The method is properly declared at to calling site (it's not a missing include)
- This method is a template method within a template class
- The method is a template method within a template class
then you should have a look at the explanation in the notebook about the `template` keyword.
then you should have a look at the explanation in the notebook about the `template` keyword.
%% Cell type:markdown id:20 tags:
%% Cell type:markdown id:20 tags:
## Help yourself making the compiler error messages clearer!
## Help yourself making the compiler error messages clearer!
Recent versions of C++ have provided many great tools to help you specify at compile time that a condition must be met:
Recent versions of C++ have provided many great tools to help you specify at compile time that a condition must be met:
-`static_assert` (since C++ 11)
-`static_assert` (since C++ 11)
-`concept` (since C++ 20)
-`concept` (since C++ 20)
To which you may also add nifty stuff not directly in the language or STL but that may be added easily such as strong types (here is a [series of FluentCpp posts](https://www.fluentcpp.com/2016/12/05/named-constructors/) explaining the underlying idea; an implementation is provided [there](https://github.com/joboccara/NamedType) but it's easy to write your own implementation tailored for your needs when you read the series).
To which you may also add nifty stuff not directly in the language or STL but that may be added easily such as strong types (here is a [series of FluentCpp posts](https://www.fluentcpp.com/2016/12/05/named-constructors/) explaining the underlying idea; an implementation is provided [there](https://github.com/joboccara/NamedType) but it's easy to write your own implementation tailored for your needs when you read the series).
You should really consider using them, especially if you're writing a library, because it might really save a lot of time for the user of the library if a clear message explains exactly how the code didn't match the expectations of the library.
You should really consider using them, especially if you're writing a library, because it might really save a lot of time for the user of the library if a clear message explains exactly how the code didn't match the expectations of the library.
