The compiling stage is where we use a modified version of GCC in order to generate information that can be used by EDoc++. The EDoc++ GCC Modification generates EDoc++ data files and can optionally place that data in one of a few places:
Next to source file : g++ -fedoc-source ... OR export EDOC_SOURCE=yes; g++ ...
If compiling a file like:
will create data in:
In a specified directory : g++ -fedoc-dir=/some/dir ... OR export EDOC_DIR=/some/dir; g++ ...
If directory is set to
foo/bar/baz.cpp will place data
In user specified file : g++ -fedoc-file=/some/foo/bar/baz.edc OR export EDOC_FILE=/some/foo/bar/baz.edc; g++ ...
Will place data in file specified.
Embedded into compiled binary file : g++ -fedoc-embed ... OR export EDOC_EMBED=yes; g++ ...
Will embed EDoc++ data into the compiled binary. This will place the EDoc++ data files into the binary in a .edoc binary file section. This data can be extracted using libbfd. This functionality should be available in the edoc application.
Of the above options, there are two ways to inform the modified
GCC where to place the data. The first is to provide a command line
-fedoc-embed, the second is to provide an
environment variable like
EDOC_EMBED=yes. Using the
environment variable may seem a little strance but can be a very
convenient method for building existing projects with EDoc++ information
embedded into the binaries without having to modify the projects build
The GCC modification can generate EDoc++ data into two formats:
Binary EDC file : g++ -fedoc-format=binary ... OR export EDOC_FORMAT=binary; g++ ...
Text EDC file : g++ -fedoc-format=text ... OR export EDOC_FORMAT=text; g++
By default it will generate binary data. This is fastest and significantly smaller in size than the text format however the text format is very useful for debugging problems and is mostly used by EDoc++ maintainers.
So now we can generate some data to be analysed. So lets generate some edoc information for our example program.
g++ -fedoc-source -c main.cpp -o main.o g++ -fedoc-source -c extra.cpp -o extra.o g++ main.o extra.o -o simple
OR the equivalent
export EDOC_SOURCE=yes g++ -c main.cpp -o main.o g++ -c extra.cpp -o extra.o g++ main.o extra.o -o simple
This will create the executable:
simple and the EDoc++ data files:
extra.cpp.edc that can be used by the edoc
Usually when analysing a complete projects source code with
EDoc++, you will compile the source of the project as per normal but
using the modified GCC and first setting one of the environment
variables. I have found the
EDOC_EMBED=yes to be the most
useful as you can then run the edoc application over the resulting
binaries whether they be an application or a library and should have all
the necessary data for that binary embedded into it.