add a way to reuse Nuklear configuration across multiple source files

[sleeptightAnsiC]

Problems:

• Nuklear is configured with macro defines. If you're including it inside of multiple source files, you need to ensure that config stays the same across all of them.
• If you change any macro define, you should recompile whole Nuklear and all files using it just to be sure. If macro defines come from command line, it complicates this process a lot, even with proper incremental build system.
• Nuklear may depend on some specific header coming from other library (e.g. <SDL3/SDL.h> in case you want to reuse SDL's types) and ensuring that this header is available everywhere is complicated
• clangd (LSP) and other static analysis tools can get quite confused when predefines are coming indirectly from source file (see my comment below)
• Currently, if you want those problems solved, you need all kinds of hacks to make it behave correctly, either in build recipe or somewhere in Nuklear.
• I've created a kicka$$ config for demo/sdl3_renderer, which lets you build this demo on multiple platforms, but due to mentioned limitations, it must live in the main file here, which makes it quite awkward to copy and reuse in your own code (example)
• demos with similar backends could reuse the same configuration code, which is currently impossible

I thought about all of these for quite some time, and the solution that I use in my personal branch looks like this. Somewhere at the very top of src/Nuklear.h :

/*
 * Useful when you have a lot of stuff that you want to overwrite
 * Create "nk_config.h" file somewhere and make sure that preprocessor can find it
 * For example, use following compiler flags: -I/path/to/config/dir -DNK_CONFIG
 */
#ifdef NK_CONFIG
  #include "nk_config.h"
#endif

^ This works very well for my build system (custom GNU Make recipe), and I'm pretty sure it should work with everything else too. I've seen this trick used throughout many C libraries. Every private file in Nuklear is including this thing so it solves the problem. We should probably ensure that src/nuklear_internal.h also includes it, and maybe add our own include guards just to make sure, but those are just details that I'll figure out.

If you clicked at the link to the branch from above, you would also notice that I already tried a different solution:

#ifdef NK_CONFIG_FILE
  #include NK_CONFIG_FILE
#endif

^ but this one is impossible to support portably. MSVC does not support this trick to this very day, and trying to support it would require additional macro. I also noticed that passing paths into macro defines at command line (e.g. -Dmacro=/my/path) is very error prone (expansion works differently between compilers and shell types) and so I abandoned this idea entirely. (but we can also add it later, I guess)

Any thoughts ?

[RobLoach]

I'd be fine with this. Could also ease some of the demo code too.

[sleeptightAnsiC]

I'm still having some concerns about this. I'm afraid that people compiling the demos for the very first time might be a bit confused. Also the fact that it looks for exactly "nk_config.h" could cause some problems. EDIT: see #886 (comment)

I've seen few PRs related to CMake and some other build systems. Maybe I should tag few people involved in those, as they could be affected by this feature in some way or another.

Hmn....

[sleeptightAnsiC]

Potentially related to:

• Converting examples/demos to CMake #524
• Main makefile to perform the needed steps for each change. #101
• pls add cmake support #731
• Add CMake scripts to D3D11/D3D12 demos #808
• CMake and CPack integration (removing Python dependency in the process) #462

Tagging anyone who might be affected by this change in some way: @learn-more @trexxet @Xeverous @ModulePillow @chaoticbob @SamuelMarks @riri (sorry for of a bit of spam, feel free to ignore this one, I just looked through all those PRs and Issues, and thought you might be interested)

What do you guys think? Usually, it's up to the build system to handle configuration, so I think this feature would be beneficial for Cmake recipes (and any other build system really). Do you think this approach will be enough? maybe there is something wrong about it?

[Xeverous]

My thoughts:

• The "use the same defines for every file" is a contract of the library. It is the user's responsibility to ensure consistency. I don't see a big problem in it - any reasonable build system should be able to apply the same flags for every file. If not, Nuklear can recommend every descendant project to have their own "Nuklear config header" that contains required macros and then includes Nuklear - such project would then use Nuklear only through this config header (this approach would be recommended, not required).
• #include NK_CONFIG_FILE - this approach is actually used by Freetype library (#include <ft2build.h> #include FT_FREETYPE_H). As for MSVC - well, this is the Internet Explorer of compilers on many issues. They just finally added proper __cplusplus definition (no longer always-1998) and ISO-compliant printf few years ago. Their assert still remains non-compliant. Don't expect anything here. Boost (C++ std beta code and other highly respected projects) uses MSVC-specific ifdefs for them specifically because MSVC preprocessor can't work normally like anything else. In short, if you go for any particular solution and MSVC has a problem with it, ifdef it for MSVC and implement it the way Microslop intended.
• "clangd (LSP) and other static analysis tools can get quite confused" - I use clangd and have no problems with it. It correctly recognizes Nuklear code and even Freetype's weird include. No missing symbols and no warnings. No custom .clangd required.

So in short, I think this is a non-issue because:

• library uses should be able to ensure consistency through their own build system
• if not, they can always make the "config header" themselves and never include Nuklear directly

I'm fine if this issue ends in doing absolutely nothing.

[sleeptightAnsiC]

Nuklear can recommend every descendant project to have their own "Nuklear config header" that contains required macros and then includes Nuklear

This works well, if you're using Nuklear as single-header-lib amalgamation but, if you're using it by building directly from ./src/nk_*.c, this will not work because those sources will still look for default nuklear.h. (I actually tried this approach in the past)

We also need something for our demos to be able to reuse the config across multiple files. This was the primary reason for reporting this (#884 (comment)). I don't believe we could use that trick here (?)

I'm fine if this issue ends in doing absolutely nothing.

okey...? 👀

EDIT:

I use clangd and have no problems with it. It correctly recognizes Nuklear code and even Freetype's weird include.

It does recognize the symbols, and all kinds of workflows related to you application are fine, the problem becomes when you inspect internals. It won't recognize the correct processor paths there as those depend on predefs indirectly coming from a different file. Your trick is probably also affected by this.

[learn-more]

The idea seems nice, but I would suggest a slightly different name:
nk_user_config.h or something along those lines, to better indicate that it is a user customizable header.

• Nuklear is configured with macro defines. If you're including it inside of multiple source files, you need to ensure that config stays the same across all of them.
• If you change any macro define, you should recompile whole Nuklear and all files using it. If you're using an incremental build system, you may have a problem to detect those changes and all files affected by it.

msvc has a pragma to detect mismatched macro defines, maybe that could help in at least detecting these issues?
https://learn.microsoft.com/en-us/cpp/preprocessor/detect-mismatch?view=msvc-170

[trexxet]

• Nuklear is configured with macro defines. If you're including it inside of multiple source files, you need to ensure that config stays the same across all of them.

In my old project, I just moved all of that into a separate include and used it instead of nuklear.h:

#pragma once
#define NK_INCLUDE_FIXED_TYPES
#define NK_INCLUDE_DEFAULT_ALLOCATOR
#define NK_INCLUDE_STANDARD_IO
#define NK_INCLUDE_STANDARD_VARARGS
#define NK_INCLUDE_VERTEX_BUFFER_OUTPUT
#define NK_INCLUDE_FONT_BAKING
#define NK_INCLUDE_DEFAULT_FONT
#include "lib/nuklear/nuklear.h"
#include "lib/nuklear/nuklear_sdl_gl3.h"
#define MAX_VERTEX_MEMORY 512 * 1024
#define MAX_ELEMENT_MEMORY 128 * 1024

if you're using it by building directly from ./src/nk_*.c

Then you can define these flags in the build system (at least that's easy to do in CMake). Also, what's the purpose of using it directly?

[sleeptightAnsiC]

if you're using it by building directly from ./src/nk_*.c, this will not work

[...] what's the purpose of using it directly?

Guys, don't act like the files under Nuklear/src/ do not exist, please... People prefer to use these for various reasons (see vurtun/nuklear#117 and vurtun/nuklear@f5aa92c) and it's a valid way of building this library. I really don't want the discussion to go off topic.

you can define these flags in the build system (at least that's easy to do in CMake).

Yes, in Cmake it is. This library uses Makefiles for compiling the demos. It's just way easier to inject one config header with one macro define. Every workflow should support this, even the one without build system. If someone doesn't like the config header, they can always take its content and apply it in some different way.

I just moved all of that into a separate include

That seems the same as Xeverous' idea from #886 (comment)

[sleeptightAnsiC]

PR at #955

I'm afraid that people compiling the demos for the very first time might be a bit confused.

I've decided that demos will not use any of this directly. The demo's config (if any) will be split into another header with different name, and demo's main.c will simply include it right before nuklear.h, without any additional tricks.

Only demo/sdl3_renderer has proper config at the moment, which was already inside of main.c, so user had to copy it no matter what.

No one will ever be forced to use config include. It's totally optional.

[sleeptightAnsiC]

clangd (LSP) and other static analysis tools can get quite confused when you use single-header-library with predefines coming indirectly from source file

I use clangd and have no problems with it. It correctly recognizes Nuklear code and even Freetype's weird include. No missing symbols and no warnings.

It does recognize the symbols, and all kinds of workflows related to you application are fine, the problem becomes when you inspect internals.

Just a small proof that this specific limitation of clangd/ccls is old, well known, and documented in many places:

• false diagnostics in include files due to never-firing #ifdefs MaskRay/ccls#115
• Support non-self-contained files clangd/clangd#45
• Use parsed files to improve header compile commands clangd/clangd#123
• Clangd does not resolve include, in spite of correct include path being present in compile command clangd/clangd#147