This is an automated email from the ASF dual-hosted git repository.
mssun pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-teaclave.git
The following commit(s) were added to refs/heads/master by this push:
new 140ad29 [docs] Add doc for the build system (#320)
140ad29 is described below
commit 140ad297c93aa4e9d26aa6f7e03def18f15c9c29
Author: Mingshen Sun <[email protected]>
AuthorDate: Thu May 28 17:07:02 2020 -0700
[docs] Add doc for the build system (#320)
---
README.md | 1 +
docs/build-system.md | 121 +++++++++++++++++++++++++++++++++++++++++++++++++++
tests/README.md | 6 +++
3 files changed, 128 insertions(+)
diff --git a/README.md b/README.md
index e0ee3f3..51ba875 100644
--- a/README.md
+++ b/README.md
@@ -41,6 +41,7 @@ platform, making computation on privacy-sensitive data safe
and simple.
- [Threat Model](docs/threat-model.md)
- [Mutual Attestation: Why and How](docs/mutual-attestation.md)
- [Access Control](docs/access-control.md)
+- [Build System](docs/build-system.md)
### Codebase
diff --git a/docs/build-system.md b/docs/build-system.md
new file mode 100644
index 0000000..6b013c3
--- /dev/null
+++ b/docs/build-system.md
@@ -0,0 +1,121 @@
+---
+permalink: /docs/build-system
+---
+
+# Build System
+
+The Teaclave's build system utilizes CMake to coordinate compilation, linking,
+signing, etc. for various components written in different languages (e.g.,
Rust, C,
+Python) for different targets (e.g., Linux and SGX). In this document, we will
+introduce our build system in details.
+
+## Quick Start
+
+1. Download and [install](https://cmake.org/install/) CMake, the minimum
+ required version is 3.10.
+2. Open a shell and create a build directory.
+ ```
+ $ mkdir build && cd build
+ ```
+3. Run the following command to configure with `TEST_MODE` on.
+ ```
+ $ cmake -DTEST_MODE=ON ..
+ ```
+4. Build the whole platform.
+ ```
+ $ make
+ ```
+
+When making changes, run:
+
+- `make format`: Format current source code.
+- `make run-tests`: Make sure all tests are passed.
+
+You can find more detailed configurations and targets in the following
sections.
+
+## Variables and Options
+
+There are a lot of variables and options you can configure to control the build
+system.
+
+To set a variable or option, you can pass `-DXXX=` to `cmake`. For example,
+`cmake -DTEST_MODE=ON ..` to enable the `TEST_MODE` option.
+
+### Variables
+
+- `SGX_SDK`: Set (or get from env vars) the path of Intel SGX SDK. Defaults to
+ `/opt/sgxsdk`.
+- `RUSTFLAGS`: Set (or get from env vars) flags passed to rustc.
+- `MESAPY_VERSION`: Set the commit hash to the upstream MesaPy version.
+- `RUSTUP_TOOLCHAIN`: Set the Rust toolchain version.
+- `CMAKE_BUILD_TYPE`: Set the build type. Defaults to debug.
+
+### Options
+
+- `COV`: Build with coverage information. Defaults to OFF.
+- `OFFLINE`: Compile Rust code with `cargo --offline`. Defaults to ON.
+- `TEST_MODE`: Build with mock data and disabling some functions for testing.
+ Defaults to OFF.
+- `SGX_SIM_MODE`: Build in SGX simulation mode. Defaults to OFF.
+- `DCAP`: Use DCAP instead of IAS as the attestation service. Defaults to OFF.
+- `GIT_SUBMODULE`: Sync submodules with the upstream repositories. Defaults to
+ ON.
+- `CLP`: Enable `cargo clippy` to lint Rust code during the compilation.
+ Defaults to OFF.
+
+## Targets
+
+The followings are supported targets you can call with `make`. For example, to
build a specific
+service like execution service, you can just run `make
teaclave_execution_service`.
+
+### App/Enclave
+
+An SGX application has two parts: the app part and the enclave part. You can
+compile them separately or together using with these targets:
+
+- `sgxapp-teaclave_{service_name}`: Build the app part of a service.
+- `sgxlib-teaclave_{service_name}`: Build the enclave part of a service.
+- `teaclave_{service_name}`: Build (compile, link and sign, etc.) the app and
+ enclave of a service.
+- `sgxapp-teaclave_{test_name}`: Build the app part of a test driver.
+- `sgxlib-teaclave_{test_name}`: Build the enclave part of a test driver.
+- `teaclave_{test_name}`: Build (compile, link, and sign, etc.) the app and
+ enclave of a test driver.
+
+These targets are automatically generated from the
+`cmake/tomls/Cargo.sgx_{}.toml` files. Basically, they are:
+
+- `test_name` can be: `function_tests`, `unit_tests`, `integration_tests`, etc.
+- `service_name` can be: `access_control_service`, `authentication_service`,
+ `storage_service`, `execution_service`, `frontend_service`,
+ `management_service`, `scheduler_service`, etc.
+
+### Bin
+
+- `teaclave_cli`: Build the Teclave command line tool.
+- `teaclave_dcap_ref_as`: Build the reference implementation of DCAP's
+ attestation service.
+
+Above targets are automatically generated from the
+`cmake/tomls/Cargo.unix_app.toml` files.
+
+### Linting
+
+- `format`: Format all code.
+
+### Tests
+
+- `run-tests`: Run all test cases.
+- `run-integration-tests`: Run integration tests only.
+- `run-funtional-tests`: Run functional tests only.
+- `run-examples`: Run all examples.
+- `cov`: Aggregate coverage results and generate report, needs to config cmake
+ with `-DCOV=ON`.
+
+### Misc
+- `clean`: Cleanup all building intermediates.
+
+## Codebase
+
+You can find source code to learn more about our build system in the
+`CMakeLists.txt` file and the `cmake` directories.
diff --git a/tests/README.md b/tests/README.md
index 500079a..e39b03f 100644
--- a/tests/README.md
+++ b/tests/README.md
@@ -23,6 +23,12 @@ $ make run-integration-tests
$ make run-functional-tests # this will start all services in the
background automatically
```
+## Test Coverage
+
+To generate a coverage report for tests, you can configure cmake with
+`-DCOV=ON`. Then build the platform and run all tests. At last, you need to run
+`make cov` to aggregate coverage results.
+
## Directory Structure
- `unit`:
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
