Introduction

In this intermittent series, I’ll be looking at the most common error messages your C++ compiler (and linker) can produce, explaining exactly what they mean, and showing how they can be fixed (or, better still avoided). The article will specifically talk about the errors produced by the GCC command line compiler, but I’ll occasionally provide some coverage of Microsoft C++ as well. The articles are aimed at beginner to intermediate C++ programmers, and will mostly not be OS-specific.

Error Messages 101

Compiler error messages from the GCC g++ compiler generally look like something this:

main.cpp: In function 'int main()':
main.cpp:4:12: error: 'bar' was not declared in this scope

which was produced by this code:

int main() {
    int foo = bar;
}

The first line of the error says which function the following error(s) is in. The error message itself comes in four main parts; the file the error occurs in, the line number and character offset at which the compiler thinks the error occurs, the fact that it is an error, and not a warning, and the text of the message.

As well as error, the compiler can also produce warnings. These are usually about constructs that, while not being actually illegal in C++, are considered dubious, or constructs that the compiler has extensions to cover. In almost all cases, you don’t want to use such constructs, and you should treat warnings as errors; in other words, your code should always compile with zero warnings. You should also increase the level of warnings from the compiler’s default, which is usually too low. With g++, you should use at least the -Wall and -Wextra compiler options to do this:

g++ -Wall -Wextra myfile.cpp

No such file or directory

The error I’m looking at today most commonly occurs when you are including a header file using the preprocessor #include directive. For example, suppose you have the following code in a file called myfile.cpp:

#include "myheader.h"

and you get the following error message:

myfile.cpp:1:22: fatal error: myheader.h: No such file or directory
compilation terminated.

What could be causing it? Well, the basic cause is that the compiler cannot find a file called myheader.h in the directories it searches when processing the #include directive. This could be so for a number of reasons.

The simplest reason is that you want the compiler to look for myheader.h in the same directory as the myfile.cpp source file, but it can’t find it. this may be because you simply haven’t created the header file yet, but the more common reason is that you either misspelled the header file name in the #include directive, or that you made a mistake in naming  the header file when you created it with your editor. Look very closely at the names in both the C++ source and in your source code directory listing. You may be tempted to think "I know that file is there!", but if the compiler says it isn’t there, then it isn’t, no matter how sure you are that it is.

This problem is somewhat greater on Unix-like system, such as Linux, as there file names are character case sensitive, so Myheader.h, MyHeader.h, myheader.h and so on would all  name different files, and if you get the case wrong, the compiler will not look for something "similar". For this reason, a very good rule of thumb is:

Never use mixed case when naming C++ source and header files. Use only alphanumeric characters and the underscore when naming C+++ files. Never include spaces or other special characters in file names.

Apart from avoiding file not found errors, this will also make life much easier if you are porting your code to other operating systems which may or may not respect character case.

The wrong directory?

Another situation where you may get this error message is if you have split your header files up from your C++ source files into separate directories. This is generally good practice, but can cause problems. Suppose your C++ project is rooted at C:/myprojects/aproject, and that in the aproject directory you have two sub-directorys called src (for the .cpp files) and inc (for the header files), and you put myfile.cpp  in the src directory, and myheader.h in the inc directory, so that you have this setup:

myprojects
  aproject
    inc
      myheader.h
    src
      myfile.cpp

Now if you compile the source myfile.cpp from the src directory, you will get the "No such file or directory" error message. The C++ compiler knows nothing about the directory structures of your project, and won’t look in the inc directory for the header. You need to tell it to look there somehow.

One thing some people try when faced with this problem is to re-write myfile.cpp so it looks like this:

#include "c:/myprojects/aproject/inc/myheader.h"

or the slightly more sophisticated:

#include "../inc/myheader.h"

Both of these are a bad idea, as they tie your C++ code to the project’s directory structure and/or location, both of which you will probably want to change at some point in the future. If the directory structure does change, you will have to edit all your #include directories.The better way to deal with this problem is to tell the compiler directly where to look for header files. You can do that with the compiler’s -I option, which tells the compiler to look in the specified directory, as well as the ones it normally searches:

g++ -Ic:/myprojects/aproject/inc myfile.cpp

Now the original #include directive:

#include "myheader.h"

will work, and if your directory structure changes you need only modify the compiler command line. Of course, writing such command lines is error prone, and you should put such stuff in a makefile, the use of which is unfortunately outside the scope of this article.

Problems with libraries

Somewhat similar issues to those described above can occur when you want to use a third-party library.  Suppose you want to use the excellent random number generating facilities of the Boost library. If you are copying example code, you may well end up with something like this in your C++ source file:

#include "boost/random.hpp"

This will in all probability lead to yet another "No such file or directory" message, as once again the compiler does not know where "boost/random.hpp" is supposed to be. In fact, it is one of the subdirectories of the Boost installation, and on my system I can get the #include directive to work using this command line:

g++ -Ic:/prog/boost1461 myfile.cpp

where /prog/boost1461 is the root directory for my specific Boost library installation.

Can’t find C++ Standard Library files?

One last problem that beginners run into is the inability of the compiler to find header files that are part of the C++ Standard Library. One particular favourite is this one:

#include <iostream.h>

where you are learning C++ from a very, very old book. Modern C++ implementations have not contained a file called iostream.h for a very long time indeed, and your compiler is never going to find it. You need to use the correct, standard names for such headers (and to get a better book!):

#include <iostream>

If this still fails, then there is almost certainly something very wrong with your GCC installation. The GCC compiler looks for Standard Library files in a subdirectory of its installation, and locates that directory relative to the directory containing the compiler executable, so if the Standard Library headers are available, the compiler should always find them.

Conclusion

This article looked at the "No such file or directory"  message of the GCC C++ compiler.  If you get this message you should:

• Remember that the compiler is always right in situations like this.
• Look very closely at the file name to make sure it is correct.
• Avoid naming file using mixed-case or special characters.
• Use the -I compiler option to tell the compiler where to look for files.
• Make sure that GCC is correctly installed on your system.