web-view

web-view copied to clipboard

Docs.rs says that the build failed for 0.7.2, and there's no documentation link on crates.io. Taken together, this means that there seems to be no publicly available reference documentation for this library, which is obviously not ideal.

I just tried compiling the rustdoc myself and I got the same error that docs.rs did.

I just tried and was able to compile the docs of the current master version (on Linux). The version from crates.io downloaded with "https://crates.io/api/v1/crates/web-view/0.7.2/download" does not compile at all on my machine however.

It's funny because when I add the dependency web-view = "0.7.2", stuff seem to compile just fine.

I found that building docs from https://crates.io/api/v1/crates/web-view/0.7.2/download works just fine... once I remove Cargo.lock from the directory. I'm thinking maybe excluding Cargo.lock from the posted crate might help—you generally don't want Cargo.lock files in library crates anyway.

I confirm the same thing holds for the 0.7.0 and 0.7.1 releases, which also had doc-build failures on docs.rs.

I'm going to put in a PR.

There seems to be some build issue I cannot yet reproduce when building in docs.rs: https://docs.rs/crate/web-view/0.7.3/builds/353813

Hmmm...

$ wget -O web-view-0.7.3.tar.gz 'https://crates.io/api/v1/crates/web-view/0.7.3/download'
$ tar tzf web-view-0.7.3.tar.gz | egrep Cargo
web-view-0.7.3/Cargo.lock
web-view-0.7.3/Cargo.toml
web-view-0.7.3/Cargo.toml.orig

Still including Cargo.lock. My previous PR's changes serve as documentation, but apparently have no actual effect when Cargo packages up the crate.

$ tar xzf web-view-0.7.3.tar.gz && cd web-view-0.7.3
$ cargo doc
   Compiling proc-macro2 v1.0.24
   Compiling unicode-xid v0.2.0
   Compiling syn v1.0.48
   Compiling serde v1.0.104
[...]
   Compiling thiserror v1.0.22
   Compiling toml v0.5.7
   Compiling system-deps v1.3.2
error[E0609]: no field `defines` on type `pkg_config::Library`
   --> /home/zec/.cargo/registry/src/github.com-1ecc6299db9ec823/system-deps-1.3.2/src/lib.rs:634:24
    |
634 |             defines: l.defines,
    |                        ^^^^^^^ unknown field
    |
    = note: available fields are: `libs`, `link_paths`, `frameworks`, `framework_paths`, `include_paths`, `version`

error: aborting due to previous error

For more information about this error, try `rustc --explain E0609`.
error: could not compile `system-deps`

That's the error in the build logs for 0.7.3 on docs.rs. Now, without the Cargo.lock included in the crate from crates.io:

$ cargo clean ; rm Cargo.lock
$ cargo doc
    Updating crates.io index
   Compiling proc-macro2 v1.0.24
   Compiling unicode-xid v0.2.1
[...]
 Documenting gtk-sys v0.10.0
 Documenting webkit2gtk-sys v0.12.0
 Documenting webview-sys v0.6.2
 Documenting web-view v0.7.3 (/[...]/tmp/web-view-0.7.3)
    Finished dev [unoptimized + debuginfo] target(s) in 1m 13s

Once again, like for 0.7.{0,1,2} from crates.io, removing Cargo.lock allows the docs to build successfully. Also of note is that crates.io's webview-sys 0.6.2 doesn't have a Cargo.lock and built fine on docs.rs.

So, I guess one solution would still be to figure out how to exclude Cargo.lock once and for all, which my previous efforts failed to do correctly.

Let's see what Cargo actually does.

Starting with a fresh checkout of the master branch:

$ cargo build && cargo doc
[...]
    Finished dev [unoptimized + debuginfo] target(s) in 25.87s
$ ls -a
.   Cargo.lock  examples  .github     LICENSE    src     webview-sys
..  Cargo.toml  .git      .gitignore  README.md  target

So now, there's Cargo.lock and target/ in the directory. Let's see the crate file Cargo generates during the publishing process:

$ cargo package
   Packaging web-view v0.7.3 (/[...]/tmp/web-view)
[...]
    Finished dev [unoptimized + debuginfo] target(s) in 54.34s
$ ls target/package/
web-view-0.7.3  web-view-0.7.3.crate
$ tar tzf target/package/web-view-0.7.3.crate | egrep 'Cargo'
web-view-0.7.3/Cargo.lock
web-view-0.7.3/Cargo.toml
web-view-0.7.3/Cargo.toml.orig

So, on my local machine I can duplicate that Cargo is putting a Cargo.lock into the file that gets uploaded. What's more, the contents of that Cargo.lock are almost identical to that in the checkout post-build (differing only in the entry for webview-sys being changed to use a version from crates.io).

[looks through the Cargo Book]

This turns out to be documented behavior. To wit:

Cargo.lock is automatically included if the package contains an executable binary or example target. cargo-install(1) will use the packaged lock file if the --locked flag is used.

Indeed, when running cargo package on a pristine checkout, a Cargo.lock gets put into the built target/package/web-view-0.7.3.crate, even if there isn't a Cargo.lock in the working directory.

To summarize: the fact that the web-view crate has example targets causes Cargo.lock to be included in the packaged crate. In turn, that means the contents of the packaged and uploaded crate are dependent on some combination of (1) the contents of the crate registry at the time of packaging and (2) the (history-dependent) contents of the uploader's working directory at the time of packaging.

As confirmation of the above:

$ git mv examples not-really-examples ; git commit -m 'Testing'
$ cargo clean ; cargo build
[...]
$ ls Cargo.lock
Cargo.lock
$ cargo package
[...]
$ tar tzf target/package/web-view-0.7.3.crate | egrep 'Cargo'
web-view-0.7.3/Cargo.toml
web-view-0.7.3/Cargo.toml.orig

Perhaps we should move the examples out of the web-view crate?

We don't actually need this to be built in docs.rs to have a solution (although docs.rs is ideal I think). Instead, with each release, a maintainer can build the docs locally (which works fine at least on Linux if dependencies are installed), and then push it to Github Pages which can then be set as the documentation link in Cargo.toml and thus crates.io as well.