-
Notifications
You must be signed in to change notification settings - Fork 446
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
[DOCS] Add C to Rust code migration guide (#1629)
* docs: Add c-to-migration guide docs * docs: Update suggested typos in `docs/Rust_migration_guide.md` Co-authored-by: Punit Lodha <[email protected]> --------- Co-authored-by: Punit Lodha <[email protected]>
- Loading branch information
1 parent
34bb9dd
commit 90204d4
Showing
1 changed file
with
71 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,71 @@ | ||
# C to Rust Migration Guide | ||
|
||
## Porting C Functions to Rust | ||
|
||
This guide outlines the process of migrating C functions to Rust while maintaining compatibility with existing C code. | ||
|
||
### Step 1: Identify the C Function | ||
|
||
First, identify the C function you want to port. For example, let's consider a function named `net_send_cc()` in a file called `networking.c`: | ||
|
||
```c | ||
void net_send_cc() { | ||
// Some C code | ||
} | ||
``` | ||
|
||
### Step 2: Create a Pure Rust Equivalent | ||
|
||
Write an equivalent function in pure Rust within the `lib_ccxr` module: | ||
|
||
```rust | ||
fn net_send_cc() { | ||
// Rust equivalent code to `net_send_cc` function in `networking.c` | ||
} | ||
``` | ||
|
||
### Step 3: Create a C-Compatible Rust Function | ||
|
||
In the `libccxr_exports` module, create a new function that will be callable from C: | ||
|
||
```rust | ||
#[no_mangle] | ||
pub extern "C" fn ccxr_net_send_cc() { | ||
net_send_cc() // Call the pure Rust function | ||
} | ||
``` | ||
|
||
### Step 4: Declare the Rust Function in C | ||
|
||
In the original C file (`networking.c`), declare the Rust function as an external function: | ||
|
||
```rust | ||
extern void ccxr_net_send_cc(); | ||
``` | ||
|
||
### Step 5: Modify the Original C Function | ||
|
||
Update the original C function to use the Rust implementation when available: | ||
|
||
```c | ||
void net_send_cc() { | ||
#ifndef DISABLE_RUST | ||
return ccxr_net_send_cc(); // Use the Rust implementation | ||
#else | ||
// Original C code | ||
#endif | ||
} | ||
``` | ||
|
||
## Rust module system | ||
|
||
- `lib_ccxr` crate -> **The Idiomatic Rust layer** | ||
|
||
- Path: `src/rust/lib_ccxr` | ||
- This layer will contain the migrated idiomatic Rust. It will have complete documentation and tests. | ||
|
||
- `libccxr_exports` module -> **The C-like Rust layer** | ||
|
||
- Path: `src/rust/src/libccxr_exports` | ||
- This layer will have function names the same as defined in C but with the prefix `ccxr_`. These are the functions defined in the `lib_ccx` crate under appropriate modules. And these functions will be provided to the C library. | ||
- Ex: `extern "C" fn ccxr_<function_name>(<args>) {}` |