Skip to content

Update documentation for new pkgid attribute. #10944

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Dec 14, 2013
Merged

Update documentation for new pkgid attribute. #10944

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 16 additions & 29 deletions doc/rust.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -612,10 +612,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" ];
Expand Down Expand Up @@ -778,36 +776,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
Expand Down Expand Up @@ -1745,7 +1731,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)).
Expand Down Expand Up @@ -3798,7 +3785,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`.
Expand Down
2 changes: 1 addition & 1 deletion doc/rustdoc.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
7 changes: 4 additions & 3 deletions doc/rustpkg.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -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

Expand Down
34 changes: 15 additions & 19 deletions doc/tutorial.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand All @@ -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

Expand All @@ -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() {}
Expand All @@ -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

Expand Down