Skip to content

/rust

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document static linking and support OSX frameworks #10742

Merged
merged 2 commits into from Dec 2, 2013

Conversation

Reviewers
No reviews
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
5 participants
@alexcrichton @cmr @dwrensha @huonw @bors
@alexcrichton
Copy link
Member

alexcrichton commented Dec 1, 2013

Commits have the fun details, and scrutiny on the new documentation would be appreciated!
@alexcrichton
Support OSX frameworks 
This adds support to link to OSX frameworks via the new link attribute when
using `kind = "framework"`. It is a compiler error to request linkage to a
framework when the target is not macos because other platforms don't support
frameworks.

Closes #2023
f9d6fd2
@huonw

huonw reviewed Dec 1, 2013
View changes

doc/rust.md Outdated
In one session of compilation, the compiler can generate multiple artifacts
through the usage of command line flags and the `crate_type` attribute.

* `--bin`, `#[crate_type = "bin"]` - A runnable executable should be produced.

This comment has been minimized.

Sign in to view
Copy link
@huonw

huonw Dec 1, 2013

Member

Could the flags just be --crate-type bin, etc?

This comment has been minimized.

Sign in to view
Copy link
@alexcrichton

alexcrichton Dec 1, 2013

Author Member

I thought of doing something like that, but I didn't want to break the existing --lib flag because it seems like creating a library should still be "just that simple". Perhaps --lib would imply --crate-type dylib though, and --bin would imply --crate-type bin and then we could put all the more colorful flavors behind the crate-type flag.

This comment has been minimized.

Sign in to view
Copy link
@cmr

cmr Dec 1, 2013

Member

"should" in all of these should be "will"
@huonw

huonw reviewed Dec 1, 2013
View changes

doc/rust.md Outdated

1. If a dynamic library is being produced, then it is required for all upstream
rust dependencies to also be dynamic. This is a limitation of the current
implementation of linkage model that all upstream dependencies must be

This comment has been minimized.

Sign in to view
Copy link
@huonw

huonw Dec 1, 2013

Member

Drop the "that all upstream ...", since "This" clearly refers to the requirement for them to be dynamic in the previous sentence.

This comment has been minimized.

Sign in to view
Copy link
@cmr

cmr Dec 1, 2013

Member

"of the linkage model"
@huonw

huonw reviewed Dec 1, 2013
View changes

doc/rust.md Outdated

When producing a dynamic library, the compiler will generate an error if an
upstream dependency could not be found, and also if an upstream dependency
could only be found in an `rlib` format.

This comment has been minimized.

Sign in to view
Copy link
@huonw

huonw Dec 1, 2013

Member

What about if they are found as a staticlib?

This comment has been minimized.

Sign in to view
Copy link
@alexcrichton

alexcrichton Dec 1, 2013

Author Member

The compiler won't look for anything built as a staticlib. It isn't guaranteed that staticlibs will always have metadata, and they're only useful for the final result before putting it in an external application.
@huonw

huonw reviewed Dec 1, 2013
View changes

doc/rust.md Outdated

2. If a static library is being produced, then the same limitations of creating
dynamic libraries are in effect. This means that all upstream dependecies are
required to be available in `rlib` formats.

This comment has been minimized.

Sign in to view
Copy link
@huonw

huonw Dec 1, 2013

Member

This isn't the same limitation as for dynamic libraries. Is the following a correct interpretation "If a static library is being produced, then all upstream dependencies have to be available in as rlibs, for a similar reason for dynamic libraries requiring dynamic dependencies".

(Also dependencies is misspelt on the previous line.)

This comment has been minimized.

Sign in to view
Copy link
@alexcrichton

alexcrichton Dec 1, 2013

Author Member

