I am compiling C++ on VS 2005.
When and why use #include and when and why use pre-decleration as class XXXX?
What is the benefit of using each option and which one is preffered?
I would also glad for a good tutorial on compiling.
Always prefer forward declaration whenever possible. Changes to the referred class file will not trigger recompilation of cpp files including the class using the pre-declared one. This reduces a bit the dependencies.
On each place where you are effectively using the class XXXX, you will have to include that header. If you derive from class XXXX, you will also have to include the header.
A header file is used to contain the declaration of entities that are defined in separate compilation units. If you did not have a header file, you'd have to enter such declarations in every compilation unit (which is essentially what #include does for you, it inserts the contained text at that point in the file, however if you did not use a header, you'd have to do it multiple times and that is both error prone and difficult to maintain when the code changes.
You'd use a declaration directly in the .cpp file for example if the symbol being defined is only ever used within that compilation unit and therefore did not need global visibility. In the case of data declarations, you also typically declare them static to give them scope limited to the compilation unit.
Related
When is it necessary to separately declare a class in a ”.h” file and provide the
function implementations in a ”.cpp” file?
It is not strictly necessary, as far as the C++ language is concerned. You can put all class methods inline in the .h file.
However, putting the implementations into a separate .cpp offers many benefits, such as:
C++ is very complex. As the code grows, it will take longer and longer to compile it. Every .cpp file that includes the same header file will end up compiling the same code, over and over again.
Related to the first point: if any change is made to the class's methods, if all the class methods are in a separate .cpp file, only that .cpp needs recompilation. If all class methods are placed inline into the .h file, every .cpp that includes will must be recompiled.
Very often, the class's methods will use other classes as part of doing whatever they need to do. So, if they're all placed inline in the .h file, the .h file that defines those other classes will need to be included also, also slowing down the compilation of every .cpp file that includes the header file. If the class methods are in a separate .cpp file, only that .cpp file needs to include the other headers, and most of the time it's only necessary to add some forward declarations to the .h.
It's done that way so that you only build the class' code one time.
If you put the class' code in the .h file, then every file that picks up the .h (to access the public functions of the class) will also duplicate the class' code.
The compiler will happily do this for you.
The linker, however, will complain mightily about duplicate lvalues in the namespace.
Along the same lines, yet conversely: inline functions need to be in the .h so that their code will get picked up in the other code files, which is exactly the intent of inline functions.
If you want to use declarations to implement/define the function, declarations that you don't want to make visible in the *.h file, then it would be necessary to move the definition of the function to a separate file.
Usually that's a good separation between class definition (.h) and class implementation (.cpp) People can just read the .h files to know and use the class without bothering reading the implementation details.
It's, however, not mandatory to always separate .h and .cpp, you can have the class definition and implementation in a single file (eg., for some simple classes, or some quick prototypes).
From a technical perspective (in terms of what a compiler needs or will accept) it is almost never necessary - it is possible to copy/paste the content of every (non-standard) header file into the source files that include them, and compile that. After all, that is effectively what the preprocessor does with #include directives - copy the included file in place, after which the resultant source is fed to later phases of the compiler.
It is possible for a compiler to run out of memory when compiling source - in which case breaking the program into smaller pieces, including header files, can help - but such circumstances (on machines with very limited hardware resources, such as memory) are very rare in modern development.
However, humans are less consistent and more error prone than compilers when dealing with source files, so humans benefit from use of header files. For example, instead of typing (or copying in) needed declarations into every source file that needs them (an activity which people find boring, and tend to make mistakes when doing) simply place the declarations in a header file and #include it when needed.
So then it comes down to when placing declarations in a header file makes life easier for a human, allowing them to avoid making errors, and to focus their effort on the creative parts of software development (implementing new things) rather than the mechanical (copying function declarations into source files that need them).
In practice, it normally works out that a class which will be used within more than one compilation unit (aka source file) is better off being defined in a header file. A class which is local to a single compilation unit (e.g. to contain implementation details for that compilation unit that do not need to be directly accessed by others) does not need to be in a header file, since it can be defined directly without use of a header. The problems come in if such "local" classes later need to be used in other compilation units - in that case, it is usually advisable to migrate the necessary declarations to a header file, to aid reuse.
Header files also tend to become necessary for authors of libraries - who write a set of functions for use by other programmers, but don't wish to ship the source. This is a non-technical constraint (i.e. policy based), rather than a technical one. In that case, they can distribute the header files and the compiled object (or library) files, and keep their source code private. Of course, technically, they could provide a set of text files with instructions of the form "copy these declarations to your program when you need to use them" instead of header files ..... but that would make the library unpopular with developers, since it forces them back into the mundane and error-prone activity of copying text around rather than doing useful development.
Considerations like reducing compile times are also non-technical reasons (a compiler doesn't care how long it takes to build a program, but people do). Separating class definitions into header (class definition, any inline functions) and separate source (definition of non-inline member functions) does tend to reduce build times, and aid with incremental builds.
I'm trying to use a third party C++ library that isn't using namespaces and is causing symbol conflicts. The conflicting symbols are for classes my code isn't utilizing, so I was considering creating custom header files for the third party library where the class declarations only include the public members my code is using, leaving out any members that use the conflicting classes. Basically creating an interface.
I have three questions:
If the compilation to .obj files works, will this technique still cause symbol conflicts when I get to linking?
If that isn't a problem, will the varying class declarations cause problems when linking? For example, does the linker verify that the declaration of a class used by each .obj file has the same number of members?
If neither of those are a problem and I'm able to link the .obj files, will it cause problems when invoking methods? I don't know exactly how C++ works under the hood, but if it uses indexes to point to class methods, and those indexes were different from one .obj file to another, I'm guessing this approach would blow up at runtime.
In theory, you need identical declarations for this to work.
In practice, you will definitely need to make sure your declarations contain:
All the methods you use
All the virtual methods, used or not.
All the data members
You need all these in the right order of declaration too.
You might get away with faking the data members, but would need to make sure you put in stubs that had the same size.
If you do not do all this, you will not get the same object layout and even if a link works it will fail badly and quickly at run-time.
If you do this, it still seems risky to me and as a worst case may appear to work but have odd run time failures.
"if it uses indexes ": To some extent exactly how virtual functions work is implementation defined, but typically it does use an index into a virtual function table.
What you might be able to do is to:
Take the original headers
Keep the full declarations for the classes you use
Stub out the classes and declarations you do not use but are referenced by the ones you do.
Remove all the types not referenced at all.
For explanatory purposes a simplified explaination follows.
c++ allows you to use functions you declare. what you do is putting multiple definitions to a single declaration across multiple translation units. if you expose the class declaration in a header file your compiler sees this in each translation unit, that includes the header file.
Therefore your own class functions have to be defined exactly as they have been declared (same function names same arguments).
if the function is not called you are allowed not to define it, because the compiler doesn't know whether it might be defined in another translation unit.
Compilation causes label creation for each defined function(symbol) in the object code. On the other hand a unresolved label is created for each symbol that is referenced to (a call site, a variable use).
So if you follow this rules you should get to the point where your code compiles but fails to link. The linker is the tool that maps defined symbols from each translation-unit to symbol references.
If the object files that are linked together have multiple definitions to the same functions the linker is unable to create an exact match and therefore fails to link.
In practice you most likely want to provide a library and enjoy using your own classes without bothering what your user might define. In spite of the programmer taking extra care to put things into a namespace two users might still choose the same name for a namespace. This will lead to link failures, because the compiler exposed the symbols and is supposed to link them.
gcc has added an attribute to explicitly mark symbols, that should not be exposed to the linker. (called attribute hidden (see this SO question))
This makes it possible to have multiple definitions of a class with the same name.
In order for this to work across compilation units, you have to make sure class declarations are not exposed in an interface header as it could cause multiple unmatching declarations.
I recommend using a wrapper to encapsulate the third party library.
Wrapper.h
#ifndef WRAPPER_H_
#define WRAPPER_H_
#include <memory>
class third_party;
class Wrapper
{
public:
void wrappedFunction();
Wrapper();
private:
// A better choice would be a unique_ptr but g++ and clang++ failed to
// compile due to "incomplete type" which is the whole point
std::shared_ptr<third_party> wrapped;
};
#endif
Wrapper.cpp
#include "Wrapper.h"
#include <third_party.h>
void Wrapper::wrappedFunction()
{
wrapped->command();
}
Wrapper::Wrapper():wrapped{std::make_shared<third_party>()}
{
}
The reason why a unique_ptr doesn't work is explained here: std::unique_ptr with an incomplete type won't compile
You can move the entire library into a namespace by using a clever trick to do with imports. All the import directive does is copy the relevant code into the current "translation unit" (a fancy name for the current code). You can take advantage of this as so
I've borrowed heavily from another answer by user JohnB which was later deleted by him.
// my_thirdparty.h
namespace ThirdParty {
#include "thirdparty.h"
//... Include all the headers here that you need to use for thirdparty.
}
// my_thirdparty.cpp / .cc
namespace ThirdParty {
#include "thirdparty.cpp"
//... Put all .cpp files in here that are currently in your project
}
Finally, remove all the .cpp files in the third party library from your project. Only compile my_thirdparty.cpp.
Warning: If you include many library files from the single my_thirdparty.cpp this might introduce compiler issues due to interaction between the individual .cpp files. Things such as include namespace or bad define / include directives can cause this. Either resolve or create multiple my_thirdparty.cpp files, splitting the library between them.
Do stand alone C++ functions need a header file and a code file?
I am writing some C++ functions that use some of my other C++ classes but don't belong in a class themselves. They are intended to be compiled in a dll and so I was wondering if it was necessary to declare them in a separate header file or if I could/should just put the declarations in the .cc file.
Maybe this would just be bad practice?
The header file is useful because it is able to let other source files know about the functions that are declared in a different translation unit.
This is necessary by the compiler to be able to check that what you are invoking is correct for the type checker. But the necessity comes from the declaration itself not from the existence of the header file.
For a DLL, if I remember correctly, you are not forced to do it just because you are going to declare the signature of the function anyway whenever you are using them, eg.
extern C __declspec(dllimport) void foo();
Of course this means that you will need to forward declare them anyway so I don't see any problem in having an header files for your DLL, it will just keep all signatures together.
It is not strictly necessary, but it is strongly recommended.
Place the function declarations in a header file and the function definitions in a source (.cc) file. The motivation is to allow the users (here, fellow programmers) to view only the interface but not the implementation (since it can change). Moreover, it allows other source files to include your header file and use the functions provided by you.
The only exception are static functions, they should not be declared in a header file because they are not supposed to be viewed or used outside your source file..
If you are going to use a function outside of the source file in which it's defined, you absolutely need a declaration. It is best to put the declaration in a header file so that it's consistent, otherwise you just end up repeating yourself and introducing a potential source of bugs.
I've just been given my first real C++ application on the job after working through some books learning the language.
It was my understanding that your cpp source files required the cooresponding header, yet one of the libraries in my project is building fine with a number of cpp files that DO NOT include the cooresponding header. This particular cpp implements a class found in a header that has a different name and a number of other pieces of code beyond just the original class declaration.
How is it that the cpp can compile functions belonging to a class that it has no knowledge of?
Can the implementation of these functions be compiled independently and are simply called when a client application using the library (and including the header with the class declaration) calls the corresponding member function? If this is the case, how is the implementation binary referenced by the client application?
(I assume this is the linker...but I would love to have this cleared up).
I anticipate the answer may expose a misunderstanding of mine with regard to the include and compilation process, and I'd really like to learn this aspect of C++ well. Thank you!
When a c++ source file is compiled the first stage it goes through is preprocessing.
When the include directive is reached the file is found and the entire contents of the file, whatever that may be is included into the source file, as if it had been written in the source file itself.
You will be able to define any function from a class in any source file that includes the class's declaration, this is the source file "knowing" about the class / function".
There's also no requirement that the contents of a header and a source file will have any relationship. It's widely considered to be very good practise however.
The implementation of each compilation unit (a source file) is compiled independently. Any function definition could be placed in any compilation unit, and it would make not difference whatsoever. When the compilation units are linked together the usages of every declaration are matched to all the definitions.
The only other pattern that some people might use other than the 1:1 relationship between source files and header files (that I can think of) is that the header files each describe a class and each source file would implement a collection of related functionality. But this is a bad idea (in my opinion) because it would encourage the definitions of various classes to because highly coupled.
These are several questions. You should try to split these.
The name of the files where something is declared is not relavant. The compiler gets the preprocessor output independent from the files that have been read by the preprocessor. The compiler might be use some file/line information in the preprocessed file to issue more readable diagnostic messages.
When you declare a class in a header file and copy that declaration to a implementation file everything works fine as long as you don't change one of the copies of the declaration. This is bad dangerous and should be avoided. Declare anything always once.
When you compile an implementation of a class member function you get a function that the linker can link to your client program. A good tool chain is able to link only the functions that are accessed. So you can separate the interface (in the header files) from the implementation that is provided in a static library. The linker will add each object module in the library to your executable until all symbol references are resolved.
When dividing your code up into multiple files just what exactly should go into an .h file and what should go into a .cpp file?
Header files (.h) are designed to provide the information that will be needed in multiple files. Things like class declarations, function prototypes, and enumerations typically go in header files. In a word, "definitions".
Code files (.cpp) are designed to provide the implementation information that only needs to be known in one file. In general, function bodies, and internal variables that should/will never be accessed by other modules, are what belong in .cpp files. In a word, "implementations".
The simplest question to ask yourself to determine what belongs where is "if I change this, will I have to change code in other files to make things compile again?" If the answer is "yes" it probably belongs in the header file; if the answer is "no" it probably belongs in the code file.
Fact is, in C++, this is somewhat more complicated that the C header/source organization.
What does the compiler see?
The compiler sees one big source (.cpp) file with its headers properly included. The source file is the compilation unit that will be compiled into an object file.
So, why are headers necessary?
Because one compilation unit could need information about an implementation in another compilation unit. So one can write for example the implementation of a function in one source, and write the declaration of this function in another source needing to use it.
In this case, there are two copies of the same information. Which is evil...
The solution is to share some details. While the implementation should remain in the Source, the declaration of shared symbols, like functions, or definition of structures, classes, enums, etc., could need to be shared.
Headers are used to put those shared details.
Move to the header the declarations of what need to be shared between multiple sources
Nothing more?
In C++, there are some other things that could be put in the header because, they need, too, be shared:
inline code
templates
constants (usually those you want to use inside switches...)
Move to the header EVERYTHING what need to be shared, including shared implementations
Does it then mean that there could be sources inside the headers?
Yes. In fact, there are a lot of different things that could be inside a "header" (i.e. shared between sources).
Forward declarations
declarations/definition of functions/structs/classes/templates
implementation of inline and templated code
It becomes complicated, and in some cases (circular dependencies between symbols), impossible to keep it in one header.
Headers can be broken down into three parts
This means that, in an extreme case, you could have:
a forward declaration header
a declaration/definition header
an implementation header
an implementation source
Let's imagine we have a templated MyObject. We could have:
// - - - - MyObject_forward.hpp - - - -
// This header is included by the code which need to know MyObject
// does exist, but nothing more.
template<typename T>
class MyObject ;
.
// - - - - MyObject_declaration.hpp - - - -
// This header is included by the code which need to know how
// MyObject is defined, but nothing more.
#include <MyObject_forward.hpp>
template<typename T>
class MyObject
{
public :
MyObject() ;
// Etc.
} ;
void doSomething() ;
.
// - - - - MyObject_implementation.hpp - - - -
// This header is included by the code which need to see
// the implementation of the methods/functions of MyObject,
// but nothing more.
#include <MyObject_declaration.hpp>
template<typename T>
MyObject<T>::MyObject()
{
doSomething() ;
}
// etc.
.
// - - - - MyObject_source.cpp - - - -
// This source will have implementation that does not need to
// be shared, which, for templated code, usually means nothing...
#include <MyObject_implementation.hpp>
void doSomething()
{
// etc.
} ;
// etc.
Wow!
In the "real life", it is usually less complicated. Most code will have only a simple header/source organisation, with some inlined code in the source.
But in other cases (templated objects knowing each others), I had to have for each object separate declaration and implementation headers, with an empty source including those headers just to help me see some compilation errors.
Another reason to break down headers into separate headers could be to speed up the compilation, limiting the quantity of symbols parsed to the strict necessary, and avoiding unecessary recompilation of a source who cares only for the forward declaration when an inline method implementation changed.
Conclusion
You should make your code organization both as simple as possible, and as modular as possible. Put as much as possible in the source file. Only expose in headers what needs to be shared.
But the day you'll have circular dependancies between templated objects, don't be surprised if your code organization becomes somewhat more "interesting" that the plain header/source organization...
^_^
in addition to all other answers, i will tell you what you DON'T place in a header file:
using declaration (the most common being using namespace std;) should not appear in a header file because they pollute the namespace of the source file in which it is included.
What compiles into nothing (zero binary footprint) goes into header file.
Variables do not compile into nothing, but type declarations do (coz they only describe how variables behave).
functions do not, but inline functions do (or macros), because they produce code only where called.
templates are not code, they are only a recipe for creating code. so they also go in h files.
In general, you put declarations in the header file and definitions in the implementation (.cpp) file. The exception to this is templates, where the definition must also go in the header.
This question and ones similar to it has been asked frequently on SO - see Why have header files and .cpp files in C++? and C++ Header Files, Code Separation for example.
Mainly header file contain class skeleton or declaration (does not change frequently)
and cpp file contains class implementation (changes frequently).
Header (.h)
Macros and includes needed for the interfaces (as few as possible)
The declaration of the functions and classes
Documentation of the interface
Declaration of inline functions/methods, if any
extern to global variables (if any)
Body (.cpp)
Rest of macros and includes
Include the header of the module
Definition of functions and methods
Global variables (if any)
As a rule of thumb, you put the "shared" part of the module on the .h (the part that other modules needs to be able to see) and the "not shared" part on the .cpp
PD: Yes, I've included global variables. I've used them some times and it's important not to define them on the headers, or you'll get a lot of modules, each defining its own variable.
Your class and function declarations plus the documentation, and the definitions for inline functions/methods (although some prefer to put them in separate .inl files).
the header file (.h) should be for declarations of classes, structs and its methods, prototypes, etc. The implementation of those objects are made in cpp.
in .h
class Foo {
int j;
Foo();
Foo(int)
void DoSomething();
}
I'd expect to see:
declarations
comments
definitions marked inline
templates
the really answer though is what not to put in:
definitons (can lead to things being multiply defined)
using declarations/directives (forces them on anyone including your header, can cause nameclashes)
The header Defines something but doesn't tell anything about the implementation. ( Excluding Templates in this "metafore".
With that said, you need to divide "definitions" into sub-groups, there are, in this case, two types of definitions.
You define the "layout" of your strucutre, telling only as much as is needed by the surrounding usage groups.
The definitions of a variable, function and a class.
Now, I am of course talking about the first subgroup.
The header is there to define the layout of your structure in order to help the rest of the software use the implementation. You might want to see it as an "abstraction" of your implementation, which is vaughly said but, I think it suits quite well in this case.
As previous posters have said and shown you declare private and public usage areas and their headers, this also includes private and public variables. Now, I don't want to go into design of the code here but, you might want to consider what you put in your headers, since that is the Layer between the end user and the implementation.
Header files - shouldn't change during development too often -> you should think, and write them at once (in ideal case)
Source files - changes during implementation