Should platform specific crates compile as empty or fail build on wrong platform?

[faern]

Are there any recommendations whether or not a crate that only works on one, or a subset of, platforms, should be written in such a way that they still build on the platforms they don't support or fail compilation?

For example, winapi builds on non-windows platforms, but it becomes empty.

It might be that a crate needs some stuff in build.rs that will only work on the platforms it is intended to support. Would it then be fully OK to let it fail compilation on the other platforms? Or is it recommended to put some effort into making it build, but not contain anything usable? For a crate only working on macOS, this is an example of how one could write their build.rs:

#[cfg(target_os = "macos")]
fn main() {
    // Do the required build stuff that only works on macOS
}

/// Alternative 1: Fail on wrong platforms.
#[cfg(not(target_os = "macos"))]
fn main() {
    panic!("This crate only makes sense to use on macOS");
}

/// Alternative 2: Work around the problem, but also add conditional compilation to `lib.rs` so it builds empty
#[cfg(not(target_os = "macos"))]
fn main() {}

Making a crate fail on the wrong platform requires a user of the crate to depend on it just for the specific platforms. Example:

[target.'cfg(unix)'.dependencies]
libc = "0.2"

This is a bit more burdensome, but has the benefit of clearly communicating where it's needed and removes the need for downloading and building the crate on the other platforms.

If there can be any consensus whether or not it's recommended to strive towards building an empty crate or fail compilation, then I think it would be awesome to have that recommendation in the API guidelines.

[dtolnay]

Unfortunately I don't have any experience with platform specific code so I don't have an opinion about this. Could you @mention some crate authors who do it one way and the other way and we can try to sort it out? I would love to include a guideline related to this.

[faern]

Sure!

I'll ping some people who are owners or top contributors to some platform specific crates. Hope they have some good insights, or can ping people who do, about what works best in practice!

When going through the repos now, I realize more or less all of the big ones does compile to an empty crate on the unsupported platforms. But it might still be valuable to get some input on their experience with this.

• @retep998 from winapi.
• @carllerche or @asomers from nix.
• @alexcrichton from miow.
• @BurntSushi from wincolor.
• @diwic from dbus.

[asomers]

IMHO it's fine for platform-specific crates to fail on the wrong platforms. Forcing consumers not download platform-specific dependencies when building on the wrong platform is a definite benefit. The biggest problem I have with platform-specific crates is that docs.rs doesn't build their documentation correctly. docs.rs always presents the Linux documentation as the default, and doesn't work at all for any but the most common handful of platforms.

[retep998]

Your example with build scripts is a bad idea because it breaks cross compilation. Build scripts need to be designed in a cross platform manner and be able to run everywhere. It's just that if cargo tells the build script via environment variables that the target is one the crate doesn't support, then the build script can do nothing. Granted, there are situations where this can't be practically done, such as the cc crate trying to find the VC++ toolchain which simply won't work when the host is non-Windows.

While things like [target.'cfg(windows)'.dependencies] for winapi generally works well, there are situations where you can't rely on this. Crates that support older versions of Rust don't have access to this nifty feature, and sometimes platform combinations are so convoluted that it can be difficult to specify the dependency cfg correctly. If a crate doesn't know whether it needs a given dependency until its build script runs, then it isn't even possible to avoid building that dependency. Therefore I'm in favor of crates compiling to nothing on unsupported platforms, rather than failing and causing a massive headache to someone just trying to get a project working on their platform.

[alexcrichton]

I would personally recommend:

• A guideline that says platform-specific dependencies should only be included on relevant platforms (e.g. [target.'cfg(unix)'.dependencies] and such)
• Authors should strive to have the crate compile on all platforms, even if it means that it's empty on some.

That way users are warned that you should trim your dependency graph wherever possible, but if mistakes are made they end up being harmless in the long run.

[diwic]

I've never given it a thought (until now), and no one has ever complained about this on my github tracker...

First, I think we should avoid build.rs scripts whenever we can, because it makes building harder (e g reasoning about incremental compilation, I suppose).

Second, while dbus in practice is used on unix only, I think there is some Windows port (and I have no idea about MacOS). So I prefer my compilation to just fail (due to missing libraries etc) rather than "compile to empty", because if someone tries to compile my library on Windows, in most cases they would have preferred it to "compile to empty" but in some case they actually want to get that Windows port working. So there seem to be no choice that's always right.

[faern]

Very nice input so far!

I can describe the scenario I'm in which made me start thinking about this. I'm using bindgen to generate bindings in build.rs (which seems recommended over using the CLI tool from the bindgen guide). The problem is the header references some macOS SDK headers, so I must point to them with -I/sdk/path where I use xcodebuild to figure out /sdk/path. So the entire binding generation is dependent on the Xcode CLI tools being installed along with a macOS SDK, and all of this of course only works on macOS.

What I did to get rid of this problem was to change my build.rs into a generate_bindings.sh in my repo that would generate the bindings with the bindgen CLI. Then I add the generated bindings to my crate and commit to git. This removes the binding generation step from the build process and it works much better on all platforms. Possible downsides include having to commit many thousands lines of generated code.

So I was naturally wondering if there was a recommended way to do this.