1# LibUV Sandbox 2 3This library is a sandboxed version of [LibUV](https://libuv.org/), implemented 4using Sandboxed API. 5 6## Setup 7 8The repository can be cloned using: 9``` 10git clone --recursive [URL to this repo] 11``` 12The `--recursive` flag ensures that submodules are also cloned. 13 14Alternatively, if the repository has already been cloned but the submodules have 15not, these can be cloned using: 16``` 17git submodule update --init --recursive 18``` 19 20The full list of Sandboxed API dependencies can be found on 21[Sandboxed API Getting Started page](https://developers.google.com/code-sandboxing/sandboxed-api/getting-started). 22 23The following commands, used from the current `libuv/` directory, build the 24library: 25``` 26mkdir -p build 27cd build 28cmake .. -G Ninja -D SAPI_ROOT=[path to sandboxed-api] 29cmake --build . 30``` 31 32## Implementation details 33 34LibUV can't be directly sandboxed by Sandboxed API. Because of the size and 35complexity of the library, doing so creates some compilation errors and does not 36create the correct APIs for all methods. The solution for this issue is creating 37a wrapper library, whose methods (which can be sandboxed properly) internally 38call the original LibUV's methods. 39 40Using these wrapper methods is extremely simple, the only relevant difference is 41that they have a `sapi_` prefix before their names (e.g. `uv_loop_init` becomes 42`sapi_uv_loop_init`). The only exception is the variadic method 43`uv_loop_configure`. This has two wrappers, `sapi_uv_loop_configure` (with no 44additional parameters) and `sapi_uv_loop_configure_int` (with an additional 45`int` parameter). Currently, these are the only valid calls to the method in 46LibUV. 47 48#### Wrapper generator 49 50The wrapper is generated automatically by a Python script that is called by 51CMake at build time. This script can be found in the `generator` folder. 52 53#### Function pointers 54 55The functions whose pointers will be passed to the library's methods 56(*callbacks*) can't be implemented in the files making use of the library, but 57must be in other files. These files must be compiled together with the library, 58and this is done by adding their absolute path to the CMake variable 59`SAPI_UV_CALLBACKS`. 60 61The pointers can then be obtained using an `RPCChannel` object, as shown in the 62example `idle-basic.cc`. 63 64## Examples 65 66The `examples` directory contains the sandboxed versions of example source codes 67taken from from [LibUV's User Guide](https://docs.libuv.org/en/v1.x/guide.html). 68More information about each example can be found in the examples' 69[README](examples/README.md). 70 71To build these examples when building the library, the CMake variable 72`SAPI_UV_ENABLE_EXAMPLES` must be set to `ON`. This enables Sandboxed API 73examples as well. 74 75## Testing 76 77The `tests` folder contains some test cases created using Google Test. 78 79To build these tests when building the library, the CMake variable 80`SAPI_UV_ENABLE_TESTS` must be set to `ON`. This enables Sandboxed API tests as 81well. 82 83## Policies 84 85Each example and test has an ad-hoc policy implemented on its own file. These 86policies can be used as references for pieces of code that perform similar 87operations. For example, the `helloworld.cc` example has a policy that only 88allows the strictly necessary syscalls for running a loop. 89 90## Callbacks 91 92The `callbacks.h` and `callbacks.cc` files in the `callbacks` folder implement 93all the callbacks used by examples and tests. 94