auto merge of #10944 : metajack/rust/pkgid-docs, r=cmr

Author: bors

doc/rust.md

@@ -609,10 +609,8 @@ Attributes on the anonymous crate module define important metadata that influenc
 the behavior of the compiler.
 
 ~~~~
-// Linkage attributes
-#[ link(name = "projx",
-        vers = "2.5",
-        uuid = "9cccc5d5-aceb-4af5-8285-811211826b82") ];
+// Package ID
+#[ pkgid = "projx#2.5" ];
 
 // Additional metadata attributes
 #[ desc = "Project X" ];
@@ -775,36 +773,24 @@ An _`extern mod` declaration_ specifies a dependency on an external crate.
 The external crate is then bound into the declaring scope
 as the `ident` provided in the `extern_mod_decl`.
 
-The external crate is resolved to a specific `soname` at compile time,
-and a runtime linkage requirement to that `soname` is passed to the linker for
-loading at runtime.
-The `soname` is resolved at compile time by scanning the compiler's library path
-and matching the `link_attrs` provided in the `use_decl` against any `#link` attributes that
-were declared on the external crate when it was compiled.
-If no `link_attrs` are provided,
-a default `name` attribute is assumed,
-equal to the `ident` given in the `use_decl`.
-
-Optionally, an identifier in an `extern mod` declaration may be followed by an equals sign,
-then a string literal denoting a relative path on the filesystem.
-This path should exist in one of the directories in the Rust path,
-which by default contains the `.rust` subdirectory of the current directory and each of its parents,
-as well as any directories in the colon-separated (or semicolon-separated on Windows)
-list of paths that is the `RUST_PATH` environment variable.
-The meaning of `extern mod a = "b/c/d";`, supposing that `/a` is in the RUST_PATH,
-is that the name `a` should be taken as a reference to the crate whose absolute location is
-`/a/b/c/d`.
+The external crate is resolved to a specific `soname` at compile time, and a
+runtime linkage requirement to that `soname` is passed to the linker for
+loading at runtime.  The `soname` is resolved at compile time by scanning the
+compiler's library path and matching the optional `pkgid` provided as a string literal
+against the `pkgid` attributes that were declared on the external crate when
+it was compiled.  If no `pkgid` is provided, a default `name` attribute is
+assumed, equal to the `ident` given in the `extern_mod_decl`.
 
 Four examples of `extern mod` declarations:
 
 ~~~~ {.xfail-test}
-extern mod pcre (uuid = "54aba0f8-a7b1-4beb-92f1-4cf625264841");
+extern mod pcre;
 
-extern mod extra; // equivalent to: extern mod extra ( name = "extra" );
+extern mod extra; // equivalent to: extern mod extra = "extra";
 
-extern mod rustextra (name = "extra"); // linking to 'extra' under another name
+extern mod rustextra = "extra"; // linking to 'extra' under another name
 
-extern mod complicated_mod = "some-file/in/the-rust/path";
+extern mod foo = "some/where/foo#1.0"; // a full package ID for rustpkg
 ~~~~
 
 ##### Use declarations
