From aa8a163a09be02e9b603641c4dbbf8e3e2fe1e20 Mon Sep 17 00:00:00 2001 From: Quentin Monnet Date: Tue, 12 Nov 2024 17:55:11 +0000 Subject: [PATCH] README.md: Clean-up minor issues, add link to Fabric's docs Make the README more welcoming to readers who don't know the project by adding a quick intro and linking to the docs. Also add a warning to state that the project is not usable, yet. Signed-off-by: Quentin Monnet --- README.md | 41 +++++++++++++++++++++++++++-------------- 1 file changed, 27 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index 570b9a7d..4150a38a 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,22 @@ # Hedgehog Dataplane +This repository contains the Dataplane for [Hedgehog's Open Network +Fabric][fabric-docs]. This component acts as a gateway between different VPCs +managed by the Fabric, or to communicate with endpoints outside of the Fabric. + +> [!WARNING] +> This project is under development, and is not yet functional. + +[fabric-docs]: https://docs.githedgehog.com + ## Build instructions ### Prerequisites -- Recent `x86_64` linux machine of some kind required for development +- A recent `x86_64` linux machine is required for development - Bash (you very likely have this) -- [Docker](https://www.docker.com/) (install through your package manager) -- Cargo / Rust (install via [`rustup`](https://rustup.rs/)) +- [Docker][docker] (install through your package manager) +- Cargo / Rust (install via [`rustup`]) * :warning: You need a recent version of rust (1.82.0 or better) to build the project. @@ -20,17 +29,21 @@ rustup target add x86_64-unknown-linux-gnu rustup target add x86_64-unknown-linux-musl ``` - -- [just](https://github.com/casey/just) (install through your package manager or cargo) -## Step 0. Clone the repository +- [just][just] (install through your package manager or cargo) + +[docker]: https://www.docker.com/ +[rustup]: https://rustup.rs/ +[just]: https://github.com/casey/just + +### Step 0. Clone the repository ```bash git clone git@github.com:githedgehog/dataplane.git cd dataplane ``` -## Step 1. Get the sysroot +### Step 1. Get the sysroot In the source directory, run @@ -42,7 +55,7 @@ You should now have a directory called `compile-env` which contains the tools ne You should also have `./compile-env/sysroot` which contains the libraries that `dpdk-sys` needs to link against. Both `x86_64-unknown-linux-gnu` and `x86_64-unknown-linux-musl` targets are currently supported. -## Step 2. Fake nix +### Step 2. Fake nix The sysroot is currently built using nix, but you don't need nix to build the project. The idea is to symlink `/nix` to `./compile-env/nix` so that the build scripts can find the libraries they need. @@ -52,7 +65,7 @@ This is a compromise between requiring the developer to understand nix (which ca > This is a hack! > It works fine but the plan won't work if you already have /nix. > If you already have /nix talk to me, and we will make it work. -> It should be pretty easy (we will just need to export some stuff +> It should be pretty easy (we will just need to export some stuff > from `dpdk-sys`) ```bash @@ -62,7 +75,7 @@ just fake-nix > [!NOTE] > If you move your project directory, you will need to run `just fake-nix refake` to update the symlinks. -## Step 3. Build the project +### Step 3. Build the project At this point you should be able to run @@ -80,9 +93,9 @@ just cargo build --profile=release at which point the executables will be in `target/x86_64-unknown-linux-gnu/release/scratch` and `target/x86_64-unknown-linux-musl/release/scratch`. -## Step 4. Run the tests (debug mode) +### Step 4. Run the tests (debug mode) -To run the test suite, you can run +To run the test suite, you can run ```bash just cargo test @@ -103,14 +116,14 @@ just cargo test --profile=release > [!WARNING] > Release builds may not work on your development machine! -> +> > The release build's dependencies are compiled with `-march=x86-64-v4` because we expect to release with a very new processor. > As a result, getting `SIGILL` on an older chip is no surprise. > We test release builds in CI, but they may not work on your dev box ¯\\\_(ツ)\_\/¯ > [!NOTE] > Why the `just` in `just cargo build ...`? -> +> > `just` is computing the correct `RUSTFLAGS` for us depending on the profile. > After that it simply calls `cargo build`. > Normally we would include those kinds of setting in `Cargo.toml` but `cargo` can not currently express all the `RUSTFLAGS` we are using (thus the `just` wrapper).