Tutorial: Develop a Rust package using pixi
#
In this tutorial, we will show you how to develop a Rust package using pixi
.
The tutorial is written to be executed from top to bottom, missing steps might result in errors.
The audience for this tutorial is developers who are familiar with Rust and cargo
and how are interested to try pixi for their development workflow.
The benefit would be within a rust workflow that you lock both rust and the C/System dependencies your project might be using. E.g tokio users will almost most definitely use openssl
.
If you're new to pixi, you can check out the basic usage guide. This will teach you the basics of pixi project within 3 minutes.
Prerequisites#
- You need to have
pixi
installed. If you haven't installed it yet, you can follow the instructions in the installation guide. The crux of this tutorial is to show you only need pixi!
Create a pixi project.#
It should have created a directory structure like this:
The pixi.toml
file is the manifest file for your project. It should look like this:
[project]
name = "my_rust_project"
version = "0.1.0"
description = "Add a short description here"
authors = ["User Name <user.name@email.url>"]
channels = ["conda-forge"]
platforms = ["linux-64"] # (1)!
[tasks]
[dependencies]
- The
platforms
is set to your system's platform by default. You can change it to any platform you want to support. e.g.["linux-64", "osx-64", "osx-arm64", "win-64"]
.
Add Rust dependencies#
To use a pixi project you don't need any dependencies on your system, all the dependencies you need should be added through pixi, so other users can use your project without any issues.
This will add the rust
package to your pixi.toml
file under [dependencies]
.
Which includes the rust
toolchain, and cargo
.
Add a cargo
project#
Now that you have rust installed, you can create a cargo
project in your pixi
project.
pixi run
is pixi's way to run commands in the pixi
environment, it will make sure that the environment is set up correctly for the command to run.
It runs its own cross-platform shell, if you want more information checkout the tasks
documentation.
You can also activate the environment in your own shell by running pixi shell
, after that you don't need pixi run ...
anymore.
Now we can build a cargo
project using pixi
.
build
task to your pixi.toml
file using the following command:
Which creates this field in the pixi.toml
file:
And now you can build your project using:
You can also run your project using:
Which you can simplify with a task again.So you should get the following output:
Congratulations, you have a Rust project running on your machine with pixi!
Next steps, why is this useful when there is rustup
?#
Cargo is not a binary package manager, but a source-based package manager.
This means that you need to have the Rust compiler installed on your system to use it.
And possibly other dependencies that are not included in the cargo
package manager.
For example, you might need to install openssl
or libssl-dev
on your system to build a package.
This is the case for pixi
as well, but pixi
will install these dependencies in your project folder, so you don't have to worry about them.
Add the following dependencies to your cargo project:
If your system is not preconfigured to build C and have the libssl-dev
package installed you will not be able to build the project:
pixi run build
...
Could not find directory of OpenSSL installation, and this `-sys` crate cannot
proceed without this knowledge. If OpenSSL is installed and this crate had
trouble finding it, you can set the `OPENSSL_DIR` environment variable for the
compilation process.
Make sure you also have the development packages of openssl installed.
For example, `libssl-dev` on Ubuntu or `openssl-devel` on Fedora.
If you're in a situation where you think the directory *should* be found
automatically, please open a bug at https://github.com/sfackler/rust-openssl
and include information about your system as well as this message.
$HOST = x86_64-unknown-linux-gnu
$TARGET = x86_64-unknown-linux-gnu
openssl-sys = 0.9.102
It looks like you're compiling on Linux and also targeting Linux. Currently this
requires the `pkg-config` utility to find OpenSSL but unfortunately `pkg-config`
could not be found. If you have OpenSSL installed you can likely fix this by
installing `pkg-config`.
...
Now you should be able to build your project again:
pixi run build
...
Compiling git2 v0.18.3
Compiling my_rust_project v0.1.0 (/my_rust_project)
Finished dev [unoptimized + debuginfo] target(s) in 7.44s
Running `target/debug/my_rust_project`
Extra: Add more tasks#
You can add more tasks to your pixi.toml
file to simplify your workflow.
For example, you can add a test
task to run your tests:
And you can add a clean
task to clean your project:
You can add a formatting task to your project:
You can extend these tasks to run multiple commands with the use of the depends-on
field.
Conclusion#
In this tutorial, we showed you how to create a Rust project using pixi
.
We also showed you how to add dependencies to your project using pixi
.
This way you can make sure that your project is reproducible on any system that has pixi
installed.
Show Off Your Work!#
Finished with your project? We'd love to see what you've created! Share your work on social media using the hashtag #pixi and tag us @prefix_dev. Let's inspire the community together!