[rustc.git] / src / doc / unstable-book / src / language-features / link-args.md

# `link_args`

The tracking issue for this feature is: [#29596]

[#29596]: https://github.com/rust-lang/rust/issues/29596

------------------------

You can tell `rustc` how to customize linking, and that is via the `link_args`
attribute. This attribute is applied to `extern` blocks and specifies raw flags
which need to get passed to the linker when producing an artifact. An example
usage would be:

```rust,no_run
#![feature(link_args)]

#[link_args = "-foo -bar -baz"]
extern "C" {}
# fn main() {}
```

Note that this feature is currently hidden behind the `feature(link_args)` gate
because this is not a sanctioned way of performing linking. Right now `rustc`
shells out to the system linker (`gcc` on most systems, `link.exe` on MSVC), so
it makes sense to provide extra command line arguments, but this will not
always be the case. In the future `rustc` may use LLVM directly to link native
libraries, in which case `link_args` will have no meaning. You can achieve the
same effect as the `link_args` attribute with the `-C link-args` argument to
`rustc`.

It is highly recommended to *not* use this attribute, and rather use the more
formal `#[link(...)]` attribute on `extern` blocks instead.
Commit	Line	Data
8bb4bdeb XL	1	# `link_args`
	2
	3	The tracking issue for this feature is: [#29596]
	4
	5	[#29596]: https://github.com/rust-lang/rust/issues/29596
	6
	7	------------------------
	8
	9	You can tell `rustc` how to customize linking, and that is via the `link_args`
	10	attribute. This attribute is applied to `extern` blocks and specifies raw flags
	11	which need to get passed to the linker when producing an artifact. An example
	12	usage would be:
	13
	14	```rust,no_run
	15	#![feature(link_args)]
	16
	17	#[link_args = "-foo -bar -baz"]
5869c6ff	18	extern "C" {}
8bb4bdeb XL	19	# fn main() {}
	20	```
	21
	22	Note that this feature is currently hidden behind the `feature(link_args)` gate
	23	because this is not a sanctioned way of performing linking. Right now `rustc`
	24	shells out to the system linker (`gcc` on most systems, `link.exe` on MSVC), so
	25	it makes sense to provide extra command line arguments, but this will not
	26	always be the case. In the future `rustc` may use LLVM directly to link native
	27	libraries, in which case `link_args` will have no meaning. You can achieve the
	28	same effect as the `link_args` attribute with the `-C link-args` argument to
	29	`rustc`.
	30
	31	It is highly recommended to not use this attribute, and rather use the more
	32	formal `#[link(...)]` attribute on `extern` blocks instead.