@@ -1507,19 +1507,15 @@ an `abi` string, as shown here:
15071507extern "stdcall" { }
15081508~~~~
15091509
1510- The ` link_name ` attribute allows the name of the library to be specified.
1510+ The ` link ` attribute allows the name of the library to be specified. When
1511+ specified the compiler will attempt to link against the native library of the
1512+ specified name.
15111513
15121514~~~~ {.xfail-test}
1513- #[link_name = "crypto"]
1515+ #[link(name = "crypto") ]
15141516extern { }
15151517~~~~
15161518
1517- The ` nolink ` attribute tells the Rust compiler
1518- not to do any linking for the external block.
1519- This is particularly useful for creating external blocks for libc,
1520- which tends to not follow standard library naming conventions
1521- and is linked to all Rust programs anyway.
1522-
15231519The type of a function
15241520declared in an extern block
15251521is ` extern "abi" fn(A1, ..., An) -> R ` ,
@@ -2074,6 +2070,38 @@ The currently implemented features of the compiler are:
20742070 closure as ` once ` is unlikely to be supported going forward. So
20752071 they are hidden behind this feature until they are to be removed.
20762072
2073+ * ` managed_boxes ` - Usage of ` @ ` pointers is gated due to many
2074+ planned changes to this feature. In the past, this has meant
2075+ "a GC pointer", but the current implementation uses
2076+ reference counting and will likely change drastically over
2077+ time. Additionally, the ` @ ` syntax will no longer be used to
2078+ create GC boxes.
2079+
2080+ * ` asm ` - The ` asm! ` macro provides a means for inline assembly. This is often
2081+ useful, but the exact syntax for this feature along with its semantics
2082+ are likely to change, so this macro usage must be opted into.
2083+
2084+ * ` non_ascii_idents ` - The compiler supports the use of non-ascii identifiers,
2085+ but the implementation is a little rough around the
2086+ edges, so this can be seen as an experimental feature for
2087+ now until the specification of identifiers is fully
2088+ fleshed out.
2089+
2090+ * ` thread_local ` - The usage of the ` #[thread_local] ` attribute is experimental
2091+ and should be seen as unstable. This attribute is used to
2092+ declare a ` static ` as being unique per-thread leveraging
2093+ LLVM's implementation which works in concert with the kernel
2094+ loader and dynamic linker. This is not necessarily available
2095+ on all platforms, and usage of it is discouraged (rust
2096+ focuses more on task-local data instead of thread-local
2097+ data).
2098+
2099+ * ` link_args ` - This attribute is used to specify custom flags to the linker,
2100+ but usage is strongly discouraged. The compiler's usage of the
2101+ system linker is not guaranteed to continue in the future, and
2102+ if the system linker is not used then specifying custom flags
2103+ doesn't have much meaning.
2104+
20772105If a feature is promoted to a language feature, then all existing programs will
20782106start to receive compilation warnings about #[ feature] directives which enabled
20792107the new feature (because the directive is no longer necessary). However, if
@@ -3197,6 +3225,32 @@ let bo: Binop = add;
31973225x = bo(5,7);
31983226~~~~
31993227
3228+ ### Closure types
3229+
3230+ The type of a closure mapping an input of type ` A ` to an output of type ` B ` is ` |A| -> B ` . A closure with no arguments or return values has type ` || ` .
3231+
3232+
3233+ An example of creating and calling a closure:
3234+
3235+ ``` rust
3236+ let captured_var = 10 ;
3237+
3238+ let closure_no_args = || println! (" captured_var={}" captured_var );
3239+
3240+ let closure_args = | arg : int | -> int {
3241+ println! (" captured_var={}, arg={}" captured_var , arg );
3242+ arg // Note lack of semicolon after 'arg'
3243+ };
3244+
3245+ fn call_closure (c1 : || , c2 : | int | -> int ) {
3246+ c1 ();
3247+ c2 (2 );
3248+ }
3249+
3250+ call_closure (closure_no_args , closure_args );
3251+
3252+ ```
3253+
32003254### Object types
32013255
32023256Every trait item (see [ traits] ( #traits ) ) defines a type with the same name as the trait.
@@ -3615,6 +3669,111 @@ queues, as well as code to copy values between queues and their recipients and
36153669to serialize values for transmission over operating-system inter-process
36163670communication facilities.
36173671
3672+ ### Linkage
3673+
3674+ The Rust compiler supports various methods to link crates together both
3675+ statically and dynamically. This section will explore the various methods to
3676+ link Rust crates together, and more information about native libraries can be
3677+ found in the [ ffi tutorial] [ ffi ] .
3678+
3679+ In one session of compilation, the compiler can generate multiple artifacts
3680+ through the usage of command line flags and the ` crate_type ` attribute.
3681+
3682+ * ` --bin ` , ` #[crate_type = "bin"] ` - A runnable executable will be produced.
3683+ This requires that there is a ` main ` function in the crate which will be run
3684+ when the program begins executing. This will link in all Rust and native
3685+ dependencies, producing a distributable binary.
3686+
3687+ * ` --lib ` , ` #[crate_type = "lib"] ` - A Rust library will be produced. This is
3688+ an ambiguous concept as to what exactly is produced because a library can
3689+ manifest itself in several forms. The purpose of this generic ` lib ` option is
3690+ to generate the "compiler recommended" style of library. The output library
3691+ will always be usable by rustc, but the actual type of library may change
3692+ from time-to-time. The remaining output types are all different flavors of
3693+ libraries, and the ` lib ` type can be seen as an alias for one of them (but
3694+ the actual one is compiler-defined).
3695+
3696+ * ` --dylib ` , ` #[crate_type = "dylib"] ` - A dynamic Rust library will be
3697+ produced. This is different from the ` lib ` output type in that this forces
3698+ dynamic library generation. The resulting dynamic library can be used as a
3699+ dependency for other libraries and/or executables. This output type will
3700+ create ` *.so ` files on linux, ` *.dylib ` files on osx, and ` *.dll ` files on
3701+ windows.
3702+
3703+ * ` --staticlib ` , ` #[crate_type = "staticlib"] ` - A static system library will
3704+ be produced. This is different from other library outputs in that the Rust
3705+ compiler will never attempt to link to ` staticlib ` outputs. The purpose of
3706+ this output type is to create a static library containing all of the local
3707+ crate's code along with all upstream dependencies. The static library is
3708+ actually a ` *.a ` archive on linux and osx and a ` *.lib ` file on windows. This
3709+ format is recommended for use in situtations such as linking Rust code into an
3710+ existing non-Rust application because it will not have dynamic dependencies on
3711+ other Rust code.
3712+
3713+ * ` --rlib ` , ` #[crate_type = "rlib"] ` - A "Rust library" file will be produced.
3714+ This is used as an intermediate artifact and can be thought of as a "static
3715+ Rust library". These ` rlib ` files, unlike ` staticlib ` files, are interpreted
3716+ by the Rust compiler in future linkage. This essentially means that ` rustc `
3717+ will look for metadata in ` rlib ` files like it looks for metadata in dynamic
3718+ libraries. This form of output is used to produce statically linked
3719+ executables as well as ` staticlib ` outputs.
3720+
3721+ Note that these outputs are stackable in the sense that if multiple are
3722+ specified, then the compiler will produce each form of output at once without
3723+ having to recompile.
3724+
3725+ With all these different kinds of outputs, if crate A depends on crate B, then
3726+ the compiler could find B in various different forms throughout the system. The
3727+ only forms looked for by the compiler, however, are the ` rlib ` format and the
3728+ dynamic library format. With these two options for a dependent library, the
3729+ compiler must at some point make a choice between these two formats. With this
3730+ in mind, the compiler follows these rules when determining what format of
3731+ dependencies will be used:
3732+
3733+ 1 . If a dynamic library is being produced, then it is required for all upstream
3734+ Rust dependencies to also be dynamic. This is a limitation of the current
3735+ implementation of the linkage model. The reason behind this limitation is to
3736+ prevent multiple copies of the same upstream library from showing up, and in
3737+ the future it is planned to support a mixture of dynamic and static linking.
3738+
3739+ When producing a dynamic library, the compiler will generate an error if an
3740+ upstream dependency could not be found, and also if an upstream dependency
3741+ could only be found in an ` rlib ` format. Remember that ` staticlib ` formats
3742+ are always ignored by ` rustc ` for crate-linking purposes.
3743+
3744+ 2 . If a static library is being produced, all upstream dependecies are
3745+ required to be available in ` rlib ` formats. This requirement stems from the
3746+ same reasons that a dynamic library must have all dynamic dependencies.
3747+
3748+ Note that it is impossible to link in native dynamic dependencies to a static
3749+ library, and in this case warnings will be printed about all unlinked native
3750+ dynamic dependencies.
3751+
3752+ 3 . If an ` rlib ` file is being produced, then there are no restrictions on what
3753+ format the upstream dependencies are available in. It is simply required that
3754+ all upstream dependencies be available for reading metadata from.
3755+
3756+ The reason for this is that ` rlib ` files do not contain any of their upstream
3757+ dependencies. It wouldn't be very efficient for all ` rlib ` files to contain a
3758+ copy of ` libstd.rlib ` !
3759+
3760+ 4 . If an executable is being produced, then things get a little interesting. As
3761+ with the above limitations in dynamic and static libraries, it is required
3762+ for all upstream dependencies to be in the same format. The next question is
3763+ whether to prefer a dynamic or a static format. The compiler currently favors
3764+ static linking over dynamic linking, but this can be inverted with the `-Z
3765+ prefer-dynamic` flag to the compiler.
3766+
3767+ What this means is that first the compiler will attempt to find all upstream
3768+ dependencies as ` rlib ` files, and if successful, it will create a statically
3769+ linked executable. If an upstream dependency is missing as an ` rlib ` file,
3770+ then the compiler will force all dependencies to be dynamic and will generate
3771+ errors if dynamic versions could not be found.
3772+
3773+ In general, ` --bin ` or ` --lib ` should be sufficient for all compilation needs,
3774+ and the other options are just available if more fine-grained control is desired
3775+ over the output format of a Rust crate.
3776+
36183777### Logging system
36193778
36203779The runtime contains a system for directing [ logging
@@ -3766,3 +3925,5 @@ Additional specific influences can be seen from the following languages:
37663925* The typeclass system of Haskell.
37673926* The lexical identifier rule of Python.
37683927* The block syntax of Ruby.
3928+
3929+ [ ffi ] : tutorial-ffi.html
0 commit comments