docs/README-nacl.md
changeset 10486 5bf595c48fd4
parent 9066 c2af3ff967cc
     1.1 --- a/docs/README-nacl.md	Fri Oct 07 17:30:21 2016 -0700
     1.2 +++ b/docs/README-nacl.md	Fri Oct 07 17:46:58 2016 -0700
     1.3 @@ -1,103 +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 -
   1.107 +Native Client
   1.108 +================================================================================
   1.109 +
   1.110 +Requirements: 
   1.111 +
   1.112 +* Native Client SDK (https://developer.chrome.com/native-client), 
   1.113 +  (tested with Pepper version 33 or higher).
   1.114 +
   1.115 +The SDL backend for Chrome's Native Client has been tested only with the PNaCl
   1.116 +toolchain, which generates binaries designed to run on ARM and x86_32/64 
   1.117 +platforms. This does not mean it won't work with the other toolchains!
   1.118 +
   1.119 +================================================================================
   1.120 +Building SDL for NaCl
   1.121 +================================================================================
   1.122 +
   1.123 +Set up the right environment variables (see naclbuild.sh), then configure SDL with:
   1.124 +
   1.125 +    configure --host=pnacl --prefix some/install/destination
   1.126 +    
   1.127 +Then "make". 
   1.128 +
   1.129 +As an example of how to create a deployable app a Makefile project is provided 
   1.130 +in test/nacl/Makefile, which includes some monkey patching of the common.mk file 
   1.131 +provided by NaCl, without which linking properly to SDL won't work (the search 
   1.132 +path can't be modified externally, so the linker won't find SDL's binaries unless 
   1.133 +you dump them into the SDK path, which is inconvenient).
   1.134 +Also provided in test/nacl is the required support file, such as index.html, 
   1.135 +manifest.json, etc.
   1.136 +SDL apps for NaCl run on a worker thread using the ppapi_simple infrastructure.
   1.137 +This allows for blocking calls on all the relevant systems (OpenGL ES, filesystem),
   1.138 +hiding the asynchronous nature of the browser behind the scenes...which is not the
   1.139 +same as making it disappear!
   1.140 +
   1.141 +
   1.142 +================================================================================
   1.143 +Running tests
   1.144 +================================================================================
   1.145 +
   1.146 +Due to the nature of NaCl programs, building and running SDL tests is not as
   1.147 +straightforward as one would hope. The script naclbuild.sh in build-scripts 
   1.148 +automates the process and should serve as a guide for users of SDL trying to build 
   1.149 +their own applications.
   1.150 +
   1.151 +Basic usage:
   1.152 +    
   1.153 +    ./naclbuild.sh path/to/pepper/toolchain (i.e. ~/naclsdk/pepper_35)
   1.154 +    
   1.155 +This will build testgles2.c by default.
   1.156 +
   1.157 +If you want to build a different test, for example testrendercopyex.c:
   1.158 +    
   1.159 +    SOURCES=~/sdl/SDL/test/testrendercopyex.c ./naclbuild.sh ~/naclsdk/pepper_35
   1.160 +    
   1.161 +Once the build finishes, you have to serve the contents with a web server (the
   1.162 +script will give you instructions on how to do that with Python).
   1.163 +
   1.164 +================================================================================
   1.165 +RWops and nacl_io
   1.166 +================================================================================
   1.167 +
   1.168 +SDL_RWops work transparently with nacl_io. Two functions control the mount points:
   1.169 +    
   1.170 +    int mount(const char* source, const char* target, 
   1.171 +                      const char* filesystemtype, 
   1.172 +                      unsigned long mountflags, const void *data);
   1.173 +    int umount(const char *target);
   1.174 +    
   1.175 +    For convenience, SDL will by default mount an httpfs tree at / before calling 
   1.176 +the app's main function. Such setting can be overridden by calling:
   1.177 +    
   1.178 +    umount("/");
   1.179 +
   1.180 +And then mounting a different filesystem at /
   1.181 +
   1.182 +It's important to consider that the asynchronous nature of file operations on a
   1.183 +browser is hidden from the application, effectively providing the developer with
   1.184 +a set of blocking file operations just like you get in a regular desktop 
   1.185 +environment, which eases the job of porting to Native Client, but also introduces 
   1.186 +a set of challenges of its own, in particular when big file sizes and slow 
   1.187 +connections are involved.
   1.188 +
   1.189 +For more information on how nacl_io and mount points work, see:
   1.190 +    
   1.191 +    https://developer.chrome.com/native-client/devguide/coding/nacl_io
   1.192 +    https://src.chromium.org/chrome/trunk/src/native_client_sdk/src/libraries/nacl_io/nacl_io.h
   1.193 +
   1.194 +To be able to save into the directory "/save/" (like backup of game) :
   1.195 +
   1.196 +    mount("", "/save", "html5fs", 0, "type=PERSISTENT");
   1.197 +
   1.198 +And add to manifest.json :
   1.199 +
   1.200 +    "permissions": [
   1.201 +        "unlimitedStorage"
   1.202 +    ]
   1.203 +
   1.204 +================================================================================
   1.205 +TODO - Known Issues
   1.206 +================================================================================
   1.207 +* Testing of all systems with a real application (something other than SDL's tests)
   1.208 +* Key events don't seem to work properly
   1.209 +