flox in 5 minutes¶
Assuming you've installed flox
, clone the rust-env-demo
repository and cd
into it:
$ git clone [email protected]:flox-examples/rust-env-demo.git
Cloning into 'rust-env-demo'...
...
Resolving deltas: ...
$ cd rust-env-demo
This repository contains a Rust crate (package) that queries the Rust homepage and a flox environment for working on the crate.
Up and running¶
Run flox develop
and choose rust-env
to enter the development shell:
$ flox develop rust-env
...
• Updated input 'flox-floxpkgs/nixpkgs/nixpkgs':
follows 'flox-floxpkgs/nixpkgs/nixpkgs-stable'
...
...$ which cargo
/nix/store/...-auditable-cargo-.../bin/cargo
Let's build and run the crate with cargo run
to verify that everything is working properly:
...$ cargo run
...
Running `target/debug/rust-env-demo`
<!doctype html>
<html lang="en-US">
<head>
<meta charset="utf-8">
<title>...Rust Programming Language...</title>
...
Great, the code works.
Let's see if Rust's linter (clippy
) has anything to say about our code quality.
Run the linter with cargo clippy
:
I wonder which parts of our code are taking the longest to execute?
We'll use the just
command runner to collect CPU profiling data for our Rust project with the just profile
command:
flamegraph.svg
file in a browser to see that execution time is dominated by curl
, so our code is doing just fine.
Now that we've worked on this project we can leave the flox
environment by typing exit
:
The flox
environment for this project just did a number of things for you:
- You were provided with the tools to build a Rust project
- You were provided with Rust development tooling like
clippy
- Compatible versions of all system dependencies required for the build were downloaded and put in a place where build tools could find them
- You were provided with a development environment that contained tools for CPU profiling
- After leaving the environment the project tooling was no longer made available so that it didn't pollute your global environment
If this sounds mundane, great! Getting a build working and getting a working development environment set up should be a mundane task, but it's often incredibly frustrating once you need to set up libraries outside those provided by your language, or once you need to take into account different operating systems or CPU architectures.
Let's examine in detail how flox
allowed you to immediately get up and running on this project.
Package build¶
This repository contains a Rust crate that queries the Rust homepage by linking against libcurl
rather than calling the curl
command as a subprocess.
In order for this to work a number of things have to be configured correctly for each developer working on the project:
- Everyone must have compatible versions of
libcurl
- Everyone must have
libcurl
installed in a location that build tools can find - Everyone must have compatible versions of all of
libcurl
's transitive dependencies installed and locatable - Compatible versions of any platform-specific dependencies must be installed and locatable
Satisfying these conditions across multiple machines running on the same platform is already difficult, let alone across multiple operating systems and CPU architectures.
flox
handles many of these details for you with minimal involvement on your part.
Once someone creates a build definition that works on a given platform, the software will build for everyone else on that same platform.
Compiling this crate on macOS requires platform-specific dependencies.
flox
allows you to specify those as well.
Again, once the build definition is updated to build on one macOS machine, it will build on all of the other macOS machines running the same CPU architecture.
Development environment¶
The flox develop
command places you in a shell capable of building the package and optionally includes other software that you need for development such as linters, language servers, etc.
When you used flox develop
to enter the development shell for this particular project you were automatically provided with:
rust-analyzer
(Rust language server implementation),clippy
(linter), andrustfmt
(formatter) for code intelligence and autoformatting- As part of this, the
RUST_SRC_PATH
environment variable was set correctly for use byrust-analyzer
- As part of this, the
cargo-watch
so that you can automatically run tests or other commands when your code changescargo-semver-checks
to automatically detect semver-breaking changescargo-flamegraph
to collect CPU profiling datajust
(a command runner) and aJustfile
for running project-specific tasks
Onboarding a new developer now means running flox develop
instead of a day or two following out of date installation instructions and onboarding documentation.
With flox your instructions for setting up a development environment never fall out of date because the development environment is the same as the build environment!
Where to next?¶
-
Create developer environments with project environments.
-
Learn how to share and reuse flox environments.