Hm good point, I shall re-word.
doc/rust.md
prefer-dynamic` flag to the compiler.

What this means is that first the compiler will attempt to find all upstream
dependencies as `rlib` files, and if successful, it will create a statically

This comment has been minimized.

Sign in to view
Copy link
@huonw

huonw Dec 1, 2013

Member

Presumably all the standard libraries are compiled as a rlib by default, so binaries linking to only std and extra will normally be statically linked? (Just out of interest.)

This comment has been minimized.

Sign in to view
Copy link
@alexcrichton

alexcrichton Dec 1, 2013

Author Member

That is correct, although only lib{rustuv,extra,std} are built as rlib files.
@huonw

huonw reviewed Dec 1, 2013
View changes

doc/rust.md Outdated
With all these different kinds of outputs, if crate A depends on crate B, then
the compiler could find B in various different forms throughout the system. The
only forms looked for by the compiler, however, are the `rlib` format and
dynamic library format. With these two options for a dependant library, the

This comment has been minimized.

Sign in to view
Copy link
@huonw

huonw Dec 1, 2013

Member

"dependent"?
@huonw

huonw reviewed Dec 1, 2013
View changes

doc/rust.md Outdated
@@ -3611,6 +3645,111 @@ queues, as well as code to copy values between queues and their recipients and
to serialize values for transmission over operating-system inter-process
communication facilities.

### Linkage

The rust compiler supports various methods to link crates together along with

This comment has been minimized.

Sign in to view
Copy link
@huonw

huonw Dec 1, 2013

Member

Genuine question: should "Rust" be capitalised? (There are a few other places with it lowercase in these additions too.)

This comment has been minimized.

Sign in to view
Copy link
@alexcrichton

alexcrichton Dec 1, 2013

Author Member

I think that it should be, I think I'm just bad at doing that.
@huonw

huonw reviewed Dec 1, 2013
View changes

doc/tutorial-ffi.md Outdated
platform's C ABI. The `#[link_args]` attribute is used to instruct the linker to link against the
snappy library so the symbols are resolved.
The `extern` block is a list of function signatures in a foreign library, in
this case with the platform's C ABI. The `#[linke(...)]` attribute is used to

This comment has been minimized.

Sign in to view
Copy link
@huonw

huonw Dec 1, 2013

Member

#[link(...)] right?
@huonw

huonw reviewed Dec 1, 2013
View changes

doc/tutorial-ffi.md Outdated

~~~~ {.xfail-test}
use std::libc::size_t;

#[link_args = "-lsnappy"]
#[link(name = "-lsnappy")]

This comment has been minimized.

Sign in to view
Copy link
@huonw

huonw Dec 1, 2013

Member

Is the name meant to be snappy or is it actually supposed to be written as -lsnappy?

This comment has been minimized.

Sign in to view
Copy link
@alexcrichton

alexcrichton Dec 1, 2013

Author Member

Ah, just snappy
@huonw

huonw reviewed Dec 1, 2013
View changes

doc/tutorial-ffi.md Outdated
recommended to build the native dependency as a static library so that it
doesn't have to be distributed with the rust library.

Dynamic libraries, however, will be propagated among crates. What this means is

This comment has been minimized.

Sign in to view
Copy link
@huonw

huonw Dec 1, 2013

Member

"What this means" is used 3 times in two paragraphs, and to start two consecutive sentences here.

This comment has been minimized.

Sign in to view
Copy link
@alexcrichton

alexcrichton Dec 1, 2013

Author Member

Haha, can you tell what sentences I was distracted for a few minutes between and how often I read backwards?
@huonw

huonw reviewed Dec 1, 2013
View changes

doc/tutorial-ffi.md Outdated
meaning.

It is highly recommended to *not* use this attribute, and rather use the more
format `#[link(...)]` attribute on `extern` blocks instead.

This comment has been minimized.

Sign in to view
Copy link
@huonw

huonw Dec 1, 2013

Member

"The more format"?

This comment has been minimized.

Sign in to view
Copy link
@alexcrichton

alexcrichton Dec 1, 2013

Author Member

Ah, formal is what I was going for
@huonw

huonw reviewed Dec 1, 2013
View changes

