Cargo build-scripts doc includes very visible anti-example and "hand-wavy" non-working code

[kornelski]

This page: http://doc.crates.io/build-script.html doesn't answer my question: how can I replace Make with Rust? (I'd rather not replace it—#887—but you insist)

It did not help me write my build script, and left me frustrated.

I skim pages rather than read every single word of them (sorry!), and the first thing I've noticed when looking for simple solution to copy&paste was this example:

  Command::new("gcc").arg("src/hello.c")
                       .arg("-c")
                       .arg("-o")
                       .arg(format!("{}/hello.o", out_dir))
                       .status()
                       .unwrap();
    Command::new("ar").arg("crus")
                      .arg("libhello.a")
                      .arg("hello.o")
                      .cwd(&out_dir)
                      .status()
                      .unwrap();

When Cargo told me not to use bash and I found that as an answer, I was incredibly annoyed. It's replacing 2 lines of simple bash code with 20 lines of Rust, without gaining any portability, functionality or readability. It just shows Rust is a bad tool for the job (I'm not writing my build scripts in C, so I'm not going to write them in Rust).

And regardless of whether using Rust instead of bash is a good idea, this example isn't even the correct answer to the problem.

As far as I understand this document, the solutions for building custom C code are:

1. Admittedly pointless practice that doesn't solve any problems caused by non-portability of bash invoking GCC
2. "Hand-wavy" example that requires a library which is entirely hypothetical and can't actually be used, so this leaves only the option no.1.

Instead of an essay that explores only bad options, could you include real working examples that represent the best practice you're advocating for?

(sorry about pissed-off tone of these bugs, I can't help it)

[alexcrichton]

I'll try to make the example a little more brief, but I found it difficult to include a copy-and-paste-able example which didn't depend on an actual third-party repo which can go out of date or disappear over time. The "hand wavy" library exists today, I just don't want to point to it as it may change over time.

If you take the time to read the sections around this example they point out that this is an un-portable example and explain in detail as to why. I'm sorry that you're frustrated at this, but there are very concrete reasons for this change laid out in the RFC which "using a makefile" simply doesn't solve. I've typically found that very tiny tasks are more verbose with a build script but a "real build script" is rarely quite small. As scripts change over time the necessity for a build-dependency becomes painfully obvious.

For now though, I'm going to close this because the documentation is quite clear about the examples, and the "best practice" is the mentioned example about using a common dependency. As I said above, I don't want to favor any third-party package as it tends to bias and it also may change over time at which point the docs will be out of sync. Once crates.io is online it should be fairly easy to discover packages for build-dependencies.

[kornelski]

difficult to include a copy-and-paste-able example which didn't depend on an actual third-party repo which can go out of date or disappear over time

If it's difficult for you, it's even more difficult for me. What am I supposed to do, if not find and use an actual third-party library that can go out of date or disappear over time?

The documentation doesn't face the actual problem and doesn't give any working solution.

I'm expecting docs to say "here, that's how you do it" instead of "well, it's tough, you should go and explore the problem and figure it out yourself".

I'd still prefer an example that works right now, and when the best way to do this changes, then update the example. At least when the example breaks I'll be able to go back to the docs and copy the new best version, instead of docs having poor example all the time, and only vague information about actual best practice.

The "hand wavy" library exists today

You know that, but the docs don't say it!

It's cool you don't want to bless any specific 3rd party library, but it's not helpful when docs are worded as if no library existed yet, because it leaves me frustrated that instead of a working solution docs dodge the problem and give unspecified seemingly-nonexistent hand-wavy thing.

Instead of using "For example, the build script could be written as:" I suggest removing the cringeworthy gcc invocation altogether and say something like:

"The build script can be written like this using one of existing Rust build libraries:"

Perhaps followed by few links to libraries or at least a search page using right keywords.

[alexcrichton]

I've opened a new issue about promoting awareness about build dependencies and in general improving the experience around using them, which I think that this bug segues nicely into.