From 8dae0201e0022c4cc5d3e7278cde7b99f2eae30f Mon Sep 17 00:00:00 2001 From: Ruben Arts Date: Wed, 10 Apr 2024 15:45:10 +0200 Subject: [PATCH 01/11] docs(tutorial): add rust tutorial including openssl example --- docs/tutorials/ros2.md | 5 +- docs/tutorials/rust.md | 152 +++++++++++++++++++++++++++++++++++++++++ mkdocs.yml | 1 + 3 files changed, 156 insertions(+), 2 deletions(-) create mode 100644 docs/tutorials/rust.md diff --git a/docs/tutorials/ros2.md b/docs/tutorials/ros2.md index e873a1fd3..dc7014558 100644 --- a/docs/tutorials/ros2.md +++ b/docs/tutorials/ros2.md @@ -11,8 +11,9 @@ The audience for this tutorial is developers who are familiar with ROS 2 and how The crux of this tutorial is to show you only need pixi! - On Windows, it's advised to enable Developer mode. Go to Settings -> Update & Security -> For developers -> Developer mode. -If you're new to pixi, you can check out the [basic usage](../basic_usage.md) guide. -This will teach you the basics of pixi project within 3 minutes. +!!! note "" + If you're new to pixi, you can check out the [basic usage](../basic_usage.md) guide. + This will teach you the basics of pixi project within 3 minutes. ## Create a pixi project. diff --git a/docs/tutorials/rust.md b/docs/tutorials/rust.md new file mode 100644 index 000000000..352bb16e2 --- /dev/null +++ b/docs/tutorials/rust.md @@ -0,0 +1,152 @@ +# 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. + +!!! note "" + If you're new to pixi, you can check out the [basic usage](../basic_usage.md) 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](../index.md). + The crux of this tutorial is to show you only need pixi! + +## Create a pixi project. + +```shell +pixi init my_rust_project +cd my_rust_project +``` + +It should have created a directory structure like this: + +```shell +my_rust_project +├── .gitattributes +├── .gitignore +└── pixi.toml +``` + +The `pixi.toml` file is the manifest file for your project. It should look like this: + +```toml title="pixi.toml" +[project] +name = "my_rust_project" +version = "0.1.0" +description = "Add a short description here" +authors = ["User Name "] +channels = ["conda-forge"] +platforms = ["linux-64"] + +[tasks] + +[dependencies] +``` + +## 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. +```shell +pixi add rust +``` + +This will add the `rust` package to your `pixi.toml` file. + +## Add a `cargo` project +As you now have rust installed, you can create a `cargo` project in your `pixi` project. +```shell +pixi run cargo init +``` + +Now we can build a `cargo` project using `pixi`. +```shell +pixi run cargo build +``` +To simplify the build process, you can add a `build` task to your `pixi.toml` file using the following command: +```shell +pixi task add build "cargo build" +``` +Which creates this field in the `pixi.toml` file: +```toml title="pixi.toml" +[tasks] +build = "cargo build" +``` + +And now you can build your project using: +```shell +pixi run build +``` + +You can also run your project using: +```shell +pixi run cargo run +``` +Which you can simplify with a task again. +```shell +pixi task add start "cargo run" +``` + +So you should get the following output: +```shell +pixi run start +Hello, world! +``` + +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 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: +```shell +pixi run cargo add git2 +``` + +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: +```shell +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`. +... +``` +You can fix this with pixi: +```shell +pixi add openssl pkg-config compilers +``` + +Now you can build your project again: +```shell +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` +``` diff --git a/mkdocs.yml b/mkdocs.yml index b7257542b..923c3f05b 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -104,6 +104,7 @@ nav: - RStudio: ide_integration/r_studio.md - Tutorials: - ROS 2: tutorials/ros2.md + - Rust: tutorials/rust.md - Examples: - C++/Cmake: examples/cpp-sdl.md - OpenCV: examples/opencv.md From 204a42d552b49e2abd159889817f3c843144c2a5 Mon Sep 17 00:00:00 2001 From: Ruben Arts Date: Fri, 12 Apr 2024 16:05:27 +0200 Subject: [PATCH 02/11] Update docs/tutorials/rust.md Co-authored-by: Tim de Jager --- docs/tutorials/rust.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorials/rust.md b/docs/tutorials/rust.md index 352bb16e2..95fcc23f6 100644 --- a/docs/tutorials/rust.md +++ b/docs/tutorials/rust.md @@ -53,7 +53,7 @@ To use a pixi project you don't need any dependencies on your system, all the de pixi add rust ``` -This will add the `rust` package to your `pixi.toml` file. +This will add the `rust` package to your `pixi.toml` file. Which includes the `rust` toolchain, and `cargo`. ## Add a `cargo` project As you now have rust installed, you can create a `cargo` project in your `pixi` project. From 62653c8b0741bea5af44ecaabf2ed0814cb1d0fe Mon Sep 17 00:00:00 2001 From: Ruben Arts Date: Fri, 12 Apr 2024 16:05:33 +0200 Subject: [PATCH 03/11] Update docs/tutorials/rust.md Co-authored-by: Tim de Jager --- docs/tutorials/rust.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorials/rust.md b/docs/tutorials/rust.md index 95fcc23f6..bd3a30a9f 100644 --- a/docs/tutorials/rust.md +++ b/docs/tutorials/rust.md @@ -56,7 +56,7 @@ pixi add rust This will add the `rust` package to your `pixi.toml` file. Which includes the `rust` toolchain, and `cargo`. ## Add a `cargo` project -As you now have rust installed, you can create a `cargo` project in your `pixi` project. +Now that you have rust installed, you can create a `cargo` project in your `pixi` project. ```shell pixi run cargo init ``` From 41b966d3ef84c5bd38f161176f39837f5f6e2f5c Mon Sep 17 00:00:00 2001 From: Ruben Arts Date: Fri, 12 Apr 2024 16:05:39 +0200 Subject: [PATCH 04/11] Update docs/tutorials/rust.md Co-authored-by: Tim de Jager --- docs/tutorials/rust.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorials/rust.md b/docs/tutorials/rust.md index bd3a30a9f..acb9a5cf6 100644 --- a/docs/tutorials/rust.md +++ b/docs/tutorials/rust.md @@ -95,7 +95,7 @@ pixi run start Hello, world! ``` -Congratulations you have a Rust project running on your machine with pixi! +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 package manager. From a985667d0bcd46daf37de2be5efb95a052e319d8 Mon Sep 17 00:00:00 2001 From: Ruben Arts Date: Fri, 12 Apr 2024 16:05:45 +0200 Subject: [PATCH 05/11] Update docs/tutorials/rust.md Co-authored-by: Tim de Jager --- docs/tutorials/rust.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorials/rust.md b/docs/tutorials/rust.md index acb9a5cf6..7eee27b98 100644 --- a/docs/tutorials/rust.md +++ b/docs/tutorials/rust.md @@ -98,7 +98,7 @@ Hello, world! 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 package manager. +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. From f808ea5db712484aa19cdc2dec520e39696801ba Mon Sep 17 00:00:00 2001 From: Ruben Arts Date: Fri, 12 Apr 2024 16:06:03 +0200 Subject: [PATCH 06/11] Update docs/tutorials/rust.md Co-authored-by: Tim de Jager --- docs/tutorials/rust.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorials/rust.md b/docs/tutorials/rust.md index 7eee27b98..b2115b62d 100644 --- a/docs/tutorials/rust.md +++ b/docs/tutorials/rust.md @@ -136,7 +136,7 @@ could not be found. If you have OpenSSL installed you can likely fix this by installing `pkg-config`. ... ``` -You can fix this with pixi: +You can fix this, by adding some dependencies, with pixi: ```shell pixi add openssl pkg-config compilers ``` From 7606145f6c67d37cc42722158984eebf5ae7eb4c Mon Sep 17 00:00:00 2001 From: Ruben Arts Date: Fri, 12 Apr 2024 16:06:17 +0200 Subject: [PATCH 07/11] Update docs/tutorials/rust.md Co-authored-by: Tim de Jager --- docs/tutorials/rust.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/tutorials/rust.md b/docs/tutorials/rust.md index b2115b62d..349c492c1 100644 --- a/docs/tutorials/rust.md +++ b/docs/tutorials/rust.md @@ -4,6 +4,7 @@ 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`. !!! note "" If you're new to pixi, you can check out the [basic usage](../basic_usage.md) guide. From c4493fef57445e8c19f83acdc7c3d89ca8c01585 Mon Sep 17 00:00:00 2001 From: Ruben Arts Date: Fri, 12 Apr 2024 16:06:22 +0200 Subject: [PATCH 08/11] Update docs/tutorials/rust.md Co-authored-by: Tim de Jager --- docs/tutorials/rust.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorials/rust.md b/docs/tutorials/rust.md index 349c492c1..34f65c8c3 100644 --- a/docs/tutorials/rust.md +++ b/docs/tutorials/rust.md @@ -142,7 +142,7 @@ You can fix this, by adding some dependencies, with pixi: pixi add openssl pkg-config compilers ``` -Now you can build your project again: +Now you should be able to build your project again: ```shell pixi run build ... From 9b981cec0903b96a2fc790bf0be08b6110f164f5 Mon Sep 17 00:00:00 2001 From: Ruben Arts Date: Fri, 12 Apr 2024 16:07:12 +0200 Subject: [PATCH 09/11] Update docs/tutorials/rust.md Co-authored-by: Tim de Jager --- docs/tutorials/rust.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorials/rust.md b/docs/tutorials/rust.md index 34f65c8c3..ee53387b6 100644 --- a/docs/tutorials/rust.md +++ b/docs/tutorials/rust.md @@ -113,7 +113,7 @@ pixi run cargo add git2 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: ```shell 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 From 9030e14b46e88dbb7578bd22c33e048b179c3eda Mon Sep 17 00:00:00 2001 From: Ruben Arts Date: Fri, 12 Apr 2024 16:33:32 +0200 Subject: [PATCH 10/11] docs: improve rust tutorial --- docs/tutorials/rust.md | 52 ++++++++++++++++++++++++++++++++++++++---- 1 file changed, 47 insertions(+), 5 deletions(-) diff --git a/docs/tutorials/rust.md b/docs/tutorials/rust.md index ee53387b6..d4b998f00 100644 --- a/docs/tutorials/rust.md +++ b/docs/tutorials/rust.md @@ -33,20 +33,22 @@ my_rust_project The `pixi.toml` file is the manifest file for your project. It should look like this: -```toml title="pixi.toml" +```toml title="pixi.toml" [project] name = "my_rust_project" version = "0.1.0" description = "Add a short description here" authors = ["User Name "] channels = ["conda-forge"] -platforms = ["linux-64"] +platforms = ["linux-64"] # (1)! [tasks] [dependencies] ``` +1. 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. @@ -54,7 +56,8 @@ To use a pixi project you don't need any dependencies on your system, all the de pixi add rust ``` -This will add the `rust` package to your `pixi.toml` file. Which includes the `rust` toolchain, and `cargo`. +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. @@ -62,6 +65,10 @@ Now that you have rust installed, you can create a `cargo` project in your `pixi pixi run cargo init ``` +`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](../features/advanced_tasks.md). +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`. ```shell pixi run cargo build @@ -113,7 +120,7 @@ pixi run cargo add git2 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: ```shell 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 @@ -137,7 +144,7 @@ could not be found. If you have OpenSSL installed you can likely fix this by installing `pkg-config`. ... ``` -You can fix this, by adding some dependencies, with pixi: +You can fix this, by adding the necessary dependencies for building git2, with pixi: ```shell pixi add openssl pkg-config compilers ``` @@ -151,3 +158,38 @@ pixi run build 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: +```shell +pixi task add test "cargo test" +``` + +And you can add a `clean` task to clean your project: +```shell +pixi task add clean "cargo clean" +``` + +You can add a formatting task to your project: +```shell +pixi task add fmt "cargo fmt" +``` + +You can extend these tasks to run multiple commands with the use of the `depends_on` field. +```shell +pixi task add lint "cargo clippy" --depends-on fmt +``` + +## 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! From 2388c18593e68b07bd181977c0a19b3bd89b924e Mon Sep 17 00:00:00 2001 From: Ruben Arts Date: Fri, 12 Apr 2024 16:36:11 +0200 Subject: [PATCH 11/11] docs: take call to action to ros2 tutorial --- docs/tutorials/ros2.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/docs/tutorials/ros2.md b/docs/tutorials/ros2.md index dc7014558..eaff371de 100644 --- a/docs/tutorials/ros2.md +++ b/docs/tutorials/ros2.md @@ -209,6 +209,17 @@ pixi run ros2 run my_cpp_package my_cpp_node pixi task add hello-cpp "ros2 run my_cpp_package my_cpp_node" ``` +## Conclusion +In this tutorial, we showed you how to create a Python & CMake ROS2 project using `pixi`. +We also showed you how to **add dependencies** to your project using `pixi`, and how to **run your project** using `pixi run`. +This way you can make sure that your project is **reproducible** on all your machines that have `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! + ## Frequently asked questions ### What happens with `rosdep`?