[Tracker] Heaviest contributors to compile time

Pick one header from the top-100 list in the issue (start with a lower-cost one like include/godot_cpp/variant/char_utils.hpp rather than core/class_db.hpp), and read its include tree to find includes that can be moved to .cpp files, replaced with forward declarations, or trimmed. Reproduce the numbers by building with clang --ftime-trace and the linked clang-project-profiler tool, then re-measure. Done when the project still builds and tests pass with a measurably lower fresh compile cost for that header; note gen/ entries are generated and must be fixed in the generator, not by hand.

• Analog to https://github.com/godotengine/godot/issues/111218

I used my clang-project-profiler to gather information on the strongest contributors to compile time.

Workaround

If you're just looking to decrease your personal compile time during development, use build profiles. At the time of writing, there is unfortunately no documentation for this feature, but it should cut most extensions' compile time by ~80%.

If you're looking to help decrease the compile time for everyone, keep reading.

Methodology

To most effectively reduce the amount of cross includes between our headers, we need metrics. I came up with two:

• Fresh compile cost: An estimation of the from-scratch compile time caused the header. It is calculated from adding self time across all compile units' time traces, and partial responsibility over includees.
  • Optimizing this is useful for all contributors, and anyone else compiling godot-cpp.
• Recompile cost: An estimation of the potential of each file to cause recompiles. It is calculated from self time across all compile units' time traces, weighed by its size (to estimate churn potential), and partial responsibility over includees.
  • Optimizing this is useful for regular contributors and CI. In the case of godot-cpp, probably not critical.

Both are mainly based on clang --ftime-trace and include trees (while the second one also uses file size to estimate churn potential). I've consolidated my efforts into a public tool:

https://github.com/Ivorforce/clang-project-profiler

Tracker

Below is the top 100 list of headers that should be investigated..

Please remember that not all of these files can be 'fixed'. Also, note that this list was gathered on macOS. On other systems, libcpp entries will evaluate differently.

These numbers are based on https://github.com/godotengine/godot-cpp-template. Other projects will measure differently.

last update: 2026-10-07

Fresh compile cost

