When EDoc++ data has been generated it is usually in a number of
different *.edc
Note: The above statement also applies to EDoc++ data files that are embedded into binaries.
So we have a number of EDoc++ data files where each represents a translation unit of code. This is the same as object files that are produced by the g++ compiler, and then they are all linked together. We must also "link together" all EDoc++ data files. This process is known as merging the data files.
EDoc++ data files are merged together automatically by the edoc application when multiple EDoc++ data files are provided on the command line for the edoc application. So merging can be done at the same time as the Output Stage. However we will demonstrate them as separate stages here for clarity.
Continuing our example from above we will merge:
main.cpp.edc and extra.cpp.edc
to create a merged EDoc++ data file:
simple.edc
edoc -d1 main.cpp.edc extra.cpp.edc --merged-output simple.edc
Note: The -d1 informs the edoc application to enter debug/verbose mode 1 which will display the input and output file names that it is processing.
This will produce an output like:
edoc -d1 main.cpp.edc extra.cpp.edc --merged-output simple.edc Loading edc file: main.cpp.edc... Loading edc file: extra.cpp.edc... Writing merged data to output file: simple.edc...
It is also possible to provide "archives" of EDoc++ data files on the edoc command line. An archive is considered a file system element that contains one or more EDoc++ data files. There are currently two supported archive types:
Directory
The Directory archive type will extract all EDoc++ data files that exist within a provided directory or its subdirs. This is helpful if you have a directory full of .edc files that may have been generated using: g++ --fedoc-dir=/some/dir
Binary File
This archive type will extract all .edc files that may have been embedded into a binary object, library or executable file. This is one of the most useful archives. Generally EDoc++ data will be placed into a binary file archive when generating data using: g++ -fedoc-embed
To show an example of this we will recompile the "simple" example this time using embedded data files so that the application binary file: "simple" will be used as an EDoc++ data archive. This is possible using libbfd which will store arbitrary data into a binary file which is what is done when embedding EDoc++ data into a binary. See the following steps:
Note: Ignore the --disable-auto-import flag below for the moment, it is just there to simplify the output for this example by telling EDoc++ not to search for additional EDoc++ data files automatically (For libraries like libc or libstdc++).
g++ -fedoc-embed main.cpp extra.cpp -o simple edoc --disable-auto-import -d1 simple --merged-output simple.edc Loading edc file: simple:../../../gcc-4.0.4/gcc/crtstuff.c.edc... Loading edc file: simple:main.cpp.edc... Loading edc file: simple:extra.cpp.edc... Loading edc file: simple:../../../gcc-4.0.4/gcc/crtstuff.c.edc... Writing merged data to output file: simple.edc...