README.md

# Pigweed Rust Third Party Crates

This is a repository to vendor and provide build rules for the third party
crates that Pigweed's rust code depends on. Currently only Bazel build rules are
provided.

## `std` and `no_std`

This repository provides two separate sets of crates. One for `std` environments
and one for `no_std` environments. The set that is used is determined by the
`//:std_enabled` constraint setting and defaults to `std`. To use `no_std` add
`@rust_crates//:no_std` to your platform definition.

## Adding and Updating the Crates

The list of vendored crates is defined by the dependencies listed in
[//crates/Cargo.toml](crates/Cargo.toml) and
[//crates_std/Cargo.toml](crates_std/Cargo.toml). The
contents of the `//crates` and `//crates_std` directories are generated by the
`//:crates_vendor` and `//:crates_vendor_std` targets.

To update the vendored crates, build files, and aliases to match run the following commands from the
top level directory of the repository:

```bash
bazel run //:crates_vendor -- --repin
bazel run //:crates_vendor_std -- --repin
cargo run -- --config config.toml > aliases.bzl
```

Licenses can be checked with `cargo license -d` in the appropriate stub_crate.

## Markdown Formatting

We keep this, and all Markdown files in this repository, in a consistent
Markdown format using [mdformat](https://pypi.org/project/mdformat). To install
and format, use the following commands:

```bash
pip install mdformat-gfm
mdformat README.md
```

## FAQ

### collect2: fatal error: cannot find 'ld' error

```
  = note: collect2: fatal error: cannot find 'ld'
          compilation terminated.
```

If you get the above error when running `bazel run //:crates_vendor -- --repin`,
ensure `lld` is installed on your system. For instance, on Debian based systems:

```
sudo apt install lld
```

### env: Studio: No such file or directory

An error like above is cause by having a directory in your `$PATH` containing
a space.  `rules_rust`'s wrapper script around vendoring does not properly
escape the path.

Workaround: remove directories containing spaces from your `$PATH`.