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

Code before:

/**
 * # CategoryDLOpenNotes
 *
 * This header allows you to annotate your code so external tools know about
 * optional shared library dependencies.
 *
 * You can specify optional dependencies like this:
 *
 * ```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:
 *
 * ```
 *  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
#define SDL_dlopennote_h

#define SDL_ELF_NOTE_DLOPEN_PRIORITY_REQUIRED    "required"
#define SDL_ELF_NOTE_DLOPEN_PRIORITY_RECOMMENDED "recommended"
#define SDL_ELF_NOTE_DLOPEN_PRIORITY_SUGGESTED   "suggested"

#if defined(__ELF__) && !defined(SDL_DISABLE_DLOPEN_NOTES)


Review comment (suggestion):
If this turns out problematic, we can do this test in `SDL3Config.cmake` and add this flag automatically.

Code after:

/* 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
#define SDL_dlopennote_h

/**
 * Use this macro with SDL_ELF_NOTE_DLOPEN() to note that a dynamic shared library dependency is optional.
 *
 * Optional functionality uses the dependency, the binary will work and the dependency is only needed for full-featured installations.
 *
 * \since This macro is available since SDL 3.4.0.
 *
 * \sa SDL_ELF_NOTE_DLOPEN
 * \sa SDL_ELF_NOTE_DLOPEN_PRIORITY_RECOMMENDED
 * \sa SDL_ELF_NOTE_DLOPEN_PRIORITY_REQUIRED
 */
#define SDL_ELF_NOTE_DLOPEN_PRIORITY_SUGGESTED   "suggested"

/**
 * Use this macro with SDL_ELF_NOTE_DLOPEN() to note that a dynamic shared library dependency is recommended.
 *