@@ -1742,7 +1728,8 @@ names are effectively reserved. Some significant attributes include:
 * The `doc` attribute, for documenting code in-place.
 * The `cfg` attribute, for conditional-compilation by build-configuration.
 * The `lang` attribute, for custom definitions of traits and functions that are known to the Rust compiler (see [Language items](#language-items)).
-* The `link` attribute, for describing linkage metadata for a crate.
+* The `link` attribute, for describing linkage metadata for a extern blocks.
+* The `pkgid` attribute, for describing the package ID of a crate.
 * The `test` attribute, for marking functions as unit tests.
 * The `allow`, `warn`, `forbid`, and `deny` attributes, for
   controlling lint checks (see [Lint check attributes](#lint-check-attributes)).
@@ -3795,7 +3782,7 @@ specified then log level 4 is assumed.  Debug messages can be omitted
 by passing `--cfg ndebug` to `rustc`.
 
 As an example, to see all the logs generated by the compiler, you would set
-`RUST_LOG` to `rustc`, which is the crate name (as specified in its `link`
+`RUST_LOG` to `rustc`, which is the crate name (as specified in its `pkgid`
 [attribute](#attributes)). To narrow down the logs to just crate resolution,
 you would set it to `rustc::metadata::creader`. To see just error logging
 use `rustc=0`.

doc/rustdoc.md

@@ -13,7 +13,7 @@ comments":
 ~~~
 // the "link" crate attribute is currently required for rustdoc, but normally
 // isn't needed.
-#[link(name="universe")];
+#[pkgid = "universe"];
 #[crate_type="lib"];
 
 //! Tools for dealing with universes (this is a doc comment, and is shown on

doc/rustpkg.md

@@ -89,6 +89,10 @@ as well as `foo/src/bar/extras/baz/lib.rs`,
 then both `bar` and `bar/extras/baz` are valid package identifiers
 in the workspace `foo`.
 
+Because rustpkg uses generic source file names as the main inputs, you will
+need to specify the package identifier in them using the `pkgid` attribute
+on the crate.
+
 ## Source files
 
 rustpkg searches for four different fixed filenames in order to determine the crates to build:
@@ -108,9 +112,6 @@ When building a package that is not under version control,
 or that has no tags, `rustpkg` assumes the intended version is 0.1.
 
 > **Note:** A future version of rustpkg will support semantic versions.
-> Also, a future version will add the option to specify a version with a metadata
-> attribute like `#[link(vers = "3.1415")]` inside the crate module,
-> though this attribute will never be mandatory.
 
 # Dependencies
 

doc/tutorial.md

@@ -3070,22 +3070,21 @@ Therefore, if you plan to compile your crate as a library, you should annotate i
 // lib.rs
 
 # #[crate_type = "lib"];
-// Crate linkage metadata
-#[link(name = "farm", vers = "2.5")];
+// Package ID
+#[pkgid = "farm#2.5"];
 
 // ...
 # fn farm() {}
 ~~~~
 
-You can also in turn require in a `extern mod` statement that certain link metadata items match some criteria.
-For that, Rust currently parses a comma-separated list of name/value pairs that appear after
-it, and ensures that they match the attributes provided in the `link` attribute of a crate file.
-This enables you to, e.g., pick a crate based on its version number, or link a library under a
-different name. For example, these two `mod` statements would both accept and select the crate define above:
+You can also specify package ID information in a `extern mod` statement.  For
+example, these `extern mod` statements would both accept and select the
+crate define above:
 
 ~~~~ {.xfail-test}
-extern mod farm(vers = "2.5");
-extern mod my_farm(name = "farm", vers = "2.5");
+extern mod farm;
+extern mod farm = "farm#2.5";
+extern mod my_farm = "farm";
 ~~~~
 
 Other crate settings and metadata include things like enabling/disabling certain errors or warnings,
@@ -3096,21 +3095,18 @@ or setting the crate type (library or executable) explicitly:
 // ...
 
 // This crate is a library ("bin" is the default)
+#[pkgid = "farm#2.5"];
 #[crate_type = "lib"];
 
 // Turn on a warning
 #[warn(non_camel_case_types)]
 # fn farm() {}
 ~~~~
 
-If you're compiling your crate with `rustpkg`,
-link annotations will not be necessary, because they get
-inferred by `rustpkg` based on the Package id and naming conventions.
-
-
-> ***Note:*** The rules regarding link metadata, both as attributes and on `extern mod`,
-              as well as their interaction with `rustpkg`
-              are currently not clearly defined and will likely change in the future.
+> ***Note:*** The rules regarding package IDs, both as attributes and as used
+              in `extern mod`, as well as their interaction with `rustpkg` are
+              currently not clearly defined and will likely change in the
+              future.
 
 ## A minimal example
 
@@ -3120,7 +3116,7 @@ We define two crates, and use one of them as a library in the other.
 
 ~~~~
 // world.rs
-#[link(name = "world", vers = "0.42")];
+#[pkgid = "world#0.42"];
 # extern mod extra;
 pub fn explore() -> &'static str { "world" }
 # fn main() {}
@@ -3144,7 +3140,7 @@ Now compile and run like this (adjust to your platform if necessary):
 Notice that the library produced contains the version in the file name
 as well as an inscrutable string of alphanumerics. As explained in the previous paragraph,
 these are both part of Rust's library versioning scheme. The alphanumerics are
-a hash representing the crates link metadata.
+a hash representing the crates package ID.
 
 ## The standard library and the prelude