Hi there! We have a rust crate that uses gstreamer behind the feature gate. We want to host it’s documentation on docs.rs but it fails (build logs) to run custom build scripts. To fix this, I added the following in Cargo.toml:
After this also, the docs.rs fails (new build logs) but this time with a different error.
I also saw gstreamer-rs Merge Request !527 that implemented a different approach for building docs.rs for gstreamer itself.
I am not sure whats the recommended way for libraries here, could we have a feature gate or something that would make gstreamer at least build on docs.rs. Sorry, if it already exists.
The documentation built like this would not contain any of the actual API documentation that is included in the documentation here.
Reason for that is that going via just cargo doc does not allow injecting additional documentation from somewhere, and we can’t include the C documentation in the binding’s source code directly because that would automatically have them be covered by the LGPL.
Check the docs CI job for how to build the full documentation.
Running cargo doc should still work (just with fewer docs) as long as you pass the parameters you found (an MR adding those to Cargo.toml would be good). I’m not sure about the new errors you’re getting. Can that be reproduce locally somehow, and if so please create an issue in gitlab about that.
I was creating the issue on gitlab but the following content was marked as spam and I was unable to create the issue. I know that this system is in place to improve development process and to avoid spam. My Account is also new on both gitlab and discourse that could be the reason also. I am posting the content of the issue here for now, if you want you can either allow my gitlab account AS1100K to not be marked as spam or just create the issue yourself. Whatever seems best to you
[Discussion on Discourse](https://discourse.gstreamer.org/t/how-to-make-docs-rs-build-for-crate-using-gstreamer/4576?u=as1100k)
I noticed that when the crate has `gstreamer` as dependency it fails to build on `docs.rs`. I checked the [`Cargo.toml`](https://gitlab.freedesktop.org/gstreamer/gstreamer-rs/-/blob/main/gstreamer/Cargo.toml?ref_type=heads#L58) and found that `gstreamer` passes the following parameters:
```toml
[package.metadata.docs.rs]
rustc-args = ["--cfg", "docsrs"]
rustdoc-args = ["--cfg", "docsrs"]
```
I also passed them on my crate, but the `docs.rs` build fails _([log.txt](/uploads/5620ed7784e1b43d993c3c08dd9462d6/log.txt))_ with error:
```
[INFO] [stderr] Checking gstreamer v0.23.5
[INFO] [stderr] error[E0432]: unresolved imports `miniobject::MiniObject`, `miniobject::MiniObjectRef`
[INFO] [stderr] --> /opt/rustwide/cargo-home/registry/src/index.crates.io-1949cf8c6b5b557f/gstreamer-0.23.5/src/lib.rs:75:22
[INFO] [stderr] |
[INFO] [stderr] 75 | pub use miniobject::{MiniObject, MiniObjectRef};
[INFO] [stderr] | ^^^^^^^^^^ ^^^^^^^^^^^^^ no `MiniObjectRef` in `miniobject`
[INFO] [stderr] | |
[INFO] [stderr] | no `MiniObject` in `miniobject`
[INFO] [stderr] | help: a similar name exists in the module: `IsMiniObject`
```
_This is just the beginning of the log file for preview._
If I don't pass the above parameters the below error is thrown:
```
[INFO] [stderr] warning: gstreamer-app-sys@0.23.4:
[INFO] [stderr] error: failed to run custom build command for `gstreamer-app-sys v0.23.4`
[INFO] [stderr]
[INFO] [stderr] Caused by:
[INFO] [stderr] process didn't exit successfully: `/opt/rustwide/target/debug/build/gstreamer-app-sys-9da892f4361925be/build-script-build` (exit status: 1)
[INFO] [stderr] --- stdout
[INFO] [stderr] cargo:rerun-if-changed=/opt/rustwide/cargo-home/registry/src/index.crates.io-1949cf8c6b5b557f/gstreamer-app-sys-0.23.4/Cargo.toml
[INFO] [stderr] cargo:rerun-if-env-changed=GSTREAMER_APP_1.0_NO_PKG_CONFIG
[INFO] [stderr] cargo:rerun-if-env-changed=PKG_CONFIG_x86_64-unknown-linux-gnu
[INFO] [stderr] cargo:rerun-if-env-changed=PKG_CONFIG_x86_64_unknown_linux_gnu
[INFO] [stderr] cargo:rerun-if-env-changed=HOST_PKG_CONFIG
[INFO] [stderr] cargo:rerun-if-env-changed=PKG_CONFIG
[INFO] [stderr] cargo:rerun-if-env-changed=PKG_CONFIG_PATH_x86_64-unknown-linux-gnu
[INFO] [stderr] cargo:rerun-if-env-changed=PKG_CONFIG_PATH_x86_64_unknown_linux_gnu
[INFO] [stderr] cargo:rerun-if-env-changed=HOST_PKG_CONFIG_PATH
[INFO] [stderr] cargo:rerun-if-env-changed=PKG_CONFIG_PATH
[INFO] [stderr] cargo:rerun-if-env-changed=PKG_CONFIG_LIBDIR_x86_64-unknown-linux-gnu
[INFO] [stderr] cargo:rerun-if-env-changed=PKG_CONFIG_LIBDIR_x86_64_unknown_linux_gnu
[INFO] [stderr] cargo:rerun-if-env-changed=HOST_PKG_CONFIG_LIBDIR
[INFO] [stderr] cargo:rerun-if-env-changed=PKG_CONFIG_LIBDIR
[INFO] [stderr] cargo:rerun-if-env-changed=PKG_CONFIG_SYSROOT_DIR_x86_64-unknown-linux-gnu
[INFO] [stderr] cargo:rerun-if-env-changed=PKG_CONFIG_SYSROOT_DIR_x86_64_unknown_linux_gnu
[INFO] [stderr] cargo:rerun-if-env-changed=HOST_PKG_CONFIG_SYSROOT_DIR
[INFO] [stderr] cargo:rerun-if-env-changed=PKG_CONFIG_SYSROOT_DIR
[INFO] [stderr] cargo:warning=
[INFO] [stderr] pkg-config exited with status code 1
[INFO] [stderr] > PKG_CONFIG_ALLOW_SYSTEM_CFLAGS=1 pkg-config --libs --cflags gstreamer-app-1.0 gstreamer-app-1.0 >= 1.14
[INFO] [stderr]
[INFO] [stderr] The system library `gstreamer-app-1.0` required by crate `gstreamer-app-sys` was not found.
[INFO] [stderr] The file `gstreamer-app-1.0.pc` needs to be installed and the PKG_CONFIG_PATH environment variable must contain its parent directory.
[INFO] [stderr] The PKG_CONFIG_PATH environment variable is not set.
[INFO] [stderr]
[INFO] [stderr] HINT: if you have installed the library, try setting PKG_CONFIG_PATH to the directory containing `gstreamer-app-1.0.pc`.
```
I have tested it on [`kornia-io`](https://github.com/kornia/kornia-rs/tree/main/crates/kornia-io) and a very minimal local crate with a single dependency `gstreamer` version `0.23` but building `gstreamer` works.
## Reproduce the Error
1. Clone [`rust-lang/docs.rs`](https://github.com/rust-lang/docs.rs)
2. Copy `.env.sample` to `.env` and replace `crates-build-env/linux-micro` image with `crates-build-env/linux` because this is the image `docs.rs` uses
```diff
- export DOCSRS_DOCKER_IMAGE=ghcr.io/rust-lang/crates-build-env/linux-micro
+ export DOCSRS_DOCKER_IMAGE=ghcr.io/rust-lang/crates-build-env/linux
````
3. Run the web interface using `docker compose run -p 3000:3000 web` and now `docs.rs` will be available on http://localhost:3000
4. Create a minimal crate with the following `Cargo.toml` as example:
```toml
[package]
name = "test_crate"
version = "0.1.0"
authors = ["Hello"]
license = "MIT"
edition = "2021"
[dependencies]
gstreamer = "0.23"
[package.metadata.docs.rs]
rustc-args = ["--cfg", "docsrs"]
rustdoc-args = ["--cfg", "docsrs"]
```
5. Build the docs using the following command:
```bash
docker compose run --rm -v "/path/to/crate:/sources/test_crate" web build crate --local /sources/test_crate
```
_NOTE: You may need to package the crate using `cargo package`_