godot-cpp/include/godot_cpp/core/class_db.hpp: 131s
godot-cpp/include/godot_cpp/core/binder_common.hpp: 92s
godot-cpp/gen/include/godot_cpp/variant/builtin_types.hpp: 78s
godot-cpp/include/godot_cpp/variant/variant.hpp: 75s
godot-cpp/include/godot_cpp/core/object.hpp: 74s
godot-cpp/include/godot_cpp/core/engine_ptrcall.hpp: 55s
godot-cpp/gen/include/godot_cpp/classes/object.hpp: 45s
godot-cpp/include/godot_cpp/core/type_info.hpp: 42s
godot-cpp/include/godot_cpp/classes/ref.hpp: 36s
godot-cpp/include/godot_cpp/variant/typed_array.hpp: 34s
godot-cpp/include/godot_cpp/core/method_ptrcall.hpp: 32s
godot-cpp/include/godot_cpp/core/method_bind.hpp: 28s
godot-cpp/gen/include/godot_cpp/variant/string.hpp: 25s
godot-cpp/gen/include/godot_cpp/classes/ref_counted.hpp: 24s
godot-cpp/include/godot_cpp/templates/hashfuncs.hpp: 24s
godot-cpp/include/godot_cpp/variant/callable_method_pointer.hpp: 22s
godot-cpp/gen/include/godot_cpp/classes/class_db_singleton.hpp: 22s
godot-cpp/include/godot_cpp/core/property_info.hpp: 20s
godot-cpp/include/godot_cpp/variant/vector3.hpp: 18s
godot-cpp/include/godot_cpp/templates/a_hash_map.hpp: 17s
godot-cpp/gen/include/godot_cpp/classes/global_constants_binds.hpp: 15s
godot-cpp/include/godot_cpp/templates/hash_map.hpp: 15s
godot-cpp/include/godot_cpp/templates/hash_set.hpp: 14s
godot-cpp/include/godot_cpp/variant/char_utils.hpp: 13s
godot-cpp/gen/include/godot_cpp/variant/builtin_binds.hpp: 12s
godot-cpp/include/godot_cpp/variant/char_range.inc.hpp: 12s
godot-cpp/include/godot_cpp/templates/cowdata.hpp: 11s
godot-cpp/include/godot_cpp/classes/wrapped.hpp: 10s
godot-cpp/include/godot_cpp/variant/transform3d.hpp: 10s
godot-cpp/gen/include/godot_cpp/classes/resource.hpp: 9s
godot-cpp/include/godot_cpp/variant/char_string.hpp: 9s
godot-cpp/include/godot_cpp/core/print_string.hpp: 8s
godot-cpp/gen/include/godot_cpp/variant/utility_functions.hpp: 8s
godot-cpp/include/godot_cpp/variant/transform2d.hpp: 7s
godot-cpp/include/godot_cpp/variant/basis.hpp: 7s
godot-cpp/include/godot_cpp/variant/aabb.hpp: 6s
godot-cpp/gen/include/godot_cpp/variant/string_name.hpp: 6s
godot-cpp/gen/include/godot_cpp/classes/canvas_item.hpp: 6s
godot-cpp/include/godot_cpp/core/math.hpp: 6s
godot-cpp/gen/include/godot_cpp/classes/control.hpp: 6s
godot-cpp/include/godot_cpp/variant/plane.hpp: 5s
godot-cpp/include/godot_cpp/templates/vector.hpp: 5s
godot-cpp/include/godot_cpp/variant/quaternion.hpp: 5s
godot-cpp/gen/include/godot_cpp/classes/node.hpp: 5s
godot-cpp/gen/include/godot_cpp/classes/text_server.hpp: 4s
godot-cpp/include/godot_cpp/variant/projection.hpp: 4s
godot-cpp/include/godot_cpp/templates/local_vector.hpp: 4s
godot-cpp/gen/include/godot_cpp/classes/texture2d.hpp: 4s
godot-cpp/include/godot_cpp/variant/rect2.hpp: 3s
godot-cpp/gen/include/godot_cpp/variant/packed_vector3_array.hpp: 3s
godot-cpp/include/godot_cpp/variant/vector2.hpp: 3s
godot-cpp/gen/include/godot_cpp/classes/visual_shader_node.hpp: 3s
godot-cpp/gen/include/godot_cpp/variant/callable.hpp: 3s
godot-cpp/gen/include/godot_cpp/classes/node2d.hpp: 3s
godot-cpp/include/godot_cpp/variant/rect2i.hpp: 3s
godot-cpp/gen/include/godot_cpp/variant/packed_string_array.hpp: 3s
godot-cpp/include/godot_cpp/templates/list.hpp: 3s
godot-cpp/gen/include/godot_cpp/classes/node3d.hpp: 3s
godot-cpp/include/godot_cpp/variant/callable_custom.hpp: 3s
godot-cpp/include/godot_cpp/variant/color.hpp: 2s
godot-cpp/include/godot_cpp/core/memory.hpp: 2s
godot-cpp/gen/include/godot_cpp/classes/container.hpp: 2s
godot-cpp/include/godot_cpp/variant/vector3i.hpp: 2s
godot-cpp/gen/include/godot_cpp/variant/packed_color_array.hpp: 2s
godot-cpp/gen/include/gdextension_interface.h: 2s
godot-cpp/include/godot_cpp/variant/vector4i.hpp: 2s
godot-cpp/include/godot_cpp/variant/vector2i.hpp: 2s
godot-cpp/gen/include/godot_cpp/variant/packed_vector2_array.hpp: 2s
godot-cpp/include/godot_cpp/templates/safe_refcount.hpp: 2s
godot-cpp/include/godot_cpp/variant/vector4.hpp: 2s
godot-cpp/gen/include/godot_cpp/variant/packed_vector4_array.hpp: 1s
godot-cpp/gen/include/godot_cpp/classes/texture.hpp: 1s
godot-cpp/gen/include/godot_cpp/variant/array.hpp: 1s
godot-cpp/include/godot_cpp/godot.hpp: 1s
godot-cpp/gen/include/godot_cpp/classes/image.hpp: 1s
godot-cpp/gen/include/godot_cpp/classes/material.hpp: 1s
godot-cpp/gen/include/godot_cpp/classes/font.hpp: 1s
godot-cpp/gen/include/godot_cpp/core/gdextension_interface_loader.hpp: 1s
godot-cpp/gen/include/godot_cpp/classes/mesh.hpp: 1s
godot-cpp/gen/include/godot_cpp/variant/packed_byte_array.hpp: 1s
godot-cpp/include/godot_cpp/templates/sort_array.hpp: 1s
godot-cpp/gen/include/godot_cpp/variant/builtin_vararg_methods.hpp: 1s
godot-cpp/gen/include/godot_cpp/variant/packed_float32_array.hpp: 1s
godot-cpp/gen/include/godot_cpp/classes/visual_instance3d.hpp: 1s
godot-cpp/include/godot_cpp/templates/span.hpp: 1s
godot-cpp/gen/include/godot_cpp/variant/packed_int64_array.hpp: 1s
godot-cpp/gen/include/godot_cpp/variant/packed_int32_array.hpp: 1s
godot-cpp/include/godot_cpp/core/defs.hpp: 1s
godot-cpp/gen/include/godot_cpp/classes/range.hpp: 1s

