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 <[email protected]>

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 [email protected]: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).