mirror
/
SDL
mirror of https://github.com/libsdl-org/SDL.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

docs: Updated README-emscripten.md. 

This now mentions the main callbacks as a possible option, and removes the
part about prebuilt libraries. The latter can return when Emscripten packages
SDL3.

Fixes #11080.
This commit is contained in:
Ryan C. Gordon 2024-10-21 23:36:56 -04:00
parent c56af0d975
commit b0982e8982
No known key found for this signature in database
GPG Key ID: FA148B892AB48044
1 changed files with 22 additions and 37 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

59
docs/README-emscripten.md
View File

@ -2,7 +2,7 @@
## The state of things ## The state of things
(As of September 2023, but things move quickly and we don't update this (As of October 2024, but things move quickly and we don't update this
document often.) document often.)
In modern times, all the browsers you probably care about (Chrome, Firefox, In modern times, all the browsers you probably care about (Chrome, Firefox,
@ -33,23 +33,15 @@ Many many things just need some simple adjustments and they'll compile
like any other C/C++ code, as long as SDL was handling the platform-specific like any other C/C++ code, as long as SDL was handling the platform-specific
work for your program. work for your program.
First, you probably need this in at least one of your source files: First: assembly language code has to go. Replace it with C. You can even use
```c
#ifdef __EMSCRIPTEN__
#include <emscripten.h>
#endif
```
Second: assembly language code has to go. Replace it with C. You can even use
[x86 SIMD intrinsic functions in Emscripten](https://emscripten.org/docs/porting/simd.html)! [x86 SIMD intrinsic functions in Emscripten](https://emscripten.org/docs/porting/simd.html)!
Third: Middleware has to go. If you have a third-party library you link Second: Middleware has to go. If you have a third-party library you link
against, you either need an Emscripten port of it, or the source code to it against, you either need an Emscripten port of it, or the source code to it
to compile yourself, or you need to remove it. to compile yourself, or you need to remove it.
Fourth: You still start in a function called main(), but you need to get out of Third: If your program starts in a function called main(), you need to get
it and into a function that gets called repeatedly, and returns quickly, out of it and into a function that gets called repeatedly, and returns quickly,
called a mainloop. called a mainloop.
Somewhere in your program, you probably have something that looks like a more Somewhere in your program, you probably have something that looks like a more
@ -109,6 +101,13 @@ don't want any shutdown code that might be sitting below this code
to actually run if main() were to continue on, since we're just to actually run if main() were to continue on, since we're just
getting started. getting started.
Another option is to use SDL' main callbacks, which handle this for you
without platform-specific code in your app. Please refer to
[the wiki](https://wiki.libsdl.org/SDL3/README/main-functions#main-callbacks-in-sdl3)
or `docs/README-main-functions.md` in the SDL source code.
There's a lot of little details that are beyond the scope of this There's a lot of little details that are beyond the scope of this
document, but that's the biggest initial set of hurdles to porting document, but that's the biggest initial set of hurdles to porting
your app to the web. your app to the web.
@ -127,8 +126,8 @@ must be there, but you have to be careful (and read more detailed
documentation than this for the finer points). documentation than this for the finer points).
Even when using threads, your main thread needs to set an Emscripten Even when using threads, your main thread needs to set an Emscripten
mainloop that runs quickly and returns, or things will fail to work mainloop (or use SDL's main callbacks) that runs quickly and returns, or
correctly. things will fail to work correctly.
You should definitely read [Emscripten's pthreads docs](https://emscripten.org/docs/porting/pthreads.html) You should definitely read [Emscripten's pthreads docs](https://emscripten.org/docs/porting/pthreads.html)
for all the finer points. Mostly SDL's thread API will work as expected, for all the finer points. Mostly SDL's thread API will work as expected,
@ -202,6 +201,9 @@ If you use SDL's 2D render API, it will use GLES2 internally, which
Emscripten will turn into WebGL calls. You can also use OpenGL ES 2 Emscripten will turn into WebGL calls. You can also use OpenGL ES 2
directly by creating a GL context and drawing into it. directly by creating a GL context and drawing into it.
If the browser (and hardware) support WebGL 2, you can create an OpenGL ES 3
context.
Calling SDL_RenderPresent (or SDL_GL_SwapWindow) will not actually Calling SDL_RenderPresent (or SDL_GL_SwapWindow) will not actually
present anything on the screen until your return from your mainloop present anything on the screen until your return from your mainloop
function. function.
@ -209,25 +211,8 @@ function.
## Building SDL/emscripten ## Building SDL/emscripten
First: do you _really_ need to build SDL from source?
If you aren't developing SDL itself, have a desire to mess with its source SDL currently requires at least Emscripten 3.16.0 to build. Newer versions
code, or need something on the bleeding edge, don't build SDL. Just use
Emscripten's packaged version!
Compile and link your app with `-sUSE_SDL=2` and it'll use a build of
SDL packaged with Emscripten. This comes from the same source code and
fixes the Emscripten project makes to SDL are generally merged into SDL's
revision control, so often this is much easier for app developers.
`-sUSE_SDL=1` will select Emscripten's JavaScript reimplementation of SDL
1.2 instead; if you need SDL 1.2, this might be fine, but we generally
recommend you don't use SDL 1.2 in modern times.
If you want to build SDL, though...
SDL currently requires at least Emscripten 3.1.35 to build. Newer versions
are likely to work, as well. are likely to work, as well.
@ -260,6 +245,7 @@ emmake make -j4
``` ```
To build the tests, add `-DSDL_TESTS=On` to the `emcmake cmake` command line. To build the tests, add `-DSDL_TESTS=On` to the `emcmake cmake` command line.
To build the examples, add `-DSDL_EXAMPLES=On` to the `emcmake cmake` command line.
## Building your app ## Building your app
@ -267,8 +253,7 @@ To build the tests, add `-DSDL_TESTS=On` to the `emcmake cmake` command line.
You need to compile with `emcc` instead of `gcc` or `clang` or whatever, but You need to compile with `emcc` instead of `gcc` or `clang` or whatever, but
mostly it uses the same command line arguments as Clang. mostly it uses the same command line arguments as Clang.
Link against the SDL/build/libSDL3.a file you generated by building SDL, Link against the libSDL3.a file you generated by building SDL.
link with `-sUSE_SDL=2` to use Emscripten's prepackaged SDL2 build.
Usually you would produce a binary like this: Usually you would produce a binary like this:
@ -288,8 +273,8 @@ runs your app. You will (probably) eventually want to replace or customize
that file and do `-o index.js` instead to just build the code pieces. that file and do `-o index.js` instead to just build the code pieces.
If you're working on a program of any serious size, you'll likely need to If you're working on a program of any serious size, you'll likely need to
link with `-sALLOW_MEMORY_GROWTH=1 -sMAXIMUM_MEMORY=1gb` to get access link with `-s ALLOW_MEMORY_GROWTH=1 -s MAXIMUM_MEMORY=1gb` to get access
to more memory. If using pthreads, you'll need the `-sMAXIMUM_MEMORY=1gb` to more memory. If using pthreads, you'll need the `-s MAXIMUM_MEMORY=1gb`
or the app will fail to start on iOS browsers, but this might be a bug that or the app will fail to start on iOS browsers, but this might be a bug that
goes away in the future. goes away in the future.