Merging Stage

When EDoc++ data has been generated it is usually in a number of different *.edc files. Each separate .edc file as generated by the modified g++ represents a different translation unit that was compiled. So for every object file in a project you will have an associated EDoc++ data file too.

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:

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...