Skip to content

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: 

...$ cargo clippy
...Finished dev [unoptimized + debuginfo] target(s) in ...
Nope, everything looks good.

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: 

...$ just profile
...
writing flamegraph to "flamegraph.svg"
You can open the 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: 

...$ exit
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), and rustfmt (formatter) for code intelligence and autoformatting
    • As part of this, the RUST_SRC_PATH environment variable was set correctly for use by rust-analyzer
  • cargo-watch so that you can automatically run tests or other commands when your code changes
  • cargo-semver-checks to automatically detect semver-breaking changes
  • cargo-flamegraph to collect CPU profiling data
  • just (a command runner) and a Justfile 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?