error[E0277]: the trait bound `*::*Encoder<W>: std::io::Write` is not satisfied

[sorairolake]

When I tried to build the documentation for zip crate v1.3.0 (cargo doc), the following errors occurred:

error[E0277]: the trait bound `deflate::DeflateEncoder<W>: std::io::Write` is not satisfied
  --> zopfli-0.8.0/src/deflate.rs:63:73
   |
63 |     pub fn new_buffered(options: Options, btype: BlockType, sink: W) -> std::io::BufWriter<Self> {
   |                                                                         ^^^^^^^^^^^^^^^^^^^^^^^^ the trait `std::io::Write` is not implemented for `deflate::DeflateEncoder<W>`
   |
note: required by a bound in `std::io::BufWriter`
  --> library/std/src/io/buffered/bufwriter.rs:69:1

error[E0277]: the trait bound `gzip::GzipEncoder<W>: std::io::Write` is not satisfied
  --> zopfli-0.8.0/src/gzip.rs:48:17
   |
48 |     ) -> Result<std::io::BufWriter<Self>, Error> {
   |                 ^^^^^^^^^^^^^^^^^^^^^^^^ the trait `std::io::Write` is not implemented for `gzip::GzipEncoder<W>`
   |
note: required by a bound in `std::io::BufWriter`
  --> library/std/src/io/buffered/bufwriter.rs:69:1

error[E0277]: the trait bound `zlib::ZlibEncoder<W>: std::io::Write` is not satisfied
  --> zopfli-0.8.0/src/zlib.rs:43:17
   |
43 |     ) -> Result<std::io::BufWriter<Self>, Error> {
   |                 ^^^^^^^^^^^^^^^^^^^^^^^^ the trait `std::io::Write` is not implemented for `zlib::ZlibEncoder<W>`
   |
note: required by a bound in `std::io::BufWriter`
  --> library/std/src/io/buffered/bufwriter.rs:69:1

For more information about this error, try `rustc --explain E0277`.
error: could not document `zopfli`
warning: build failed, waiting for other jobs to finish...

This error seems to occur at least since Rust 1.76.0.^1 There is no problem at least as of Rust 1.74.0, so the error may be caused by the standard library rather than this crate.

Environment:

$ cargo --version
cargo 1.78.0 (54d8815d0 2024-03-26)
$ rustc --version
rustc 1.78.0 (9b00956e5 2024-04-29)

[AlexTMjugador]

Thank you for reporting this! I remember opening an issue on the Rust repository about similar Zopfli documentation build problems many months ago: https://github.com/rust-lang/rust/issues/117796.

Back then, I worked around rustdoc changes by adding explicit trait implementations, but I wasn't convinced rustdoc was moving in a good direction for crates with intricate feature combinations.

This issue might be unrelated, but I find it frustrating to figure out the root cause and then work around changes that break things that used to work. Documentation is for human consumption, it's already grunt enough work to keep it relevant and up to date, and it should be generated even if the code is slightly invalid, especially given Rust's commitment to "stability without stagnation." (Though that doesn't apply to nightlies, you have to deal with nightlies if you want your docs to show up on docs.rs, so you practically don't have much of a choice.)

I could tackle this at some point, but my bandwidth for open source work is very limited lately, so I have to prioritize using my free time for more fulfilling open source endeavors.

If someone else can dedicate the time to open a PR for this, it would be much appreciated. Given how increasingly busy everyone is, this is a steep ask, but if someone does submit it, I'll review and merge it.

[AlexTMjugador]

For the sake of completeness, I think it's worth mentioning that, while the issue I linked to mentions https://github.com/zopfli-rs/zopfli/commit/ed7c9cd5ee27d3c0174a471b2b333debcbb64247 as a fix, I tried running cargo doc --no-deps --all-features with the latest nightly, and it still does not work. This is due to an issue with simd-adler32, for which I contributed a fix upstream. Unfortunately, that fix hasn't been included in a release yet, so it can't be used with the Zopfli crate as published on crates.io:

The nightly feature enabled by --all-features is required during docs.rs documentation generation to leverage the unstable #[feature(doc_auto_cfg)] attribute. Although working around this issue by never enabling simd-adler32's nightly feature is not ideal, it seems to be the lesser of two evils, perhaps. The alternative is having Zopfli broken when the nightly feature is used due to SIMD intrinsics changes...

Some may argue that's what one gets by depending on nightly features, which technically are not stable. But let me say this: #[feature(doc_auto_cfg)] has been effectively stable for years, and is used by large projects like Bevy and wgpu. It’s unclear why it hasn’t been officially stabilized, aside from the matter possibly not getting the right attention from the right person.

On the other hand, given the popularity of compression algorithms using such a hash, I think simd-adler32 is a foundational crate in the Rust compression ecosystem. So I find it baffling that Rust developers made such breaking changes to SIMD without publicly reaching out to one of its major users, as far as I can see. Instead, the responsibility of keeping the lights on fell on me, a random kind developer on the Internet, to submit a PR to fix the issue. Unfortunately, the changes have yet to be published in a release, so the fix isn't even really fixing things.

But I think I've shared enough of my thoughts on the situation and might be getting a bit off-topic here. The bottom line is that, at the moment, Zopfli's rustdoc is stuck in nightly feature hell due to a combination of factors. Unfortunately, there aren’t any good ways to move forward until the ecosystem aligns, which is a problem beyond computer engineering, I'm afraid.

What's your situation with the zip crate? Maybe knowing a bit about it makes me feel less uncomfortable giving up on SIMD optimizations that only work on older nightlies anyway.

[mqudsi]

Regarding keeping docs compiling under all feature permutations: it’s indeed a nightmare. I embarked down that path before and even after I sorted out all the conditional attributes (and rewrote what would have been normal doc tests with arcane cgf_attr syntax instead) it ended up causing other issues in the ecosystem, eg https://github.com/rust-lang/rustfmt/issues/5420

[AlexTMjugador]

I didn't mention this here at the time I pushed it, but on the commit that fixed this issue I decided to just drop the simd-adler32 nightly flag.

While this may not be the best solution from a performance perspective, it's preferable to having Zopfli fail to build with updated nightly toolchains. On the bright side, Zopfli spends most of its execution time on actual compression in typical cases, so the concrete choice of block hasher implementation isn't that critical.

I'm looking forward to re-enabling the simd-adler32 nightly feature once its build issues are resolved in a future release.