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 rustc::middle::weak_lang_items;
101 use rustc_mir::monomorphize::Instance;
102 use rustc_mir::monomorphize::item::{MonoItem, MonoItemExt, InstantiationMode};
103 use rustc::hir::def_id::{DefId, LOCAL_CRATE};
104 use rustc::hir::map as hir_map;
105 use rustc::ty::{self, Ty, TyCtxt, TypeFoldable};
106 use rustc::ty::fold::TypeVisitor;
107 use rustc::ty::item_path::{self, ItemPathBuffer, RootMode};
108 use rustc::ty::maps::Providers;
109 use rustc::ty::subst::Substs;
110 use rustc::hir::map::definitions::DefPathData;
111 use rustc::util::common::record_time;
114 use syntax_pos::symbol::Symbol;
118 pub fn provide(providers: &mut Providers) {
119 *providers = Providers {
127 fn get_symbol_hash<'a, 'tcx>(tcx: TyCtxt<'a, 'tcx, 'tcx>,
129 // the DefId of the item this name is for
132 // instance this name will be for
133 instance: Instance<'tcx>,
135 // type of the item, without any generic
136 // parameters substituted; this is
137 // included in the hash as a kind of
141 // values for generic type parameters,
143 substs: &'tcx Substs<'tcx>)
145 debug!("get_symbol_hash(def_id={:?}, parameters={:?})", def_id, substs);
147 let mut hasher = ty::util::TypeIdHasher::<u64>::new(tcx);
149 record_time(&tcx.sess.perf_stats.symbol_hash_time, || {
150 // the main symbol name is not necessarily unique; hash in the
151 // compiler's internal def-path, guaranteeing each symbol has a
153 hasher.hash(tcx.def_path_hash(def_id));
155 // Include the main item-type. Note that, in this case, the
156 // assertions about `needs_subst` may not hold, but this item-type
157 // ought to be the same for every reference anyway.
158 assert!(!item_type.has_erasable_regions());
159 hasher.visit_ty(item_type);
161 // If this is a function, we hash the signature as well.
162 // This is not *strictly* needed, but it may help in some
163 // situations, see the `run-make/a-b-a-linker-guard` test.
164 if let ty::TyFnDef(..) = item_type.sty {
165 item_type.fn_sig(tcx).visit_with(&mut hasher);
168 // also include any type parameters (for generic items)
169 assert!(!substs.has_erasable_regions());
170 assert!(!substs.needs_subst());
171 substs.visit_with(&mut hasher);
173 let is_generic = substs.types().next().is_some();
174 let avoid_cross_crate_conflicts =
175 // If this is an instance of a generic function, we also hash in
176 // the ID of the instantiating crate. This avoids symbol conflicts
177 // in case the same instances is emitted in two crates of the same
181 // If we're dealing with an instance of a function that's inlined from
182 // another crate but we're marking it as globally shared to our
183 // compliation (aka we're not making an internal copy in each of our
184 // codegen units) then this symbol may become an exported (but hidden
185 // visibility) symbol. This means that multiple crates may do the same
186 // and we want to be sure to avoid any symbol conflicts here.
187 match MonoItem::Fn(instance).instantiation_mode(tcx) {
188 InstantiationMode::GloballyShared { may_conflict: true } => true,
192 if avoid_cross_crate_conflicts {
193 let instantiating_crate = if is_generic {
194 if !def_id.is_local() && tcx.share_generics() {
195 // If we are re-using a monomorphization from another crate,
196 // we have to compute the symbol hash accordingly.
197 let upstream_monomorphizations =
198 tcx.upstream_monomorphizations_for(def_id);
200 upstream_monomorphizations.and_then(|monos| monos.get(&substs)
202 .unwrap_or(LOCAL_CRATE)
210 hasher.hash(&tcx.original_crate_name(instantiating_crate).as_str()[..]);
211 hasher.hash(&tcx.crate_disambiguator(instantiating_crate));
215 // 64 bits should be enough to avoid collisions.
219 fn def_symbol_name<'a, 'tcx>(tcx: TyCtxt<'a, 'tcx, 'tcx>, def_id: DefId)
222 let mut buffer = SymbolPathBuffer::new();
223 item_path::with_forced_absolute_paths(|| {
224 tcx.push_item_path(&mut buffer, def_id);
226 buffer.into_interned()
229 fn symbol_name<'a, 'tcx>(tcx: TyCtxt<'a, 'tcx, 'tcx>, instance: Instance<'tcx>)
232 ty::SymbolName { name: Symbol::intern(&compute_symbol_name(tcx, instance)).as_str() }
235 fn compute_symbol_name<'a, 'tcx>(tcx: TyCtxt<'a, 'tcx, 'tcx>, instance: Instance<'tcx>)
238 let def_id = instance.def_id();
239 let substs = instance.substs;
241 debug!("symbol_name(def_id={:?}, substs={:?})",
244 let node_id = tcx.hir.as_local_node_id(def_id);
246 if let Some(id) = node_id {
247 if *tcx.sess.plugin_registrar_fn.get() == Some(id) {
248 let disambiguator = tcx.sess.local_crate_disambiguator();
249 return tcx.sess.generate_plugin_registrar_symbol(disambiguator);
251 if *tcx.sess.derive_registrar_fn.get() == Some(id) {
252 let disambiguator = tcx.sess.local_crate_disambiguator();
253 return tcx.sess.generate_derive_registrar_symbol(disambiguator);
257 // FIXME(eddyb) Precompute a custom symbol name based on attributes.
258 let attrs = tcx.get_attrs(def_id);
259 let is_foreign = if let Some(id) = node_id {
260 match tcx.hir.get(id) {
261 hir_map::NodeForeignItem(_) => true,
265 tcx.is_foreign_item(def_id)
268 if let Some(name) = weak_lang_items::link_name(&attrs) {
269 return name.to_string();
273 if let Some(name) = attr::first_attr_value_str_by_name(&attrs, "link_name") {
274 return name.to_string();
276 // Don't mangle foreign items.
277 return tcx.item_name(def_id).to_string();
280 if let Some(name) = tcx.trans_fn_attrs(def_id).export_name {
282 return name.to_string();
285 if attr::contains_name(&attrs, "no_mangle") {
287 return tcx.item_name(def_id).to_string();
290 // We want to compute the "type" of this item. Unfortunately, some
291 // kinds of items (e.g., closures) don't have an entry in the
292 // item-type array. So walk back up the find the closest parent
293 // that DOES have an entry.
294 let mut ty_def_id = def_id;
297 let key = tcx.def_key(ty_def_id);
298 match key.disambiguated_data.data {
299 DefPathData::TypeNs(_) |
300 DefPathData::ValueNs(_) => {
301 instance_ty = tcx.type_of(ty_def_id);
305 // if we're making a symbol for something, there ought
306 // to be a value or type-def or something in there
308 ty_def_id.index = key.parent.unwrap_or_else(|| {
309 bug!("finding type for {:?}, encountered def-id {:?} with no \
310 parent", def_id, ty_def_id);
316 // Erase regions because they may not be deterministic when hashed
317 // and should not matter anyhow.
318 let instance_ty = tcx.erase_regions(&instance_ty);
320 let hash = get_symbol_hash(tcx, def_id, instance, instance_ty, substs);
322 SymbolPathBuffer::from_interned(tcx.def_symbol_name(def_id)).finish(hash)
325 // Follow C++ namespace-mangling style, see
326 // http://en.wikipedia.org/wiki/Name_mangling for more info.
328 // It turns out that on macOS you can actually have arbitrary symbols in
329 // function names (at least when given to LLVM), but this is not possible
330 // when using unix's linker. Perhaps one day when we just use a linker from LLVM
331 // we won't need to do this name mangling. The problem with name mangling is
332 // that it seriously limits the available characters. For example we can't
333 // have things like &T in symbol names when one would theoretically
334 // want them for things like impls of traits on that type.
336 // To be able to work on all platforms and get *some* reasonable output, we
337 // use C++ name-mangling.
338 struct SymbolPathBuffer {
343 impl SymbolPathBuffer {
345 let mut result = SymbolPathBuffer {
346 result: String::with_capacity(64),
347 temp_buf: String::with_capacity(16)
349 result.result.push_str("_ZN"); // _Z == Begin name-sequence, N == nested
353 fn from_interned(symbol: ty::SymbolName) -> Self {
354 let mut result = SymbolPathBuffer {
355 result: String::with_capacity(64),
356 temp_buf: String::with_capacity(16)
358 result.result.push_str(&symbol.name);
362 fn into_interned(self) -> ty::SymbolName {
363 ty::SymbolName { name: Symbol::intern(&self.result).as_str() }
366 fn finish(mut self, hash: u64) -> String {
367 // E = end name-sequence
368 let _ = write!(self.result, "17h{:016x}E", hash);
373 impl ItemPathBuffer for SymbolPathBuffer {
374 fn root_mode(&self) -> &RootMode {
375 const ABSOLUTE: &'static RootMode = &RootMode::Absolute;
379 fn push(&mut self, text: &str) {
380 self.temp_buf.clear();
381 let need_underscore = sanitize(&mut self.temp_buf, text);
382 let _ = write!(self.result, "{}", self.temp_buf.len() + (need_underscore as usize));
384 self.result.push('_');
386 self.result.push_str(&self.temp_buf);
390 // Name sanitation. LLVM will happily accept identifiers with weird names, but
392 // gas accepts the following characters in symbols: a-z, A-Z, 0-9, ., _, $
394 // returns true if an underscore must be added at the start
395 pub fn sanitize(result: &mut String, s: &str) -> bool {
398 // Escape these with $ sequences
399 '@' => result.push_str("$SP$"),
400 '*' => result.push_str("$BP$"),
401 '&' => result.push_str("$RF$"),
402 '<' => result.push_str("$LT$"),
403 '>' => result.push_str("$GT$"),
404 '(' => result.push_str("$LP$"),
405 ')' => result.push_str("$RP$"),
406 ',' => result.push_str("$C$"),
408 // '.' doesn't occur in types and functions, so reuse it
410 '-' | ':' => result.push('.'),
412 // These are legal symbols
416 | '_' | '.' | '$' => result.push(c),
420 for c in c.escape_unicode().skip(1) {
423 '}' => result.push('$'),
431 // Underscore-qualify anything that didn't start as an ident.
432 !result.is_empty() &&
433 result.as_bytes()[0] != '_' as u8 &&
434 ! (result.as_bytes()[0] as char).is_xid_start()