Project:Rust/rust-dev

= About =

The  overlay is a prototype experiment for building crates as individual crate units.

This overlay handles each crate similarly to how non-binary programming languages like Perl, Python and Ruby work, by installing (possibly augmented) copies of the extracted crate archives, constructing a local directory registry source as described in source replacement in the cargo book, while deferring actual binary compilation to the relevant target leaves, leveraging slot-operator deps for automatic rebuilds.

But its currently a very complicated mountain of work and not quite ready for prime-time.

= Repositories =


 * main repo: https://github.com/gyakovlev/rust-dev-overlay
 * kentnl's work-in-progress: https://github.com/kentfredric/rust-dev-overlay

= Common Pitfalls =

denied warnings
Many crates employ a rust attribute macro of some variation of:

#[deny(warnings)]

This makes all warnings fatal, but this is only typically visible when directly compiling or testing a crate, as cargo automatically passes  when building dependencies.

Typically, you can circumvent this issue with something like

src_test { RUSTFLAGS="${RUSTFLAGS} --cap-lints warn" rust-crate_src_test }

Which will usually turn them back into just loud warnings.

further caveats
However, due to a few rust bugs, this approach does not work. More over, some of these warnings may eventually become fatal in future rusts, so its pertinent to see them and possibly get them fixed upstream. This means in some cases one has to patch out the relevant  lines to allow tests to pass / binaries to compile. But in some cases, one may instead wish to patch out the reasons for the warnings and get it fixed upstream.

Relevant bugs:
 * capping lints does not work for rustdoc
 * rustdoc --test mis-reports origins of

apparently required non-target dependencies
Standard crates have several kinds of dependency grades:


 * with
 * specific verisions of the above
 * specific verisions of the above
 * specific verisions of the above
 * specific verisions of the above

But unfortunately, depending on aspects of the crate, all of these can be required to satisfy the  section of the crate, which invokes :

ecargo package --allow-dirty --no-metadata --no-verify

( to re-roll the patched sources back into a cargo-repository compatible format )

Removing non-essential binaries
One of the thing that causes spurious dependencies to be deemed "mandatory" are binary asepcts, namely:


 * installable executables
 * examples
 * tests ( which are compiled executables )

These can take a variety of forms:


 * sections in
 * sections in
 * Any file called,  , or
 * Any file called  under

For the most part, I've just opted to remove these binary aspects entirely, as its usually examples which trigger this, and also patch out any relevant lines in, including pruning any   that are proven to only be needed for examples.

Very few crates have actual binaries that need to be installed, and doing that while keeping dependencies slim is a bit of a mess right now, so look at | this example case for now

Removing non-target platform dependencies
Many crates have target-specific dependencies using prefixes like:

[target."cfg(target_os = \"fuchsia\")".dependencies.fuchsia-zircon] version = "0.3.2" [target."cfg(target_os = \"fuchsia\")".dependencies.fuchsia-zircon-sys] version = "0.3.2" [target."cfg(unix)".dependencies.libc] version = "0.2.42" [target."cfg(windows)".dependencies.kernel32-sys] version = "0.2" [target."cfg(windows)".dependencies.miow] version = "0.2.1" [target."cfg(windows)".dependencies.winapi] version = "0.2.6"

Unfortunately, the way cargo works is it can require these crates to be present in the registry in order to build, which is presently rediculous as our dominant audience is served by  , and if these dependencies are shipped, it lends to massive dependency graphs.

Its simpler to simply cull those sections with a patch, so only dependencies which would be used on unix are included (eg: leaving  intact).