From c9471d15a89bc790b4c09614d057e552495fcf02 Mon Sep 17 00:00:00 2001 From: Kyle Carow Date: Mon, 29 Jun 2026 18:10:29 -0600 Subject: [PATCH 1/3] dev section fillout & cleanup --- docs/content/{ => deleteme}/developers.md | 0 .../compilation-from-source.md | 0 docs/content/developers/environment-setup.md | 99 +++++++++++++++++++ .../content/{ => developers}/how-to-update.md | 0 .../{ => developers}/release-process.md | 0 docs/content/installation.md | 7 +- docs/myst.yml | 7 +- 7 files changed, 106 insertions(+), 7 deletions(-) rename docs/content/{ => deleteme}/developers.md (100%) rename docs/content/{ => developers}/compilation-from-source.md (100%) create mode 100644 docs/content/developers/environment-setup.md rename docs/content/{ => developers}/how-to-update.md (100%) rename docs/content/{ => developers}/release-process.md (100%) diff --git a/docs/content/developers.md b/docs/content/deleteme/developers.md similarity index 100% rename from docs/content/developers.md rename to docs/content/deleteme/developers.md diff --git a/docs/content/compilation-from-source.md b/docs/content/developers/compilation-from-source.md similarity index 100% rename from docs/content/compilation-from-source.md rename to docs/content/developers/compilation-from-source.md diff --git a/docs/content/developers/environment-setup.md b/docs/content/developers/environment-setup.md new file mode 100644 index 000000000..13c1741a7 --- /dev/null +++ b/docs/content/developers/environment-setup.md @@ -0,0 +1,99 @@ +# Environment Setup + +A few options exist for environment setup: +1. [Pixi (recommended)](#1-pixi) +2. [Anaconda](#2-anaconda) +2. [Custom](#3-custom) + +## 1. Pixi +[Pixi](https://pixi.prefix.dev/latest/) is a tool that ensures environment hygiene and reproducibility. FASTSim has an established setup for +Pixi that you can take advantage of to quickly get started. + +### Pixi Installation + +Full installation instructions are available in the pixi docs: +[https://pixi.prefix.dev/latest/installation/](https://pixi.prefix.dev/latest/installation/) + +After installation, confirm pixi is available in a fresh terminal: + +```sh +pixi --version +``` + +### Environment Installation + +From the repository root, install FASTSim and development dependencies: + +```sh +pixi install -e dev +``` + +The `dev` Pixi environment installs FASTSim, the Rust compiler, testing dependencies, and other conveniences. If these are not necessary, see the `pyproject.toml` file for other options. + +### Environment Usage + +To use the environment in a terminal: + +- Run individual commands: + +```sh +pixi run -e dev +``` + +- Or, activate an interactive shell: + +```sh +pixi shell -e dev +``` + +See the Pixi documentation or run `pixi --help` for more usage information. The [direnv](https://direnv.net) tool automates launching a shell for you, and FASTSim has a preconfigured `.envrc` file. + +### direnv: Automatic Environment Activation + +If you use direnv, you can auto-load the pixi dev environment when entering this repository. + +Setup: + +1. Install direnv: [https://direnv.net/docs/installation.html](https://direnv.net/docs/installation.html) +2. Enable the hook for your shell (see [direnv docs](https://direnv.net/docs/hook.html)). +3. Allow `direnv` to run `.envrc`: + ```sh + direnv allow + ``` + +After that, entering the directory will auto-activate the pixi `dev` environment. Messages about environment variables can be suppressed by creating `~/.config/direnv/direnv.toml` containing the line: +```toml +hide_env_diff = true +``` + +## 2. Anaconda + +Anaconda users can easily install Rust using the conda-forge `rust` package + +1. Create a new environment with Python and Rust + ``` + conda create -n fastsim python=3.12 rust -c conda-forge + ``` + +2. Activate the new environment + ``` + conda activate + ``` + +2. From the repository root, install FASTSim and development dependencies: + + ```sh + pip install --group dev -e . + ``` + +## 3. Custom + +If you do not want to use Pixi or Anaconda, install Rust and Python dependencies manually. + +1. Install Rust system-wide: [https://www.rust-lang.org/tools/install](https://www.rust-lang.org/tools/install) +2. Create and activate a Python environment (using your environment manager of choice). +3. From the repository root, install FASTSim and development dependencies: + + ```sh + pip install --group dev -e . + ``` diff --git a/docs/content/how-to-update.md b/docs/content/developers/how-to-update.md similarity index 100% rename from docs/content/how-to-update.md rename to docs/content/developers/how-to-update.md diff --git a/docs/content/release-process.md b/docs/content/developers/release-process.md similarity index 100% rename from docs/content/release-process.md rename to docs/content/developers/release-process.md diff --git a/docs/content/installation.md b/docs/content/installation.md index 34a4847af..23555775d 100644 --- a/docs/content/installation.md +++ b/docs/content/installation.md @@ -32,12 +32,11 @@ toolchain is the only prerequisite you need to set up yourself. pip install . ``` -For an editable install that also includes the development dependencies, run -`pip install -e ".[dev]"` from the repository root instead. Source changes are -then picked up the next time FASTSim is imported. + - Add the editable `-e` flag to detect source changes each time FASTSim is imported. + - Add the `--group dev` flag to install optional developer dependencies. Building from source is not necessary for most use cases. For more detail on -the developer build, see [Compilation from Source](compilation-from-source.md). +the developer build, see [Compilation from Source](developers/compilation-from-source.md). ## Next Steps diff --git a/docs/myst.yml b/docs/myst.yml index e41a06726..f63b6afdf 100644 --- a/docs/myst.yml +++ b/docs/myst.yml @@ -51,9 +51,10 @@ project: - file: demo_notebooks/vehicle_controls/demo_cruise_and_coast.ipynb - title: Developers children: - - file: content/compilation-from-source.md - - file: content/release-process.md - - file: content/how-to-update.md + - file: content/developers/environment-setup.md + - file: content/developers/compilation-from-source.md + - file: content/developers/release-process.md + - file: content/developers/how-to-update.md - url: https://docs.rs/fastsim-core/latest/fastsim_core/ title: Rust API Documentation - url: https://github.com/NatLabRockies/fastsim/releases From e941efec33747681129dda1cc82fd85945a417af Mon Sep 17 00:00:00 2001 From: Kyle Carow <40699307+kylecarow@users.noreply.github.com> Date: Thu, 2 Jul 2026 15:40:06 -0600 Subject: [PATCH 2/3] Clarify Anaconda environment setup instructions Updated Anaconda setup instructions to specify environment name and include pip upgrade. --- docs/content/developers/environment-setup.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/content/developers/environment-setup.md b/docs/content/developers/environment-setup.md index 13c1741a7..a1b16ad93 100644 --- a/docs/content/developers/environment-setup.md +++ b/docs/content/developers/environment-setup.md @@ -70,19 +70,20 @@ hide_env_diff = true Anaconda users can easily install Rust using the conda-forge `rust` package -1. Create a new environment with Python and Rust +1. Create a new environment with Python and Rust (e.g. named `fastsim`) ``` conda create -n fastsim python=3.12 rust -c conda-forge ``` 2. Activate the new environment ``` - conda activate + conda activate fastsim ``` 2. From the repository root, install FASTSim and development dependencies: ```sh + pip install --upgrade pip pip install --group dev -e . ``` From 9b0904af3efaa3185c145c52818eb2809544fa4f Mon Sep 17 00:00:00 2001 From: Kyle Carow Date: Fri, 3 Jul 2026 08:10:46 -0600 Subject: [PATCH 3/3] added note about conda install from pixi.lock --- docs/content/developers/environment-setup.md | 29 +++++++++++++++++++- 1 file changed, 28 insertions(+), 1 deletion(-) diff --git a/docs/content/developers/environment-setup.md b/docs/content/developers/environment-setup.md index a1b16ad93..1d7fbc0bd 100644 --- a/docs/content/developers/environment-setup.md +++ b/docs/content/developers/environment-setup.md @@ -72,7 +72,7 @@ Anaconda users can easily install Rust using the conda-forge `rust` package 1. Create a new environment with Python and Rust (e.g. named `fastsim`) ``` - conda create -n fastsim python=3.12 rust -c conda-forge + conda create --name fastsim python=3.12 rust -c conda-forge ``` 2. Activate the new environment @@ -87,6 +87,33 @@ Anaconda users can easily install Rust using the conda-forge `rust` package pip install --group dev -e . ``` +:::{note} +This section suggests dependencies independent of the `pyproject.toml`, so may become outdated. + +As of writing, a way to build an Anaconda environment from `pixi.lock` using +the [`conda-lockfiles` plugin](https://github.com/conda/conda-lockfiles) is nearly supported: + +```console +conda install --name base conda-forge::conda-lockfiles +``` + +``` +conda env create --name fastsim --file pixi.lock +``` + +However, this plugin only supports `pixi.lock` version 6, while version 7 released in [May 2026](https://pixi.prefix.dev/latest/CHANGELOG/#0680-2026-05-07). + +Output: +``` +PluginError: Failed to parse environment specification from file: field 'version': Input should be less than or equal to 6 +``` + +Relevant links: +- https://github.com/conda/conda-lockfiles/pull/143 +- https://github.com/conda/conda-lockfiles/issues/44 +::: + + ## 3. Custom If you do not want to use Pixi or Anaconda, install Rust and Python dependencies manually.