buildRustCrate: Allow version specific dependency renaming + parameter doc

[kolloch]

This PR allows version specific crate renames:

pkgs.buildRustCrate {
  # ...
  crateRenames = {
     my_crate_name = [
         { version = "1.2.3"; rename = "my_alternative_name01" ; }
         { version = "3.2.3"; rename = "my_alternative_name03" ; }
     ];
     # ...
   };

I also documented all buildRustCrate parameters.

Motivation for this change

This roughly corresponds to the following snippet in Cargo.toml:

[dependencies]
my_alternative_name01 = { package = "my_crate_name", version = "0.1" }
my_alternative_name03 = { package = "my_crate_name", version = "0.3" }

Including multiple versions of a crate is very popular during ecosystem transitions, e.g. from futures 0.1 to futures 0.3.

Corresponding issue in crate2nix: nix-community/crate2nix#83

Things done

• Tested using sandboxing (nix.useSandbox on NixOS, or option sandbox in nix.conf on non-NixOS linux)
• Built on platform(s) nix build -f . buildRustCrateTests
  • NixOS
  • macOS
  • other Linux distributions
• Tested via one or more NixOS test(s) if existing and applicable for the change (look inside nixos/tests) (See above)
• Tested compilation of all pkgs that depend on this change using nix-shell -p nixpkgs-review --run "nixpkgs-review wip"
• Tested execution of all binary files (usually in ./result/bin/)
• Determined the impact on package closure size (by running nix path-info -S before and after)
• Ensured that relevant documentation is up to date
• Fits CONTRIBUTING.md.

[andir]

Two minor remarks. Overall this looks good.

I also see the need for version specific overrides for things like (native)buildInputs.

Currently you have to "switch" on the version or name attribute in the overrides if you need different native inputs for the same crate name.

We should probably consider what larger refactoring we can do additionally to ease such pains.

[kolloch]

Thank you for the review, @andir !

For buildInputs, the crateOverrides mechanism can be used. This PR is a bit special because it concerns the extern name with which a certain crate is used within a dependent crate. So maybe those separate concerns can be handled better but will still need to be handled differently.