Challenges in Building Documentation for ez-ffmpeg on docs.rs Due to FFmpeg 7.1 Dependency

[YeautyYE]

Crate name

ez-ffmpeg​

Build failure link

https://docs.rs/crate/ez-ffmpeg/0.1.0/builds/1833652

Additional details

Issue:

In the previous issue (#2765), I highlighted the challenges faced while generating documentation for ez-ffmpeg on docs.rs. Specifically, the build process fails due to the absence of FFmpeg 7.1 in the current build environment. In version 0.1.1 of ez-ffmpeg, we enabled the build feature of ffmpeg-sys-next to compile FFmpeg 7.1 during the build process. However, this approach requires network access to clone the FFmpeg source code, which is restricted in the docs.rs environment.

Previous Attempts:

In version 0.1.0, we attempted to build the documentation without initiating network requests, but this resulted in build failures due to missing components in the default environment. The build log detailing these errors can be found here: https://docs.rs/crate/ez-ffmpeg/0.1.0/builds/1833652

Reason for Submitting a New Issue:

The previous issue was closed without a resolution that allows ez-ffmpeg to build its documentation successfully on docs.rs. Given the importance of having accessible documentation for users of the crate, I am submitting this new issue to seek further guidance and potential solutions.

Potential Solutions:

1. Add FFmpeg 7.1 to crates-build-env: Integrating FFmpeg 7.1 into the crates-build-env Docker image would allow projects like ez-ffmpeg to build successfully without requiring network access during the docs.rs documentation generation process. We are willing to contribute by submitting a pull request to include FFmpeg 7.1 in the build environment.

2. Detect docs.rs Environment in Build Script: By checking for the DOCS_RS environment variable within the build.rs script, we can conditionally adjust the build process to accommodate the docs.rs environment. This approach would involve skipping network-dependent steps when the DOCS_RS variable is detected:

   fn main() {
       if std::env::var("DOCS_RS").is_ok() {
           // Adjust build process for docs.rs environment
       } else {
           // Regular build process
       }
   }

3. Utilize [package.metadata.docs.rs] Configuration: Leveraging the [package.metadata.docs.rs] section in Cargo.toml allows for customization of the documentation build process on docs.rs. This configuration can specify features to be enabled or dependencies to be adjusted specifically for the docs.rs environment.

Request for Guidance:

We seek advice on the feasibility of the proposed solutions or any alternative recommendations to successfully generate documentation for ez-ffmpeg on docs.rs. Specifically:

• Is adding FFmpeg 7.1 to the crates-build-env a viable solution, and would such a contribution be accepted?

• Are there best practices for configuring the build script or Cargo.toml to handle the absence of network access during the docs.rs build process?

Environment Details:

• rustc version: 1.87.0-nightly (b74da9613 2025-03-06)

• docs.rs version: 0.6.0 (004a02c 2025-03-05)

We appreciate your time and assistance in resolving this issue.

[syphar]

you could have just reopened the old issue, or commented on it, I don't have new information for you.

Is adding FFmpeg 7.1 to the crates-build-env a viable solution, and would such a contribution be accepted?

of course, otherwise I wouldn't have proposed it? one caveat: we only accept adding packages from the ubuntu repositories. Please also check if rust-lang/crates-build-env#168 might perhaps already include the ffmpeg version you need.

Are there best practices for configuring the build script or Cargo.toml to handle the absence of network access during the docs.rs build process?

I feel like I'm repeating myself :)

From my last comment:

either vendor the source
or
using https://docs.rs/about/metadata to build a version of the crate that doesn't need the third party source, and builds just what's needed for the docs. This would be what you call " allow skipping or handling the network-dependent build step", and would be a change to ffmpeg-sys-next.

I don't have specific examples, but any -sys crate will have chosen one of the solutions.

[YeautyYE]

Apologies for opening a new issue; I do not have the necessary permissions to reopen previously closed issues. I will attempt to add FFmpeg 7 to rust-lang/crates-build-env. If successful, I will close this issue. Thank you for your understanding.​

[syphar]

please check first if the new version perhaps isn't already in rust-lang/crates-build-env#168

[YeautyYE]

Apologies for any confusion earlier. Upon reviewing the proposed update to Ubuntu 24.04 (Noble) in rust-lang/crates-build-env#168, I have observed that certain FFmpeg libraries are currently at older versions within the build environment. Specifically:

• libavcodec is at version 60, whereas version 61 is available.
• libavdevice is at version 60, with version 61 available.
• libavfilter is at version 9, with version 10 available.
• libavutil is at version 58, whereas version 59 is available.

Upgrading these libraries to their respective latest versions within the build environment would ensure compatibility with FFmpeg 7.0 and its features.

Could you please consider updating these libraries in the build environment to support FFmpeg 7.0? This upgrade would enhance compatibility and functionality for projects relying on the latest FFmpeg features.

Thank you for your attention to this matter.

[syphar]

I have observed that certain FFmpeg libraries are currently at older versions within the build environment.

do you mean they are old in the current build environment? or that they are also old in the PR?

Could you please consider updating these libraries in the build environment to support FFmpeg 7.0? This upgrade would enhance compatibility and functionality for projects relying on the latest FFmpeg features.

are they available as ubuntu package in 24.04? If yes, you will have them then. If not, we won't add them to the build image for now. Any custom installation step would be too much of a maintenance burden for our already very small team.

If it's not available as ubuntu package, the remaining options are (as stated above):

• vendor the necessary files into the crate (in this case, the ffmpeg-sys-next crate)
• use conditional compilation / docs.rs metadata to make the crate compile without ffmpeg available, just for the docs.

[YeautyYE]

Thank you for your input. I apologize for the confusion—I realized that my previous lookup was based on Ubuntu 24.10. At this point, it appears that for Ubuntu 24.04 the necessary FFmpeg 7.0 packages are not available as Ubuntu packages. Consequently, I'll need to explore alternative solutions (such as vendoring the required files into the crate or using conditional compilation for docs) to address this issue.

[YeautyYE]

I tried using the FFmpeg packages available on Ubuntu 24.04, but they only provide version 6.0, which doesn't meet the requirement for my code.
I then attempted to include the precompiled FFmpeg libraries directly in my project under the third_party directory. However, these libraries are at least 20MB in size, which exceeds crates.io's 10MB upload limit.
Using conditional compilation isn't a viable option here because our code is fundamentally dependent on FFmpeg.
Is there any alternative approach or workaround you could recommend for this scenario?

Thanks for your help!

[GuillaumeGomez]

You don't actually need to have the C lib around to get docs, there are many ways to go around this limitation.

By using cfg(doc) (or any feature, I'd recommend a docs-rs feature instead), you can make it so that the C-lib items are defined but empty. If you do it in a macro, you can generate both definitions in one place.

[YeautyYE]

By using cfg(doc) (or any feature, I'd recommend a docs-rs feature instead), you can make it so that the C-lib items are defined but empty. If you do it in a macro, you can generate both definitions in one place.

Thanks for the suggestion! I appreciate your input and will try to implement a solution using cfg(doc) (or a dedicated docs‑rs feature) to provide stub definitions for the C library items so that the docs can be generated without the actual FFmpeg library.

Just to clarify, when you mention a "docs‑rs feature," do you mean a Cargo feature that is enabled specifically during docs.rs builds (for example, via the [package.metadata.docs.rs] configuration)? My understanding is that such a feature would allow us to conditionally compile empty definitions for the FFmpeg-related items (using something like #[cfg(feature = "docs-rs")]), making the library compile for documentation purposes without needing the full C library. Any additional insights on this approach would be greatly appreciated!

Thanks again for your help.

[GuillaumeGomez]

Exactly, a feature enabled via [package.metadata.docs.rs]. And yes, the point is to allow you to build without actually needing the C library. I did that for a few crates of mine binding proprietary C libs.

[YeautyYE]

Exactly, a feature enabled via [package.metadata.docs.rs]. And yes, the point is to allow you to build without actually needing the C library. I did that for a few crates of mine binding proprietary C libs.

Thank you very much for your suggestion! With your advice, I was able to use conditional compilation to avoid compiling the high-version FFmpeg API that isn’t supported in the docs.rs environment—while still linking against the FFmpeg library in normal builds. This solution enabled docs.rs to generate the documentation correctly. I really appreciate your invaluable help!