search

time-rs / time

The most used Rust library for date and time handling.
https://time-rs.github.io
Apache License 2.0
1.13k stars 281 forks source link

Split the `time` crate #350

Open jhpratt opened 3 years ago

jhpratt commented 3 years ago

The main time crate can be moved to time-core, while the formatting and parsing mechanism (including parsing format descriptions) can be moved to the time-formatting crate. At that point, the time crate could re-export everything from time-core, time-formatting, and time-macros, behind feature gates as appropriate. Implementations of internal helper traits in time-macros can be accomplished via a newtype.

The primary advantage of doing this is that the time-macros crate will no longer have to duplicate logic for a sizable number of items. Thus this change in structure will be an overall reduction in code. I believe that it will also improve compile-times, although this is already decent. Certainly the largest advantage is that because of the deduplication the macros will always be in sync with the core crate. This ensures that something can't exist in one and not the other.

These sub-crates, like time-macros, will not be intended for direct usage and should be considered an unstable implementation detail.

The time-formatting crate is blocked on rust-lang/cargo#8832; interaction between features would be far from ideal until this is stabilized (for six months per MSRV guarantees). Another blocker that I don't believe there is an issue for — if it's even desired — is having #[doc(cfg(…))] visible on re-exports. Without this a user may think that an API is available when it isn't. I'm guaranteeing that the feature flags in time, time-core, etc. all match but the compiler is unaware of this and thus removes the annotation in its entirety.

jhpratt commented 2 years ago

The primary blocker of weak dependencies will land in Rust 1.60, reaching MSRV on 2022-10-07. At some point before then I'll investigate the #[doc(cfg(…))] on re-exports and the potential for cyclical dependencies.

jhpratt commented 2 years ago

Looking into the #[doc(cfg(…))] story. Unfortunately it works the way I expected, which functionally means that the annotations are not visible because the re-exporting crate doesn't have anything behind a gate. This is inherent to the way workspaces work, so I don't see this changing any time soon.

For what it's worth, I may still go ahead and just hack some raw HTML into the definitions to simulate the existing annotations. The improvement in code structure may make it worthwhile.