diff --git a/docs/src/setup/linux.md b/docs/src/setup/linux.md index d165f9dd..2e7100aa 100644 --- a/docs/src/setup/linux.md +++ b/docs/src/setup/linux.md @@ -11,6 +11,7 @@ initial examples. - [Install Rust](#install-rust) - [Install SIMICS](#install-simics) - [Build TSFFS](#build-tsffs) + - [Set Up For Local Development](#set-up-for-local-development) ## Install Local Dependencies @@ -170,4 +171,49 @@ ispm packages -i linux64/packages/simics-pkg-31337-6.0.0-linux64.ispm \ ``` You are now ready to use TSFFS! See the [User Guide](./UserGuide.md) to learn how to -add TSFFS to your SIMICS projects, configure TSFFS, and run fuzzing campaigns. \ No newline at end of file +add TSFFS to your SIMICS projects, configure TSFFS, and run fuzzing campaigns. + +## Set Up For Local Development + + +End users can skip this step, it is only necessary if you will be developing the fuzzer. + +If you want to develop TSFFS locally, it is helpful to be able to run normal `cargo` +commands to build, run clippy and rust analyzer, and so forth. + +To set up your environment for local development, note the installed SIMICS base version +you would like to target. For example, SIMICS 6.0.169. For local development, it is +generally best to pick the most recent installed version. You can print the latest +version you have installed by running (`jq` can be installed with your package manager): + +```sh +ispm packages --list-installed --json | jq -r '[ .installedPackages[] | select(.pkgNumber == 1000) ] | ([ .[].version ] | max_by(split(".") | map(tonumber))) as $m | first(first(.[]|select(.version == $m)).paths[0])' +``` + +On the author's system, for example, this prints: + +```txt +/home/YOUR_USERNAME/simics/simics-6.0.169 +``` + +Add this path in the `[env]` section of `.cargo/config.toml` as the variable +`SIMICS_BASE` in your local TSFFS repository. Using this path, `.cargo/config.toml` +would look like: + +```toml +[env] +SIMICS_BASE = "/home/YOUR_USERNAME/simics/simics-6.0.169" +``` + +This lets `cargo` find your SIMICS installation, and it uses several fallback methods to +find the SIMICS libraries to link with. Paths to the libraries are provided via the +SIMICS Makefile system, which is used by the `./build.rs` script above, hence this step +is only needed for local development. + +Finally, check that your configuration is correct by running: + +```sh +cargo clippy +``` + +The process should complete without error. \ No newline at end of file diff --git a/docs/src/setup/windows.md b/docs/src/setup/windows.md index c7323bd5..ee331471 100644 --- a/docs/src/setup/windows.md +++ b/docs/src/setup/windows.md @@ -13,6 +13,7 @@ should be run in PowerShell (the default shell on recent Windows versions). - [Install SIMICS](#install-simics) - [Build TSFFS](#build-tsffs) - [Test TSFFS](#test-tsffs) + - [Set Up For Local Development](#set-up-for-local-development) - [Troubleshooting](#troubleshooting) - [I Already Have A MinGW Installation](#i-already-have-a-mingw-installation) - [Command is Unrecognized](#command-is-unrecognized) @@ -149,6 +150,51 @@ cd $env:TEMP\TSFFS-Windows ./simics ./fuzz.simics ``` +## Set Up For Local Development + +End users can skip this step, it is only necessary if you will be developing the fuzzer. + +If you want to develop TSFFS locally, it is helpful to be able to run normal `cargo` +commands to build, run clippy and rust analyzer, and so forth. + +To set up your environment for local development, note the installed SIMICS base version +you would like to target. For example, SIMICS 6.0.169. For local development, it is +generally best to pick the most recent installed version. You can print the latest +version you have installed by running (`jq` can be installed with `winget install +stedolan.jq`): + +```sh +ispm packages --list-installed --json | jq -r '[ .installedPackages[] | select(.pkgNumber == 1000) ] | ([ .[].version ] | max_by(split(".") | map(tonumber))) as $m | first(first(.[]|select(.version == $m)).paths[0])' +``` + +On the author's system, for example, this prints: + +```txt +C:\Users\YOUR_USERNAME\simics\simics-6.0.169 +``` + +Add this path in the `[env]` section of `.cargo/config.toml` as the variable +`SIMICS_BASE` in your local TSFFS repository. Using this path, `.cargo/config.toml` +would look like: + +```toml +[env] +SIMICS_BASE = "C:\Users\YOUR_USERNAME\simics\simics-6.0.169" +``` + +This lets `cargo` find your SIMICS installation, and it uses several fallback methods to +find the SIMICS libraries to link with. Paths to the libraries are provided via the +SIMICS Makefile system, which is used by the `./build.rs` script above, hence this step +is only needed for local development. + +Finally, check that your configuration is correct by running: + +```sh +cargo clippy +``` + +The process should complete without error. + ## Troubleshooting ### I Already Have A MinGW Installation