@@ -618,7 +618,7 @@ each of which may have some number of [attributes](#attributes) attached to it.
618
618
619
619
~~~~~~~~ {.ebnf .gram}
620
620
item : mod_item | fn_item | type_item | struct_item | enum_item
621
- | static_item | trait_item | impl_item | extern_block ;
621
+ | static_item | trait_item | impl_item | foreign_mod_item ;
622
622
~~~~~~~~
623
623
624
624
An _ item_ is a component of a crate; some module items can be defined in crate
@@ -752,11 +752,10 @@ link_attr : ident '=' literal ;
752
752
~~~~~~~~
753
753
754
754
An _ ` extern mod ` declaration_ specifies a dependency on an external crate.
755
- The external crate is then bound into the declaring scope
756
- as the ` ident ` provided in the ` extern_mod_decl ` .
755
+ The external crate is then bound into the declaring scope as the ` ident ` provided in the ` extern_mod_decl ` .
757
756
758
- The external crate is resolved to a specific ` soname ` at compile time,
759
- and a runtime linkage requirement to that ` soname ` is passed to the linker for
757
+ The external crate is resolved to a specific ` soname ` at compile time, and a
758
+ runtime linkage requirement to that ` soname ` is passed to the linker for
760
759
loading at runtime. The ` soname ` is resolved at compile time by scanning the
761
760
compiler's library path and matching the ` link_attrs ` provided in the
762
761
` use_decl ` against any ` #link ` attributes that were declared on the external
@@ -993,10 +992,10 @@ Thus the return type on `f` only needs to reflect the `if` branch of the conditi
993
992
#### Extern functions
994
993
995
994
Extern functions are part of Rust's foreign function interface,
996
- providing the opposite functionality to [ external blocks ] ( #external-blocks ) .
997
- Whereas external blocks allow Rust code to call foreign code,
998
- extern functions with bodies defined in Rust code _ can be called by foreign
999
- code _ . They are defined in the same way as any other Rust function,
995
+ providing the opposite functionality to [ foreign modules ] ( #foreign-modules ) .
996
+ Whereas foreign modules allow Rust code to call foreign code,
997
+ extern functions with bodies defined in Rust code _ can be called by foreign code _ .
998
+ They are defined in the same way as any other Rust function,
1000
999
except that they have the ` extern ` modifier.
1001
1000
1002
1001
~~~
@@ -1012,8 +1011,7 @@ let fptr: *u8 = new_vec;
1012
1011
~~~
1013
1012
1014
1013
The primary motivation for extern functions is
1015
- to create callbacks for foreign functions that expect to receive function
1016
- pointers.
1014
+ to create callbacks for foreign functions that expect to receive function pointers.
1017
1015
1018
1016
### Type definitions
1019
1017
@@ -1310,61 +1308,64 @@ impl Seq<bool> for u32 {
1310
1308
}
1311
1309
~~~~
1312
1310
1313
- ### External blocks
1311
+ ### Foreign modules
1314
1312
1315
1313
~~~ {.ebnf .gram}
1316
- extern_block_item : "extern" '{' extern_block '} ;
1317
- extern_block : [ foreign_fn ] * ;
1314
+ foreign_mod_item : "extern mod" ident '{' foreign_mod '} ;
1315
+ foreign_mod : [ foreign_fn ] * ;
1318
1316
~~~
1319
1317
1320
- External blocks form the basis for Rust's foreign function interface.
1321
- Declarations in an external block describe symbols
1322
- in external, non-Rust libraries.
1323
-
1324
- Functions within external blocks
1325
- are declared in the same way as other Rust functions,
1326
- with the exception that they may not have a body
1327
- and are instead terminated by a semicolon.
1318
+ Foreign modules form the basis for Rust's foreign function interface. A
1319
+ foreign module describes functions in external, non-Rust
1320
+ libraries.
1321
+ Functions within foreign modules are declared in the same way as other Rust functions,
1322
+ with the exception that they may not have a body and are instead terminated by a semicolon.
1328
1323
1329
1324
~~~
1330
1325
# use core::libc::{c_char, FILE};
1331
1326
# #[nolink]
1332
1327
1333
- extern {
1328
+ extern mod c {
1334
1329
fn fopen(filename: *c_char, mode: *c_char) -> *FILE;
1335
1330
}
1336
1331
~~~
1337
1332
1338
- Functions within external blocks may be called by Rust code,
1339
- just like functions defined in Rust.
1340
- The Rust compiler automatically translates
1341
- between the Rust ABI and the foreign ABI.
1333
+ Functions within foreign modules may be called by Rust code, just like functions defined in Rust.
1334
+ The Rust compiler automatically translates between the Rust ABI and the foreign ABI.
1335
+
1336
+ The name of the foreign module has special meaning to the Rust compiler in
1337
+ that it will treat the module name as the name of a library to link to,
1338
+ performing the linking as appropriate for the target platform. The name
1339
+ given for the foreign module will be transformed in a platform-specific way
1340
+ to determine the name of the library. For example, on Linux the name of the
1341
+ foreign module is prefixed with 'lib' and suffixed with '.so', so the
1342
+ foreign mod 'rustrt' would be linked to a library named 'librustrt.so'.
1342
1343
1343
- A number of [ attributes] ( #attributes ) control the behavior of external
1344
- blocks .
1344
+ A number of [ attributes] ( #attributes ) control the behavior of foreign
1345
+ modules .
1345
1346
1346
- By default external blocks assume
1347
- that the library they are calling uses the standard C "cdecl" ABI.
1348
- Other ABIs may be specified using the ` abi ` attribute as in
1347
+ By default foreign modules assume that the library they are calling use the
1348
+ standard C "cdecl" ABI. Other ABIs may be specified using the ` abi `
1349
+ attribute as in
1349
1350
1350
1351
~~~ {.xfail-test}
1351
1352
// Interface to the Windows API
1352
1353
#[abi = "stdcall"]
1353
- extern { }
1354
+ extern mod kernel32 { }
1354
1355
~~~
1355
1356
1356
- The ` link_name ` attribute allows the name of the library to be specified.
1357
+ The ` link_name ` attribute allows the default library naming behavior to
1358
+ be overridden by explicitly specifying the name of the library.
1357
1359
1358
1360
~~~ {.xfail-test}
1359
1361
#[link_name = "crypto"]
1360
- extern { }
1362
+ extern mod mycrypto { }
1361
1363
~~~
1362
1364
1363
- The ` nolink ` attribute tells the Rust compiler
1364
- not to do any linking for the external block.
1365
- This is particularly useful for creating external blocks for libc,
1366
- which tends to not follow standard library naming conventions
1367
- and is linked to all Rust programs anyway.
1365
+ The ` nolink ` attribute tells the Rust compiler not to do any linking for the foreign module.
1366
+ This is particularly useful for creating foreign
1367
+ modules for libc, which tends to not follow standard library naming
1368
+ conventions and is linked to all Rust programs anyway.
1368
1369
1369
1370
## Attributes
1370
1371
@@ -1424,8 +1425,6 @@ names are effectively reserved. Some significant attributes include:
1424
1425
* The ` test ` attribute, for marking functions as unit tests.
1425
1426
* The ` allow ` , ` warn ` , ` forbid ` , and ` deny ` attributes, for controlling lint checks. Lint checks supported
1426
1427
by the compiler can be found via ` rustc -W help ` .
1427
- * The ` deriving ` attribute, for automatically generating
1428
- implementations of certain traits.
1429
1428
1430
1429
Other attributes may be added or removed during development of the language.
1431
1430
@@ -1527,47 +1526,6 @@ A complete list of the built-in language items follows:
1527
1526
> ** Note:** This list is likely to become out of date. We should auto-generate it
1528
1527
> from ` librustc/middle/lang_items.rs ` .
1529
1528
1530
- ### Deriving
1531
-
1532
- The ` deriving ` attribute allows certain traits to be automatically
1533
- implemented for data structures. For example, the following will
1534
- create an ` impl ` for the ` Eq ` and ` Clone ` traits for ` Foo ` , the type
1535
- parameter ` T ` will be given the ` Eq ` or ` Clone ` constraints for the
1536
- appropriate ` impl ` :
1537
-
1538
- ~~~
1539
- #[deriving(Eq, Clone)]
1540
- struct Foo<T> {
1541
- a: int,
1542
- b: T
1543
- }
1544
- ~~~
1545
-
1546
- The generated ` impl ` for ` Eq ` is equivalent to
1547
-
1548
- ~~~
1549
- # struct Foo<T> { a: int, b: T }
1550
- impl<T: Eq> Eq for Foo<T> {
1551
- fn eq(&self, other: &Foo<T>) -> bool {
1552
- self.a == other.a && self.b == other.b
1553
- }
1554
-
1555
- fn ne(&self, other: &Foo<T>) -> bool {
1556
- self.a != other.a || self.b != other.b
1557
- }
1558
- }
1559
- ~~~
1560
-
1561
- Supported traits for ` deriving ` are:
1562
-
1563
- * Comparison traits: ` Eq ` , ` TotalEq ` , ` Ord ` , ` TotalOrd ` .
1564
- * Serialization: ` Encodable ` , ` Decodable ` . These require ` std ` .
1565
- * ` Clone ` , to perform deep copies.
1566
- * ` IterBytes ` , to iterate over the bytes in a data type.
1567
- * ` Rand ` , to create a random instance of a data type.
1568
- * ` ToStr ` , to convert to a string. For a type with this instance,
1569
- ` obj.to_str() ` has the same output as ` fmt!("%?", obj) ` .
1570
-
1571
1529
# Statements and expressions
1572
1530
1573
1531
Rust is _ primarily_ an expression language. This means that most forms of
0 commit comments