1 // Copyright 2016 The Rust Project Developers. See the COPYRIGHT
2 // file at the top-level directory of this distribution and at
3 // http://rust-lang.org/COPYRIGHT.
5 // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
6 // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
7 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
8 // option. This file may not be copied, modified, or distributed
9 // except according to those terms.
11 //! The Rust Linkage Model and Symbol Names
12 //! =======================================
14 //! The semantic model of Rust linkage is, broadly, that "there's no global
15 //! namespace" between crates. Our aim is to preserve the illusion of this
16 //! model despite the fact that it's not *quite* possible to implement on
17 //! modern linkers. We initially didn't use system linkers at all, but have
18 //! been convinced of their utility.
20 //! There are a few issues to handle:
22 //! - Linkers operate on a flat namespace, so we have to flatten names.
23 //! We do this using the C++ namespace-mangling technique. Foo::bar
26 //! - Symbols for distinct items with the same *name* need to get different
27 //! linkage-names. Examples of this are monomorphizations of functions or
28 //! items within anonymous scopes that end up having the same path.
30 //! - Symbols in different crates but with same names "within" the crate need
31 //! to get different linkage-names.
33 //! - Symbol names should be deterministic: Two consecutive runs of the
34 //! compiler over the same code base should produce the same symbol names for
37 //! - Symbol names should not depend on any global properties of the code base,
38 //! so that small modifications to the code base do not result in all symbols
39 //! changing. In previous versions of the compiler, symbol names incorporated
40 //! the SVH (Stable Version Hash) of the crate. This scheme turned out to be
41 //! infeasible when used in conjunction with incremental compilation because
42 //! small code changes would invalidate all symbols generated previously.
44 //! - Even symbols from different versions of the same crate should be able to
45 //! live next to each other without conflict.
47 //! In order to fulfill the above requirements the following scheme is used by
50 //! The main tool for avoiding naming conflicts is the incorporation of a 64-bit
51 //! hash value into every exported symbol name. Anything that makes a difference
52 //! to the symbol being named, but does not show up in the regular path needs to
53 //! be fed into this hash:
55 //! - Different monomorphizations of the same item have the same path but differ
56 //! in their concrete type parameters, so these parameters are part of the
57 //! data being digested for the symbol hash.
59 //! - Rust allows items to be defined in anonymous scopes, such as in
60 //! `fn foo() { { fn bar() {} } { fn bar() {} } }`. Both `bar` functions have
61 //! the path `foo::bar`, since the anonymous scopes do not contribute to the
62 //! path of an item. The compiler already handles this case via so-called
63 //! disambiguating `DefPaths` which use indices to distinguish items with the
64 //! same name. The DefPaths of the functions above are thus `foo[0]::bar[0]`
65 //! and `foo[0]::bar[1]`. In order to incorporate this disambiguation
66 //! information into the symbol name too, these indices are fed into the
67 //! symbol hash, so that the above two symbols would end up with different
70 //! The two measures described above suffice to avoid intra-crate conflicts. In
71 //! order to also avoid inter-crate conflicts two more measures are taken:
73 //! - The name of the crate containing the symbol is prepended to the symbol
74 //! name, i.e. symbols are "crate qualified". For example, a function `foo` in
75 //! module `bar` in crate `baz` would get a symbol name like
76 //! `baz::bar::foo::{hash}` instead of just `bar::foo::{hash}`. This avoids
77 //! simple conflicts between functions from different crates.
79 //! - In order to be able to also use symbols from two versions of the same
80 //! crate (which naturally also have the same name), a stronger measure is
81 //! required: The compiler accepts an arbitrary "disambiguator" value via the
82 //! `-C metadata` commandline argument. This disambiguator is then fed into
83 //! the symbol hash of every exported item. Consequently, the symbols in two
84 //! identical crates but with different disambiguators are not in conflict
85 //! with each other. This facility is mainly intended to be used by build
88 //! A note on symbol name stability
89 //! -------------------------------
90 //! Previous versions of the compiler resorted to feeding NodeIds into the
91 //! symbol hash in order to disambiguate between items with the same path. The
92 //! current version of the name generation algorithm takes great care not to do
93 //! that, since NodeIds are notoriously unstable: A small change to the
94 //! code base will offset all NodeIds after the change and thus, much as using
95 //! the SVH in the hash, invalidate an unbounded number of symbol names. This
96 //! makes re-using previously compiled code for incremental compilation
97 //! virtually impossible. Thus, symbol hash generation exclusively relies on
98 //! DefPaths which are much more robust in the face of changes to the code base.
100 use common
::{CrateContext, gensym_name}
;
101 use monomorphize
::Instance
;
102 use util
::sha2
::{Digest, Sha256}
;
104 use rustc
::middle
::cstore
;
105 use rustc
::hir
::def_id
::DefId
;
106 use rustc
::ty
::{self, TyCtxt, TypeFoldable}
;
107 use rustc
::ty
::item_path
::{ItemPathBuffer, RootMode}
;
108 use rustc
::hir
::map
::definitions
::{DefPath, DefPathData}
;
111 use syntax
::parse
::token
::{self, InternedString}
;
112 use serialize
::hex
::ToHex
;
114 pub fn def_id_to_string
<'a
, 'tcx
>(tcx
: TyCtxt
<'a
, 'tcx
, 'tcx
>, def_id
: DefId
) -> String
{
115 let def_path
= tcx
.def_path(def_id
);
116 def_path_to_string(tcx
, &def_path
)
119 pub fn def_path_to_string
<'a
, 'tcx
>(tcx
: TyCtxt
<'a
, 'tcx
, 'tcx
>, def_path
: &DefPath
) -> String
{
120 let mut s
= String
::with_capacity(def_path
.data
.len() * 16);
122 s
.push_str(&tcx
.crate_name(def_path
.krate
));
124 s
.push_str(&tcx
.crate_disambiguator(def_path
.krate
));
126 for component
in &def_path
.data
{
129 component
.data
.as_interned_str(),
130 component
.disambiguator
)
137 fn get_symbol_hash
<'a
, 'tcx
>(ccx
: &CrateContext
<'a
, 'tcx
>,
139 // path to the item this name is for
142 // type of the item, without any generic
143 // parameters substituted; this is
144 // included in the hash as a kind of
146 item_type
: ty
::Ty
<'tcx
>,
148 // values for generic type parameters,
150 parameters
: &[ty
::Ty
<'tcx
>])
152 debug
!("get_symbol_hash(def_path={:?}, parameters={:?})",
153 def_path
, parameters
);
157 let mut hash_state
= ccx
.symbol_hasher().borrow_mut();
161 // the main symbol name is not necessarily unique; hash in the
162 // compiler's internal def-path, guaranteeing each symbol has a
164 hash_state
.input_str(&def_path_to_string(tcx
, def_path
));
166 // Include the main item-type. Note that, in this case, the
167 // assertions about `needs_subst` may not hold, but this item-type
168 // ought to be the same for every reference anyway.
169 assert
!(!item_type
.has_erasable_regions());
170 let encoded_item_type
= tcx
.sess
.cstore
.encode_type(tcx
, item_type
, def_id_to_string
);
171 hash_state
.input(&encoded_item_type
[..]);
173 // also include any type parameters (for generic items)
174 for t
in parameters
{
175 assert
!(!t
.has_erasable_regions());
176 assert
!(!t
.needs_subst());
177 let encoded_type
= tcx
.sess
.cstore
.encode_type(tcx
, t
, def_id_to_string
);
178 hash_state
.input(&encoded_type
[..]);
181 return format
!("h{}", truncated_hash_result(&mut *hash_state
));
183 fn truncated_hash_result(symbol_hasher
: &mut Sha256
) -> String
{
184 let output
= symbol_hasher
.result_bytes();
185 // 64 bits should be enough to avoid collisions.
186 output
[.. 8].to_hex()
190 fn exported_name_with_opt_suffix
<'a
, 'tcx
>(ccx
: &CrateContext
<'a
, 'tcx
>,
191 instance
: &Instance
<'tcx
>,
192 suffix
: Option
<&str>)
194 let &Instance { def: mut def_id, ref substs }
= instance
;
196 debug
!("exported_name_with_opt_suffix(def_id={:?}, substs={:?}, suffix={:?})",
197 def_id
, substs
, suffix
);
199 if let Some(node_id
) = ccx
.tcx().map
.as_local_node_id(def_id
) {
200 if let Some(&src_def_id
) = ccx
.external_srcs().borrow().get(&node_id
) {
205 let def_path
= ccx
.tcx().def_path(def_id
);
206 assert_eq
!(def_path
.krate
, def_id
.krate
);
208 // We want to compute the "type" of this item. Unfortunately, some
209 // kinds of items (e.g., closures) don't have an entry in the
210 // item-type array. So walk back up the find the closest parent
211 // that DOES have an entry.
212 let mut ty_def_id
= def_id
;
215 let key
= ccx
.tcx().def_key(ty_def_id
);
216 match key
.disambiguated_data
.data
{
217 DefPathData
::TypeNs(_
) |
218 DefPathData
::ValueNs(_
) => {
219 instance_ty
= ccx
.tcx().lookup_item_type(ty_def_id
);
223 // if we're making a symbol for something, there ought
224 // to be a value or type-def or something in there
226 ty_def_id
.index
= key
.parent
.unwrap_or_else(|| {
227 bug
!("finding type for {:?}, encountered def-id {:?} with no \
228 parent", def_id
, ty_def_id
);
234 // Erase regions because they may not be deterministic when hashed
235 // and should not matter anyhow.
236 let instance_ty
= ccx
.tcx().erase_regions(&instance_ty
.ty
);
238 let hash
= get_symbol_hash(ccx
, &def_path
, instance_ty
, substs
.types
.as_slice());
240 let mut buffer
= SymbolPathBuffer
{
241 names
: Vec
::with_capacity(def_path
.data
.len())
243 ccx
.tcx().push_item_path(&mut buffer
, def_id
);
245 if let Some(suffix
) = suffix
{
249 mangle(buffer
.names
.into_iter(), Some(&hash
[..]))
252 struct SymbolPathBuffer
{
253 names
: Vec
<InternedString
>,
256 impl ItemPathBuffer
for SymbolPathBuffer
{
257 fn root_mode(&self) -> &RootMode
{
258 const ABSOLUTE
: &'
static RootMode
= &RootMode
::Absolute
;
262 fn push(&mut self, text
: &str) {
263 self.names
.push(token
::intern(text
).as_str());
267 pub fn exported_name
<'a
, 'tcx
>(ccx
: &CrateContext
<'a
, 'tcx
>,
268 instance
: &Instance
<'tcx
>)
270 exported_name_with_opt_suffix(ccx
, instance
, None
)
273 pub fn exported_name_with_suffix
<'a
, 'tcx
>(ccx
: &CrateContext
<'a
, 'tcx
>,
274 instance
: &Instance
<'tcx
>,
277 exported_name_with_opt_suffix(ccx
, instance
, Some(suffix
))
280 /// Only symbols that are invisible outside their compilation unit should use a
281 /// name generated by this function.
282 pub fn internal_name_from_type_and_suffix
<'a
, 'tcx
>(ccx
: &CrateContext
<'a
, 'tcx
>,
286 let path
= [token
::intern(&t
.to_string()).as_str(),
287 gensym_name(suffix
).as_str()];
288 let def_path
= DefPath
{
290 krate
: cstore
::LOCAL_CRATE
,
292 let hash
= get_symbol_hash(ccx
, &def_path
, t
, &[]);
293 mangle(path
.iter().cloned(), Some(&hash
[..]))
296 // Name sanitation. LLVM will happily accept identifiers with weird names, but
298 // gas accepts the following characters in symbols: a-z, A-Z, 0-9, ., _, $
299 pub fn sanitize(s
: &str) -> String
{
300 let mut result
= String
::new();
303 // Escape these with $ sequences
304 '@'
=> result
.push_str("$SP$"),
305 '
*'
=> result
.push_str("$BP$"),
306 '
&'
=> result
.push_str("$RF$"),
307 '
<'
=> result
.push_str("$LT$"),
308 '
>'
=> result
.push_str("$GT$"),
309 '
('
=> result
.push_str("$LP$"),
310 '
)'
=> result
.push_str("$RP$"),
311 '
,'
=> result
.push_str("$C$"),
313 // '.' doesn't occur in types and functions, so reuse it
315 '
-'
| '
:'
=> result
.push('
.'
),
317 // These are legal symbols
321 | '_'
| '
.'
| '$'
=> result
.push(c
),
325 for c
in c
.escape_unicode().skip(1) {
328 '
}'
=> result
.push('$'
),
336 // Underscore-qualify anything that didn't start as an ident.
337 if !result
.is_empty() &&
338 result
.as_bytes()[0] != '_'
as u8 &&
339 ! (result
.as_bytes()[0] as char).is_xid_start() {
340 return format
!("_{}", &result
[..]);
346 pub fn mangle
<PI
: Iterator
<Item
=InternedString
>>(path
: PI
, hash
: Option
<&str>) -> String
{
347 // Follow C++ namespace-mangling style, see
348 // http://en.wikipedia.org/wiki/Name_mangling for more info.
350 // It turns out that on OSX you can actually have arbitrary symbols in
351 // function names (at least when given to LLVM), but this is not possible
352 // when using unix's linker. Perhaps one day when we just use a linker from LLVM
353 // we won't need to do this name mangling. The problem with name mangling is
354 // that it seriously limits the available characters. For example we can't
355 // have things like &T in symbol names when one would theoretically
356 // want them for things like impls of traits on that type.
358 // To be able to work on all platforms and get *some* reasonable output, we
359 // use C++ name-mangling.
361 let mut n
= String
::from("_ZN"); // _Z == Begin name-sequence, N == nested
363 fn push(n
: &mut String
, s
: &str) {
364 let sani
= sanitize(s
);
365 n
.push_str(&format
!("{}{}", sani
.len(), sani
));
368 // First, connect each component with <len, name> pairs.
373 if let Some(s
) = hash
{
377 n
.push('E'
); // End name-sequence.