sandboxed-api/sandboxed_api/docs/library.md
Christian Blichmann 2ed1e9b7a4 Merge pull request #5 from disconnect3d:patch-5
PiperOrigin-RevId: 239387531
Change-Id: I7929c296cb838c5a1ed05539efca4e771c1f68b3
2019-03-20 14:51:11 +01:00

124 lines
4.8 KiB
Markdown

# Library
## BUILD.bazel
Here, you'll prepare a build target, that your [host code](host-code.md)
will make use of.
Start by preparing a `sapi_library()` target in your `BUILD.bazel`
file.
For reference, you can take a peek at a working example from the
[zlib example](../examples/zlib/lib/BUILD.bazel).
```python
load(
"//sandboxed_api/tools/generator:sapi_generator.bzl",
"sapi_library",
)
sapi_library(
name = "zlib-sapi",
srcs = [], # Extra code compiled with the SAPI library
hdrs = [] # Leave empty if embedded SAPI libraries are used, and the
# default sandbox policy is sufficient.
embed = True,
functions = [
"deflateInit_",
"deflate",
"deflateEnd",
],
lib = "@zlib//:zlibonly",
lib_name = "Zlib",
namespace = "sapi::zlib",
)
```
* **`name`** - name for your SAPI target
* **`srcs`** - any additional sources that you'd like to include with your
Sandboxed API library - typically, it's not necessary, unless you want to
provide your SAPI Library sandbox definition in a .cc file, and not in the
`sandbox.h` file.
* **`hdrs`** - as with **`srcs`**. Typically your sandbox definition (sandbox.h)
should go here, or empty, if embedded SAPI library is used, and the default
sandbox policy is sufficient.
* **`functions`** - a list of functions that you'd like to use in your host
code. Leaving this list empty will try to export and wrap all functions found
in the library.
* **`embed`** - whether the SAPI library should be embedded inside host code,
so the SAPI Sandbox can be initialized with the
`::sapi::Sandbox::Sandbox(FileToc*)` constructor.
* **`lib`** - (mandatory) the library target you want to sandbox and expose to
the host code.
* **`lib_name`** - (mandatory) name of the object which is proxying your library
functions from the `functions` list. You will call functions from the
sandboxed library via this object.
* **`input_files`** - list of source files, which SAPI interface generator
should scan for library's function declarations. Library's exported headers
are always scanned, so `input_files` can usually be left empty.
* **`namespace`** - a C++ namespace identifier to place API object defined in
`lib_name` into. Defaults to `sapigen`.
* **`deps**`** - a list of any additional dependency targets to add. Typically
not necessary.
* **`header`** - name of the header file to use instead of the generated one.
Do not use if you want to auto-generate the code.
## `sapi_library()` Rule Targets
For the above definition, `sapi_library()` build rule provides the following
targets:
* **`zlib-sapi`** - sandboxed library, substitiution for normal cc_library;
consists of **`zlib_sapi.bin`** and sandbox dependencies
* **`zlib-sapi.interface`** - generated library interface
* **`zlib-sapi.embed`** - `cc_embed_data()` target used to embed sandboxee in
the binary. See `bazel/embed_data.bzl`.
* **`zlib-sapi.bin`** - sandboxee binary, consists of small communication stub
and the library that is being sandboxed.
## Interface Generation
__`zlib-sapi`__ target creates target library with small communication stub
wrapped in [Sandbox2](../sandbox2/README.md). To be able to use the stub and
code within the sanbox, you should generate the interface file.
There are two options:
1. Add dependency on __`zlib-sapi.interface`__. This will auto-generate a
header that you can include in your code - the header name is of the form:
__`TARGET_NAME`__`.sapi.h`.
2. Run `bazel build TARGET_NAME.interface`, save generated header in your
project and include it in the code. You will also need to add the `header`
argument to the `sapi_library()` rule to indicate that you will skip code
generation.
## Sandbox Description (`sandbox.h`)
**Note**: If the default SAPI Sandbox policy is sufficient, and the constructor
used is **`::sapi::Sandbox::Sandbox(FileToc*)`**, then this file might not be
necessary.
In this step you will prepare the sandbox definition file (typically named
`sandbox.h`) for your library.
The goal of this is to tell the SAPI code where the sandboxed library can be
found, and how it should be contained.
At first, you should tell the SAPI code what your sandboxed library should be
allowed to do in terms of security policies and other process constraints. In
order to do that, you will have to implement and instantiate an object based on
the [::sapi::Sandbox](../sandbox.h) class.
This object will also specify where your SAPI Library can be found
and how it should be executed (though you can depend on default settings).
A working example of such SAPI object definition file can be found
[here](../examples/sum/lib/sandbox.h).
In order to familiarize yourself with the Sandbox2 policies, you might want to
take a look at the [Sandbox2 documenation](../sandbox2/README.md).