1 // Copyright 2015 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 use std::collections::HashMap;
12 use std::ffi::OsString;
13 use std::fs::{self, File};
14 use std::io::prelude::*;
15 use std::io::{self, BufWriter};
16 use std::path::{Path, PathBuf};
17 use std::process::Command;
19 use context::SharedCrateContext;
22 use back::symbol_export::{self, ExportedSymbols};
23 use middle::dependency_format::Linkage;
24 use rustc::hir::def_id::{LOCAL_CRATE, CrateNum};
26 use session::config::{self, CrateType, OptLevel, DebugInfoLevel};
27 use serialize::{json, Encoder};
29 /// For all the linkers we support, and information they might
30 /// need out of the shared crate context before we get rid of it.
31 pub struct LinkerInfo {
32 exports: HashMap<CrateType, Vec<String>>,
35 impl<'a, 'tcx> LinkerInfo {
36 pub fn new(scx: &SharedCrateContext<'a, 'tcx>,
37 exports: &ExportedSymbols) -> LinkerInfo {
39 exports: scx.sess().crate_types.borrow().iter().map(|&c| {
40 (c, exported_symbols(scx, exports, c))
45 pub fn to_linker(&'a self,
47 sess: &'a Session) -> Box<Linker+'a> {
48 if sess.target.target.options.is_like_msvc {
54 } else if sess.target.target.options.is_like_emscripten {
70 /// Linker abstraction used by back::link to build up the command to invoke a
73 /// This trait is the total list of requirements needed by `back::link` and
74 /// represents the meaning of each option being passed down. This trait is then
75 /// used to dispatch on whether a GNU-like linker (generally `ld.exe`) or an
76 /// MSVC linker (e.g. `link.exe`) is being used.
78 fn link_dylib(&mut self, lib: &str);
79 fn link_rust_dylib(&mut self, lib: &str, path: &Path);
80 fn link_framework(&mut self, framework: &str);
81 fn link_staticlib(&mut self, lib: &str);
82 fn link_rlib(&mut self, lib: &Path);
83 fn link_whole_rlib(&mut self, lib: &Path);
84 fn link_whole_staticlib(&mut self, lib: &str, search_path: &[PathBuf]);
85 fn include_path(&mut self, path: &Path);
86 fn framework_path(&mut self, path: &Path);
87 fn output_filename(&mut self, path: &Path);
88 fn add_object(&mut self, path: &Path);
89 fn gc_sections(&mut self, keep_metadata: bool);
90 fn position_independent_executable(&mut self);
91 fn optimize(&mut self);
92 fn debuginfo(&mut self);
93 fn no_default_libraries(&mut self);
94 fn build_dylib(&mut self, out_filename: &Path);
95 fn args(&mut self, args: &[String]);
96 fn hint_static(&mut self);
97 fn hint_dynamic(&mut self);
98 fn whole_archives(&mut self);
99 fn no_whole_archives(&mut self);
100 fn export_symbols(&mut self, tmpdir: &Path, crate_type: CrateType);
101 fn subsystem(&mut self, subsystem: &str);
104 pub struct GnuLinker<'a> {
105 cmd: &'a mut Command,
110 impl<'a> GnuLinker<'a> {
111 fn takes_hints(&self) -> bool {
112 !self.sess.target.target.options.is_like_osx
116 impl<'a> Linker for GnuLinker<'a> {
117 fn link_dylib(&mut self, lib: &str) { self.cmd.arg("-l").arg(lib); }
118 fn link_staticlib(&mut self, lib: &str) { self.cmd.arg("-l").arg(lib); }
119 fn link_rlib(&mut self, lib: &Path) { self.cmd.arg(lib); }
120 fn include_path(&mut self, path: &Path) { self.cmd.arg("-L").arg(path); }
121 fn framework_path(&mut self, path: &Path) { self.cmd.arg("-F").arg(path); }
122 fn output_filename(&mut self, path: &Path) { self.cmd.arg("-o").arg(path); }
123 fn add_object(&mut self, path: &Path) { self.cmd.arg(path); }
124 fn position_independent_executable(&mut self) { self.cmd.arg("-pie"); }
125 fn args(&mut self, args: &[String]) { self.cmd.args(args); }
127 fn link_rust_dylib(&mut self, lib: &str, _path: &Path) {
128 self.cmd.arg("-l").arg(lib);
131 fn link_framework(&mut self, framework: &str) {
132 self.cmd.arg("-framework").arg(framework);
135 fn link_whole_staticlib(&mut self, lib: &str, search_path: &[PathBuf]) {
136 let target = &self.sess.target.target;
137 if !target.options.is_like_osx {
138 self.cmd.arg("-Wl,--whole-archive")
140 .arg("-Wl,--no-whole-archive");
142 // -force_load is the macOS equivalent of --whole-archive, but it
143 // involves passing the full path to the library to link.
144 let mut v = OsString::from("-Wl,-force_load,");
145 v.push(&archive::find_library(lib, search_path, &self.sess));
150 fn link_whole_rlib(&mut self, lib: &Path) {
151 if self.sess.target.target.options.is_like_osx {
152 let mut v = OsString::from("-Wl,-force_load,");
156 self.cmd.arg("-Wl,--whole-archive").arg(lib)
157 .arg("-Wl,--no-whole-archive");
161 fn gc_sections(&mut self, keep_metadata: bool) {
162 // The dead_strip option to the linker specifies that functions and data
163 // unreachable by the entry point will be removed. This is quite useful
164 // with Rust's compilation model of compiling libraries at a time into
165 // one object file. For example, this brings hello world from 1.7MB to
168 // Note that this is done for both executables and dynamic libraries. We
169 // won't get much benefit from dylibs because LLVM will have already
170 // stripped away as much as it could. This has not been seen to impact
171 // link times negatively.
173 // -dead_strip can't be part of the pre_link_args because it's also used
174 // for partial linking when using multiple codegen units (-r). So we
176 if self.sess.target.target.options.is_like_osx {
177 self.cmd.arg("-Wl,-dead_strip");
178 } else if self.sess.target.target.options.is_like_solaris {
179 self.cmd.arg("-Wl,-z");
180 self.cmd.arg("-Wl,ignore");
182 // If we're building a dylib, we don't use --gc-sections because LLVM
183 // has already done the best it can do, and we also don't want to
184 // eliminate the metadata. If we're building an executable, however,
185 // --gc-sections drops the size of hello world from 1.8MB to 597K, a 67%
187 } else if !keep_metadata {
188 self.cmd.arg("-Wl,--gc-sections");
192 fn optimize(&mut self) {
193 if !self.sess.target.target.options.linker_is_gnu { return }
195 // GNU-style linkers support optimization with -O. GNU ld doesn't
196 // need a numeric argument, but other linkers do.
197 if self.sess.opts.optimize == config::OptLevel::Default ||
198 self.sess.opts.optimize == config::OptLevel::Aggressive {
199 self.cmd.arg("-Wl,-O1");
203 fn debuginfo(&mut self) {
204 // Don't do anything special here for GNU-style linkers.
207 fn no_default_libraries(&mut self) {
208 self.cmd.arg("-nodefaultlibs");
211 fn build_dylib(&mut self, out_filename: &Path) {
212 // On mac we need to tell the linker to let this library be rpathed
213 if self.sess.target.target.options.is_like_osx {
214 self.cmd.args(&["-dynamiclib", "-Wl,-dylib"]);
216 // Note that the `osx_rpath_install_name` option here is a hack
217 // purely to support rustbuild right now, we should get a more
218 // principled solution at some point to force the compiler to pass
219 // the right `-Wl,-install_name` with an `@rpath` in it.
220 if self.sess.opts.cg.rpath ||
221 self.sess.opts.debugging_opts.osx_rpath_install_name {
222 let mut v = OsString::from("-Wl,-install_name,@rpath/");
223 v.push(out_filename.file_name().unwrap());
227 self.cmd.arg("-shared");
231 fn whole_archives(&mut self) {
232 if !self.takes_hints() { return }
233 self.cmd.arg("-Wl,--whole-archive");
236 fn no_whole_archives(&mut self) {
237 if !self.takes_hints() { return }
238 self.cmd.arg("-Wl,--no-whole-archive");
241 fn hint_static(&mut self) {
242 if !self.takes_hints() { return }
243 self.cmd.arg("-Wl,-Bstatic");
246 fn hint_dynamic(&mut self) {
247 if !self.takes_hints() { return }
248 self.cmd.arg("-Wl,-Bdynamic");
251 fn export_symbols(&mut self, tmpdir: &Path, crate_type: CrateType) {
252 // If we're compiling a dylib, then we let symbol visibility in object
253 // files to take care of whether they're exported or not.
255 // If we're compiling a cdylib, however, we manually create a list of
256 // exported symbols to ensure we don't expose any more. The object files
257 // have far more public symbols than we actually want to export, so we
258 // hide them all here.
259 if crate_type == CrateType::CrateTypeDylib ||
260 crate_type == CrateType::CrateTypeProcMacro {
264 let mut arg = OsString::new();
265 let path = tmpdir.join("list");
267 debug!("EXPORTED SYMBOLS:");
269 if self.sess.target.target.options.is_like_osx {
270 // Write a plain, newline-separated list of symbols
271 let res = (|| -> io::Result<()> {
272 let mut f = BufWriter::new(File::create(&path)?);
273 for sym in self.info.exports[&crate_type].iter() {
275 writeln!(f, "_{}", sym)?;
279 if let Err(e) = res {
280 self.sess.fatal(&format!("failed to write lib.def file: {}", e));
283 // Write an LD version script
284 let res = (|| -> io::Result<()> {
285 let mut f = BufWriter::new(File::create(&path)?);
286 writeln!(f, "{{\n global:")?;
287 for sym in self.info.exports[&crate_type].iter() {
289 writeln!(f, " {};", sym)?;
291 writeln!(f, "\n local:\n *;\n}};")?;
294 if let Err(e) = res {
295 self.sess.fatal(&format!("failed to write version script: {}", e));
299 if self.sess.target.target.options.is_like_osx {
300 arg.push("-Wl,-exported_symbols_list,");
301 } else if self.sess.target.target.options.is_like_solaris {
304 arg.push("-Wl,--version-script=");
311 fn subsystem(&mut self, subsystem: &str) {
312 self.cmd.arg(&format!("-Wl,--subsystem,{}", subsystem));
316 pub struct MsvcLinker<'a> {
317 cmd: &'a mut Command,
322 impl<'a> Linker for MsvcLinker<'a> {
323 fn link_rlib(&mut self, lib: &Path) { self.cmd.arg(lib); }
324 fn add_object(&mut self, path: &Path) { self.cmd.arg(path); }
325 fn args(&mut self, args: &[String]) { self.cmd.args(args); }
327 fn build_dylib(&mut self, out_filename: &Path) {
328 self.cmd.arg("/DLL");
329 let mut arg: OsString = "/IMPLIB:".into();
330 arg.push(out_filename.with_extension("dll.lib"));
334 fn gc_sections(&mut self, _keep_metadata: bool) {
335 // MSVC's ICF (Identical COMDAT Folding) link optimization is
336 // slow for Rust and thus we disable it by default when not in
337 // optimization build.
338 if self.sess.opts.optimize != config::OptLevel::No {
339 self.cmd.arg("/OPT:REF,ICF");
341 // It is necessary to specify NOICF here, because /OPT:REF
342 // implies ICF by default.
343 self.cmd.arg("/OPT:REF,NOICF");
347 fn link_dylib(&mut self, lib: &str) {
348 self.cmd.arg(&format!("{}.lib", lib));
351 fn link_rust_dylib(&mut self, lib: &str, path: &Path) {
352 // When producing a dll, the MSVC linker may not actually emit a
353 // `foo.lib` file if the dll doesn't actually export any symbols, so we
354 // check to see if the file is there and just omit linking to it if it's
356 let name = format!("{}.dll.lib", lib);
357 if fs::metadata(&path.join(&name)).is_ok() {
362 fn link_staticlib(&mut self, lib: &str) {
363 self.cmd.arg(&format!("{}.lib", lib));
366 fn position_independent_executable(&mut self) {
370 fn no_default_libraries(&mut self) {
371 // Currently we don't pass the /NODEFAULTLIB flag to the linker on MSVC
372 // as there's been trouble in the past of linking the C++ standard
373 // library required by LLVM. This likely needs to happen one day, but
374 // in general Windows is also a more controlled environment than
375 // Unix, so it's not necessarily as critical that this be implemented.
377 // Note that there are also some licensing worries about statically
378 // linking some libraries which require a specific agreement, so it may
379 // not ever be possible for us to pass this flag.
382 fn include_path(&mut self, path: &Path) {
383 let mut arg = OsString::from("/LIBPATH:");
388 fn output_filename(&mut self, path: &Path) {
389 let mut arg = OsString::from("/OUT:");
394 fn framework_path(&mut self, _path: &Path) {
395 bug!("frameworks are not supported on windows")
397 fn link_framework(&mut self, _framework: &str) {
398 bug!("frameworks are not supported on windows")
401 fn link_whole_staticlib(&mut self, lib: &str, _search_path: &[PathBuf]) {
403 self.link_staticlib(lib);
405 fn link_whole_rlib(&mut self, path: &Path) {
407 self.link_rlib(path);
409 fn optimize(&mut self) {
410 // Needs more investigation of `/OPT` arguments
413 fn debuginfo(&mut self) {
414 // This will cause the Microsoft linker to generate a PDB file
415 // from the CodeView line tables in the object files.
416 self.cmd.arg("/DEBUG");
419 fn whole_archives(&mut self) {
420 // hints not supported?
422 fn no_whole_archives(&mut self) {
423 // hints not supported?
426 // On windows static libraries are of the form `foo.lib` and dynamic
427 // libraries are not linked against directly, but rather through their
428 // import libraries also called `foo.lib`. As a result there's no
429 // possibility for a native library to appear both dynamically and
430 // statically in the same folder so we don't have to worry about hints like
431 // we do on Unix platforms.
432 fn hint_static(&mut self) {}
433 fn hint_dynamic(&mut self) {}
435 // Currently the compiler doesn't use `dllexport` (an LLVM attribute) to
436 // export symbols from a dynamic library. When building a dynamic library,
437 // however, we're going to want some symbols exported, so this function
438 // generates a DEF file which lists all the symbols.
440 // The linker will read this `*.def` file and export all the symbols from
441 // the dynamic library. Note that this is not as simple as just exporting
442 // all the symbols in the current crate (as specified by `trans.reachable`)
443 // but rather we also need to possibly export the symbols of upstream
444 // crates. Upstream rlibs may be linked statically to this dynamic library,
445 // in which case they may continue to transitively be used and hence need
446 // their symbols exported.
447 fn export_symbols(&mut self,
449 crate_type: CrateType) {
450 let path = tmpdir.join("lib.def");
451 let res = (|| -> io::Result<()> {
452 let mut f = BufWriter::new(File::create(&path)?);
454 // Start off with the standard module name header and then go
455 // straight to exports.
456 writeln!(f, "LIBRARY")?;
457 writeln!(f, "EXPORTS")?;
458 for symbol in self.info.exports[&crate_type].iter() {
459 debug!(" _{}", symbol);
460 writeln!(f, " {}", symbol)?;
464 if let Err(e) = res {
465 self.sess.fatal(&format!("failed to write lib.def file: {}", e));
467 let mut arg = OsString::from("/DEF:");
472 fn subsystem(&mut self, subsystem: &str) {
473 // Note that previous passes of the compiler validated this subsystem,
474 // so we just blindly pass it to the linker.
475 self.cmd.arg(&format!("/SUBSYSTEM:{}", subsystem));
477 // Windows has two subsystems we're interested in right now, the console
478 // and windows subsystems. These both implicitly have different entry
479 // points (starting symbols). The console entry point starts with
480 // `mainCRTStartup` and the windows entry point starts with
481 // `WinMainCRTStartup`. These entry points, defined in system libraries,
482 // will then later probe for either `main` or `WinMain`, respectively to
483 // start the application.
485 // In Rust we just always generate a `main` function so we want control
486 // to always start there, so we force the entry point on the windows
487 // subsystem to be `mainCRTStartup` to get everything booted up
490 // For more information see RFC #1665
491 if subsystem == "windows" {
492 self.cmd.arg("/ENTRY:mainCRTStartup");
497 pub struct EmLinker<'a> {
498 cmd: &'a mut Command,
503 impl<'a> Linker for EmLinker<'a> {
504 fn include_path(&mut self, path: &Path) {
505 self.cmd.arg("-L").arg(path);
508 fn link_staticlib(&mut self, lib: &str) {
509 self.cmd.arg("-l").arg(lib);
512 fn output_filename(&mut self, path: &Path) {
513 self.cmd.arg("-o").arg(path);
516 fn add_object(&mut self, path: &Path) {
520 fn link_dylib(&mut self, lib: &str) {
521 // Emscripten always links statically
522 self.link_staticlib(lib);
525 fn link_whole_staticlib(&mut self, lib: &str, _search_path: &[PathBuf]) {
527 self.link_staticlib(lib);
530 fn link_whole_rlib(&mut self, lib: &Path) {
535 fn link_rust_dylib(&mut self, lib: &str, _path: &Path) {
536 self.link_dylib(lib);
539 fn link_rlib(&mut self, lib: &Path) {
540 self.add_object(lib);
543 fn position_independent_executable(&mut self) {
547 fn args(&mut self, args: &[String]) {
551 fn framework_path(&mut self, _path: &Path) {
552 bug!("frameworks are not supported on Emscripten")
555 fn link_framework(&mut self, _framework: &str) {
556 bug!("frameworks are not supported on Emscripten")
559 fn gc_sections(&mut self, _keep_metadata: bool) {
563 fn optimize(&mut self) {
564 // Emscripten performs own optimizations
565 self.cmd.arg(match self.sess.opts.optimize {
566 OptLevel::No => "-O0",
567 OptLevel::Less => "-O1",
568 OptLevel::Default => "-O2",
569 OptLevel::Aggressive => "-O3",
570 OptLevel::Size => "-Os",
571 OptLevel::SizeMin => "-Oz"
573 // Unusable until https://github.com/rust-lang/rust/issues/38454 is resolved
574 self.cmd.args(&["--memory-init-file", "0"]);
577 fn debuginfo(&mut self) {
578 // Preserve names or generate source maps depending on debug info
579 self.cmd.arg(match self.sess.opts.debuginfo {
580 DebugInfoLevel::NoDebugInfo => "-g0",
581 DebugInfoLevel::LimitedDebugInfo => "-g3",
582 DebugInfoLevel::FullDebugInfo => "-g4"
586 fn no_default_libraries(&mut self) {
587 self.cmd.args(&["-s", "DEFAULT_LIBRARY_FUNCS_TO_INCLUDE=[]"]);
590 fn build_dylib(&mut self, _out_filename: &Path) {
591 bug!("building dynamic library is unsupported on Emscripten")
594 fn whole_archives(&mut self) {
598 fn no_whole_archives(&mut self) {
602 fn hint_static(&mut self) {
606 fn hint_dynamic(&mut self) {
610 fn export_symbols(&mut self, _tmpdir: &Path, crate_type: CrateType) {
611 let symbols = &self.info.exports[&crate_type];
613 debug!("EXPORTED SYMBOLS:");
617 let mut arg = OsString::from("EXPORTED_FUNCTIONS=");
618 let mut encoded = String::new();
621 let mut encoder = json::Encoder::new(&mut encoded);
622 let res = encoder.emit_seq(symbols.len(), |encoder| {
623 for (i, sym) in symbols.iter().enumerate() {
624 encoder.emit_seq_elt(i, |encoder| {
625 encoder.emit_str(&("_".to_string() + sym))
630 if let Err(e) = res {
631 self.sess.fatal(&format!("failed to encode exported symbols: {}", e));
634 debug!("{}", encoded);
640 fn subsystem(&mut self, _subsystem: &str) {
645 fn exported_symbols(scx: &SharedCrateContext,
646 exported_symbols: &ExportedSymbols,
647 crate_type: CrateType)
649 let export_threshold = symbol_export::crate_export_threshold(crate_type);
651 let mut symbols = Vec::new();
652 exported_symbols.for_each_exported_symbol(LOCAL_CRATE, export_threshold, |name, _| {
653 symbols.push(name.to_owned());
656 let formats = scx.sess().dependency_formats.borrow();
657 let deps = formats[&crate_type].iter();
659 for (index, dep_format) in deps.enumerate() {
660 let cnum = CrateNum::new(index + 1);
661 // For each dependency that we are linking to statically ...
662 if *dep_format == Linkage::Static {
663 // ... we add its symbol list to our export list.
664 exported_symbols.for_each_exported_symbol(cnum, export_threshold, |name, _| {
665 symbols.push(name.to_owned());