github.com/yanyiwu/go@v0.0.0-20150106053140-03d6637dbb7f/misc/nacl/README (about)

     1  Native Client
     2  =============
     3  
     4  This document outlines the basics of building and developing the Go runtime and
     5  programs in the Native Client (NaCl) environment.
     6  
     7  Go 1.3 supports three architectures
     8  
     9   * nacl/386 which is standard 386.
    10   * nacl/amd64p32 which is a 64 bit architecture, where the address space is
    11     limited to a 4gb window. 
    12   * nacl/arm which is 32-bit ARMv7A architecture with 1GB address space.
    13  
    14  For background it is recommended that you read http://golang.org/s/go13nacl.
    15  
    16  Prerequisites
    17  -------------
    18  
    19  Native Client programs are executed inside a sandbox, the NaCl runtime. This
    20  runtime must be installed before you can use NaCl programs.
    21  
    22  The NaCl distribution comes with an installer which ensures you have access to
    23  the latest version of the runtime. The version tracks the Chrome numbering
    24  scheme.
    25  
    26  # Download NaCl
    27  
    28  Download nacl_sdk.zip file from
    29  	https://developers.google.com/native-client/dev/sdk/download
    30  and unpack it. I chose /opt/nacl_sdk.
    31  
    32  # Update
    33  
    34  The zip file contains a small skeleton that can be used to download the correct
    35  sdk. These are released every 6-8 weeks, in line with Chrome releases.
    36  	
    37  	% cd /opt/nacl_sdk
    38  	% ./naclsdk update
    39  
    40  At this time pepper_34 is the stable version. If naclsdk downloads a later
    41  version, please adjust accordingly. As of June 2014, only the canary sdk
    42  provides support for nacl/arm.
    43  
    44  The cmd/go helper scripts expect that the loaders sel_ldr_{x86_{32,64},arm} and
    45  nacl_helper_bootstrap_arm are in your path. I find it easiest to make a symlink
    46  from the NaCl distribution to my $GOPATH/bin directory.
    47  
    48  	% ln -nfs /opt/nacl_sdk/pepper_34/tools/sel_ldr_x86_32 $GOPATH/bin/sel_ldr_x86_32
    49  	% ln -nfs /opt/nacl_sdk/pepper_34/tools/sel_ldr_x86_64 $GOPATH/bin/sel_ldr_x86_64
    50  	% ln -nfs /opt/nacl_sdk/pepper_canary/tools/sel_ldr_arm $GOPATH/bin/sel_ldr_arm
    51  
    52  Additionally, for NaCl/ARM only:
    53  
    54  	% ln -nfs /opt/nacl_sdk/pepper_canary/tools/nacl_helper_bootstrap_arm $GOPATH/bin/nacl_helper_bootstrap_arm 
    55  
    56  Support scripts
    57  ---------------
    58  
    59  Symlink the two scripts in this directory into your $PATH, just as you did with
    60  NaCl sdk above.
    61  
    62  	% ln -nfs $GOROOT/misc/nacl/go_nacl_amd64p32_exec $GOPATH/bin/go_nacl_amd64p32_exec
    63  	% ln -nfs $GOROOT/misc/nacl/go_nacl_386_exec $GOPATH/bin/go_nacl_386_exec
    64  	% ln -nfs $GOROOT/misc/nacl/go_nacl_arm_exec $GOPATH/bin/go_nacl_arm_exec
    65  
    66  Building and testing
    67  --------------------
    68  
    69  Building for NaCl is similar to cross compiling for other platforms. However,
    70  as it is not possible to ever build in a `native` NaCl environment, the cmd/go
    71  tool has been enhanced to allow the full build, all.bash, to be executed,
    72  rather than just the compile stage, make.bash.
    73  
    74  The cmd/go tool knows that if GOOS is set to `nacl` it should not try to
    75  execute any binaries itself. Instead it passes their execution to a support
    76  script which sets up a Native Client environment and invokes the NaCl sandbox.
    77  
    78  The script's name has a special format, go_$GOOS_$GOARCH_exec, so cmd/go can
    79  find it.
    80  
    81  In short, if the support scripts are in place, the cmd/go tool can be used as
    82  per normal.
    83  
    84  # Build and test Go for NaCl
    85  
    86  NaCl does not permit direct file system access. Instead, package syscall
    87  provides a simulated file system served by in-memory data. The script
    88  nacltest.bash is the NaCl equivalent of all.bash. It builds NaCl with an
    89  in-memory file system containing files needed for tests, and then it runs the
    90  tests.
    91  
    92  	% cd go/src
    93  	% env GOARCH=amd64p32 ./nacltest.bash
    94  
    95  Debugging
    96  ---------
    97  
    98  Assuming that you have built nacl/amd64p32 binary ./mybin and can run as:
    99  
   100  	% sel_ldr_x86_64 -l /dev/null -S -e ./mybin
   101  
   102  Create the nacl manifest file mybin.manifest with the following contents:
   103  
   104  	{ "program": { "x86-64": { "url": "mybin" } } }
   105  
   106  url is the path to the binary relative to the manifest file.
   107  Then, run the program as:
   108  
   109  	% sel_ldr_x86_64 -g -l /dev/null -S -e ./mybin
   110  
   111  The -g flag instructs the loader to stop at startup. Then, in another console:
   112  
   113  	% /opt/nacl_sdk/pepper_34/toolchain/linux_x86_glibc/bin/x86_64-nacl-gdb
   114  	% nacl-manifest mybin.manifest
   115  	% target remote :4014
   116  
   117  If you see that the program is stopped in _rt0_amd64p32_nacl, then symbols are
   118  loaded successfully and you can type 'c' to start the program.
   119  Next time you can automate it as:
   120  
   121  	% /opt/nacl_sdk/pepper_34/toolchain/linux_x86_glibc/bin/x86_64-nacl-gdb \
   122  		-ex 'nacl-manifest mybin.manifest' -ex 'target remote :4014'