SDL main docs don't explain how to best manage the main function from non-C languages

[castholm]

Extracted from #12676, #14502 (comment)

It's not currently clear how users who can't use SDL_main.h (e.g. because they are using a language other than C/C++), and instead need to provide their own entry points, are supposed to handle the main function. They might want SDL to initialize platform-specifics, or hook into SDL's main callback system. The docs only mention SDL_SetMainReady() and SDL_RunApp() in passing, but it's not clear which one is best.

From my own experience using SDL outside of C, I believe the best and most portable practice is to call SDL_RunApp() from your native main function with a callback function that in turn calls SDL_EnterAppMainCallbacks().

// native main function
int main(int argc, char *argv[]) {
    return SDL_RunApp(argc, argv, myMain);
}

// SDL_RunApp callback (declared with a C calling convention)
int SDLCALL myMain(int argc, char *argv[])
{
    return SDL_EnterAppMainCallbacks(argc, argv, myAppInit, myAppIterate, myAppEvent, myAppQuit);
}

// ... declare SDL_AppInit/Iterate/Event/Quit callbacks ...

Using main callbacks is optional, but recommended to avoid needing to write platform-specific code for e.g. Emscripten.

This should work for most platforms. However, on Android you would need to export a function equivalent to myMain above with the symbol name SDL_main, which should be mentioned as a special case.

SDL_SetMainReady() should only be used as a last resort, if the user really can't/doesn't want to use SDL_RunApp(). By not using SDL_RunApp(), you are left entirely to your own devices and need to initialize platform specific details yourself.

Not letting SDL_main.h redefine the main function is an advanced use case, so I don't think this needs to be mentioned upfront in e.g. tutorials or examples. But having this kind of information somewhere in https://wiki.libsdl.org/SDL3/CategoryMain and/or https://wiki.libsdl.org/SDL3/README-main-functions would be great, especially for library authors developing SDL bindings for different languages.

[slouken]

This makes sense. @icculus, is this documentation we can add for the 3.4 release?

[icculus]

Yes.

[icculus]

This paragraph on the wiki ...

If you have never controlled your process's entry point (you are using SDL
as a module from a general-purpose scripting language interpreter, or you're
using SDL in a plugin for some otherwise-unrelated app), then there is nothing
required of you here; there is no startup code in SDL's entry point code that
is required, so using SDL_main.h is completely optional. Just start using
the SDL API when you are ready.

This isn't true, though, is it? Don't they need to call SDL_SetMainReady in this case, or something? Not as a question of SDL_main-vs-SDL_RunApp, but when main() has already happened before the SDL shared library is even loaded.

[edwood-grant]

I'd like to add my two cents, since I'm doing the Vala bindings for SDL3, these are the ways I've solved these cases for these specific bindings with main. ]The names are different to keep Vala code style, but they should do the same thing.

1. Running a different main function. I use SDL_RunApp for this case, just translates the main to another function and that's it.:

using SDL;

public int main (string[] args) {
    SDL.Main.run_app (args, main_func, null);
    return 0;
}

public int main_func (string[] args) {
    // Main func stuff here. You 'could' setup callbacks if you want here though, but I find it odd)
    return 0;
}

2. Handling callbacks via main. I setup the main callback first via SDL_EnterAppMainCallbacks, and then invoke SDL_SetMainReady. The callbacks start working on their own:

using SDL;

public static int main (string[] args) {
    SDL.Main.enter_app_main_callbacks (args, init_function, iterate_function, event_function, quit_function);
    SDL.Main.set_main_ready ();
    return 0;
}

static SDL.Init.AppResult init_function (out void* app_state, string[] args) {
    // code here
}

static SDL.Init.AppResult iterate_function (void* app_state) {
    // code here
}

static SDL.Init.AppResult event_function (void* app_state, SDL.Events.Event event) {
    // code here
}

static void quit_function (void* app_state, SDL.Init.AppResult result) {
    // code here
}

3. Implement the callbacks directly and let main do its thing. I won't show code or dwell to much on this because there is a very specific Vala way to recreate the normal callback setup commonly used in SDL3 like, for instance, the SDL3 examples, and its not pertinent to this discussion for other bindings.

But anyway, in my case, running 1. and 2. in Vala seem to work OK, but is that the correct way to implement it? I mention this, because it seems that I'm kinda doing the opposite of what @castholm is doing here in both scenarios (and I am using SDL_SetMainReady to ensure callbacks start running in 2.). Its likely that I'm not understanding something here.

So, in short, it would be good to have a definite answer on the best procedure to implement callback when you cannot implement the callbacks directly in a binding.

[maia-s]

In sdl3-main, an addon to the Rust bindings to use SDL_main/callbacks, I always go via SDL_RunApp first. If the callbacks api is enabled I call SDL_EnterAppMainCallbacks from the function passed to that. I don't call SDL_SetMainReady in either case since the docs for SDL_RunApp says you don't need that when using that.

[castholm]

But anyway, in my case, running 1. and 2. in Vala seem to work OK, but is that the correct way to implement it?

I would personally advice against 2 or 3. SDL_RunApp() is where SDL initializes platform-specific details, for example initializing the gaming runtime, the global task queues and Xbox Live for GDK. By not going through SDL_RunApp() you miss out on this, and your app might not work on all platforms unless you replicate the same required work yourself. SDL_SetMainReady() doesn't initialize anything, all it does is disable an internal safeguard that would cause SDL_Init() to fail on platforms that require special care (specifically, those that define SDL_MAIN_NEEDED.

If you only care about simpler platforms like Linux or Windows you don't need to call SDL_RunApp(), it won't make any meaningful difference in practice. But presumably if you're making a library/bindings you want to maximize portability and have it work on all platforms.

[edwood-grant]

@maia-s @castholm Fair enough, thanks for the recommendations, I certainly need to read the docs again to fully understand. But yeah, in any case, any extra docs explaining these details for binding would be pretty useful to have for others.