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