A header library is a library with all the code in the header.
If I have two cpp files that need code from the header lib, and if they both import the header, and both get compiled, the header file is getting compiled twice, I think. Would linking now throw and error because the header lib functions are being defined twice? If not an error, is this still bad practice?
What is the correct way to handle a header lib?
Just #include everywhere you want. If the library is not horribly broken, it will work fine. The library itself is responsible for having mechanisms that make it usable, in case of a header only library that means making it usable by including the header(s).
Nothing would make this bad practice, simply using by including is the purpose of a header only library.
Header files will use include guards (Include Guard wiki) that keep library functions from being defined twice. Basically, a header file will use a conditional statement that is evaluated during compilation that checks for an existing library definition. If it is defined already it ignores anymore additional definitions. These guards look like this:
/* library_name.h */
#ifndef SOME_IDENTIFIER
#define SOME_IDENTIFIER
[function prototypes]
#endif
A Daniel's Computer Blog article (Here) provides a very digestable explanation of what's going on behind the scenes and flushes out more nuances that I didn't address.
Baum mit Augen is right. If the lib uses include guards there will be no problem using #include<library_name> anywhere you want as many times as you want.
Ideally you will use #include<library_name> once at the top of any file that uses a function/class/constant from the library.
Related
I'm writing a library based on OpenVPN3, which is the C++ OpenVPN client implementation in header only, no cpp files. Therefore, I'm having to rely on having only one cpp file, which is the client itself, which includes a header that includes tons of other headers.
The problem is that, because of this, I cannot separate code into multiple cpp files. I'd like to be able for people to use my library, be it precompiled or compiled by them, but they cannot include the same headers on more than 1 cpp file or in the linking process there will be lots of redefinitions. There are also some static variables in the headers, for example.
If someone want to take a look at the number of things added into the 'master' header file: https://github.com/lucaszanella/libopenvpn3/blob/9b3440a736d90b671e9376d2d9e4911475e07112/src/OpenVPNClient.hpp
I know that there are some libraries like Asio that are also header-only and they're used without any problems by everyone.
Some techniques for not redefining a class or a function are to forward declare them but give no definition, but the problem here is that the person who's using my library is going to have to access its methods and everything. Is it possible to separate my methods from the ones used by my library on the headers?
you can put #pragma once on the most top of the file to avoid the same class clash due to being defined twice
If you do not want to duplicate import you can like tadman said:
at the top of the file
#ifndef HEADER
#define HEADER
//code goes here
#endif
I'm writing a library based on OpenVPN3, which is the C++ OpenVPN client implementation in header only, no cpp files. Therefore, I'm having to rely on having only one cpp file, which is the client itself, which includes a header that includes tons of other headers.
The problem is that, because of this, I cannot separate code into multiple cpp files. I'd like to be able for people to use my library, be it precompiled or compiled by them, but they cannot include the same headers on more than 1 cpp file or in the linking process there will be lots of redefinitions. There are also some static variables in the headers, for example.
If someone want to take a look at the number of things added into the 'master' header file: https://github.com/lucaszanella/libopenvpn3/blob/9b3440a736d90b671e9376d2d9e4911475e07112/src/OpenVPNClient.hpp
I know that there are some libraries like Asio that are also header-only and they're used without any problems by everyone.
Some techniques for not redefining a class or a function are to forward declare them but give no definition, but the problem here is that the person who's using my library is going to have to access its methods and everything. Is it possible to separate my methods from the ones used by my library on the headers?
you can put #pragma once on the most top of the file to avoid the same class clash due to being defined twice
If you do not want to duplicate import you can like tadman said:
at the top of the file
#ifndef HEADER
#define HEADER
//code goes here
#endif
I have about a dozen functions all related to the same purpose, and I am trying to create a library. A library that I can store away in a directory somewhere that I can then include as an include directory and just go about my business including said library in my projects that require its use.
Side Note:
First I'd like to say, I have given considerable time into finding an answer to this. I had thought I found a solution to it when I realized the linker would throw errors when I included the library in multiple source files. Now that I know that, I have again searched for an answer to my woes. I started looking at other libraries I know to do the same thing, or that I believe to. I looked at conio.h as I include it all the time for its kbhit() and getch() functions. Though I didn't understand most of what I had in it, I searched a few keywords and found that it may in fact be including the function definitions through a dll.
I've also done a handful of google searches.
To explain what I am doing a little bit. I have create 2 or 3 data structures that allow me to create chunks of data with headers that specify what the data is and how it is to be treated. Then a couple more for reading and writing those chunks to files.
To allow easy creation of these structures I have made stand-alone functions. To allow easy manipulation of these structures I have made even more stand-alone functions.
I, simply put, need a way to include a library that somehow directly or indirectly defines all these functions and structures. How can I do so?
(without creating a myriad of inlines)
You can include a .lib dependency in your code by using the #pragma comment
#pragma comment (lib,"LibraryFileName.lib")
You can read more about #pragma comment here.
I normally like to make a a Linker.h file in my library soultion and include that file in every header found in my library. Here is an example of it.
#ifndef __GRAPHICCOMMUNICATOR_GUARD_linklib__
#define __GRAPHICCOMMUNICATOR_GUARD_linklib__
#if defined(_DEBUG)
#pragma comment (lib,"GraphicCommunicator-mt-d.lib")
#elif !defined(_DEBUG)
#pragma comment (lib,"GraphicCommunicator-mt.lib")
#else
#error link: no suitable library
#endif
#endif // __GRAPHICCOMMUNICATOR_GUARD_linklib__
Putting everything in one header is causing the problem.
You can leave class member funnctions defined inline or other inline function in headers and include them more than once.
Otherwise you need to move implementations into cpp files and build a static (or dynamic) library. If you are learning, static may be easier. Make a new project and select "Static library" from the application settings.
To use the library you could use the #pragma answer from Caeser, or just add the .lib to the linker settings in the projects that wish to use it, along with #including the headers you need.
Is there some preferred way to organize ones include directives?
Is it better to include the files you need in the .cpp file instead of the .h file? Are the translation units affected somehow?
How about if I need it in both the .h file and .cpp file, should I just include it in the .h file? Will it matter?
Is it a good practice to keep the already defined files in a precompiled header (stdafx.h), for instance std and third party libraries? How about my own files, should I include them in a stdafx.h file along the way as I create them?
// myClass.h
#include <string>
// ^-------- should I include it here? --------
class myClass{
myClass();
~myClass();
int calculation()
};
// myClass.cpp
#include "myClass.h"
#include <string>
// ^-------- or maybe here? --------
[..]
int myClass::calculation(){
std::string someString = "Hello World";
return someString.length();
}
// stdafx.h
#include <string.h>
// ^--------- or perhaps here, and then include stdafx.h everywhere? -------
You should have them at the top of the file, all in one place. This is what everyone expects. Also, it is useful to have them grouped, e.g. first all standard headers, then 3rd-party headers (grouped by library), then your own headers. Keep this order consistent throughout the project. It makes it easier to understand dependencies. As #James Kanze points out, it is also useful to put the header that declares the content first. This way you make sure that it works if included first (meaning it does no depend on any includes that it does not include itself).
Keep the scope as small as possible, so that a change in the header affects the least number of translation-units. This means, whenever possible include it in the cpp-file only. As #Pedro d'Aquino commented, you can reduce the number of includes in a header by using forward declarations whenever possible (basically whenever you only use references or pointers to a given type).
Both - explicit is better than implicit.
After some reading, I believe you should only include headers in the PCH if you are confident that they do not change anymore. This goes for all standard headers as well as (probably) third party libraries. For your own libraries, you be the judge.
This article on Header file include patterns should be helpful for you.
Is there some preferred way to organize ones include directives?
Yes, you can find them in the above article.
Is it better to include the files you need in the .cpp file instead of
the .h file? Are the translation units
affected somehow?
Yes, it is better to have them in .cpp. Even, if a defined type is required in definition of another type, you can use forward declaration.
How about if I need it in both the .h file and .cpp file, should I just
include it in the .h file? Will it
matter?
Only in .h file, but it is suggested to forward declare in header files, and include in .cpp files.
Is it a good practice to keep the already defined files in a precompiled
header (stdafx.h), for instance std
and third party libraries? How about
my own files, should I include them in
a stdafx.h file along the way as I
create them?
I personally have not used precompiled headers, but there has been a discussion on them on Stackoverflow earlier:
Precompiled Headers? Do we really need them
Is there some preferred way to organize ones include directives?
No common conventions. Some suggest alphabet-sorting them, I personally dislike it and prefer keeping them logically grouped.
Is it better to include the files you need in the .cpp file instead of the .h file?
In general, yes. It reduces the count of times that the compiler needs to open and read the header file just to see the include guards there. That may reduce overall compilation time.
Sometimes it's also recommended to forward-declare as much classes as possible in the headers and actually include them only in .cpp's, for the same reason. The "Qt people" do so, for example.
Are the translation units affected somehow?
In semantic sense, no.
How about if I need it in both the .h file and .cpp file, should I just include it in the .h file? Will it matter?
Just include it in the header.
Is it a good practice to keep the already defined files in a precompiled header (stdafx.h), for instance std and third party libraries? How about my own files, should I include them in a stdafx.h file along the way as I create them?
Precompiled headers can significantly reduce compilation times. For example: one of my projects that includes boost::spirit::qi compiles in 20 secs with PCH on, and 80 secs — without. In general, if you use some heavily template-stuffed library like boost, you'd want to utilise the advantage of PCH.
As for the question in your code sample: since you don't use std::string in the header, it's better to include it in the .cpp file. It's alright to #include <string> in stdafx.h too — but that will just add a little bit of complexity to your project and you'll hardly notice any compilation speed-up.
(4) I wouldn't recommend to include any additional files into stdafx.h. or similar "include_first.h" files. Direct including into cpp or particular h files allow you to express dependencies of your code explicitly and exclude redundant dependencies. It is especialy helpful when you decide to decompose monolithic code into a few libs or dll's. Personally, I use files like "include_first.h" (stdafx.h) for configuration purpose only (this file contains only macro definitions for current application configuration).
It is possible to provide precompiled headers for your own files by marking another file to stop precompilation instead of stdafx.h (for instance, you can use special empty file named like "stop_pch.h").
Note, precompiled headers may not work properly for some kinds of sofisticated usage of the preprocessor (particulary, for some technics used in BOOST_PP_* )
From the performance point of view:
Changing any of the headers included from stdafx.h will trigger a new precompilation, so it depends on how "frozen" the code is. External libraries are typical candidates for stdafx.h inclusion, but you can certainly include your own libraries as well - it's a tradeoff based on how often you expect to change them.
Also, with the Microsoft compiler you can put this at the top of each header file:
#pragma once
This allows the compiler to fully skip that file after the first occurrence, saving I/O operations. The traditional ifndef/define/endif pattern requires opening and parsing the file every time it's included, which of course takes some time. It can certainly accumulate and get noticeable!
(Make sure to leave the traditional guards in there, for portability.)
It might be important to notice that the order of classes in Translation Unit need to be correct or some c++ features are just disabled and results in a compile-time error.
Edit: Adding examples:
class A { };
class B { A a; }; // order of classes need to be correct
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 7 years ago.
Improve this question
What order should headers be declared in a header / cpp file? Obviously those that are required by subsequent headers should be earlier and class specific headers should be in cpp scope not header scope, but is there a set order convention / best practice?
In a header file you have to include ALL the headers to make it compilable. And don't forget to use forward declarations instead of some headers.
In a source file:
corresponded header file
necessary project headers
3rd party libraries headers
standard libraries headers
system headers
In that order you will not miss any of your header files that forgot to include libraries by their own.
Good practice: every .h file should have a .cpp that includes that .h first before anything else. This proves that any .h file can be put first.
Even if the header requires no implementation, you make a .cpp that just includes that .h file and nothing else.
This then means that you can answer your question any way you like. It doesn't matter what order you include them in.
For further great tips, try this book: Large-Scale C++ Software Design - it's a shame it's so expensive, but it is practically a survival guide for C++ source code layout.
In header files, I tend to put standard headers first, then my own headers (both lists being ordered alphabetically). In implementation files, I put first the header corresponding (if any), then standards headers and other dependency headers.
Order is of little importance, except if you make a great use of macros and #define ; in that case, you must checked that a macro you defined doesn't replace a previously included one (except if that's what you want, of course).
Concerning this statement
those that are required by subsequent headers should be earlier
A header shouldn't rely on other headers being included before it! If it requires headers, it just includes them. Header guards will prevent multiple inclusion:
#ifndef FOO_HEADER_H
#define FOO_HEADER_H
...
#endif
EDIT
Since I wrote this answer, I changed my way of ordering the include directives in my code. Now, I try to always put headers in increasing order of standardization, so the headers of my project come first, followed by 3rd party libraries headers, followed by standard headers.
For instance, if one of my file uses a library I wrote, Qt, Boost and the standard library, I will order the includes as follow:
//foo.cpp
#include "foo.hpp"
#include <my_library.hpp>
// other headers related to my_library
#include <QtCore/qalgorithms.h>
// other Qt headers
#include <boost/format.hpp> // Boost is arguably more standard than Qt
// other boost headers
#include <algorithms>
// other standard algorithms
The reason why I do that is to detect missing dependencies in my own headers: let's assume for instance that my_library.hpp uses std::copy, but doesn't include <algorithm>. If I include it after <algorithm> in foo.cpp, this missing dependency will go unnoticed. On the contrary, with the order I just presented, the compiler will complain that std::copy has not been declared, allowing me to correct my_library.hpp.
In each "library" group, I try to keep the include directives ordered alphabetically, to find them more easily.
On a sidenote, a good practice is also to limit at a maximum the dependency between header files. Files should include as little headers as possible, especially headers file. Indeed, the more headers you include, the more code needs to be recompiled when something changes. A good way to limit these dependencies is to use forward declaration, which is very often sufficient in header files (see When can I use a forward declaration?).
Google C++ Style Guide, Names and Order of Includes :
In dir/foo.cc, whose main purpose is to implement or test the stuff in dir2/foo2.h, order your includes as follows:
dir2/foo2.h (preferred location — see details below).
C system files.
C++ system files.
Other libraries' .h files.
Your project's .h files.
I used to order them in alphabetical order (easier to find)
The "how" is not obvious, but the "what" is.
Your goal is to make sure that the order in which you include header files never matters (and i mean "NEVER !").
A good help is to test whether header files compile when building cpp files (one for each header file) that only include one of them.
For .cpp files, you should include the header of the class or whatever you are implementing first, so you catch the case where this header is missing some includes. After that, most coding guidelines tend to include system headers first, project headers second, for example the Google C++ Style Guide.
It's a dependency thing and it depends largely on what you put in our headers. A fact is that you can be really notorious about this and minimize to keep your includes strict but you'll eventually run into a scenario where you'll wanna use inclusion guards.
#ifndef MY_HEADER_H
#define MY_HEADER_H
//...
#endif
The problem isn't that apparent in the beginning, but as the complexity of your software grows so does your dependencies. You can do well, and be smart about it but larger C++ projects are generally riddled with includes. You can try, but you can only do so much. So be diligent and think about your includes, YES! But you'll most certainly have cyclic dependencies at some point and that is why you need inclusion guards.
If a header needs other headers then it just includes them in that header.
Try to structure your code so you pass pointers or references and forward declare where you can.
In the implementation then the header that defines it should be listed first (except in Visual Studio if you are using pch then stdafx would go first).
I generally list them as I need.
I've found the following convention the most useful:
module.cpp:
// this is the header used to trigger inclusion of precompiled headers
#include <precompiled.h>
// this ensures that anything that includes "module.h" works
#include "module.h"
// other headers, usually system headers, the project
The important thing is to put the module's header as the first non-precompiled header. This ensures "module.h" has no unexpected dependencies.
If you're working on a large project with slow disk access times, I've seen this style used to decrease build times:
module.cpp:
// this is the header used to trigger inclusion of precompiled headers
#include <precompiled.h>
// this ensures that anything that includes "module.h" works
#include "module.h"
// other headers, usually system headers, the project
#if !defined _OTHER_MODULE_GUARD_
#include "other_module.h"
#endif
#if !defined _ANOTHER_MODULE_GUARD_
#include "another_module.h"
#endif
It's a bit verbose but does save on disk seeking since the header won't be searched for / opened if it's already been included. Without the guard check, the compiler will seek for and open the header file, parse the whole file to end up #ifdefing the whole file out.