CODEWITHSUNDEEP
clangdoxygen
Galaxy
Galaxy

Reputation: 2481

If I provide CLANG_DATABASE_PATH in Doxyfile do I still have to provide INPUT and INCLUDE_PATH?

I am using Doxygen for documentation of my project. I have a compile_commands.json file describing the source code of my project inside the directory C:\dev\project_dir. I set the following variables:

CLANG_ASSISTED_PARSING = YES
CLANG_DATABASE_PATH    = C:\dev\project_dir

So how does this work? Do I also have to set the variables INPUT and INCLUDE_PATH? It seems that all the files and the instructions to compile them, including where to get header files from, are written in the compilation database.

And if I do have to set the variables INPUT and INCLUDE_PATH also, what should I set them to? The compilation database lists the source and header files of the project, which are scattered among multiple different directories. How should I proceed in this situation.

Upvotes: 2

Views: 1273

Answers (1)

Galaxy
Galaxy

Reputation: 2481

I found the answer.

So I set the following variables in the Doxyfile.

CLANG_ASSISTED_PARSING = YES
CLANG_DATABASE_PATH    = C:\dev\project_dir

And I set the following variables as blank:

INPUT =
INCLUDE_PATH =

INPUT specifies the paths to source code *.c *.cpp files and/or directories to be processed. INCLUDE_PATH specifies the paths to header code *.h *.hpp files and/or directories to be processed.

The CLANG_ASSISTED_PARSING = YES enables using clang compiler as the parser instead of the default doxygen parser. So if INPUT and INCLUDE_PATH are not set, then it gets the source code files and header code files from the compilation database itself. The CLANG_DATABASE_PATH specifies the directory in which the compilation database is stored. It grabs the file named compile_commands.json by default from that directory, implying that the name of the compilation database is fixed. If you name your compilation database JSON file anything else other than compile_commands.json doxygen won't be able to find it.

So if a clang compilation database JSON file is used all the *.c *.cpp files that are being compiled are placed in the INPUT. And all the header code files are placed in the INCLUDE_PATH. The clang used by doxygen parses the JSON, and every time it encounters a -I compiler flag it recognizes that file as a header file, adding it to the INCLUDE_PATH. This means that setting INPUT and INCLUDE_PATH are not mandatory. So if the compilation database is properly formatted, and all the header files are explicitly marked with the -I, only setting the CLANG_DATABASE_PATH is sufficient.

But there is a certain situation when the INCLUDE_PATH also needs to be set explicitly. For example if you have a source code file, which includes a header file, which includes another header file inside of it.

first.h

int one(int);

second.h

#include "first.h"
int two(int);

code.cpp

#include "second.h"

int main(void) {}

And the command in the compilation database is such:

clang -I path/to/second.h -c code.cpp

So in this case doxygen would read that file, and it would internally set the following variables as such:

INPUT = code.cpp
INCLUDE_PATH = path/to/second.h

This means that although doxygen will index second.h, it will miss first.h since that header file isn't explicitly provided in the -I compilation database. That would be an error. So we need to list it explicitly in the doxyfile, an an additional include path.

INPUT =
INCLUDE_PATH = path\to\first.h

CLANG_ASSISTED_PARSING = YES
CLANG_DATABASE_PATH    = C:\dev\project_dir

Upvotes: 2

Related Questions