Recompile cost

godot-cpp/include/godot_cpp/core/class_db.hpp: 301s
godot-cpp/gen/include/godot_cpp/variant/builtin_types.hpp: 250s
godot-cpp/include/godot_cpp/variant/variant.hpp: 234s
godot-cpp/include/godot_cpp/core/object.hpp: 178s
godot-cpp/include/godot_cpp/core/binder_common.hpp: 133s
godot-cpp/include/godot_cpp/core/engine_ptrcall.hpp: 131s
godot-cpp/gen/include/godot_cpp/variant/string.hpp: 97s
godot-cpp/gen/include/godot_cpp/classes/object.hpp: 80s
godot-cpp/include/godot_cpp/classes/ref.hpp: 80s
godot-cpp/gen/include/gdextension_interface.h: 70s
godot-cpp/include/godot_cpp/templates/hashfuncs.hpp: 62s
godot-cpp/include/godot_cpp/variant/vector3.hpp: 62s
godot-cpp/include/godot_cpp/core/type_info.hpp: 61s
godot-cpp/include/godot_cpp/core/property_info.hpp: 57s
godot-cpp/include/godot_cpp/core/method_ptrcall.hpp: 56s
godot-cpp/include/godot_cpp/templates/a_hash_map.hpp: 54s
godot-cpp/gen/include/godot_cpp/classes/ref_counted.hpp: 51s
godot-cpp/include/godot_cpp/core/method_bind.hpp: 47s
godot-cpp/include/godot_cpp/templates/cowdata.hpp: 44s
godot-cpp/include/godot_cpp/templates/hash_map.hpp: 44s
godot-cpp/include/godot_cpp/templates/hash_set.hpp: 42s
godot-cpp/include/godot_cpp/variant/char_utils.hpp: 41s
godot-cpp/include/godot_cpp/variant/char_string.hpp: 39s
godot-cpp/gen/include/godot_cpp/classes/class_db_singleton.hpp: 39s
godot-cpp/include/godot_cpp/variant/callable_method_pointer.hpp: 38s
godot-cpp/include/godot_cpp/variant/typed_array.hpp: 38s
godot-cpp/include/godot_cpp/variant/char_range.inc.hpp: 38s
godot-cpp/include/godot_cpp/classes/wrapped.hpp: 36s
godot-cpp/include/godot_cpp/godot.hpp: 34s
godot-cpp/include/godot_cpp/core/print_string.hpp: 33s
godot-cpp/gen/include/godot_cpp/variant/string_name.hpp: 32s
godot-cpp/gen/include/godot_cpp/variant/utility_functions.hpp: 31s
godot-cpp/gen/include/godot_cpp/core/gdextension_interface_loader.hpp: 31s
godot-cpp/include/godot_cpp/core/memory.hpp: 30s
godot-cpp/gen/include/godot_cpp/variant/builtin_binds.hpp: 29s
godot-cpp/include/godot_cpp/core/math.hpp: 29s
godot-cpp/include/godot_cpp/variant/transform3d.hpp: 28s
godot-cpp/include/godot_cpp/templates/vector.hpp: 21s
godot-cpp/gen/include/godot_cpp/classes/resource.hpp: 21s
godot-cpp/include/godot_cpp/variant/aabb.hpp: 21s
godot-cpp/include/godot_cpp/templates/local_vector.hpp: 19s
godot-cpp/include/godot_cpp/variant/basis.hpp: 18s
godot-cpp/include/godot_cpp/core/error_macros.hpp: 18s
godot-cpp/include/godot_cpp/variant/plane.hpp: 18s
godot-cpp/include/godot_cpp/variant/transform2d.hpp: 17s
godot-cpp/gen/include/godot_cpp/variant/array.hpp: 17s
godot-cpp/gen/include/godot_cpp/variant/callable.hpp: 17s
godot-cpp/include/godot_cpp/variant/quaternion.hpp: 16s
godot-cpp/include/godot_cpp/templates/list.hpp: 15s
godot-cpp/include/godot_cpp/variant/projection.hpp: 15s
godot-cpp/include/godot_cpp/variant/callable_custom.hpp: 13s
godot-cpp/gen/include/godot_cpp/variant/packed_vector3_array.hpp: 13s
godot-cpp/gen/include/godot_cpp/variant/packed_string_array.hpp: 12s
godot-cpp/include/godot_cpp/variant/vector2.hpp: 12s
godot-cpp/include/godot_cpp/variant/rect2.hpp: 10s
godot-cpp/gen/include/godot_cpp/classes/texture2d.hpp: 9s
godot-cpp/include/godot_cpp/variant/color.hpp: 8s
godot-cpp/include/godot_cpp/core/defs.hpp: 8s
godot-cpp/gen/include/godot_cpp/classes/node.hpp: 8s
godot-cpp/gen/include/godot_cpp/variant/packed_color_array.hpp: 8s
godot-cpp/include/godot_cpp/variant/rect2i.hpp: 7s
godot-cpp/gen/include/godot_cpp/classes/control.hpp: 7s
godot-cpp/gen/include/godot_cpp/classes/visual_shader_node.hpp: 7s
godot-cpp/gen/include/godot_cpp/variant/packed_vector2_array.hpp: 7s
godot-cpp/include/godot_cpp/variant/vector2i.hpp: 7s
godot-cpp/gen/include/godot_cpp/classes/canvas_item.hpp: 7s
godot-cpp/gen/include/godot_cpp/variant/packed_byte_array.hpp: 7s
godot-cpp/include/godot_cpp/variant/vector4i.hpp: 6s
godot-cpp/gen/include/godot_cpp/classes/global_constants.hpp: 6s
godot-cpp/include/godot_cpp/variant/vector4.hpp: 6s
godot-cpp/include/godot_cpp/variant/vector3i.hpp: 6s
godot-cpp/gen/include/godot_cpp/variant/packed_vector4_array.hpp: 6s
godot-cpp/gen/include/godot_cpp/classes/node3d.hpp: 5s
godot-cpp/include/godot_cpp/templates/sort_array.hpp: 5s
godot-cpp/include/godot_cpp/templates/span.hpp: 5s
godot-cpp/gen/include/godot_cpp/classes/node2d.hpp: 4s
godot-cpp/gen/include/godot_cpp/classes/text_server.hpp: 4s
godot-cpp/gen/include/godot_cpp/variant/dictionary.hpp: 4s
godot-cpp/gen/include/godot_cpp/variant/packed_int32_array.hpp: 4s
godot-cpp/gen/include/godot_cpp/variant/packed_float32_array.hpp: 4s
godot-cpp/gen/include/godot_cpp/variant/packed_int64_array.hpp: 4s
godot-cpp/gen/include/godot_cpp/variant/packed_float64_array.hpp: 4s
godot-cpp/gen/include/godot_cpp/classes/texture.hpp: 4s
godot-cpp/include/godot_cpp/templates/safe_refcount.hpp: 3s
godot-cpp/gen/include/godot_cpp/variant/rid.hpp: 3s
godot-cpp/gen/include/godot_cpp/variant/node_path.hpp: 3s
godot-cpp/gen/include/godot_cpp/classes/image.hpp: 3s
godot-cpp/gen/include/godot_cpp/classes/container.hpp: 3s
godot-cpp/include/godot_cpp/core/math_funcs_binary.hpp: 3s
godot-cpp/gen/include/godot_cpp/classes/material.hpp: 3s
godot-cpp/gen/include/godot_cpp/variant/signal.hpp: 2s
godot-cpp/include/godot_cpp/templates/pair.hpp: 2s
godot-cpp/gen/include/godot_cpp/variant/builtin_vararg_methods.hpp: 2s
godot-cpp/include/godot_cpp/templates/sort_list.hpp: 2s
godot-cpp/gen/include/godot_cpp/classes/font.hpp: 2s
godot-cpp/gen/include/godot_cpp/classes/mesh.hpp: 2s
godot-cpp/gen/include/godot_cpp/classes/visual_instance3d.hpp: 2s
godot-cpp/gen/include/godot_cpp/classes/input_event.hpp: 2s
godot-cpp/include/godot_cpp/core/math_defs.hpp: 1s
godot-cpp/include/godot_cpp/core/object_id.hpp: 1s

How to contribute

You can contribute by picking out any of the above files, and investigating its contents, includes, and includers. Some ideas:

• Can any include be removed? Prioritize includees that also appear on the list, otherwise your change might not be impactful.
• Can some includers be changed not to include this file? Prioritize includers that also appear on the list, otherwise your change might not be impactful.
• Can this file be split into independent headers with less contents or includes?

If you believe there's nothing that can be improved about a header, please comment this on this tracker.

If you manage to remove the include, recompile the extension. It is likely that some files will error on compile, because they're missing includes. In small numbers, this is expected. However, if too many files fail to compile, it may be time to reconsider: This may mean that the include was logical after all, and most files that includes the header you were trying to improve also needs to include the other include you removed.

Finally, if you feel comfortable with your changes, submit a PR, and link back to this tracker. With enough of these kinds of PRs, hopefully we can decrease godot-cpp's compile time to a minimum.