Using the HAL as a git dependency

mciantyre commented 4 years ago

cargo lets us specify git dependencies. But today, if we try to depend on the HAL (or the RAL) using a git dependency, it won't work:

[dependencies.imxrt-hal]
git = "https://github.com/imxrt-rs/imxrt-rs.git"
features = ["imxrt1062"]

cargo build
    Updating git repository `https://github.com/imxrt-rs/imxrt-rs.git`
    Updating crates.io index
error: no matching package named `imxrt-ral` found
location searched: https://github.com/imxrt-rs/imxrt-rs.git#adc91a14
perhaps you meant: imxrt-hal
required by package `imxrt-hal v0.3.0 (https://github.com/imxrt-rs/imxrt-rs.git#adc91a14)`
    ... which is depended on by `krate v0.1.0 (/private/tmp/krate)`

We see the error because

the RAL is not tracked by git, and
the HAL depends on the RAL by a path. Git dependencies will follow dependency paths in the crate's Cargo.toml file, similar to how local development will follow paths.

Supporting git dependencies is nifty. Users can track development in the HAL, and depend on features before they're released. I used git dependencies when developing the imxrt-uart-log crate, developing against the unreleased DMA feature. I checked-in the RAL's source in my fork, since I also needed unreleased RAL features for the crate development. A new collaborator, @mitchmindtree, is also sharing Cargo patches in the teensy4-rs project using git dependencies (mciantyre/teensy4-rs#64). I noticed that Mitch removed the RAL's path in order to make patching with a git dependency work. If we had support for git dependencies in this repository, we wouldn't each need one-offs to support sharing new features.

To support using the HAL as a git dependency, I propose that we roll-back #15, and we include the RAL's source code in version control. I can see a few benefits:

we can use both the HAL, and also the RAL, as git dependencies.
collaborators don't necessarily need the Python environment to develop the HAL, which is one of today's requirements. If the RAL is checked in, users only need to run the auto-generation when making fundamental changes to the RAL.

The drawback is that the imxrtral.py auto-generation script could fall out of sync with the checked-in RAL. That is, we need to defend against users who manually changes a RAL source file without making the change in imxrtral.py. I'm still working through ideas that are better than "just do a code review." My current thinking is that there's a CI job that generates the RAL, but doesn't overwrite the checked-in contents. Rather, it diffs the checked-in contents from what was just generated. If they vary, we flag the build. This should signal that RAL changes should be described in imxrtral.py instead of direct modifications to the source.

Any other approaches or ideas we should consider? Let me know! I'd like support for git dependencies so that we can develop RTIC support (mciantyre/teensy4-rs#62) without having to formally release small-ish HAL changes.

mciantyre commented 4 years ago

I pushed two branches to my imxrt-rs fork to show that changing either of 1. or 2. can enable git dependencies.

the RAL is not tracked by git [...]

This branch checks in the RAL:

[dependencies.imxrt-hal]
git = "https://github.com/mciantyre/imxrt-rs.git"
branch = "proto/ral-check-in"
features = ["imxrt1062"]

the HAL depends on the RAL by a path [...]

This branch removes the path in the HAL's dependency:

[dependencies.imxrt-hal]
git = "https://github.com/mciantyre/imxrt-rs.git"
branch = "proto/hal-no-ral-path"
features = ["imxrt1062"]

mciantyre commented 4 years ago

With #67 on master, we can now use the HAL as a git dependency.

imxrt-rs / imxrt-hal

Using the HAL as a git dependency #65