|
| 1 | +This repository contains hyperlight. Hyperlight is a lightweight Virtual Machine Manager (VMM) designed to be embedded within applications. |
| 2 | +It enables safe execution of untrusted code within micro virtual machines with very low latency and minimal overhead. |
| 3 | + |
| 4 | +This project uses just as a runner for building, testing etc. Just should already be installed. Most of the code in the repository is written in Rust, with a few files in C. |
| 5 | + |
| 6 | +## Code Standards |
| 7 | + |
| 8 | +Make sure that code is formatted and linted before committing. You can do this by running the following command: |
| 9 | + |
| 10 | +```bash |
| 11 | +just fmt-apply |
| 12 | +``` |
| 13 | +This will format the code and apply any necessary changes. You can also run the following command to check for any linting errors: |
| 14 | + |
| 15 | +```bash |
| 16 | +just clippy debug |
| 17 | +just clippy release |
| 18 | +``` |
| 19 | + |
| 20 | +If any lints fail you can try to fix them by running the following command for debug failures: |
| 21 | + |
| 22 | +```bash |
| 23 | + cargo clippy --fix --all |
| 24 | +``` |
| 25 | +And the following command for release failures: |
| 26 | + |
| 27 | +```bash |
| 28 | + cargo clippy --fix --all --release |
| 29 | +``` |
| 30 | + |
| 31 | +If this does not work, you should try and fix the errors and then run the commands again. |
| 32 | + |
| 33 | +## Development flow |
| 34 | + |
| 35 | +- build: |
| 36 | + - `just build` - builds the project in debug mode |
| 37 | + - `just build release` - builds the project in release mode |
| 38 | + - `just guests` - builds the guest library and test guests for both debug and release modes |
| 39 | +- test |
| 40 | + - `just test` - runs all tests in debug mode |
| 41 | + - `just test release` - runs all tests in release mode |
| 42 | + |
| 43 | +**IMPORTANT** You will need to run `just guests` to build the guest library before running the tests. |
| 44 | + |
| 45 | +Before pushing your code, make sure to run the following commands to ensure that everything is working correctly make sure all tests pass by running |
| 46 | +```bash |
| 47 | +just test-like-ci |
| 48 | +just test-like-ci release |
| 49 | +``` |
| 50 | + |
| 51 | +## Key Instructions |
| 52 | + |
| 53 | +**IMPORTANT**: Please make sure to follow these instructions when making changes to the codebase. If you cannot follow these instructions, please discuss it with the team first. |
| 54 | + |
| 55 | +Follow best practices and idioms for writing Rust code. |
| 56 | +Maintain the structure and organization of the codebase. Do not introduce new crates or dependencies without discussing them first. |
| 57 | +Make sure to write tests for any new code you add. Follow the existing testing patterns in the codebase. |
| 58 | +Make sure to fully document any new code you add. Use rustdoc comments and follow guidelines for good documentation. |
| 59 | +Make sure that any changes which alter anything documented in the README or the documentation in the docs directory are reflected in the documentation. |
| 60 | +Make sure that you label the PRs that you create with the correct labels. You can find details about which labels to use in the documents `docs/github-labels.md`. |
| 61 | +Make sure that you do not include any large binary files in your PR. If you need to include a large binary file, please discuss it with the team first. |
| 62 | +Make sure that you keep commits small and focused. Each commit should represent a single change or addition to the codebase. This will make it easier for reviewers to understand your changes and for you to revert them if necessary. |
| 63 | +Make sure that you arrange your commits in a logical order. You can use `git rebase -i` to do this. |
| 64 | +If you update your PR branch with new commits, make sure to rebase your branch on top of the main branch. This will help keep the commit history clean and make it easier to review your changes. |
| 65 | +Make sure that you do not have any merge commits in your PR. |
| 66 | +If when running tests you receive an Error like this "Error("No Hypervisor was found for Sandbox, Hypervisor Handler Message Receive Timedout")" then the real error is the string inside the brackets before the comma, so in this example |
| 67 | +the error is "No Hypervisor was found for Sandbox". |
| 68 | +If you see the error "No Hypervisor was found for Sandbox" then you if you are running on Linux you should check to see if there is a device called "kvm" or "mshv" in `/dev` and if it is present you should also check to see if you have rw access to it. You should ensure that you output the results of these checks for diagnostic purposes. |
| 69 | +This repository requires commits to be signed you should ensure that any commits that you create are done with `commit.gpgsign=true`. Also commits should also be signed with the `--signoff` option to comply with the DCO requirement. |
| 70 | + |
| 71 | +## Repository Structure |
| 72 | +- `dev/` - contains development scripts and tools |
| 73 | +- `src/` - contains the source code for the project |
| 74 | +- `.editorconfig` - contains the editor config for the project you should use this to configure your editor to use the same settings as the rest of the project |
| 75 | +- `Justfile` - contains the just commands for building, testing and running the project |
| 76 | +- `fuzz` - contains the fuzzing tests for the project |
| 77 | +- `src/hyperlight_common/` - contains the common code shared between the host and guest |
| 78 | +- `src/hyperlight_guest/` - contains the hyperlight-guest library code |
| 79 | +- `src/hyperlight_host/` - contains the hyperlight-host library code |
| 80 | +- `src/hyperlight_guest_capi/` - contains the hyperlight-guest C library code |
| 81 | +- `src/hyperlight_testing/` - contains the shared code for tests |
| 82 | +- `schema/` - contains the flatbuffer schemas for the project |
| 83 | +- `tests/` - contains the test guest code for the project in C and Rust |
0 commit comments