1 // Copyright 2014-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 //! [Flexible target specification.](https://github.com/rust-lang/rfcs/pull/131)
13 //! Rust targets a wide variety of usecases, and in the interest of flexibility,
14 //! allows new target triples to be defined in configuration files. Most users
15 //! will not need to care about these, but this is invaluable when porting Rust
16 //! to a new platform, and allows for an unprecedented level of control over how
17 //! the compiler works.
19 //! # Using custom targets
21 //! A target triple, as passed via `rustc --target=TRIPLE`, will first be
22 //! compared against the list of built-in targets. This is to ease distributing
23 //! rustc (no need for configuration files) and also to hold these built-in
24 //! targets as immutable and sacred. If `TRIPLE` is not one of the built-in
25 //! targets, rustc will check if a file named `TRIPLE` exists. If it does, it
26 //! will be loaded as the target configuration. If the file does not exist,
27 //! rustc will search each directory in the environment variable
28 //! `RUST_TARGET_PATH` for a file named `TRIPLE.json`. The first one found will
29 //! be loaded. If no file is found in any of those directories, a fatal error
30 //! will be given. `RUST_TARGET_PATH` includes `/etc/rustc` as its last entry,
31 //! to be searched by default.
33 //! Projects defining their own targets should use
34 //! `--target=path/to/my-awesome-platform.json` instead of adding to
35 //! `RUST_TARGET_PATH`.
37 //! # Defining a new target
39 //! Targets are defined using [JSON](http://json.org/). The `Target` struct in
40 //! this module defines the format the JSON file should take, though each
41 //! underscore in the field names should be replaced with a hyphen (`-`) in the
42 //! JSON file. Some fields are required in every target specification, such as
43 //! `data-layout`, `llvm-target`, `target-endian`, `target-pointer-width`, and
44 //! `arch`. In general, options passed to rustc with `-C` override the target's
45 //! settings, though `target-feature` and `link-args` will *add* to the list
46 //! specified by the target, rather than replace.
48 use serialize
::json
::Json
;
49 use std
::default::Default
;
50 use std
::io
::prelude
::*;
63 mod windows_msvc_base
;
65 /// Everything `rustc` knows about how to compile for a specific target.
67 /// Every field here must be specified, and has no default value.
68 #[derive(Clone, Debug)]
70 /// Target triple to pass to LLVM.
71 pub llvm_target
: String
,
72 /// String to use as the `target_endian` `cfg` variable.
73 pub target_endian
: String
,
74 /// String to use as the `target_pointer_width` `cfg` variable.
75 pub target_pointer_width
: String
,
76 /// OS name to use for conditional compilation.
77 pub target_os
: String
,
78 /// Environment name to use for conditional compilation.
79 pub target_env
: String
,
80 /// Vendor name to use for conditional compilation.
81 pub target_vendor
: String
,
82 /// Architecture to use for ABI considerations. Valid options: "x86", "x86_64", "arm",
83 /// "aarch64", "mips", "powerpc", "powerpc64" and "powerpc64le". "mips" includes "mipsel".
85 /// Optional settings with defaults.
86 pub options
: TargetOptions
,
89 /// Optional aspects of a target specification.
91 /// This has an implementation of `Default`, see each field for what the default is. In general,
92 /// these try to take "minimal defaults" that don't assume anything about the runtime they run in.
93 #[derive(Clone, Debug)]
94 pub struct TargetOptions
{
95 /// [Data layout](http://llvm.org/docs/LangRef.html#data-layout) to pass to LLVM.
96 pub data_layout
: Option
<String
>,
97 /// Linker to invoke. Defaults to "cc".
99 /// Archive utility to use when managing archives. Defaults to "ar".
102 /// Linker arguments that are unconditionally passed *before* any
103 /// user-defined libraries.
104 pub pre_link_args
: Vec
<String
>,
105 /// Objects to link before all others, always found within the
107 pub pre_link_objects_exe
: Vec
<String
>, // ... when linking an executable
108 pub pre_link_objects_dll
: Vec
<String
>, // ... when linking a dylib
109 /// Linker arguments that are unconditionally passed after any
110 /// user-defined but before post_link_objects. Standard platform
111 /// libraries that should be always be linked to, usually go here.
112 pub late_link_args
: Vec
<String
>,
113 /// Objects to link after all others, always found within the
115 pub post_link_objects
: Vec
<String
>,
116 /// Linker arguments that are unconditionally passed *after* any
117 /// user-defined libraries.
118 pub post_link_args
: Vec
<String
>,
120 /// Default CPU to pass to LLVM. Corresponds to `llc -mcpu=$cpu`. Defaults
123 /// Default target features to pass to LLVM. These features will *always* be
124 /// passed, and cannot be disabled even via `-C`. Corresponds to `llc
125 /// -mattr=$features`.
126 pub features
: String
,
127 /// Whether dynamic linking is available on this target. Defaults to false.
128 pub dynamic_linking
: bool
,
129 /// Whether executables are available on this target. iOS, for example, only allows static
130 /// libraries. Defaults to false.
131 pub executables
: bool
,
132 /// Relocation model to use in object file. Corresponds to `llc
133 /// -relocation-model=$relocation_model`. Defaults to "pic".
134 pub relocation_model
: String
,
135 /// Code model to use. Corresponds to `llc -code-model=$code_model`. Defaults to "default".
136 pub code_model
: String
,
137 /// Do not emit code that uses the "red zone", if the ABI has one. Defaults to false.
138 pub disable_redzone
: bool
,
139 /// Eliminate frame pointers from stack frames if possible. Defaults to true.
140 pub eliminate_frame_pointer
: bool
,
141 /// Emit each function in its own section. Defaults to true.
142 pub function_sections
: bool
,
143 /// String to prepend to the name of every dynamic library. Defaults to "lib".
144 pub dll_prefix
: String
,
145 /// String to append to the name of every dynamic library. Defaults to ".so".
146 pub dll_suffix
: String
,
147 /// String to append to the name of every executable.
148 pub exe_suffix
: String
,
149 /// String to prepend to the name of every static library. Defaults to "lib".
150 pub staticlib_prefix
: String
,
151 /// String to append to the name of every static library. Defaults to ".a".
152 pub staticlib_suffix
: String
,
153 /// OS family to use for conditional compilation. Valid options: "unix", "windows".
154 pub target_family
: Option
<String
>,
155 /// Whether the target toolchain is like OSX's. Only useful for compiling against iOS/OS X, in
156 /// particular running dsymutil and some other stuff like `-dead_strip`. Defaults to false.
157 pub is_like_osx
: bool
,
158 /// Whether the target toolchain is like Windows'. Only useful for compiling against Windows,
159 /// only really used for figuring out how to find libraries, since Windows uses its own
160 /// library naming convention. Defaults to false.
161 pub is_like_windows
: bool
,
162 pub is_like_msvc
: bool
,
163 /// Whether the target toolchain is like Android's. Only useful for compiling against Android.
164 /// Defaults to false.
165 pub is_like_android
: bool
,
166 /// Whether the linker support GNU-like arguments such as -O. Defaults to false.
167 pub linker_is_gnu
: bool
,
168 /// Whether the linker support rpaths or not. Defaults to false.
170 /// Whether to disable linking to compiler-rt. Defaults to false, as LLVM
171 /// will emit references to the functions that compiler-rt provides.
172 pub no_compiler_rt
: bool
,
173 /// Whether to disable linking to the default libraries, typically corresponds
174 /// to `-nodefaultlibs`. Defaults to true.
175 pub no_default_libraries
: bool
,
176 /// Dynamically linked executables can be compiled as position independent
177 /// if the default relocation model of position independent code is not
178 /// changed. This is a requirement to take advantage of ASLR, as otherwise
179 /// the functions in the executable are not randomized and can be used
180 /// during an exploit of a vulnerability in any code.
181 pub position_independent_executables
: bool
,
182 /// Format that archives should be emitted in. This affects whether we use
183 /// LLVM to assemble an archive or fall back to the system linker, and
184 /// currently only "gnu" is used to fall into LLVM. Unknown strings cause
185 /// the system linker to be used.
186 pub archive_format
: String
,
187 /// Is asm!() allowed? Defaults to true.
189 /// Whether the target uses a custom unwind resumption routine.
190 /// By default LLVM lowers `resume` instructions into calls to `_Unwind_Resume`
191 /// defined in libgcc. If this option is enabled, the target must provide
192 /// `eh_unwind_resume` lang item.
193 pub custom_unwind_resume
: bool
,
195 /// Default crate for allocation symbols to link against
196 pub lib_allocation_crate
: String
,
197 pub exe_allocation_crate
: String
,
199 /// Flag indicating whether ELF TLS (e.g. #[thread_local]) is available for
201 pub has_elf_tls
: bool
,
204 impl Default
for TargetOptions
{
205 /// Create a set of "sane defaults" for any target. This is still
206 /// incomplete, and if used for compilation, will certainly not work.
207 fn default() -> TargetOptions
{
210 linker
: option_env
!("CFG_DEFAULT_LINKER").unwrap_or("cc").to_string(),
211 ar
: option_env
!("CFG_DEFAULT_AR").unwrap_or("ar").to_string(),
212 pre_link_args
: Vec
::new(),
213 post_link_args
: Vec
::new(),
214 cpu
: "generic".to_string(),
215 features
: "".to_string(),
216 dynamic_linking
: false,
218 relocation_model
: "pic".to_string(),
219 code_model
: "default".to_string(),
220 disable_redzone
: false,
221 eliminate_frame_pointer
: true,
222 function_sections
: true,
223 dll_prefix
: "lib".to_string(),
224 dll_suffix
: ".so".to_string(),
225 exe_suffix
: "".to_string(),
226 staticlib_prefix
: "lib".to_string(),
227 staticlib_suffix
: ".a".to_string(),
230 is_like_windows
: false,
231 is_like_android
: false,
233 linker_is_gnu
: false,
235 no_compiler_rt
: false,
236 no_default_libraries
: true,
237 position_independent_executables
: false,
238 pre_link_objects_exe
: Vec
::new(),
239 pre_link_objects_dll
: Vec
::new(),
240 post_link_objects
: Vec
::new(),
241 late_link_args
: Vec
::new(),
242 archive_format
: String
::new(),
243 custom_unwind_resume
: false,
244 lib_allocation_crate
: "alloc_system".to_string(),
245 exe_allocation_crate
: "alloc_system".to_string(),
253 /// Given a function ABI, turn "System" into the correct ABI for this target.
254 pub fn adjust_abi(&self, abi
: abi
::Abi
) -> abi
::Abi
{
257 if self.options
.is_like_windows
&& self.arch
== "x86" {
267 /// Load a target descriptor from a JSON object.
268 pub fn from_json(obj
: Json
) -> Target
{
269 // this is 1. ugly, 2. error prone.
271 let get_req_field
= |name
: &str| {
273 .map(|s
| s
.as_string())
274 .and_then(|os
| os
.map(|s
| s
.to_string())) {
277 panic
!("Field {} in target specification is required", name
)
282 let get_opt_field
= |name
: &str, default: &str| {
283 obj
.find(name
).and_then(|s
| s
.as_string())
284 .map(|s
| s
.to_string())
285 .unwrap_or(default.to_string())
288 let mut base
= Target
{
289 llvm_target
: get_req_field("llvm-target"),
290 target_endian
: get_req_field("target-endian"),
291 target_pointer_width
: get_req_field("target-pointer-width"),
292 arch
: get_req_field("arch"),
293 target_os
: get_req_field("os"),
294 target_env
: get_opt_field("env", ""),
295 target_vendor
: get_opt_field("vendor", "unknown"),
296 options
: Default
::default(),
300 ($key_name
:ident
) => ( {
301 let name
= (stringify
!($key_name
)).replace("_", "-");
302 obj
.find(&name
[..]).map(|o
| o
.as_string()
303 .map(|s
| base
.options
.$key_name
= s
.to_string()));
305 ($key_name
:ident
, bool
) => ( {
306 let name
= (stringify
!($key_name
)).replace("_", "-");
308 .map(|o
| o
.as_boolean()
309 .map(|s
| base
.options
.$key_name
= s
));
311 ($key_name
:ident
, list
) => ( {
312 let name
= (stringify
!($key_name
)).replace("_", "-");
313 obj
.find(&name
[..]).map(|o
| o
.as_array()
314 .map(|v
| base
.options
.$key_name
= v
.iter()
315 .map(|a
| a
.as_string().unwrap().to_string()).collect()
319 ($key_name
:ident
, optional
) => ( {
320 let name
= (stringify
!($key_name
)).replace("_", "-");
321 if let Some(o
) = obj
.find(&name
[..]) {
322 base
.options
.$key_name
= o
324 .map(|s
| s
.to_string() );
332 key
!(relocation_model
);
337 key
!(staticlib_prefix
);
338 key
!(staticlib_suffix
);
340 key
!(data_layout
, optional
);
341 key
!(dynamic_linking
, bool
);
342 key
!(executables
, bool
);
343 key
!(disable_redzone
, bool
);
344 key
!(eliminate_frame_pointer
, bool
);
345 key
!(function_sections
, bool
);
346 key
!(target_family
, optional
);
347 key
!(is_like_osx
, bool
);
348 key
!(is_like_windows
, bool
);
349 key
!(linker_is_gnu
, bool
);
350 key
!(has_rpath
, bool
);
351 key
!(no_compiler_rt
, bool
);
352 key
!(no_default_libraries
, bool
);
353 key
!(pre_link_args
, list
);
354 key
!(post_link_args
, list
);
355 key
!(archive_format
);
356 key
!(allow_asm
, bool
);
357 key
!(custom_unwind_resume
, bool
);
362 /// Search RUST_TARGET_PATH for a JSON file specifying the given target
363 /// triple. Note that it could also just be a bare filename already, so also
364 /// check for that. If one of the hardcoded targets we know about, just
365 /// return it directly.
367 /// The error string could come from any of the APIs called, including
368 /// filesystem access and JSON decoding.
369 pub fn search(target
: &str) -> Result
<Target
, String
> {
371 use std
::ffi
::OsString
;
373 use std
::path
::{Path, PathBuf}
;
376 fn load_file(path
: &Path
) -> Result
<Target
, String
> {
377 let mut f
= try
!(File
::open(path
).map_err(|e
| e
.to_string()));
378 let mut contents
= Vec
::new();
379 try
!(f
.read_to_end(&mut contents
).map_err(|e
| e
.to_string()));
380 let obj
= try
!(json
::from_reader(&mut &contents
[..])
381 .map_err(|e
| e
.to_string()));
382 Ok(Target
::from_json(obj
))
385 // this would use a match if stringify! were allowed in pattern position
386 macro_rules
! load_specific
{
387 ( $
($name
:ident
),+ ) => (
390 let target
= target
.replace("-", "_");
393 else if target
== stringify
!($name
) {
394 let t
= $name
::target();
395 debug
!("Got builtin target: {:?}", t
);
399 else if target
== "x86_64-w64-mingw32" {
400 let t
= x86_64_pc_windows_gnu
::target();
402 } else if target
== "i686-w64-mingw32" {
403 let t
= i686_pc_windows_gnu
::target();
411 x86_64_unknown_linux_gnu
,
412 i686_unknown_linux_gnu
,
413 mips_unknown_linux_gnu
,
414 mipsel_unknown_linux_gnu
,
415 powerpc_unknown_linux_gnu
,
416 powerpc64_unknown_linux_gnu
,
417 powerpc64le_unknown_linux_gnu
,
418 arm_unknown_linux_gnueabi
,
419 arm_unknown_linux_gnueabihf
,
420 aarch64_unknown_linux_gnu
,
421 x86_64_unknown_linux_musl
,
424 arm_linux_androideabi
,
425 aarch64_linux_android
,
427 i686_unknown_freebsd
,
428 x86_64_unknown_freebsd
,
430 i686_unknown_dragonfly
,
431 x86_64_unknown_dragonfly
,
433 x86_64_unknown_bitrig
,
434 x86_64_unknown_openbsd
,
435 x86_64_unknown_netbsd
,
436 x86_64_rumprun_netbsd
,
447 x86_64_pc_windows_gnu
,
450 x86_64_pc_windows_msvc
,
451 i686_pc_windows_msvc
,
457 let path
= Path
::new(target
);
460 return load_file(&path
);
464 let mut target
= target
.to_string();
465 target
.push_str(".json");
466 PathBuf
::from(target
)
469 let target_path
= env
::var_os("RUST_TARGET_PATH")
470 .unwrap_or(OsString
::new());
472 // FIXME 16351: add a sane default search path?
474 for dir
in env
::split_paths(&target_path
) {
475 let p
= dir
.join(&path
);
477 return load_file(&p
);
481 Err(format
!("Could not find specification for target {:?}", target
))
485 fn maybe_jemalloc() -> String
{
486 if cfg
!(disable_jemalloc
) {
487 "alloc_system".to_string()
489 "alloc_jemalloc".to_string()