Project Settings File (.flude.yml)

.flude.yml is a small settings file you keep at the root of your repository. The Flude service reads it when it checks your repository out for a documentation job, so the settings are versioned with the code and are the same whether the job is started from GitHub, GitLab or Bitbucket.

It is not the engine's own ude_doc_config.json (see Target Settings); the service builds that file for you and fills it from .flude.yml and from what the CI job passed.

version: 1

include_dirs: [include, src]
exclude_dirs: [src/generated]
include_patterns: ["**/*.h", "**/*.hpp"]
exclude_patterns: ["**/*_test.h"]
include_paths: [include, third_party/fmt/include]
defines: [MYLIB_STATIC, "MYLIB_API="]
cpp_std: c++20
include_private: false
extract_anon_namespaces: true
exclude_symbols: ["detail::*", "ns::Internal"]

Every key is optional. A missing file is fine: the job runs with the defaults below.

---

Which value wins

For a setting there are three possible sources, in this order:

1. The CI job. A value the job passes (for example the GitHub Action inputs defines and cpp-std, or FLUDE_DEFINES and FLUDE_CPP_STD on GitLab and Bitbucket) wins. "Passed" means non-empty; for include_dirs it also means other than the default ["."].
2. .flude.yml.
3. The default (and, for a few settings, what Flude detects in your repository, see below).

A list is replaced as a whole, never merged: a non-empty CI list hides the same list in the file. include_private is the one boolean that merges: true from the CI job wins, otherwise the file's value, otherwise false.

An explicit value always replaces the automatic one. The clearest case is include_paths: when you do not set it, Flude builds a search list itself (the scanned directories, the repository root, conventional top-level include directories, nested include roots, and directories named in a build file you configured). When you set it, your list is the whole list and nothing is added to it.

---

Rules for the file

• The file is read as YAML, at most 64 KiB, UTF-8. The top level must be a mapping.
• A mistake fails the job instead of being ignored: an unknown key, a wrong type, a bad value. The job status names the key. Supported keys are listed in the message.
• version is optional; the only supported value is 1.
• Paths are relative to the repository root and must stay inside the repository; a path that leaves it (for example with ..) is rejected.
• The file is always read, even when include_dirs does not contain the root.
• language and parser_backend are not file settings: the service needs them before it clones your repository and checks the backend against your account's entitlements. Pass them from the CI job.

---

Keys

Which files are read

Key	Type	Default	Meaning
include_dirs	list of paths	["."]	Directories scanned for source files.
exclude_dirs	list of paths	empty	Directories skipped, including everything below them.
include_patterns	list of globs	["**/*.h"] for C++	Which files inside include_dirs are read.
exclude_patterns	list of globs	empty	Files skipped even when they match include_patterns.

How the C++ code is read (syntactic backend)

These keys are read by the syntactic backend, which is what a C++ job uses unless your account has another backend (see Parser Backends).

Key	Type	Default	Meaning
include_paths	list of paths	detected	Directories the preprocessor searches for #include. Explicit value = the whole list.
defines	list of strings	empty	Macros your build passes with -D: NAME, NAME=VALUE or NAME(args)=VALUE. They select the #if branches that are read. NAME= (empty value) removes an annotation macro such as an export marker. At most 200 entries of at most 512 characters.
cpp_std	string	from CMakeLists.txt, else c++17	The C++ standard #if is evaluated for: c++11, c++14, c++17, c++20 or c++23.
vcxproj_path, vcxproj_configuration, vcxproj_platform	string	none	A Visual Studio project whose macros and include directories are read statically (nothing is built).
bazel_build_path, bazel_target_name	string	none	A Bazel BUILD file and target read the same way.
cmake_lists_path	string	none	A CMakeLists.txt read the same way.

Naming a build file (vcxproj_path, bazel_build_path or cmake_lists_path) also turns on reading the include directories that file declares. What is read and its limits are described in Parser Backends. If your repository has a build file and you do not name it, Flude does not read it for macros or include directories; the only exception is the C++ standard, which is taken from a top-level CMakeLists.txt when cpp_std is not set.

