Home | History | Annotate | Download | only in nacl
      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 https://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_40 is the stable version. The NaCl port needs at least pepper_39
     41 to work. If naclsdk downloads a later version, please adjust accordingly.
     42 
     43 The cmd/go helper scripts expect that the loaders sel_ldr_{x86_{32,64},arm} and
     44 nacl_helper_bootstrap_arm are in your path. I find it easiest to make a symlink
     45 from the NaCl distribution to my $GOPATH/bin directory.
     46 
     47 	% ln -nfs /opt/nacl_sdk/pepper_39/tools/sel_ldr_x86_32 $GOPATH/bin/sel_ldr_x86_32
     48 	% ln -nfs /opt/nacl_sdk/pepper_39/tools/sel_ldr_x86_64 $GOPATH/bin/sel_ldr_x86_64
     49 	% ln -nfs /opt/nacl_sdk/pepper_39/tools/sel_ldr_arm $GOPATH/bin/sel_ldr_arm
     50 
     51 Additionally, for NaCl/ARM only:
     52 
     53 	% ln -nfs /opt/nacl_sdk/pepper_39/tools/nacl_helper_bootstrap_arm $GOPATH/bin/nacl_helper_bootstrap_arm
     54 
     55 Support scripts
     56 ---------------
     57 
     58 Symlink the two scripts in this directory into your $PATH, just as you did with
     59 NaCl sdk above.
     60 
     61 	% ln -nfs $GOROOT/misc/nacl/go_nacl_amd64p32_exec $GOPATH/bin/go_nacl_amd64p32_exec
     62 	% ln -nfs $GOROOT/misc/nacl/go_nacl_386_exec $GOPATH/bin/go_nacl_386_exec
     63 	% ln -nfs $GOROOT/misc/nacl/go_nacl_arm_exec $GOPATH/bin/go_nacl_arm_exec
     64 
     65 Building and testing
     66 --------------------
     67 
     68 Building for NaCl is similar to cross compiling for other platforms. However,
     69 as it is not possible to ever build in a `native` NaCl environment, the cmd/go
     70 tool has been enhanced to allow the full build, all.bash, to be executed,
     71 rather than just the compile stage, make.bash.
     72 
     73 The cmd/go tool knows that if GOOS is set to `nacl` it should not try to
     74 execute any binaries itself. Instead it passes their execution to a support
     75 script which sets up a Native Client environment and invokes the NaCl sandbox.
     76 
     77 The script's name has a special format, go_$GOOS_$GOARCH_exec, so cmd/go can
     78 find it.
     79 
     80 In short, if the support scripts are in place, the cmd/go tool can be used as
     81 per normal.
     82 
     83 # Build and test Go for NaCl
     84 
     85 NaCl does not permit direct file system access. Instead, package syscall
     86 provides a simulated file system served by in-memory data. The script
     87 nacltest.bash is the NaCl equivalent of all.bash. It builds NaCl with an
     88 in-memory file system containing files needed for tests, and then it runs the
     89 tests.
     90 
     91 	% cd go/src
     92 	% env GOARCH=amd64p32 ./nacltest.bash
     93 
     94 Debugging
     95 ---------
     96 
     97 Assuming that you have built nacl/amd64p32 binary ./mybin and can run as:
     98 
     99 	% sel_ldr_x86_64 -l /dev/null -S -e ./mybin
    100 
    101 Create the nacl manifest file mybin.manifest with the following contents:
    102 
    103 	{ "program": { "x86-64": { "url": "mybin" } } }
    104 
    105 url is the path to the binary relative to the manifest file.
    106 Then, run the program as:
    107 
    108 	% sel_ldr_x86_64 -g -l /dev/null -S -e ./mybin
    109 
    110 The -g flag instructs the loader to stop at startup. Then, in another console:
    111 
    112 	% /opt/nacl_sdk/pepper_39/toolchain/linux_x86_glibc/bin/x86_64-nacl-gdb
    113 	% nacl-manifest mybin.manifest
    114 	% target remote :4014
    115 
    116 If you see that the program is stopped in _rt0_amd64p32_nacl, then symbols are
    117 loaded successfully and you can type 'c' to start the program.
    118 Next time you can automate it as:
    119 
    120 	% /opt/nacl_sdk/pepper_39/toolchain/linux_x86_glibc/bin/x86_64-nacl-gdb \
    121 		-ex 'nacl-manifest mybin.manifest' -ex 'target remote :4014'
    122