search

embassy-rs / embassy

Modern embedded framework, using Rust and async.
https://embassy.dev
Apache License 2.0
5.52k stars 767 forks source link

Is it still recommended to use git link in Cargo.toml? #3331

Open BjornTheProgrammer opened 1 month ago

BjornTheProgrammer commented 1 month ago

In the book, the current recommended method of using embassy inside your cargo project is to set a patch with its git link and revision. As seen below...

[dependencies]
embassy-time = { version = "0.2", features = ["defmt", "defmt-timestamp-uptime", "tick-hz-32_768"] }

[patch.crates-io]
embassy-time = { git = "https://github.com/embassy-rs/embassy", rev = "7703f47c1ecac029f603033b7977d9a2becef48c" }

This is 9 months old, and I'm wondering if this is still recommended.

If it is still recommended, why is that the case?

As far as I can tell, the versioning given by cargo ensures much more stability, and clarity of how old your dependencies are. It prevents issues of using the wrong revision. It is easier to set up. Additionally, you might accidentally use a revision of new, unstable, nonpolished code (which has happened to me). Moreover, you cannot push a crate to crates.io with a git link. Finally, it tells you if there are any breaking changes between versions.

If this is not recommended anymore, should I submit a pull request to update the docs?

YgorSouza commented 1 month ago

Should probably sort out #2936 first. For example, the embassy-stm32 crate still hasn't been updated since its initial release 8 months ago. Others have had more recent releases, but we can't count on them staying up to date and consistent with each other without a proper schedule.

Erhannis commented 2 weeks ago

On this topic - I'm trying to get Embassy set up in my project and BOY is it hard to tell how you're supposed to get started. Like, I saw there were different crates for different platforms, so I went to embassy-rp (didn't even realize there was a Book), found https://docs.embassy.dev/embassy-rp/git/rp2040/index.html , which didn't say what was supposed to go in the toml, but I saw the examples and their toml, but of course that had ALL the bells and whistles, presumably more than needed, so then I searched github for Cargo.toml that contained embassy-rp.... Perhaps embassy and each of its fragments (e.g. embassy-rp ) should have a "Getting Started" link pointing to https://embassy.dev/book/index.html#_getting_started ? "Documentation" isn't the link I'd normally click for the quick-start, and it didn't really help after I'd selected my platform anyway.

BjornTheProgrammer commented 2 weeks ago

I was working on a quick start cli, which generates a template based on your platform and while back. I don't know if this would help mitigate issues like that, but it seems like it might.

Erhannis commented 2 weeks ago

It would probably help - though I was trying to integrate embassy into an existing project, so, 50/50.