1Native Client
2================================================================================
3
4Requirements:
5
6* Native Client SDK (https://developer.chrome.com/native-client),
7  (tested with Pepper version 33 or higher).
8
9The SDL backend for Chrome's Native Client has been tested only with the PNaCl
10toolchain, which generates binaries designed to run on ARM and x86_32/64
11platforms. This does not mean it won't work with the other toolchains!
12
13================================================================================
14Building SDL for NaCl
15================================================================================
16
17Set up the right environment variables (see naclbuild.sh), then configure SDL with:
18
19    configure --host=pnacl --prefix some/install/destination
20
21Then "make".
22
23As an example of how to create a deployable app a Makefile project is provided
24in test/nacl/Makefile, which includes some monkey patching of the common.mk file
25provided by NaCl, without which linking properly to SDL won't work (the search
26path can't be modified externally, so the linker won't find SDL's binaries unless
27you dump them into the SDK path, which is inconvenient).
28Also provided in test/nacl is the required support file, such as index.html,
29manifest.json, etc.
30SDL apps for NaCl run on a worker thread using the ppapi_simple infrastructure.
31This allows for blocking calls on all the relevant systems (OpenGL ES, filesystem),
32hiding the asynchronous nature of the browser behind the scenes...which is not the
33same as making it disappear!
34
35
36================================================================================
37Running tests
38================================================================================
39
40Due to the nature of NaCl programs, building and running SDL tests is not as
41straightforward as one would hope. The script naclbuild.sh in build-scripts
42automates the process and should serve as a guide for users of SDL trying to build
43their own applications.
44
45Basic usage:
46
47    ./naclbuild.sh path/to/pepper/toolchain (i.e. ~/naclsdk/pepper_35)
48
49This will build testgles2.c by default.
50
51If you want to build a different test, for example testrendercopyex.c:
52
53    SOURCES=~/sdl/SDL/test/testrendercopyex.c ./naclbuild.sh ~/naclsdk/pepper_35
54
55Once the build finishes, you have to serve the contents with a web server (the
56script will give you instructions on how to do that with Python).
57
58================================================================================
59RWops and nacl_io
60================================================================================
61
62SDL_RWops work transparently with nacl_io. Two functions control the mount points:
63
64    int mount(const char* source, const char* target,
65                      const char* filesystemtype,
66                      unsigned long mountflags, const void *data);
67    int umount(const char *target);
68
69    For convenience, SDL will by default mount an httpfs tree at / before calling
70the app's main function. Such setting can be overridden by calling:
71
72    umount("/");
73
74And then mounting a different filesystem at /
75
76It's important to consider that the asynchronous nature of file operations on a
77browser is hidden from the application, effectively providing the developer with
78a set of blocking file operations just like you get in a regular desktop
79environment, which eases the job of porting to Native Client, but also introduces
80a set of challenges of its own, in particular when big file sizes and slow
81connections are involved.
82
83For more information on how nacl_io and mount points work, see:
84
85    https://developer.chrome.com/native-client/devguide/coding/nacl_io
86    https://src.chromium.org/chrome/trunk/src/native_client_sdk/src/libraries/nacl_io/nacl_io.h
87
88To be able to save into the directory "/save/" (like backup of game) :
89
90    mount("", "/save", "html5fs", 0, "type=PERSISTENT");
91
92And add to manifest.json :
93
94    "permissions": [
95        "unlimitedStorage"
96    ]
97
98================================================================================
99TODO - Known Issues
100================================================================================
101* Testing of all systems with a real application (something other than SDL's tests)
102* Key events don't seem to work properly
103
104