Merge pull request #118 from tweedegolf/c-compilation

Improve module 6 with extra instructions

book/src/foreign-function-interface.md

@@ -78,7 +78,7 @@ Use a CRC checksum function written in Rust in a C program
     [dependencies]
     ```
 
-2. Expose an extern rust function 
+2. Expose an extern rust function in the `lib.rs`
 
     ```rust
     #[no_mangle]
@@ -93,16 +93,16 @@ Use a CRC checksum function written in Rust in a C program
 3. Create a C header file `crc_in_rust.h`
 
     ```c
-    #include <inttypes.h> // uint32_t, uint8_t
+    #include <stdint.h> // uint32_t, uint8_t
     #include <stddef.h> // size_t
 
     uint32_t crc32(const uint8_t data[], size_t data_length);
     ```
 
-4. Use the rust `crc32` function in C
+4. Create `main.c` and use the rust `crc32` function
 
     ```c
-    #include <inttypes.h> // uint32_t, uint8_t
+    #include <stdint.h> // uint32_t, uint8_t
     #include <stddef.h> // size_t
     #include <stdio.h> // printf
     #include "crc_in_rust.h"
@@ -113,19 +113,35 @@ Use a CRC checksum function written in Rust in a C program
 
         uint32_t hash = crc32(data, data_length);
 
-        printf("Hash: 0x%d\n", hash);
+        printf("Hash: %d\n", hash);
 
         return 0;
     }
     ```
+5. Give the rust function the same signature as the one defined in the header file
 
-5. compile and run
+6. Compile the rust crate and then run
 
+    Linux & MacOS:
     ```sh
+    # Build main.c, link it to the dynamic library and output the executable called main
     $ clang main.c target/debug/libcrc_in_rust.so -omain
+    # Run the executable
     $ ./main
     Hash: -1386739207
     ```
+
+    Windows:
+    ```ps
+    # Build main.c, link it to the import library of the DLL and output the executable called main.exe
+    ❯ clang main.c .\target\debug\crc_in_rust.dll.lib -o "main.exe"
+    # Move the dll to the same folder as the exe so it can find it
+    ❯ cp .\target\debug\crc_in_rust.dll crc_in_rust.dll
+    # Run the executable
+    ❯ .\main.exe
+    Hash: -1386739207
+    ```
+
 ## Exercise 6.1.3: TweetNaCl Bindgen
 
 Use `cargo bindgen` to generate the FFI bindings. Bindgen will look at a C header file, and generate rust functions, types and constants based on the C definitions.

book/src/instructions.md

@@ -123,8 +123,67 @@ With CodeLLDB installed correctly, you can also start a debug session by clickin
 Play a little with setting breakpoints by clicking on a line number, making a red circle appear and stepping over/into/out of functions using the controls.
 You can view variable values by hovering over them while execution is paused, or by expanding the 'Local' view under 'Variables' in the left panel during a debug session.
 
+# Instructions for FFI module
+*This part is relevant only if you're partaking in one of the modules on Rust FFI.*
+
+For doing FFI we will need to compile some C code and for that we need a C compiler installed.
+We've chosen to use `clang` in our excercises.
+
+The prerequisite is that calling `clang` in your terminal should work. If it doesn't, follow the instructions for your platform below.
+
+## Linux
+
+For the bookworms using a Debian-like:
+```bash
+sudo apt update
+sudo apt install clang
+```
+
+If you're on Arch, btw:
+```bash
+sudo pacman -S clang
+```
+
+For those tipping their Fedora's:
+```bash
+sudo dnf install clang
+```
+
+## Windows
+
+Always make sure to select the option to add the install to `path`.
+
+Using winget:
+```ps
+winget install -i -e --id LLVM.LLVM
+```
+
+For the sweethearts using chocolatey:
+```ps
+choco install llvm
+```
+
+For the handsome people preferring manual installation:
+- Go to the releases page: https://github.com/llvm/llvm-project/releases
+- Go to a recent release
+- Search for LLVM-[VERSION]-win64.exe and download it
+- Run the exe
+
+## MacOS
+
+Using brew:
+```bash
+brew install llvm
+```
+
+Then also add to path, e.g.:
+```bash
+echo 'export PATH="$(brew --prefix llvm)/bin:$PATH"' >> ~/.zshrc
+source ~/.zshrc
+```
+
 # Instructions for embedded
-*This part is relevant only if you're partaking in one of the workshops on embedded Rust.*
+*This part is relevant only if you're partaking in one of the modules on embedded Rust.*
 
 ## Hardware
 We will use the [BBC micro:bit](https://microbit.org/buy/bbc-microbit-single) V2 and either you've already got it or we will bring it with us.