Running CppTool

After compiling CppTool you will have an executable application that will extract all declarations from a C or C++ project.

There are two ways to use the CppTool executable, but both tools support the argument -out <data_out_dir>, which sets the output directory for the data files. It defaults to data_out.

It should be noted that CppTool functions like a compiler and will reject broken or uncompilable code.

##Compilation database

If the project that needs to be inspected uses the CMake build system and the environment supports UNIX makefiles, it is possible to use CMake's Compilation Database feature to automatically determine how each file needs to be compiled.

Generate the UNIX makefile target for the chosen project, but enable the option CMAKE_EXPORT_COMPILE_COMMANDS. This will create a compile_commands.json file in the root of the build directory. Then proceed to compile the project so any generated files are present.

When using this method there are two arguments that you can provide to CppTool:

• -p <cmake_build_dir> which sets the build directory, defaults to the current directory and needs to be properly set to correctly discover the compile_commands.json file.
• -extra-arg="<arg>" specify an additional compilation argument that needs to be provided to Clang for every compilation, useful to specify missing include directories.

Execute CppTool with the following command: <CppToolExe> [args] <files...>

This will run the internal Clang compiler on each of the given files based on the configuration stored in the compilation database, it will then export all relevant declarations to a uniquely named file in the selected output directory.

When using this approach on OSX, it is likely that there will be errors due to missing system headers. Because the normal clang compiler is specialized by Apple it assumes come includes that are not normally enabled for clang.

To fix these errors, add the following -extra-arg arguments to the invocation:

-extra-arg=-I/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/include/c++/v1/ -extra-arg=-I/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/lib/clang/6.0/include

• Paths might differ based on the version of OSX that is being used, these paths are for OSX 10.10, Xcode 6.2

##Manual invocation

If the compilation database is not available it is possible to invoke CppTool like a compiler.

By executing CppTool with the following syntax: <CppToolExe> <files...> -- <compiler args> it will compile all the given files using the given compiler arguments. See Clang's User Manual for a full guide on the options.