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