doc/tutorial-ffi.md Outdated
crates. What this means is that that static library will always be included in
the artifact that rustc produces (whether it's a library or an executable). As a
result, if a rust library has a native library as a build dependency, it is
recommended to build the native dependency as a static library so that it

This comment has been minimized.

Sign in to view
Copy link
@huonw

huonw Dec 1, 2013

Member

With this in mind, should kind default to static rather than dynamic?

This comment has been minimized.

Sign in to view
Copy link
@alexcrichton

alexcrichton Dec 1, 2013

Author Member

Perhaps? Perhaps we should also just require kind to be specified.
@huonw

huonw reviewed Dec 1, 2013
View changes

doc/tutorial-ffi.md Outdated
Note that frameworks are only available on OSX targets.

The semantics of these different kinds of native libraries a little subtle. The
rust compiler will never propagate usage of static native libraries among

This comment has been minimized.

Sign in to view
Copy link
@huonw

huonw Dec 1, 2013

Member

I'm not clear what this means? Presumably one can still use the symbols imported from a static native library in another crate if they are exported appropriately (i.e. #[link(name="foo", kind="static")] extern { pub fn some_symbol(); } extern mod that_crate; fn main() { unsafe { that_crate::some_symbol() } })?

Is it meant to mean "Rustc will only link the crate with the explicit #[link(name="foo", kind="static")] against the foo static library"? (I think this paragraph, and possibly the next, could do with some simplification.)

This comment has been minimized.

Sign in to view
Copy link
@alexcrichton

alexcrichton Dec 1, 2013

Author Member

You have the correct idea, I shall re-word to be clearer.
@dwrensha

dwrensha reviewed Dec 1, 2013
View changes

doc/rust.md Outdated
@@ -2070,6 +2070,40 @@ The currently implemented features of the compiler are:
closure as `once` is unlikely to be supported going forward. So
they are hidden behind this feature until they are to be removed.

* `managed_boxes` - Usage of `@` pointers is gated by default due to many
planned changes to this feature. This in the past has mean

This comment has been minimized.

Sign in to view
Copy link
@dwrensha

dwrensha Dec 1, 2013

Contributor

s/mean/meant/
@cmr

cmr reviewed Dec 1, 2013
View changes

doc/rust.md Outdated
### Linkage

The rust compiler supports various methods to link crates together along with
mixing static libraries. This section will explore the various methods to link

This comment has been minimized.

Sign in to view
Copy link
@cmr

cmr Dec 1, 2013

Member

"along with mixing static libraries" is awful wording. I don't even know what it's supposed to mean to recommend alternatives.
@cmr

cmr reviewed Dec 1, 2013
View changes

doc/rust.md Outdated
through the usage of command line flags and the `crate_type` attribute.

* `--bin`, `#[crate_type = "bin"]` - A runnable executable should be produced.
This requires that there is a `main` function in the crate which will be run

This comment has been minimized.

Sign in to view
Copy link
@cmr

cmr Dec 1, 2013

Member

We appear to not have any documentation whatsoever on how entry points work. It'd be nice to have a section on "Entry point" that this references.
@cmr

cmr reviewed Dec 1, 2013
View changes

doc/rust.md Outdated
dependencies, producing a distributable binary.

* `--lib`, `#[crate_type = "lib"]` - A rust library should be produced. This is
a little bit of an ambiguous concept as to what exactly is produced because a

This comment has been minimized.

Sign in to view
Copy link
@cmr

cmr Dec 1, 2013

Member

s/a little bit of//
@cmr

cmr reviewed Dec 1, 2013
View changes

doc/rust.md Outdated

With all these different kinds of outputs, if crate A depends on crate B, then
the compiler could find B in various different forms throughout the system. The
only forms looked for by the compiler, however, are the `rlib` format and

This comment has been minimized.

Sign in to view
Copy link
@cmr

cmr Dec 1, 2013

Member

"and the dynamic..."
@cmr

cmr reviewed Dec 1, 2013
View changes

doc/tutorial-ffi.md Outdated
* `#[link(name = "foo", kind = "bar")]`

In both of these cases, `foo` is the name of the native library that we're
linking too, and in the second case `bar` is the type of native library that the

This comment has been minimized.

Sign in to view
Copy link
@cmr

cmr Dec 1, 2013

Member

s/too/to/
@cmr

cmr reviewed Dec 1, 2013
View changes

doc/tutorial-ffi.md Outdated

Note that frameworks are only available on OSX targets.

The semantics of these different kinds of native libraries a little subtle. The

This comment has been minimized.

Sign in to view
Copy link
@cmr

cmr Dec 1, 2013

Member

"is subtle"
@alexcrichton

This comment has been minimized.

Sign in to view
Copy link
Member Author

alexcrichton commented Dec 1, 2013

I've updated with all the feedback (thanks!).
@cmr

cmr reviewed Dec 2, 2013
View changes

doc/rust.md Outdated
@@ -2070,6 +2070,40 @@ The currently implemented features of the compiler are:
closure as `once` is unlikely to be supported going forward. So
they are hidden behind this feature until they are to be removed.

* `managed_boxes` - Usage of `@` pointers is gated by default due to many

This comment has been minimized.

Sign in to view
Copy link
@cmr

cmr Dec 2, 2013

Member

s/by default//
@cmr

cmr reviewed Dec 2, 2013
View changes

doc/rust.md Outdated
@@ -2070,6 +2070,40 @@ The currently implemented features of the compiler are:
closure as `once` is unlikely to be supported going forward. So
they are hidden behind this feature until they are to be removed.

* `managed_boxes` - Usage of `@` pointers is gated by default due to many
planned changes to this feature. This in the past has meant

This comment has been minimized.

Sign in to view
Copy link
@cmr

cmr Dec 2, 2013

Member

"In this past, this has meant..."
@cmr

cmr reviewed Dec 2, 2013
View changes

doc/rust.md Outdated
planned changes to this feature. This in the past has meant
"a GC pointer", but the current implementation uses
reference counting and will likely change drastically over
time. It is also planned such that `@` will no longer be the

This comment has been minimized.

Sign in to view
Copy link
@cmr

cmr Dec 2, 2013

Member

"Additionally, the @ syntax will no longer be used to create GC boxes."
@cmr

cmr reviewed Dec 2, 2013
View changes

doc/rust.md Outdated
"a GC pointer", but the current implementation uses
reference counting and will likely change drastically over
time. It is also planned such that `@` will no longer be the
syntax to create GC boxes in the future. For now, this can

This comment has been minimized.

Sign in to view
Copy link
@cmr

cmr Dec 2, 2013

Member

Remove last sentence (it's a feature gate, and you've already stated that it's drastically changing)
@cmr

cmr reviewed Dec 2, 2013
View changes

doc/rust.md Outdated
be seen as an experimental feature which will change
drastically in the near future.

* `asm` - The `asm!` macro provides a way to specify native assembly to be run

This comment has been minimized.

Sign in to view
Copy link
@cmr

cmr Dec 2, 2013

Member

This is a bit confusing. It isn't run when the crate is compiled. Perhaps a better wording:

"The asm! macro provides a means for inline assembly. This is often..."
@cmr

cmr reviewed Dec 2, 2013
View changes

doc/rust.md Outdated
this feature along with its semantics are likely to change, so this
macro usage must be opted into.

* `non_ascii_idents` - The compiler supports the usage of non-ascii identifiers,

This comment has been minimized.

Sign in to view
Copy link
@cmr

cmr Dec 2, 2013

Member

s/usage/use/
@cmr

cmr reviewed Dec 2, 2013
View changes

doc/rust.md Outdated
* `thread_local` - The usage of the `#[thread_local]` attribute is experimental
and should be seen as unstable. This attribute is used to
declare a `static` as being unique per-thread leveraging
LLVM's implementation which works in concert with the dynamic

This comment has been minimized.

Sign in to view
Copy link
@cmr

cmr Dec 2, 2013

Member

This isn't exactly true; it works with static linking too.
@cmr

cmr reviewed Dec 2, 2013
View changes

doc/tutorial-ffi.md Outdated
When declaring the argument types to a foreign function, the Rust compiler will not check if the
declaration is correct, so specifying it correctly is part of keeping the binding correct at
runtime.
When declaring the argument types to a foreign function, the Rust compiler will

This comment has been minimized.

Sign in to view
Copy link
@cmr

cmr Dec 2, 2013

Member

s/will not/can not/
@cmr

This comment has been minimized.

Sign in to view
Copy link
Member

cmr commented Dec 2, 2013

r=me with fixes
@alexcrichton
Bring the linkage documentation up-to-date 
This includes documentation for all the previous changes done to linking
in #10582. Additionally, this brings the list of feature-gates up-to-date with
the currently recognized list of features.
Loading status checks…
d4c40b5
@alexcrichton

This comment has been minimized.

Sign in to view
Copy link
Owner Author

alexcrichton commented on d4c40b5 Dec 2, 2013

r=cmr
@bors

This comment has been minimized.

Sign in to view
Copy link
Contributor

bors commented on d4c40b5 Dec 2, 2013

saw approval from cmr
at alexcrichton@d4c40b5

This comment has been minimized.

Sign in to view
Copy link
Contributor

bors replied Dec 2, 2013

merging alexcrichton/rust/frameworks = d4c40b5 into auto

This comment has been minimized.

Sign in to view
Copy link
Contributor

bors replied Dec 2, 2013

alexcrichton/rust/frameworks = d4c40b5 merged ok, testing candidate = c8b60a2

This comment has been minimized.

Sign in to view
Copy link
Contributor

bors replied Dec 2, 2013

fast-forwarding master to auto = c8b60a2

bors added a commit that referenced this pull request Dec 2, 2013

@bors
auto merge of #10742 : alexcrichton/rust/frameworks, r=cmr 
Commits have the fun details, and scrutiny on the new documentation would be appreciated!
c8b60a2

@bors bors closed this Dec 2, 2013

@bors bors merged commit d4c40b5 into rust-lang:master Dec 2, 2013
1 check passed

1 check passed

default all tests passed

@alexcrichton alexcrichton deleted the alexcrichton:frameworks branch Dec 4, 2013

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.