doc: Add some info about native mods and crust functions
This commit is contained in:
parent
db77c38fc9
commit
772028acdb
80
doc/rust.md
80
doc/rust.md
@ -563,7 +563,7 @@ of [attributes](#attributes) attached to it.
|
||||
|
||||
~~~~~~~~ {.ebnf .gram}
|
||||
item : mod_item | fn_item | type_item | enum_item
|
||||
| res_item | iface_item | impl_item ;
|
||||
| res_item | iface_item | impl_item | native_mod_item ;
|
||||
~~~~~~~~
|
||||
|
||||
An _item_ is a component of a crate; some module items can be defined in crate
|
||||
@ -1015,6 +1015,29 @@ Similarly, [interface](#interfaces) bounds can be specified for type
|
||||
parameters to allow methods of that interface to be called on values
|
||||
of that type.
|
||||
|
||||
#### Crust functions
|
||||
|
||||
Crust functions are part of Rust's foreign function interface,
|
||||
providing the opposite functionality to [native modules](#native-modules).
|
||||
Whereas native modules allow Rust code to call foreign
|
||||
code, crust functions allow foreign code to call Rust code. They are
|
||||
defined the same as any other Rust function, except that they are
|
||||
prepended with the `crust` keyword.
|
||||
|
||||
~~~
|
||||
crust fn new_vec() -> [int] { [] }
|
||||
~~~
|
||||
|
||||
Crust functions may not be called from Rust code, but their value
|
||||
may be taken as an unsafe `u8` pointer.
|
||||
|
||||
~~~
|
||||
let fptr: *u8 = new_vec;
|
||||
~~~
|
||||
|
||||
The primary motivation of crust functions is to create callbacks
|
||||
for native functions that expect to receive function pointers.
|
||||
|
||||
### Type definitions
|
||||
|
||||
A _type definition_ defines a new name for an existing [type](#types). Type
|
||||
@ -1222,6 +1245,61 @@ impl of seq<bool> for u32 {
|
||||
}
|
||||
~~~~
|
||||
|
||||
### Native modules
|
||||
|
||||
~~~ {.ebnf .gram}
|
||||
native_mod_item : "native mod" ident '{' native_mod '} ;
|
||||
native_mod : [ native_fn ] * ;
|
||||
~~~
|
||||
|
||||
Native modules form the basis for Rust's foreign function interface. A native
|
||||
module describes functions in external, non-Rust libraries. Functions within
|
||||
native modules are declared the same as other Rust functions, with the exception
|
||||
that they may not have a body and are instead terminated by a semi-colon.
|
||||
|
||||
~~~
|
||||
native mod c {
|
||||
fn fopen(filename: *c_char, mod: *c_char) -> *FILE;
|
||||
}
|
||||
~~~
|
||||
|
||||
Functions within native modules may be called by Rust code as it would any
|
||||
normal function and the Rust compiler will automatically translate between
|
||||
the Rust ABI and the native ABI.
|
||||
|
||||
The name of the native module has special meaning to the Rust compiler in
|
||||
that it will treat the module name as the name of a library to link to,
|
||||
performing the linking as appropriate for the target platform. The name
|
||||
given for the native module will be transformed in a platform-specific
|
||||
way to determine the name of the library. For example, on Linux the name
|
||||
of the native module is prefixed with 'lib' and suffixed with '.so', so
|
||||
the native mod 'rustrt' would be linked to a library named 'librustrt.so'.
|
||||
|
||||
A number of [attributes](#attributes) control the behavior of native mods.
|
||||
|
||||
By default native mods assume that the library they are calling use
|
||||
the standard C "cdecl" ABI. Other ABI's may be specified using the `abi`
|
||||
attribute as in
|
||||
|
||||
~~~
|
||||
// Interface to the Windows API
|
||||
#[abi = "stdcall"]
|
||||
native mod kernel32 { }
|
||||
~~~
|
||||
|
||||
The `link_name` attribute allows the default library naming behavior to
|
||||
be overriden by explicitly specifying the name of the library.
|
||||
|
||||
~~~
|
||||
#[link_name = "crypto"]
|
||||
native mod mycrypto { }
|
||||
~~~
|
||||
|
||||
The `nolink` attribute tells the Rust compiler not to perform any linking
|
||||
for the native module. This is particularly useful for creating native
|
||||
mods for libc, which tends to not follow standard library naming conventions
|
||||
and is linked to all Rust programs anyway.
|
||||
|
||||
## Attributes
|
||||
|
||||
~~~~~~~~{.ebnf .gram}
|
||||
|
Loading…
Reference in New Issue
Block a user