Skip to content

Commit

Permalink
[DOCS] Add C to Rust code migration guide (#1629)
Browse files Browse the repository at this point in the history
* 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
IshanGrover2004 and PunitLodha authored Aug 7, 2024
1 parent 34bb9dd commit 90204d4
Showing 1 changed file with 71 additions and 0 deletions.
71 changes: 71 additions & 0 deletions docs/Rust_migration_guide.md
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>) {}`

0 comments on commit 90204d4

Please sign in to comment.