Clarify the meaning of reference-typed constants

[hsivonen]

I used pub const FOO: &'static Bar = &Bar { // crate-private stuff here ... }; in a crate. Within that crate, FOO as *const Bar was consistently the same address. However, when used in another crate, FOO as *const Bar became another address.

Apparently what's happening is that the RHS of const is inlined but within a given crate (effectively allowing a crate to inline stuff that's private to another crate), duplicates are later coalesced when making the values being referred to into the data section of the object file.

What I thought was supposed to be happening was this:

I expected the Bar { // crate-private stuff here ... } bit to be evaluated once in the crate where the constant was declared and the result getting uniquely baked into the data section of the object file. I then expected the value that gets inlined at contant use time to be the address of that unique location.

Especially considering that this appears to result in a constant address within a crate but blows up when the constant is used in another crate, it would be useful for the Book and the Reference to spell out more clearly that the constant isn't just the reference value of the right-hand-side expression but the entire right-hand-side expression itself and explicitly warn about the instantiations of the constant expression getting coalesced on a per-crate basis, which gives the appearance of the reference being the value of a uniquely evaluated expression rather than the expression itself as long as you are only testing within a single crate.

[petrochenkov]

Some relevant docs can be found here: https://github.com/rust-lang/rfcs/blob/master/text/0246-const-vs-static.md
const references are described there as references to implicitly defined statics, I don't think that's correct given that address stability for these references is not guaranteed.

[steveklabnik]

The reference has its own repository now; I've moved this to rust-lang-nursery/reference#22

thanks!