docs/README-nacl.md
changeset 9025 d09d4b578e77
parent 9023 276802355854
child 9066 c2af3ff967cc
     1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/docs/README-nacl.md	Tue Jul 29 08:04:15 2014 -0700
     1.3 @@ -0,0 +1,103 @@
     1.4 +Native Client
     1.5 +================================================================================
     1.6 +
     1.7 +Requirements: 
     1.8 +    
     1.9 +    * Native Client SDK (https://developer.chrome.com/native-client), 
    1.10 +      (tested with Pepper version 33 or higher).
    1.11 +
    1.12 +The SDL backend for Chrome's Native Client has been tested only with the PNaCl
    1.13 +toolchain, which generates binaries designed to run on ARM and x86_32/64 
    1.14 +platforms. This does not mean it won't work with the other toolchains!
    1.15 +
    1.16 +================================================================================
    1.17 +Building SDL for NaCl
    1.18 +================================================================================
    1.19 +
    1.20 +Set up the right environment variables (see naclbuild.sh), then configure SDL with:
    1.21 +
    1.22 +    configure --host=pnacl --prefix some/install/destination
    1.23 +    
    1.24 +Then "make". 
    1.25 +
    1.26 +As an example of how to create a deployable app a Makefile project is provided 
    1.27 +in test/nacl/Makefile, which includes some monkey patching of the common.mk file 
    1.28 +provided by NaCl, without which linking properly to SDL won't work (the search 
    1.29 +path can't be modified externally, so the linker won't find SDL's binaries unless 
    1.30 +you dump them into the SDK path, which is inconvenient).
    1.31 +Also provided in test/nacl is the required support file, such as index.html, 
    1.32 +manifest.json, etc.
    1.33 +SDL apps for NaCl run on a worker thread using the ppapi_simple infrastructure.
    1.34 +This allows for blocking calls on all the relevant systems (OpenGL ES, filesystem),
    1.35 +hiding the asynchronous nature of the browser behind the scenes...which is not the
    1.36 +same as making it disappear!
    1.37 +
    1.38 +
    1.39 +================================================================================
    1.40 +Running tests
    1.41 +================================================================================
    1.42 +
    1.43 +Due to the nature of NaCl programs, building and running SDL tests is not as
    1.44 +straightforward as one would hope. The script naclbuild.sh in build-scripts 
    1.45 +automates the process and should serve as a guide for users of SDL trying to build 
    1.46 +their own applications.
    1.47 +
    1.48 +Basic usage:
    1.49 +    
    1.50 +    ./naclbuild.sh path/to/pepper/toolchain (i.e. ~/naclsdk/pepper_35)
    1.51 +    
    1.52 +This will build testgles2.c by default.
    1.53 +
    1.54 +If you want to build a different test, for example testrendercopyex.c:
    1.55 +    
    1.56 +    SOURCES=~/sdl/SDL/test/testrendercopyex.c ./naclbuild.sh ~/naclsdk/pepper_35
    1.57 +    
    1.58 +Once the build finishes, you have to serve the contents with a web server (the
    1.59 +script will give you instructions on how to do that with Python).
    1.60 +
    1.61 +================================================================================
    1.62 +RWops and nacl_io
    1.63 +================================================================================
    1.64 +
    1.65 +SDL_RWops work transparently with nacl_io. Two functions control the mount points:
    1.66 +    
    1.67 +    int mount(const char* source, const char* target, 
    1.68 +                      const char* filesystemtype, 
    1.69 +                      unsigned long mountflags, const void *data);
    1.70 +    int umount(const char *target);
    1.71 +    
    1.72 +    For convenience, SDL will by default mount an httpfs tree at / before calling 
    1.73 +the app's main function. Such setting can be overridden by calling:
    1.74 +    
    1.75 +    umount("/");
    1.76 +
    1.77 +And then mounting a different filesystem at /
    1.78 +
    1.79 +It's important to consider that the asynchronous nature of file operations on a
    1.80 +browser is hidden from the application, effectively providing the developer with
    1.81 +a set of blocking file operations just like you get in a regular desktop 
    1.82 +environment, which eases the job of porting to Native Client, but also introduces 
    1.83 +a set of challenges of its own, in particular when big file sizes and slow 
    1.84 +connections are involved.
    1.85 +
    1.86 +For more information on how nacl_io and mount points work, see:
    1.87 +    
    1.88 +    https://developer.chrome.com/native-client/devguide/coding/nacl_io
    1.89 +    https://src.chromium.org/chrome/trunk/src/native_client_sdk/src/libraries/nacl_io/nacl_io.h
    1.90 +
    1.91 +To be able to save into the directory "/save/" (like backup of game) :
    1.92 +
    1.93 +    mount("", "/save", "html5fs", 0, "type=PERSISTENT");
    1.94 +
    1.95 +And add to manifest.json :
    1.96 +
    1.97 +  "permissions": [
    1.98 +     "unlimitedStorage"
    1.99 +  ]
   1.100 +
   1.101 +================================================================================
   1.102 +TODO - Known Issues
   1.103 +================================================================================
   1.104 +* Testing of all systems with a real application (something other than SDL's tests)
   1.105 +* Key events don't seem to work properly
   1.106 +