What is the best practice for a shared library primary header file in C++?

Question

When I create shared libraries, I have a header file (but with no file name extension) in the root of the library source named the same as the library.

So for example, if my library was called libirock.so, then I'd have a file called irock in the project root. This file will include all of the most important headers in the library, so that when the library is to be implemented, all you need to do is use this include line:

#include <irock> // Instead of <irock.h>

I got the idea from when I saw a compiler warning similar to:

#include <string.h> is obsolete, use #include <string> instead

Two questions:

1. Is using irock instead of irock.h best practice?
2. Is is correct to use a single header file instead of many headers?

Course of action

Thanks for your answers! From the answers, I've decided:

1. Will use <irock.h> instead of <irock>.
2. I will continue to use a 'primary' header file.

Answer 1

No, the <header> instead of <header.h> idiom is supposed to be for standard library (and standard template library) headers only.

Answer 2

In a single word, no. You'll want to explicitly use irock.h

With the extension in place, it's clear that this is a header file, and any application that uses files based on file extension will correctly know how to interpret your header file.

Answer 3

#include simply puts the content of a given file name into the actual file. So if you're feeling better without file extension just do it.

Of course the file extension has a semantic meaning which is useful. Also, included files without extension are connected with the standard library in most of the users minds.

Answer 4

There is nothing in the standard governing "allowed", "prohibited" or "best practices" regarding extensions for filenames.

Use whichever form you prefer. On some platforms there's a convenience factor to having an file extensions for registered types.

For what it's worth <string.h> and <string> are totally different headers. The C++ namespaced equivalent of <string.h> is actually <cstring>.

Answer 5

What is used in Qt4, is that you can include the file names by "class name", for example

#include <QString>
#include <QWidget>
#include <QPainter>
#include <QApplication>
#include <QCoreApplication>

Those includes are dummy includes which will include the correct header. In real life, you will see that several classes are defined in a single include.h and you included that file twice.

A reason agains using the version without the ".h" is that you will get tempted to use includes which are camelCase (or PascalNotation) and if you move the code from windows to unix (linux or mac) you will usually get into problems. Not hard to do - but you do need to take care of doing it correctly.