Merge pull request #3 from aehlig/cargo-example

Add example on how to use cargo

1 files changed, 45 insertions, 0 deletions

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.