# 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.