mojo/nacl/nonsfi/README.md

About
=====

This directory contains the necessary components to run Non-SFI NaCl
nexes (native executables) from within Mojo.

Using
=====

The Non-SFI NaCl and accompanying tests should be built by default for Linux.
The boolean indicating if they are built is "mojo_use_nacl_nonsfi", defined
inside the BUILD files.

Building Non-SFI NaCl
---------------------

Build Mojo (all following commands assume you are in the root of the mojo
repository):

```
$  ./mojo/tools/mojob.py gn
$  ./mojo/tools/mojob.py build
```

Doing this build step will automatically create the necessary content handlers
and pexes.

Translating and Running Pexes
-----------------------------

When portable executable files (pexes) are generated by mojo, they are created
as `.pexe.mojo` files. These pexes are generated by building a gn target with
the `mojo_native_application` template with a PNaCl toolchain.

The "pexe" part of the name comes from the fact that they are portable, and the
"mojo" part of the name comes from the fact that they have the line `#!mojo
mojo:content_handler_nonsfi_pexe` prepended to them, so the appropriate pexe
content handler can be found by the Mojo Shell.

To run the `FOOBAR.pexe.mojo` pexe (aka, to translate and execute it), run the
following:

```
$ ./out/Debug/mojo_shell --enable-multiprocess ./out/Debug/FOOBAR.pexe.mojo
```

or, alternatively, for a version compatible with Android:

```
$  ./mojo/devtools/common/mojo_run --enable-multiprocess mojo:FOOBAR.pexe
[--android]
```

For more information on the process of translating and handling nexes and pexes,
refer to the `services/nacl` directory.

Manually Translating Pexes and Running Nexes
--------------------------------------------

A raw pexe of unit tests will be built, at
`./out/Debug/newlib_pnacl/monacl_test.pexe`.  To manually translate this pexe
into a non-SFI nexe:

```
$ ./native_client/toolchain/linux_x86/pnacl_newlib/bin/pnacl-translate \
./out/Debug/newlib_pnacl/FOOBAR.pexe -o FOOBAR.nexe -arch x86-32-nonsfi
```

Now, you should have the fully translated nexe (called
`FOOBAR.nexe`).  You can run the nexe through the monacl shell
(a minimal, "nexe-only" shell, which loads the nexe ELF file -- see
 `monacl_shell_nonsfi.cc`):

```
$ ./out/Debug/clang_x86/monacl_shell_nonsfi FOOBAR.nexe
```

This monacl_shell_nonsfi is the easiest way to run nexes in Mojo -- however, it
is not the only way. Usually, applications are launched through the
"mojo_shell", but some additional information is required to know how to handle
this content (i.e., how does the mojo_shell know it is dealing with a nonsfi
nexe?).

The BUILD.gn files in Mojo automatically make the "monacl_test" pexe, translate
it to a nexe, and prepend a line (`#!mojo mojo:content_handler_nonsfi_nexe`) to
the front of the file, at which point it is also runnable through the
mojo_shell.
These files, which start with this "#!" line, are ".mojo" files. The nexes can
be run like this:

```
$  ./out/Debug/mojo_shell --enable-multiprocess out/Debug/FOOBAR.mojo
```