Improve docs: Add compile-time options to API documentation

[teruyamato0731]

No description provided.

[teruyamato0731]

@vitaut I'm having trouble with a compilation error in the CI for this PR. I'm not sure how to resolve the build failure on older GCC versions. Could you please take a look when you have a moment?

https://github.com/fmtlib/fmt/actions/runs/18045326166/job/51354577497?pr=4551

[vitaut]

I suggest opting out older gcc from this test, e.g. by checking FMT_GCC_VERSION.

[teruyamato0731]

Thanks for the suggestion, @vitaut!

I tried using FMT_GCC_VERSION to conditionally compile the test, but it seems the root cause of the failure is different.

After taking a closer look at the CI logs, I noticed that the compilation error only occurs in the size-opt-test job, where FMT_BUILTIN_TYPES=0 is defined. In this configuration, it seems that const char* is being treated as a generic pointer rather than a C-style string. This triggers the static_assert that disallows formatting of non-void pointers.

Here is the key part of the error message:

In file included from /workspaces/fmt/include/fmt/format.h:41:0,
                 from /workspaces/fmt/include/fmt/os.h:11,
                 from /workspaces/fmt/src/os.cc:13:
/workspaces/fmt/include/fmt/base.h: In instantiation of ‘fmt::v12::detail::value<Context>::value(const T&) [with T = const char*; typename std::enable_if<(std::is_pointer<T>::value || std::is_member_pointer<T>::value), int>::type <anonymous> = 0; Context = fmt::v12::context]’:
/workspaces/fmt/include/fmt/base.h:2868:57:   required from ‘fmt::v12::remove_cvref_t<T> fmt::v12::format_to(OutputIt&&, fmt::v12::format_string<T ...>, T&& ...) [with OutputIt = fmt::v12::basic_appender<char>&; T = {fmt::v12::basic_string_view<char>&, const char (&)[3]}; typename std::enable_if<fmt::v12::detail::is_output_iterator<typename std::remove_cv<typename std::remove_reference<_From>::type>::type, char>::value, int>::type <anonymous> = 0; fmt::v12::remove_cvref_t<T> = fmt::v12::basic_appender<char>; fmt::v12::format_string<T ...> = fmt::v12::fstring<fmt::v12::basic_string_view<char>&, const char (&)[3]>]’
/workspaces/fmt/include/fmt/format-inl.h:96:56:   required from here
/workspaces/fmt/include/fmt/base.h:2261:5: error: static assertion failed: formatting of non-void pointers is disallowed
     static_assert(sizeof(T) == 0,
     ^
In file included from /workspaces/fmt/include/fmt/format.h:41:0,
                 from /workspaces/fmt/include/fmt/os.h:11,
                 from /workspaces/fmt/test/util.h:13,
                 from /workspaces/fmt/test/util.cc:8:
/workspaces/fmt/include/fmt/base.h: In instantiation of ‘fmt::v12::detail::value<Context>::value(const T&) [with T = const char*; typename std::enable_if<(std::is_pointer<T>::value || std::is_member_pointer<T>::value), int>::type <anonymous> = 0; Context = fmt::v12::context]’:
/workspaces/fmt/include/fmt/base.h:2868:57:   required from ‘fmt::v12::remove_cvref_t<T> fmt::v12::format_to(OutputIt&&, fmt::v12::format_string<T ...>, T&& ...) [with OutputIt = fmt::v12::basic_appender<char>&; T = {fmt::v12::basic_string_view<char>&, const char (&)[3]}; typename std::enable_if<fmt::v12::detail::is_output_iterator<typename std::remove_cv<typename std::remove_reference<_From>::type>::type, char>::value, int>::type <anonymous> = 0; fmt::v12::remove_cvref_t<T> = fmt::v12::basic_appender<char>; fmt::v12::format_string<T ...> = fmt::v12::fstring<fmt::v12::basic_string_view<char>&, const char (&)[3]>]’
/workspaces/fmt/include/fmt/format-inl.h:96:56:   required from here
/workspaces/fmt/include/fmt/base.h:2261:5: error: static assertion failed: formatting of non-void pointers is disallowed
     static_assert(sizeof(T) == 0,
     ^
cc1plus: error: unrecognized command line option "-Wno-dangling-else" [-Werror]
cc1plus: all warnings being treated as errors
cc1plus: error: unrecognized command line option "-Wno-dangling-else" [-Werror]
cc1plus: all warnings being treated as errors
gmake[2]: *** [test/CMakeFiles/size-opt-test.dir/build.make:118: test/CMakeFiles/size-opt-test.dir/util.cc.o] Error 1
gmake[2]: *** Waiting for unfinished jobs....
gmake[2]: *** [test/CMakeFiles/size-opt-test.dir/build.make:132: test/CMakeFiles/size-opt-test.dir/__/src/os.cc.o] Error 1
In file included from /workspaces/fmt/include/fmt/format.h:41:0,
                 from /workspaces/fmt/include/fmt/os.h:11,
                 from /workspaces/fmt/test/gtest-extra.h:15,
                 from /workspaces/fmt/test/gtest-extra.cc:8:
/workspaces/fmt/include/fmt/base.h: In instantiation of ‘fmt::v12::detail::value<Context>::value(const T&) [with T = const char*; typename std::enable_if<(std::is_pointer<T>::value || std::is_member_pointer<T>::value), int>::type <anonymous> = 0; Context = fmt::v12::context]’:
/workspaces/fmt/include/fmt/base.h:2868:57:   required from ‘fmt::v12::remove_cvref_t<T> fmt::v12::format_to(OutputIt&&, fmt::v12::format_string<T ...>, T&& ...) [with OutputIt = fmt::v12::basic_appender<char>&; T = {fmt::v12::basic_string_view<char>&, const char (&)[3]}; typename std::enable_if<fmt::v12::detail::is_output_iterator<typename std::remove_cv<typename std::remove_reference<_From>::type>::type, char>::value, int>::type <anonymous> = 0; fmt::v12::remove_cvref_t<T> = fmt::v12::basic_appender<char>; fmt::v12::format_string<T ...> = fmt::v12::fstring<fmt::v12::basic_string_view<char>&, const char (&)[3]>]’
/workspaces/fmt/include/fmt/format-inl.h:96:56:   required from here
/workspaces/fmt/include/fmt/base.h:2261:5: error: static assertion failed: formatting of non-void pointers is disallowed
     static_assert(sizeof(T) == 0,
     ^
cc1plus: error: unrecognized command line option "-Wno-dangling-else" [-Werror]
cc1plus: all warnings being treated as errors
gmake[2]: *** [test/CMakeFiles/size-opt-test.dir/build.make:104: test/CMakeFiles/size-opt-test.dir/gtest-extra.cc.o] Error 1
gmake[1]: *** [CMakeFiles/Makefile2:876: test/CMakeFiles/size-opt-test.dir/all] Error 2
gmake: *** [Makefile:166: all] Error 2

The full log is quite long, but this seems to be the core issue.

I'm not familiar with the implications of FMT_BUILTIN_TYPES=0 and how it affects string handling. Do you have any advice on how to properly fix this for this specific build configuration?

[vitaut]

It's not super clear to me from the error message where the string argument comes from and I wasn't able to repro the issue in https://www.godbolt.org/z/jqaEz1vP7. Do you have a godbolt example that demonstrates the error? Also I would recommend splitting test changes into a separate PR and just focus on docs in this one.

[vitaut]

Merged, thank you!

[teruyamato0731]

My pleasure.