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