Repository: libsdl-org/SDL
File: include/SDL3/SDL_dlopennote.h (C/C++)

Code before:
  Copyright (C) 1997-2025 Sam Lantinga <slouken@libsdl.org>

  This software is provided 'as-is', without any express or implied
  warranty.  In no event will the authors be held liable for any damages
  arising from the use of this software.

  Permission is granted to anyone to use this software for any purpose,
  including commercial applications, and to alter it and redistribute it
  freely, subject to the following restrictions:

  1. The origin of this software must not be misrepresented; you must not
     claim that you wrote the original software. If you use this software
     in a product, an acknowledgment in the product documentation would be
     appreciated but is not required.
  2. Altered source versions must be plainly marked as such, and must not be
     misrepresented as being the original software.
  3. This notice may not be removed or altered from any source distribution.
*/

/**
 * # CategoryDLOpenNotes
 *
 * This header allows you to annotate your code so external tools know about
 * (optional) shared library dependencies.
 *
 * You can specify (optional) dependencies by adding the following to the global scope:
 *
 * ```c
 * SDL_ELF_NOTE_DLOPEN(
 *     "png",
 *     "Support for loading PNG images using libpng (required for APNG)",
 *     SDL_ELF_NOTE_DLOPEN_PRIORITY_SUGGESTED,
 *     "libpng12.so.0"
 * );
 * ```
 *
 * If you determine that your toolchain doesn't support dlopen notes, you can
 * disable this feature by defining `SDL_DISABLE_DLOPEN_NOTES`. You can use this
 * CMake snippet to check for support:
 *
 * ```cmake
 *  set(CHECK_ELF_DLNOTES_SRC [==[
 *  #ifndef __ELF__
 *    ELF DL notes is only supported on ELF platforms
 *  #endif
 *  __attribute__ ((used,aligned(4),section(".note.dlopen"))) static const struct {
 *    struct { int a; int b; int c; } hdr; char name[4]; __attribute__((aligned(4))) char json[24];
 *  } dlnote = { { 4, 0x407c0c0aU, 16 }, "FDO", "[\\"a\\":{\\"a\\":\\"1\\",\\"b\\":\\"2\\"}]" };
 *  int main(int argc, char *argv[]) {
 *    return argc + dlnote.hdr.a;
 *  }

Review comment (suggestion):
What's missing in the documentation, and probably should be done in a wordy `#ifdef SDL_WIKI_DOCUMENTATION_SECTION` block is to document that you can specify multiple libraries when you don't know where the function exists (or are flexible). (preferably done by a native English speaker)
e.g.
```c
// Our app supports SDL1, SDL2 and SDL3
SDL_ELF_NOTE_DLOPEN(
    "SDL",
    "Create windows through SDL",
    SDL_ELF_NOTE_DLOPEN_PRIORITY_REQUIRED
    "libSDL-1.2.so.0", "libSDL2-2.0.so.0", "libSDL3.so.0"
);
```
(Maybe a bad example because the symbols of these libraries are incompatible)

Code after:
  Copyright (C) 1997-2025 Sam Lantinga <slouken@libsdl.org>

  This software is provided 'as-is', without any express or implied
  warranty.  In no event will the authors be held liable for any damages
  arising from the use of this software.

  Permission is granted to anyone to use this software for any purpose,
  including commercial applications, and to alter it and redistribute it
  freely, subject to the following restrictions:

  1. The origin of this software must not be misrepresented; you must not
     claim that you wrote the original software. If you use this software
     in a product, an acknowledgment in the product documentation would be
     appreciated but is not required.
  2. Altered source versions must be plainly marked as such, and must not be
     misrepresented as being the original software.
  3. This notice may not be removed or altered from any source distribution.
*/

/* WIKI CATEGORY: DlopenNotes */

/**
 * # CategoryDlopenNotes
 *
 * This header allows you to annotate your code so external tools know about
 * dynamic shared library dependencies.
 *
 * If you determine that your toolchain doesn't support dlopen notes, you can
 * disable this feature by defining `SDL_DISABLE_DLOPEN_NOTES`. You can use this
 * CMake snippet to check for support:
 *
 * ```cmake
 *  set(CHECK_ELF_DLNOTES_SRC [==[
 *  #ifndef __ELF__
 *    ELF DL notes is only supported on ELF platforms
 *  #endif
 *  __attribute__ ((used,aligned(4),section(".note.dlopen"))) static const struct {
 *    struct { int a; int b; int c; } hdr; char name[4]; __attribute__((aligned(4))) char json[24];
 *  } dlnote = { { 4, 0x407c0c0aU, 16 }, "FDO", "[\\"a\\":{\\"a\\":\\"1\\",\\"b\\":\\"2\\"}]" };
 *  int main(int argc, char *argv[]) {
 *    return argc + dlnote.hdr.a;
 *  }
 *  ]==])
 *  check_c_source_compiles("${CHECK_ELF_DLNOTES_SRC}" COMPILER_SUPPORTS_ELFNOTES)
 *  if(NOT COMPILER_SUPPORTS_ELFNOTES)
 *    set(SDL_DISABLE_DLOPEN_NOTES TRUE)
 *  endif()
 * ```
 */

#ifndef SDL_dlopennote_h