From c6b35f8f2e83621b4e53ab999e5b5bf146a73aa0 Mon Sep 17 00:00:00 2001 From: Klaus Aehlig Date: Wed, 26 Jun 2024 15:46:09 +0200 Subject: Add minimal example using cargo ... including a test (for which we add python3 as test dependency). --- src/rust/cargo/README.md | 45 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) create mode 100644 src/rust/cargo/README.md (limited to 'src/rust/cargo/README.md') diff --git a/src/rust/cargo/README.md b/src/rust/cargo/README.md new file mode 100644 index 0000000..5ac8e27 --- /dev/null +++ b/src/rust/cargo/README.md @@ -0,0 +1,45 @@ +# Importing cargo dependencies + +The [rules for rust](https://github.com/just-buildsystem/rules-rust) also +bring a tool to import dependencies from cargo. Here we give an overview of +its usage, using the subidrectory `circle` as a dependency. + +## Files written by hand + +Cargo dependencies are described as dependencies of a crate. So all the +files you would normally write by hand when writing a crate have to be +manually added. As we define a binary, those are + - `Cargo.toml`, and + - `src/main.rs`. + +## Using `just-import-cargo` + +As other import tools, `just-import-cargo` expects a repository specification +on standard input and returns one on standard output. It needs to know + - the root of the pyhsical repository, and + - the location of the crate directory, relative to the root of the physical + repository. + - the name of the already imported `rules-rust` repository. + +While the tool in general can also import `rules-rust` itself, we need to import +the rules manually first, as we have to provide our own target root for the +defaults. Future versions of the rules might bring a defaults target suitable +for our use case, but so far this is not the case. + +The name of the imported main repository is the crate name (without version), +as specified in the `Cargo.toml` file. Some care should be taken that is does +not conflict with already existing repositories; repositories from the +`etc/repos.templace.json` can have a binding to that still to be imported +repository, as usual. + +As opposed to other import tools, however, `just-import-cargo` also creates +files in the pysical repository. Those are the following. + - In the crate the file `Cargo.lock` generated by the call to cargo, as + well as a target file, + - The file `etc/defaults/rust/TARGETS` relative to in the top-level of the + physical repository (with a content independent of the respective crate). + This file is the reason that our `rules-rust/nix` use `nix.TARGETS` as + target-file name. + - In the directory `etc/deps-rust` target files for all the imported crates. + As their name encode crate name and version, calling `just-import-cargo` + for several crates should not cause a conflict here. -- cgit v1.2.3