What is the purpose or meaning behind the aux_ subdirectory in the boost libraries?
For example:
boost/parameter/aux_/
boost/mpl/aux_/
boost/local_function/aux_/
What #DevSolar wrote:
Lots of Boost functionality is implemented in templates, which -- as
we know -- need their definition to be included in the header file.
You cannot hide it in a linker library. But because portions of that
template code are auxiliary to the actual API functionality, they are
put into a subdirectory so they do not confuse the user.
It looks like several similar directory naming schemes are used in boost:
detail
impl
aux_
From what I can see all 3 of these subdirectories serve the same purpose. The naming just depends on the specific boost library. If there is a more specific purpose to the different naming convention, please edit or submit another answer...I'm only guessing here!
Thanks for the hints. I eventually did find a page on www.boost.org that mentions (just in passing!) the directory structure, and why there are different conventions. Here is what it says:
The organization of Boost library headers isn't entirely uniform, but most libraries follow a few patterns:
Some older libraries and most very small libraries place all public headers directly into boost/.
Most libraries' public headers live in a subdirectory of boost/, named after the library. For example, you'll find the Python library's def.hpp header in
boost\python\def.hpp.
Some libraries have an “aggregate header” in boost/ that #includes all of the library's other headers. For example, Boost.Python's aggregate header is
boost\python.hpp.
Most libraries place private headers in a subdirectory called detail/, or aux_/. Don't expect to find anything you can use in these directories.
Source: http://www.boost.org/doc/libs/1_56_0/more/getting_started/unix-variants.html
I am developing C++ headers only library, lets call it PROJ. When a library header is including another, it uses:
#include <proj/foo.h>
And compiler (gcc and clang) have -I path-to-proj-parent. Users of the library should also have parent of PROJ in their include search path.
My rationally for using this scheme is that after installing this library into proj subdirectory of default-seachable parent (/usr/include/proj or /usr/local/include/proj), library user do not need to specify -I option.
Is there cons to this scheme? Is using <foo.h> without proj/ prefix is more conventional and recommended way?
Question is not about if installing in subdir or not (there will be proj subdir), but rather how to refer to include-files.
If you look at boost, you will note that they use a similar scheme:
#include <boost/shared_ptr.hpp>
It has the advantage of preventing clashes with another similarly named file from another dependency.
However, in the case of boost, they take it one step further. If you include <x/y/z.hpp>, then you are likely to be dealing with an entity named ::x::y::z (be it function or class). That is, the way the directories in the project are laid out mimic the namespace organization. It's quite neat really to orient oneself.
Normally, most projects are stashed in subdirectories (and subnamespaces), but the most used ones are pulled into the boost namespace for convenience, and thus they have headers living directly in the boost folder. There are also some convenience headers (whose job is just to gather a smattering of other headers to pull them in all at once).
You may finally note, if you open a header file, than the include guards they use follow the exact same hierarchy:
#ifndef BOOST_SHARED_PTR_HPP_INCLUDED
once again because it helps avoiding clashes since it's named after the very file it's in and there can be only one at that place in the whole Boost project (on case sensitive filesystems).
It is ok to have proj in the path if you create the proj directory when you install. In fact its a good way to prevent name collisions with other include files.
The name should not be something generic like "proj' though. It should be specific to the project.
Off late I have had too use some template libraries like Boost and Thrust (for CUDA) in some of my coding work.
For using a certain feature of the Boost library, one has to include the appropriate header.e.g. for boost::lexical_cast I have to use boost/lexical_cast.hpp. It is tiring to keep including the appropriate header for every new feature of Boost / Thrust which I use for my projects.
Is there any "shortcut" to tell the pre-processor to include all the header files stored under the boost library, so that I need not bother about which header file to include?
I am using GCC under Ubuntu.
You don't want that. You want to include as little as possible. Compile times are abysmal in C++ as it is. Start to include everything everywhere and it is going to get worse even.
I have been working in a project where compilation on a decent single core CPU of the time took 50mins, linking 5-10mins. This hurts big time, if you're doing template stuff deep down in the foundations.
Boost comes with a bunch of stuff (like the MPL) that stretches the compiler to its utmost limits. It would be insane to include this stuff everywhere (except for a five-cpp-files kind of project).
You could simply make a mother-of-all header file like so:
for i in $(find /usr/include/boost/); do echo "#include <"${i/"/usr/include/"/}">"; done > master_header.hpp
Now you can add that and use precompiled headers (you may need an overnight compilation to make the PCH). You should also pass -Wl,-as-needed to the linker to avoid including unneeded libraries.
As #sbi says, this isn't advisable in the least, but since you asked... sometimes the best remedy against finding something "tiresome" is to see how much worse it could be!
Is there an automated way to take a large amount of C++ header files and combine them in a single one?
This operation must, of course, concatenate the files in the right order so that no types, etc. are defined before they are used in upcoming classes and functions.
Basically, I'm looking for something that allows me to distribute my library in two files (libfoo.h, libfoo.a), instead of the current bunch of include files + the binary library.
As your comment says:
.. I want to make it easier for library users, so they can just do one single #include and have it all.
Then you could just spend some time, including all your headers in a "wrapper" header, in the right order. 50 headers are not that much. Just do something like:
// libfoo.h
#include "header1.h"
#include "header2.h"
// ..
#include "headerN.h"
This will not take that much time, if you do this manually.
Also, adding new headers later - a matter of seconds, to add them in this "wrapper header".
In my opinion, this is the most simple, clean and working solution.
A little bit late, but here it is. I just recently stumbled into this same problem myself and coded this solution: https://github.com/rpvelloso/oneheader
How does it works?
Your project's folder is scanned for C/C++ headers and a list of headers found is created;
For every header in the list it analyzes its #include directives and assemble a dependency graph in the following way:
If the included header is not located inside the project's folder then it is ignored (e.g., if it is a system header);
If the included header is located inside the project's folder then an edge is create in the dependency graph, linking the included header to the current header being analyzed;
The dependency graph is topologically sorted to determine the correct order to concatenate the headers into a single file. If a cycle is found in the graph, the process is interrupted (i.e., if it is not a DAG);
Limitations:
It currently only detects single line #include directives (e.g., #include );
It does not handles headers with the same name in different paths;
It only gives you a correct order to combine all the headers, you still need to concatenate them (maybe you want remove or modify some of them prior to merging).
Compiling:
g++ -Wall -ggdb -std=c++1y -lstdc++fs oneheader.cpp -o oneheader[.exe]
Usage:
./oneheader[.exe] project_folder/ > file_sequence.txt
(Adapting an answer to my dupe question:)
There are several other libraries which aim for a single-header form of distribution, but are developed using multiple files; and they too need such a mechanism. For some (most?) it is opaque and not part of the distributed code. Luckily, there is at least one exception: Lyra, a command-line argument parsing library; it uses a Python-based include file fuser/joiner script, which you can find here.
The script is not well-documented, but they way you use it is with 3 command-line arguments:
--src-include - The include file to convert, i.e. to merge its include directives into its body. In your case it's libfoo.h which includes the other files.
--dst-include - The output file to write - the result of the merging.
--src-include-dir - The directory relative to which include files are specified (i.e. an "include search path" of one directory; the script doesn't support the complex mechanism of multiple include paths and search priorities which the C++ compiler offers)
The script acts recursively, so if file1.h includes another file under the --src-include-dir, that should be merged in as well.
Now, I could nitpick at the code of that script, but - hey, it works and it's FOSS - distributed with the Boost license.
If your library is so big that you cannot build and maintain a single wrapping header file like Kiril suggested, this may mean that it is not architectured well enough.
So if your library is really huge (above a million lines of source code), you might consider automating that, with tools like
GCC make dependency generator preprocessor options like -M -MD -MF etc, with another hand made script sorting them
expensive commercial static analysis tools like coverity
customizing a compiler thru plugins or (for GCC 4.6) MELT extensions
But I don't understand why you want an automated way of doing this. If the library is of reasonable size, you should understand it and be able to write and maintain a wrapping header by hand. Automating that task will take you some efforts (probably weeks, not minutes) so is worthwhile only for very large libraries.
If you have a master include file that includes all others available, you could simply hack a C preprocessor re-implementation in Perl. Process only ""-style includes and recursively paste the contents of these files. Should be a twenty-liner.
If not, you have to write one up yourself or try at random. Automatic dependency tracking in C++ is hard. Like in "let's see if this template instantiation causes an implicit instantiation of the argument class" hard. The only automated way I see is to shuffle your include files into a random order, see if the whole bunch compiles, and re-shuffle them until it compiles. Which will take n! time, you might be better off writing that include file by hand.
While the first variant is easy enough to hack, I doubt the sensibility of this hack, because you want to distribute on a package level (source tarball, deb package, Windows installer) instead of a file level.
You really need a build script to generate this as you work, and a preprocessor flag to disable use of the amalgamate (that could be for your uses).
To simplify this script/program, it helps to have your header structures and include hygiene in top form.
Your program/script will need to know your discovery paths (hint: minimise the count of search paths to one if possible).
Run the script or program (which you create) to replace include directives with header file contents.
Assuming your headers are all guarded as is typical, you can keep track of what files you have already physically included and perform no action if there is another request to include them. If a header is not found, leave it as-is (as an include directive) -- this is required for system/third party headers -- unless you use a separate header for external includes (which is not at all a bad idea).
It's good to have a build phase/translation that includes header alone and produces zero warnings or errors (warnings as errors).
Alternatively, you can create a special distribution repository so they never need to do more than pull from it occasionally.
What you want to do sounds "javascriptish" to me :-) . But if you insist, there is always "cat" (or the equivalent in Windows):
$ cat file1.h file2.h file3.h > my_big_file.h
Or if you are using gcc, create a file my_decent_lib_header.h with the following contents:
#include "file1.h"
#include "file2.h"
#include "file3.h"
and then use
$ gcc -C -E my_decent_lib_header.h -o my_big_file.h
and this way you even get file/line directives that will refer to the original files (although that can be disabled, if you wish).
As for how automatic is this for your file order, well, it is not at all; you have to decide the order yourself. In fact, I would be surprised to hear that a tool that orders header dependencies correctly in all cases for C/C++ can be built.
usually you don't want to include every bit of information from all your headers into the special header that enables the potential user to actually use your library. The non-trivial removal of type definitions, further includes or defines, that are not necessary for the user of your interface to know can not be automatedly done. As far as I know.
Short answer to your main question:
No.
My suggestions:
manually make a new header, that contains all relevant information (nothing more, nothing less) for the user of your library interface. Add nice documentation comments for each component it contains.
use forward declarations where possible, instead of full-fledged included definitions. Put the actual includes in your implementation files. The less include statements you have in your headers, the better.
don't build a deeply nested hierarchy of includes. This makes it extremely hard to keep an overview on the contents of every bit you include. The user of your library will look into the header to learn how to use it. And he will probably not be able to distinguish relevant code from irrelevant on the first sight. You want to maximize the ratio of relevant code per total code in the main header for your library.
EDIT
If you really do have a toolkit library, and the order of inclusion really does not matter, and you have a bunch of independent headers, that you want to enumerate just for convenience into a single header, then you can use a simple script. Like the following Python (untested):
import glob
with open("convenience_header.h", 'w') as f:
for header in glob.glob("*.h"):
f.write("#include \"%s\"\n" % header)
I need to submit an assignment, but I only want to include the header files from boost that I actually used (I made use of boost::shared_ptr and boost::function). I tried doing so manually, but I'm missing some header files and everytime i go to add them, it turns out I'm missing more. Is there a quick easy way to find out exactly what headers I actually need?
Thanks
The bcp command is made for this:
NAME
bcp - extract subsets of Boost
SYNOPSIS
bcp --list [options] module-list
bcp [options] module-list output-path
bcp --report [options] module-list html-file
bcp --help
DESCRIPTION
Copies all the files, including dependencies, found in module-list to
output-path. output-path must be an existing path.
But you will probably be surprised to see just how interdependent these Boost headers are.
There is a tool called bcp to do exactly that -- copy out the parts of Boost you need and no more.
There is actually another solution to your issue: the preprocessor.
The compiler you use should have a switch to only run the preprocessor: -E on gcc and clang. Given this, you can preprocess the two files you include, and stash the result of this run into a header file (each) of your own.
Add header guards, include the already preprocessed headers in lieu of the regular boost headers, and you're done.
Of course there might be some repetition between the two headers, a diff tool could potentially help you spotting it and factoring it in another common header... but for an assignment I would certainly not bother.
You might also consider telling your teacher that as he does not ask you to provide the standard library headers you compiled with, he should not be asking for the boost headers you used.