@@ -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 | foreign_mod_item ;
621
+ | static_item | trait_item | impl_item | extern_block ;
622
622
~~~~~~~~
623
623
624
624
An _ item_ is a component of a crate; some module items can be defined in crate
@@ -752,10 +752,11 @@ 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 as the ` ident ` provided in the ` extern_mod_decl ` .
755
+ The external crate is then bound into the declaring scope
756
+ as the ` ident ` provided in the ` extern_mod_decl ` .
756
757
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
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
759
760
loading at runtime. The ` soname ` is resolved at compile time by scanning the
760
761
compiler's library path and matching the ` link_attrs ` provided in the
761
762
` use_decl ` against any ` #link ` attributes that were declared on the external
@@ -992,10 +993,10 @@ Thus the return type on `f` only needs to reflect the `if` branch of the conditi
992
993
#### Extern functions
993
994
994
995
Extern functions are part of Rust's foreign function interface,
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,
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,
999
1000
except that they have the ` extern ` modifier.
1000
1001
1001
1002
~~~
@@ -1011,7 +1012,8 @@ let fptr: *u8 = new_vec;
1011
1012
~~~
1012
1013
1013
1014
The primary motivation for extern functions is
1014
- to create callbacks for foreign functions that expect to receive function pointers.
1015
+ to create callbacks for foreign functions that expect to receive function
1016
+ pointers.
1015
1017
1016
1018
### Type definitions
1017
1019
@@ -1308,64 +1310,61 @@ impl Seq<bool> for u32 {
1308
1310
}
1309
1311
~~~~
1310
1312
1311
- ### Foreign modules
1313
+ ### External blocks
1312
1314
1313
1315
~~~ {.ebnf .gram}
1314
- foreign_mod_item : "extern mod" ident '{' foreign_mod '} ;
1315
- foreign_mod : [ foreign_fn ] * ;
1316
+ extern_block_item : "extern" '{' extern_block '} ;
1317
+ extern_block : [ foreign_fn ] * ;
1316
1318
~~~
1317
1319
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.
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.
1323
1328
1324
1329
~~~
1325
1330
# use core::libc::{c_char, FILE};
1326
1331
# #[nolink]
1327
1332
1328
- extern mod c {
1333
+ extern {
1329
1334
fn fopen(filename: *c_char, mode: *c_char) -> *FILE;
1330
1335
}
1331
1336
~~~
1332
1337
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'.
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.
1343
1342
1344
- A number of [ attributes] ( #attributes ) control the behavior of foreign
1345
- modules .
1343
+ A number of [ attributes] ( #attributes ) control the behavior of external
1344
+ blocks .
1346
1345
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
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
1350
1349
1351
1350
~~~ {.xfail-test}
1352
1351
// Interface to the Windows API
1353
1352
#[abi = "stdcall"]
1354
- extern mod kernel32 { }
1353
+ extern { }
1355
1354
~~~
1356
1355
1357
- The ` link_name ` attribute allows the default library naming behavior to
1358
- be overridden by explicitly specifying the name of the library.
1356
+ The ` link_name ` attribute allows the name of the library to be specified.
1359
1357
1360
1358
~~~ {.xfail-test}
1361
1359
#[link_name = "crypto"]
1362
- extern mod mycrypto { }
1360
+ extern { }
1363
1361
~~~
1364
1362
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.
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.
1369
1368
1370
1369
## Attributes
1371
1370
@@ -1425,8 +1424,6 @@ names are effectively reserved. Some significant attributes include:
1425
1424
* The ` test ` attribute, for marking functions as unit tests.
1426
1425
* The ` allow ` , ` warn ` , ` forbid ` , and ` deny ` attributes, for controlling lint checks. Lint checks supported
1427
1426
by the compiler can be found via ` rustc -W help ` .
1428
- * The ` deriving ` attribute, for automatically generating
1429
- implementations of certain traits.
1430
1427
1431
1428
Other attributes may be added or removed during development of the language.
1432
1429
@@ -1528,47 +1525,6 @@ A complete list of the built-in language items follows:
1528
1525
> ** Note:** This list is likely to become out of date. We should auto-generate it
1529
1526
> from ` librustc/middle/lang_items.rs ` .
1530
1527
1531
- ### Deriving
1532
-
1533
- The ` deriving ` attribute allows certain traits to be automatically
1534
- implemented for data structures. For example, the following will
1535
- create an ` impl ` for the ` Eq ` and ` Clone ` traits for ` Foo ` , the type
1536
- parameter ` T ` will be given the ` Eq ` or ` Clone ` constraints for the
1537
- appropriate ` impl ` :
1538
-
1539
- ~~~
1540
- #[deriving(Eq, Clone)]
1541
- struct Foo<T> {
1542
- a: int,
1543
- b: T
1544
- }
1545
- ~~~
1546
-
1547
- The generated ` impl ` for ` Eq ` is equivalent to
1548
-
1549
- ~~~
1550
- # struct Foo<T> { a: int, b: T }
1551
- impl<T: Eq> Eq for Foo<T> {
1552
- fn eq(&self, other: &Foo<T>) -> bool {
1553
- self.a == other.a && self.b == other.b
1554
- }
1555
-
1556
- fn ne(&self, other: &Foo<T>) -> bool {
1557
- self.a != other.a || self.b != other.b
1558
- }
1559
- }
1560
- ~~~
1561
-
1562
- Supported traits for ` deriving ` are:
1563
-
1564
- * Comparison traits: ` Eq ` , ` TotalEq ` , ` Ord ` , ` TotalOrd ` .
1565
- * Serialization: ` Encodable ` , ` Decodable ` . These require ` std ` .
1566
- * ` Clone ` , to perform deep copies.
1567
- * ` IterBytes ` , to iterate over the bytes in a data type.
1568
- * ` Rand ` , to create a random instance of a data type.
1569
- * ` ToStr ` , to convert to a string. For a type with this instance,
1570
- ` obj.to_str() ` has the same output as ` fmt!("%?", obj) ` .
1571
-
1572
1528
# Statements and expressions
1573
1529
1574
1530
Rust is _ primarily_ an expression language. This means that most forms of
0 commit comments