|
1 | | -# Porting Code |
2 | | - |
3 | | -Before starting, the assumption at this point is you *need* to port code. If you're not sure you do to port code, then maybe you don't. After all, if your C/C++ code works fine, then why change it? |
4 | | - |
5 | | -TODO This section will provide a more real world C/C++ example and port it to the equivalent Rust |
6 | | - |
7 | | -## Automation tools |
8 | | - |
9 | | -### C2Rust |
10 | | - |
11 | | -The [C2Rust project](https://github.com/immunant/c2rust) is developing a tool that translates C to semantically equivalent Rust. |
12 | | - |
13 | | -There is an online demo of it working [here](https://c2rust.com/). |
14 | | - |
15 | | -As C is unsafe by default, it means the Rust equivalent is also unsafe by default, but it can be useful as a starting point for converting code. |
16 | | - |
17 | | -### Corrode |
18 | | - |
19 | | -[Corrode](https://github.com/jameysharp/corrode) is a command-line tool that can partially convert C into Rust. At the very least it may spare you some drudgery ensuring the functionality is as close to the original as possible. |
20 | | - |
21 | | -Corrode will take a C file, e.g. `somefile.c` plus any arguments from `gcc` and produces a `somefile.rs` which is the equivalent code in Rust. |
22 | | - |
23 | | -It works by parsing the C code into an abstract syntax tree and then generating Rust from that. |
24 | | - |
25 | | -Interestingly Corrode is written in Haskell and more interestingly is written as a [literate Haskell source](https://github.com/jameysharp/corrode/blob/master/src/Language/Rust/Corrode/C.md) - the code is a markdown document interspersed with Haskell. |
26 | | - |
27 | | -### Bindgen |
28 | | - |
29 | | -[Bindgen](https://github.com/servo/rust-bindgen) is a tool for generating FFI interfaces for Rust from existing C and C++ header files. You might find this beneficial if you're porting code from C / C++, or writing a new component that must work with an existing code base. |
30 | | - |
31 | | -Bindgen requires that you preinstall the Clang C++ compiler in order to parse code into a structure it can digest. |
32 | | - |
33 | | -The readme documentation on the site link provides more information on installing and using the tool. |
34 | | - |
35 | | -### CBindgen |
36 | | - |
37 | | -[CBindgen](https://github.com/eqrion/cbindgen) works in the opposite direction of bindgen - it produces C header files from Rust structures and functions. |
38 | | - |
39 | | -So if you have Rust code that you wish to call from C, then you can generate the appropriate header files that enable you to do this. |
40 | | - |
41 | | -The headers can be produced from the command line like so: |
42 | | - |
43 | | -``` |
44 | | -cargo install cbindgen |
45 | | -cbindgen -o bindings.h |
46 | | -``` |
47 | | - |
48 | | -Alternatively you can create a `build.rs` that automatically does this when you build your crate: |
49 | | - |
50 | | -```rust |
51 | | -extern crate cbindgen; |
52 | | - |
53 | | -use std::env; |
54 | | - |
55 | | -fn main() { |
56 | | - let crate_dir = env::var("CARGO_MANIFEST_DIR").unwrap(); |
57 | | - |
58 | | - cbindgen::Builder::new() |
59 | | - .with_crate(crate_dir) |
60 | | - .generate() |
61 | | - .expect("Unable to generate bindings") |
62 | | - .write_to_file("bindings.h"); |
63 | | -} |
64 | | -``` |
65 | | - |
66 | | -A `cbindgen.toml` allows you to configure things that go into the header file. See the site link for more information. |
67 | | - |
68 | | - |
69 | | -## Experiences |
70 | | - |
71 | | -A number of websites offer insights of the porting process from C to Rust |
72 | | - |
73 | | -1. [Porting Zopfli from C to Rust](https://github.com/carols10cents/rust-out-your-c-talk). Zopfli is a library that performs good but slow deflate algorithm. It produces smaller compressed files than zlib while still remaining compatible with it. |
74 | | -2. TODO |
75 | | - |
76 | | -# Tips |
77 | | - |
78 | | -## Use references wherever you can |
79 | | - |
80 | | -TODO references are equivalent to C++ references or to pointers in C. Passing by reference is an efficient way of passing any object greater than 64-bits in size into a function without relinquishing ownership. In some cases, it is even a good idea to return by reference since the caller can always clone the object if they need to, and more often than not they can just use the reference providing the lifetimes allow for it. |
81 | | - |
82 | | -TODO you do not need to use references on intrinstic types such as integers, bools etc. and there is no point unless you intend for them to be mutable and change. |
83 | | - |
84 | | -## Move semantics |
85 | | - |
86 | | -C and C++ default to copy on assign. Unless you explicitly implement a move constructor on objects, the default is copy. Copying is dangerous because it allows two data structures to potentially point to the same data, e.g. a raw file handle. Even if code implements a move constructor, the compiler will not care if you reference the old |
87 | | -object so you are required to put the object into a valid but safe state. |
88 | | - |
89 | | -Rust by default will move on assign unless the type implements a `Copy` trait. Only simple primitives or structs comprised of simple primitives can implement or derive the `Copy` trait. |
90 | | - |
91 | | -```rust |
92 | | -let x = 100; |
93 | | -let y = x; // This is a copy |
94 | | -println!("x = {}", x); |
95 | | - |
96 | | -let x = "Hello world".to_string(); |
97 | | -let y = x; // This is a move |
98 | | -println!("x = {}", x); // compile error |
99 | | -``` |
100 | | - |
101 | | -And unlike C++, you CANNOT access the old object once you have assigned the value to a new one. The compiler will generate an error if you try. |
102 | | - |
103 | | -If you need to copy data in Rust you must implement / derive the `Clone` trait which allows you to explicitly invoke `.clone()` to make a copy of an object: |
104 | | - |
105 | | -```rust |
106 | | -let x = "Hello world".to_string(); |
107 | | -let y = x.clone(); |
108 | | -println!("x = {}", x); |
109 | | - |
110 | | -#[derive(Clone)] |
111 | | -struct MyData { |
112 | | - name: String; |
113 | | -} |
114 | | -///... |
115 | | -let x = MyData { name: "Fred".to_string() }; |
116 | | -let y = x.clone(); |
117 | | -``` |
118 | | - |
119 | | -## Use modules to naturally arrange your source code |
120 | | - |
121 | | -TODO |
122 | | - |
123 | | -## Using composition and traits |
124 | | - |
125 | | -TODO Rust does not allow you to inherit one struct from another. The manner of overcoming this. |
126 | | - |
127 | | -## Using Cargo.toml to create your build profiles |
128 | | - |
129 | | -## Use Rust naming conventions and formatting |
130 | | - |
131 | | -C and C++ have never had |
132 | | - |
133 | | -# Foreign Function Interface |
134 | | - |
135 | | -TODO for now read the [FFI omnibus](http://jakegoulding.com/rust-ffi-omnibus/). |
136 | | - |
137 | | -## Leaving function names unmangled |
138 | | - |
139 | | -TODO attribute no_mangle |
140 | | - |
141 | | -## libc |
142 | | - |
143 | | -TODO Rust provides a crate with bindings for C library functions. If you find yourself receiving a pointer allocated with malloc you could free it with the corresponding call to free() via the bindings. |
144 | | - |
145 | | -TODO add the following to your `Cargo.toml` |
146 | | - |
147 | | -``` |
148 | | -[dependencies] |
149 | | -libc = "*" |
150 | | -``` |
151 | | - |
| 1 | +# Porting Code |
| 2 | + |
| 3 | +Before starting, the assumption at this point is you *need* to port code. If you're not sure you do to port code, then maybe you don't. After all, if your C/C++ code works fine, then why change it? |
| 4 | + |
| 5 | +TODO This section will provide a more real world C/C++ example and port it to the equivalent Rust |
| 6 | + |
| 7 | +## Automation tools |
| 8 | + |
| 9 | +### C2Rust |
| 10 | + |
| 11 | +The [C2Rust project](https://github.com/immunant/c2rust) is developing a tool that translates C to semantically equivalent Rust. |
| 12 | + |
| 13 | +There is an online demo of it working [here](https://c2rust.com/). |
| 14 | + |
| 15 | +As C is unsafe by default, it means the Rust equivalent is also unsafe by default, but it can be useful as a starting point for converting code. |
| 16 | + |
| 17 | +### Corrode |
| 18 | + |
| 19 | +[Corrode](https://github.com/jameysharp/corrode) is a command-line tool that can partially convert C into Rust. At the very least it may spare you some drudgery ensuring the functionality is as close to the original as possible. |
| 20 | + |
| 21 | +Corrode will take a C file, e.g. `somefile.c` plus any arguments from `gcc` and produces a `somefile.rs` which is the equivalent code in Rust. |
| 22 | + |
| 23 | +It works by parsing the C code into an abstract syntax tree and then generating Rust from that. |
| 24 | + |
| 25 | +Interestingly Corrode is written in Haskell and more interestingly is written as a [literate Haskell source](https://github.com/jameysharp/corrode/blob/master/src/Language/Rust/Corrode/C.md) - the code is a markdown document interspersed with Haskell. |
| 26 | + |
| 27 | +### Bindgen |
| 28 | + |
| 29 | +[Bindgen](https://github.com/servo/rust-bindgen) is a tool for generating FFI interfaces for Rust from existing C and C++ header files. You might find this beneficial if you're porting code from C / C++, or writing a new component that must work with an existing code base. |
| 30 | + |
| 31 | +Bindgen requires that you preinstall the Clang C++ compiler in order to parse code into a structure it can digest. |
| 32 | + |
| 33 | +The readme documentation on the site link provides more information on installing and using the tool. |
| 34 | + |
| 35 | +### CBindgen |
| 36 | + |
| 37 | +[CBindgen](https://github.com/eqrion/cbindgen) works in the opposite direction of bindgen - it produces C header files from Rust structures and functions. |
| 38 | + |
| 39 | +So if you have Rust code that you wish to call from C, then you can generate the appropriate header files that enable you to do this. |
| 40 | + |
| 41 | +The headers can be produced from the command line like so: |
| 42 | + |
| 43 | +``` |
| 44 | +cargo install cbindgen |
| 45 | +cbindgen -o bindings.h |
| 46 | +``` |
| 47 | + |
| 48 | +Alternatively you can create a `build.rs` that automatically does this when you build your crate: |
| 49 | + |
| 50 | +```rust |
| 51 | +extern crate cbindgen; |
| 52 | + |
| 53 | +use std::env; |
| 54 | + |
| 55 | +fn main() { |
| 56 | + let crate_dir = env::var("CARGO_MANIFEST_DIR").unwrap(); |
| 57 | + |
| 58 | + cbindgen::Builder::new() |
| 59 | + .with_crate(crate_dir) |
| 60 | + .generate() |
| 61 | + .expect("Unable to generate bindings") |
| 62 | + .write_to_file("bindings.h"); |
| 63 | +} |
| 64 | +``` |
| 65 | + |
| 66 | +A `cbindgen.toml` allows you to configure things that go into the header file. See the site link for more information. |
| 67 | + |
| 68 | + |
| 69 | +## Experiences |
| 70 | + |
| 71 | +A number of websites offer insights of the porting process from C to Rust |
| 72 | + |
| 73 | +1. [Porting Zopfli from C to Rust](https://github.com/carols10cents/rust-out-your-c-talk). Zopfli is a library that performs good but slow deflate algorithm. It produces smaller compressed files than zlib while still remaining compatible with it. |
| 74 | +2. TODO |
| 75 | + |
| 76 | +# Tips |
| 77 | + |
| 78 | +## Use references wherever you can |
| 79 | + |
| 80 | +TODO references are equivalent to C++ references or to pointers in C. Passing by reference is an efficient way of passing any object greater than 64-bits in size into a function without relinquishing ownership. In some cases, it is even a good idea to return by reference since the caller can always clone the object if they need to, and more often than not they can just use the reference providing the lifetimes allow for it. |
| 81 | + |
| 82 | +TODO you do not need to use references on intrinstic types such as integers, bools etc. and there is no point unless you intend for them to be mutable and change. |
| 83 | + |
| 84 | +## Move semantics |
| 85 | + |
| 86 | +C and C++ default to copy on assign. Unless you explicitly implement a move constructor on objects, the default is copy. Copying is dangerous because it allows two data structures to potentially point to the same data, e.g. a raw file handle. Even if code implements a move constructor, the compiler will not care if you reference the old |
| 87 | +object so you are required to put the object into a valid but safe state. |
| 88 | + |
| 89 | +Rust by default will move on assign unless the type implements a `Copy` trait. Only simple primitives or structs comprised of simple primitives can implement or derive the `Copy` trait. |
| 90 | + |
| 91 | +```rust |
| 92 | +let x = 100; |
| 93 | +let y = x; // This is a copy |
| 94 | +println!("x = {}", x); |
| 95 | + |
| 96 | +let x = "Hello world".to_string(); |
| 97 | +let y = x; // This is a move |
| 98 | +println!("x = {}", x); // compile error |
| 99 | +``` |
| 100 | + |
| 101 | +And unlike C++, you CANNOT access the old object once you have assigned the value to a new one. The compiler will generate an error if you try. |
| 102 | + |
| 103 | +If you need to copy data in Rust you must implement / derive the `Clone` trait which allows you to explicitly invoke `.clone()` to make a copy of an object: |
| 104 | + |
| 105 | +```rust |
| 106 | +let x = "Hello world".to_string(); |
| 107 | +let y = x.clone(); |
| 108 | +println!("x = {}", x); |
| 109 | + |
| 110 | +#[derive(Clone)] |
| 111 | +struct MyData { |
| 112 | + name: String; |
| 113 | +} |
| 114 | +///... |
| 115 | +let x = MyData { name: "Fred".to_string() }; |
| 116 | +let y = x.clone(); |
| 117 | +``` |
| 118 | + |
| 119 | +## Use modules to naturally arrange your source code |
| 120 | + |
| 121 | +TODO |
| 122 | + |
| 123 | +## Using composition and traits |
| 124 | + |
| 125 | +TODO Rust does not allow you to inherit one struct from another. The manner of overcoming this. |
| 126 | + |
| 127 | +## Using Cargo.toml to create your build profiles |
| 128 | + |
| 129 | +## Use Rust naming conventions and formatting |
| 130 | + |
| 131 | +C and C++ have never had |
| 132 | + |
| 133 | +# Foreign Function Interface |
| 134 | + |
| 135 | +TODO for now read the [FFI omnibus](http://jakegoulding.com/rust-ffi-omnibus/). |
| 136 | + |
| 137 | +## Leaving function names unmangled |
| 138 | + |
| 139 | +TODO attribute no_mangle |
| 140 | + |
| 141 | +## libc |
| 142 | + |
| 143 | +TODO Rust provides a crate with bindings for C library functions. If you find yourself receiving a pointer allocated with malloc you could free it with the corresponding call to free() via the bindings. |
| 144 | + |
| 145 | +TODO add the following to your `Cargo.toml` |
| 146 | + |
| 147 | +``` |
| 148 | +[dependencies] |
| 149 | +libc = "*" |
| 150 | +``` |
| 151 | + |
152 | 152 | TODO example of using libc |
0 commit comments