What is shown

Key	Type	Default	Meaning
include_private	boolean	false	Report private members too (Doxygen's EXTRACT_PRIVATE). Without it only public and protected members are reported.
extract_anon_namespaces	boolean	true	false drops an anonymous namespace and everything inside it (Doxygen's EXTRACT_ANON_NSPACES = NO). Read by the syntactic backend only; only the file sets it.
exclude_symbols	list of patterns	empty	Hides entities by qualified name, see below. Read by the syntactic backend only; only the file sets it. At most 200 entries of at most 512 characters, one line each.

A boolean must be true or false; 0, 1 and "false" are rejected.

---

exclude_symbols

A pattern is compared with the fully qualified name of an entity. One rule covers every kind of entity: classes, structs, namespaces, functions, variables, enums, typedefs and using aliases.

• A pattern without * matches the whole name or a suffix that starts after a ::. Secret, Secret::Inner and ns::Secret all match ns::Secret; a bare api hides ns::api and other::api, while ns::api hides only the first.
• * stands for any text, :: included. A pattern with * is compared with the whole name (ns::detail::*).
• Case matters. ? is not supported.
• Hiding a class hides its members, nested classes and enums. Hiding a namespace hides everything inside it, nested namespaces included. Hiding an enum hides its values; a value can also be hidden on its own (ns::Color::Red, or a bare Red for every enum value with that name).
• Class templates: a pattern without < ignores template arguments, so ns::Tmpl hides the general template and every specialisation. A pattern with < is compared as text with spaces ignored: ns::Tmpl<int> hides only that specialisation, ns::Tmpl<* hides every specialisation but not the general template. The comparison is textual, not semantic: unsigned and unsigned int are different texts.

The rules follow Doxygen's EXCLUDE_SYMBOLS and are wider on purpose: Doxygen matches only a bare name for members and ignores a qualified pattern on them.

---

Coming from Doxygen

Doxygen is a reference for the meaning of a setting, not something Flude runs for you. Keys with a Doxygen counterpart mean the same thing, but the defaults differ: Doxygen hides anonymous namespaces unless told otherwise, Flude shows them (extract_anon_namespaces: true).

Doxyfile	.flude.yml
INPUT	include_dirs
EXCLUDE	exclude_dirs
FILE_PATTERNS	include_patterns
EXCLUDE_PATTERNS	exclude_patterns
PREDEFINED	defines
INCLUDE_PATH	include_paths
EXTRACT_PRIVATE	include_private
EXTRACT_ANON_NSPACES	extract_anon_namespaces
EXCLUDE_SYMBOLS	exclude_symbols

You do not have to copy these by hand. The script tools/doxyfile_to_flude.py in the flude-action repository reads a Doxyfile (it never changes it) and prints a .flude.yml block:

python doxyfile_to_flude.py Doxyfile                       # print the block, the report goes to stderr
python doxyfile_to_flude.py Doxyfile --append .flude.yml   # add the block to the file

It needs only Python 3.9 or newer. Settings with no Flude counterpart (EXPAND_AS_DEFINED, EXTRACT_ALL, HIDE_*, graphs, output formats) are listed in its report as "not transferred"; that is not an error. A Doxyfile made by doxygen -g lists every key with its default, so check the result before you commit it: for example it produces extract_anon_namespaces: false.

---

Troubleshooting

• The job fails with .flude.yml: unknown setting(s) ...: a key is mistyped or not supported. The message lists the supported ones.
• A setting in the file seems to be ignored: the CI job passes a value for the same setting, and a passed value wins.
• Macro-generated or conditional entities are missing: set defines and cpp_std to what your build uses, or name your build file; see Parser Backends.
• A file outside the listed directories is needed for #include: list its directory in include_paths. Remember that an explicit include_paths replaces the automatic list, so add the repository root and any other directory you still need.