Gobley

https://gobley.dev
Admin
Gobley is a set of libraries and tools that help you integrate Rust code into your Kotlin...
Tokens:23,873
Snippets:272
Trust Score:4.9
Update:6 months ago
Show doc for...
Tokens:
Raw
### Install the Bindgen

Source: https://gobley.dev/docs/bindgen

Use cargo to install the specific version of the bindgen binary.

```bash
cargo install --bin gobley-uniffi-bindgen gobley-uniffi-bindgen@0.1.0  
```

--------------------------------

### Build Script Output Example

Source: https://gobley.dev/docs/cross-compilation-tips

This example shows the output from a dependency's build script, which can be found in `target/<Cargo triplet>/<profile>/build/<package name>-<hash>/output`. It helps in diagnosing linking issues by showing configured features and target information.

```text
cargo:rerun-if-env-changed=CARGO_FEATURE_PURE
cargo:rerun-if-env-changed=CARGO_FEATURE_NO_NEON
cargo:rerun-if-env-changed=CARGO_FEATURE_NEON
cargo:rerun-if-env-changed=CARGO_FEATURE_NEON
cargo:rerun-if-env-changed=CARGO_FEATURE_NO_NEON
cargo:rerun-if-env-changed=CARGO_FEATURE_PURE
cargo:rustc-cfg=blake3_neon
TARGET = Some("aarch64-linux-android")
OPT_LEVEL = Some("0")
HOST = Some("aarch64-apple-darwin")
...

```

--------------------------------

### Alternative Clang Compilation Methods

Source: https://gobley.dev/docs/cross-compilation-tips

Examples of using non-Apple Clang distributions or building Clang from source to avoid '___chkstk_darwin' dependencies.

```bash
# Using a different Clang distribution  
> /opt/homebrew/opt/llvm/bin/clang  
    -arch arm64                                       \
    -target arm64-apple-ios13.0.0                     \
    -isysroot $(xcrun --sdk iphoneos --show-sdk-path) \
    -c -o lib.o                                       \
    lib.cc  
  
# Building Clang from source  
> git clone https://github.com/swiftlang/llvm-project  
> git -C llvm-project checkout tags/swift-6.1.2-RELEASE  
> mkdir -p llvm-project/build  
> cmake -B llvm-project/build -S llvm-project/llvm -DLLVM_ENABLE_PROJECTS=clang  
> cmake --build llvm-project/build --target clang  
> llvm-project/build/bin/clang  
    -arch arm64                                       \
    -target arm64-apple-ios13.0.0                     \
    -isysroot $(xcrun --sdk iphoneos --show-sdk-path) \
    -c -o lib.o                                       \
    lib.cc  
```

--------------------------------

### Example ELF output

Source: https://gobley.dev/docs/cross-compilation-tips

Sample output showing program headers and section mappings for a shared object file.

```text
Elf file type is DYN (Shared object file)  
Entry point 0x0  
There are 10 program headers, starting at offset 64  
  
Program Headers:  
  Type           Offset   VirtAddr           PhysAddr           FileSiz  MemSiz   Flg Align  
  PHDR           0x000040 0x0000000000000040 0x0000000000000040 0x000230 0x000230 R   0x8  
  LOAD           0x000000 0x0000000000000000 0x0000000000000000 0x018d28 0x018d28 R   0x4000  
  LOAD           0x018d28 0x000000000001cd28 0x000000000001cd28 0x0306c8 0x0306c8 R E 0x4000  
  LOAD           0x0493f0 0x00000000000513f0 0x00000000000513f0 0x001e08 0x002c10 RW  0x4000  
  LOAD           0x04b1f8 0x00000000000571f8 0x00000000000571f8 0x000078 0x0009a0 RW  0x4000  
  DYNAMIC        0x04ae40 0x0000000000052e40 0x0000000000052e40 0x000190 0x000190 RW  0x8  
  GNU_RELRO      0x0493f0 0x00000000000513f0 0x00000000000513f0 0x001e08 0x002c10 R   0x1  
  GNU_EH_FRAME   0x00bd6c 0x000000000000bd6c 0x000000000000bd6c 0x00234c 0x00234c R   0x4  
  GNU_STACK      0x000000 0x0000000000000000 0x0000000000000000 0x000000 0x000000 RW  0x0  
  NOTE           0x000270 0x0000000000000270 0x0000000000000270 0x000098 0x000098 R   0x4  
  
 Section to Segment mapping:  
  Segment Sections...  
   00       
   01     .note.android.ident .dynsym .gnu.version .gnu.version_r .gnu.hash .hash .dynstr .rela.dyn .rela.plt .rodata .gcc_except_table .eh_frame_hdr .eh_frame   
   02     .text .plt   
   03     .data.rel.ro .fini_array .dynamic .got .got.plt .relro_padding   
   04     .data .bss   
   05     .dynamic   
   06     .data.rel.ro .fini_array .dynamic .got .got.plt .relro_padding   
   07     .eh_frame_hdr   
   08       
   09     .note.android.ident   
   None   .comment .debug_abbrev .debug_info .debug_aranges .debug_ranges .debug_str .debug_line .debug_loc .symtab .shstrtab .strtab
```

--------------------------------

### Linker Invocation Example

Source: https://gobley.dev/docs/cross-compilation-tips

This output shows the full linker command line arguments, which can be inspected to identify if both `-lc++_static` and `-lc++_shared` are present, indicating a conflict.

```text
error: linking with "<linker path>" failed: exit status: 1
  |
  = note: LC_ALL="C" PATH="..." "<linker path>" <arguments ...>

```

--------------------------------

### Verify Zig installation

Source: https://gobley.dev/docs/cross-compilation-tips

Commands to verify that the Zig compiler is correctly installed and accessible in the system path.

```powershell
> & "${env:LOCALAPPDATA}\Microsoft\WinGet\Links\zig.exe" version  
0.13.0  
> C:\ProgramData\chocolatey\bin\zig.exe version  
0.13.0
```

```cmd
> %LOCALAPPDATA%\Microsoft\WinGet\Links\zig.exe version  
0.13.0
```

```bash
> /opt/homebrew/bin/zig version  
0.13.0
```

--------------------------------

### Linker Error Output

Source: https://gobley.dev/docs/cross-compilation-tips

Example of the linker error encountered when '___chkstk_darwin' is missing.

```text
Undefined symbols for architecture arm64:  
  "___chkstk_darwin", referenced from:  
      <function name> in <library file name or object file name>  
ld: symbol(s) not found for architecture arm64  
clang: error: linker command failed with exit code 1 (use -v to see invocation)  
```

--------------------------------

### Example output of llvm-readelf

Source: https://gobley.dev/docs/cross-compilation-tips

This output displays the section headers of a shared object, identifying indices for debug sections and symbol tables.

```text
There are 33 section headers, starting at offset 0x2aafd8:  
  
Section Headers:  
  [Nr] Name              Type            Address          Off    Size   ES Flg Lk Inf Al  
  [ 0]                   NULL            0000000000000000 000000 000000 00      0   0  0  
  [ 1] .note.android.ident NOTE          0000000000000270 000270 000098 00   A  0   0  4  
  [ 2] .dynsym           DYNSYM          0000000000000308 000308 000330 18   A  6   1  8  
  [ 3] .gnu.version      VERSYM          0000000000000638 000638 000044 02   A  2   0  2  
  [ 4] .gnu.version_r    VERNEED         000000000000067c 00067c 000040 00   A  6   2  4  
  [ 5] .gnu.hash         GNU_HASH        00000000000006c0 0006c0 000020 00   A  2   0  8  
  [ 6] .dynstr           STRTAB          00000000000006e0 0006e0 00019b 00   A  0   0  1  
  [ 7] .rela.dyn         RELA            0000000000000880 000880 001c80 18   A  2   0  8  
  [ 8] .rela.plt         RELA            0000000000002500 002500 0002e8 18  AI  2  19  8  
  [ 9] .gcc_except_table PROGBITS        00000000000027e8 0027e8 001d48 00   A  0   0  4  
  [10] .rodata           PROGBITS        0000000000004530 004530 002940 00 AMS  0   0 16  
  [11] .eh_frame_hdr     PROGBITS        0000000000006e70 006e70 000a64 00   A  0   0  4  
  [12] .eh_frame         PROGBITS        00000000000078d8 0078d8 004a58 00   A  0   0  8  
  [13] .text             PROGBITS        000000000000d330 00c330 0179d8 00  AX  0   0  4  
  [14] .plt              PROGBITS        0000000000024d10 023d10 000210 00  AX  0   0 16  
  [15] .data.rel.ro      PROGBITS        0000000000025f20 023f20 0013b8 00  WA  0   0  8  
  [16] .fini_array       FINI_ARRAY      00000000000272d8 0252d8 000010 00  WA  0   0  8  
  [17] .dynamic          DYNAMIC         00000000000272e8 0252e8 000180 10  WA  6   0  8  
  [18] .got              PROGBITS        0000000000027468 025468 000070 00  WA  0   0  8  
  [19] .got.plt          PROGBITS        00000000000274d8 0254d8 000110 00  WA  0   0  8  
  [20] .relro_padding    NOBITS          00000000000275e8 0255e8 000a18 00  WA  0   0  1  
  [21] .data             PROGBITS        00000000000285e8 0255e8 000068 00  WA  0   0  8  
  [22] .bss              NOBITS          0000000000028650 025650 000918 00  WA  0   0  8  
  [23] .comment          PROGBITS        0000000000000000 025650 0001ae 01  MS  0   0  1  
  [24] .debug_abbrev     PROGBITS        0000000000000000 0257fe 000aae 00      0   0  1  
  [25] .debug_info       PROGBITS        0000000000000000 0262ac 0a4b5b 00      0   0  1  
  [26] .debug_aranges    PROGBITS        0000000000000000 0cae07 006470 00      0   0  1  
  [27] .debug_str        PROGBITS        0000000000000000 0d1277 0e855c 01  MS  0   0  1  
  [28] .debug_line       PROGBITS        0000000000000000 1b97d3 04ab52 00      0   0  1  
  [29] .debug_ranges     PROGBITS        0000000000000000 204325 092af0 00      0   0  1  
  [30] .symtab           SYMTAB          0000000000000000 296e18 00a050 18     32 1677  8  
  [31] .shstrtab         STRTAB          0000000000000000 2a0e68 000157 00      0   0  1  
  [32] .strtab           STRTAB          0000000000000000 2a0fbf 00a016 00      0   0  1  
Key to Flags:  
  W (write), A (alloc), X (execute), M (merge), S (strings), I (info),  
  L (link order), O (extra OS processing required), G (group), T (TLS),  
  C (compressed), x (unknown), o (OS specific), E (exclude),  
  R (retain), p (processor specific)  

```

--------------------------------

### Build Linker Error Example

Source: https://gobley.dev/docs/cross-compilation-tips

This error indicates an undefined reference to `__cxa_pure_virtual` during the build process, signaling a missing C++ runtime link.

```text
<file name>: undefined reference to `__cxa_pure_virtual'
```

--------------------------------

### Identify LOAD segment alignment

Source: https://gobley.dev/docs/cross-compilation-tips

Example of a specific LOAD segment header showing the alignment value.

```text
LOAD           0x000000 0x0000000000000000 0x0000000000000000 0x018d28 0x018d28 R   0x4000
```

--------------------------------

### Consume Rust in Kotlin

Source: https://gobley.dev/docs/tutorial

Example of calling exported Rust functions and objects within a Compose UI component.

```kotlin
Column {  
    Text("Addition using Rust: 2 + 3 = ${uniffi.compose_app.add(2, 3)}")  
    val greeting = remember { uniffi.compose_app.Greeter("Hello") }  
    Text(greeting.greet("Rust"))  
    DisposableEffect(greeting) {  
        onDispose {  
            greeting.close()  
        }  
    }  
}  
```

--------------------------------

### Configure Bindgen Settings via Gradle DSL

Source: https://gobley.dev/docs/gradle-plugins/uniffi

Customize bindgen settings directly within the `generateFromLibrary` or `generateFromUdl` blocks using Gradle DSL. This example shows setting the package name, defining custom types with lift/lower logic, and enabling PascalCase for enums.

```gradle
uniffi {
    generateFromLibrary {
        packageName = "com.example.foo"
        customType("Uuid") {
            typeName = "java.util.UUID"
            lift = "java.util.UUID.fromString({})".format(it)
            lower = "{}.toString()".format(it)
        }
        usePascalCaseEnumClass = true
    }
}

```

--------------------------------

### Disable automatic target installation

Source: https://gobley.dev/docs/gradle-plugins/cargo

Configure the installTargetBeforeBuild property to skip rustup target add commands globally or per-target.

```kotlin
cargo {  
    // Disable `rustup target add` for all targets  
    installTargetBeforeBuild = false  
    // Alternatively, disable `rustup target add` for a specific target (e.g. Android)  
    builds.android {  
        // installTargetBeforeBuild is inherited from the one in the `cargo {}` block   
        installTargetBeforeBuild = false  
    }  
}  
```

--------------------------------

### Call Rust Functions from Kotlin

Source: https://gobley.dev/docs/tutorial-android

After building the Rust library, Rust functions and types exported via UniFFI become accessible in Kotlin. This example shows how to call the `add` function and instantiate the `Greeter` object.

```kotlin
Column(Modifier.safeContentPadding()) {  
    Text("Addition using Rust: 2 + 3 = ${uniffi.app.add(2, 3)}")  
    val greeting = remember { uniffi.app.Greeter("Hello") }  
    Text(greeting.greet("Rust"))  
    DisposableEffect(greeting) {  
        onDispose {  
            greeting.close()  
        }  
    }  
}  

```

--------------------------------

### Runtime Linker Error Example

Source: https://gobley.dev/docs/cross-compilation-tips

This error occurs when the C++ runtime is not properly linked, preventing the dynamic loading of libraries.

```text
dlopen failed: cannot locate symbol "__cxa_pure_virtual" referenced by "/data/app/.../libyourlibrary.so"
```

--------------------------------

### Configure Cargo Profiles for Variants

Source: https://gobley.dev/docs/gradle-plugins/cargo

Specify custom Cargo profiles for debug and release variants. `CargoProfile.Bench` is used as an example for the release profile.

```kotlin
import gobley.gradle.cargo.profiles.CargoProfile  
  
cargo {  
    debug.profile = CargoProfile("my-debug")  
    release.profile = CargoProfile.Bench  
}  

```

--------------------------------

### Initialize a Rust Cargo package

Source: https://gobley.dev/docs/tutorial-jvm

Run this command in the project root to create a library crate without version control files.

```bash
cargo init --lib --name my-first-gobley-project --vcs none .  
```

--------------------------------

### Configure Windows cross-compilation

Source: https://gobley.dev/docs/tutorial-native

Directs Gobley to use the Linux binary for UniFFI on Windows to bypass COFF support limitations.

```kotlin
import gobley.gradle.GobleyHost  
import gobley.gradle.rust.dsl.hostNativeTarget  
import gobley.gradle.rust.targets.RustPosixTarget  
  
// Plugins here  
  
uniffi {  
    generateFromLibrary {  
        // Make UniFFI generate bindings using the Linux X64 build on Windows  
        if (GobleyHost.Platform.Windows.isCurrent) {  
            build = RustPosixTarget.LinuxX64  
        }  
    }  
}  
  
kotlin {  
    // Comment out the original code  
    // val hostOs = System.getProperty("os.name")  
    // val isArm64 = System.getProperty("os.arch") == "aarch64"  
    // val isMingwX64 = hostOs.startsWith("Windows")  
    // val nativeTarget = when {  
    //     hostOs == "Mac OS X" && isArm64 -> macosArm64("native")  
    //     hostOs == "Mac OS X" && !isArm64 -> macosX64("native")  
    //     hostOs == "Linux" && isArm64 -> linuxArm64("native")  
    //     hostOs == "Linux" && !isArm64 -> linuxX64("native")  
    //     isMingwX64 -> mingwX64("native")  
    //     else -> throw GradleException("Host OS is not supported in Kotlin/Native.")  
    // }  
  
    val nativeTargets = listOfNotNull(  
        // hostNativeTarget("native") is equivalent to the above  
        hostNativeTarget(),  
        // Build for Linux as well on Windows  
        if (GobleyHost.Platform.Windows.isCurrent) linuxX64() else null,  
    )  
  
    nativeTargets.forEach { target ->  
        target.binaries {  
            executable {  
                entryPoint = "main"  
            }  
        }  
    }  
  
    // Other settings here   
}  
```

--------------------------------

### Initialize a Rust library crate

Source: https://gobley.dev/docs/tutorial-android

Creates a new Rust library package within the 'app' directory. Use '--vcs none' to avoid Git integration.

```bash
cargo init --lib --vcs none app  

```

--------------------------------

### Configure build.gradle.kts for Rust integration

Source: https://gobley.dev/docs/tutorial-jvm

Apply the Gobley and UniFFI plugins and configure the cargo build block to target the host platform.

```kotlin
import gobley.gradle.GobleyHost  
import gobley.gradle.cargo.dsl.jvm  
  
plugins {  
    kotlin("jvm") version "<kotlin version>"  
    id("dev.gobley.cargo") version "0.3.7"  
    id("dev.gobley.uniffi") version "0.3.7"  
    kotlin("plugin.atomicfu") version "<kotlin version>"  
}  
  
cargo {  
    builds.jvm {  
        // Build Rust library only for the host platform  
        embedRustLibrary = (GobleyHost.current.rustTarget == rustTarget)  
    }  
}  
```

--------------------------------

### Initialize a Cargo package

Source: https://gobley.dev/docs/tutorial-native

Run this command in the terminal to create a new library crate within the current directory.

```bash
cargo init --lib --name my-first-gobley-project --vcs none .
```

--------------------------------

### Configure 16 KB page size via Gradle

Source: https://gobley.dev/docs/cross-compilation-tips

Pass the required linker flags to RUSTFLAGS using the Gradle DSL.

```gradle
cargo {  
    builds.android {  
        variants {  
            buildTaskProvider.configure {  
                additionalEnvironment.put(  
                    "RUSTFLAGS",  
                    "-C link-args=-Wl,-z,max-page-size=16384",  
                )  
            }  
        }  
    }  
}  
```

--------------------------------

### Build for Windows ARM64

Source: https://gobley.dev/docs/cross-compilation-tips

Command to initiate a build for the ARM64 Windows target using Cargo.

```bash
> cargo build --target aarch64-pc-windows-msvc
```

--------------------------------

### Open iOS project in Xcode

Source: https://gobley.dev/docs/tutorial

Command to open the iOS project in Xcode.

```bash
open -a "Xcode" ./iosApp/iosApp.xcodeproj  
```

--------------------------------

### Open Rust project directory

Source: https://gobley.dev/docs/tutorial-android

Opens the 'app' directory, which contains the Rust code, in Visual Studio Code for development.

```bash
code ./app  

```

--------------------------------

### Add rust-src component

Source: https://gobley.dev/docs/gradle-plugins/cargo

Download the standard library source code required for nightly builds.

```bash
rustup component add rust-src --toolchain nightly  
```

--------------------------------

### Configure app/Cargo.toml for UniFFI

Source: https://gobley.dev/docs/tutorial-android

Adds UniFFI as a dependency and sets the crate type to 'cdylib' for dynamic library generation. Specify the path to the Rust source file if it's not in the default location.

```toml
# This part is already added by cargo init.  
[package]  
name = "app"  
version = "0.1.0"  
edition = "2024"  
  
[dependencies]  
# We need to add this.  
uniffi = "0.29.4"  
  
# This as well.  
[lib]  
crate-type = ["cdylib"]  
# Put this only if you moved lib.rs.  
path = "src/main/rust/lib.rs"  

```

--------------------------------

### Open project in VS Code

Source: https://gobley.dev/docs/tutorial

Commands to open the project directory in Visual Studio Code.

```bash
code ./composeApp  
# or on macOS  
open -a "Visual Studio Code" ./composeApp  
```

--------------------------------

### Verify dynamic library page size

Source: https://gobley.dev/docs/cross-compilation-tips

Use llvm-readelf to inspect the page size configuration of the compiled dynamic library.

```bash
<Android SDK Root>/ndk/<NDK version>/toolchains/llvm/prebuilt/<Host Triplet>/bin/llvm-readelf -l target/<target triplet>/<profile>/libyour_project.so  
```

```bash
# On Windows, checking a AArch64 Android dynamic library  
<NDK Root>\toolchains\llvm\prebuilt\windows-x86_64\bin\llvm-readelf.exe -l target\aarch64-linux-android\debug\libyour_project.so  
  
# On macOS, checking a Arm32 Android dynamic library  
# Apple Silicon Macs also use darwin-x86_64  
<NDK Root>/toolchains/llvm/prebuilt/darwin-x86_64/bin/llvm-readelf -l target/armv7-linux-androideabi/debug/libyour_project.so  
```

--------------------------------

### Create Windows linker batch scripts

Source: https://gobley.dev/docs/cross-compilation-tips

Batch scripts to wrap the Zig compiler for use as a linker in Cargo on Windows.

```batch
@echo off  
<zig path> cc -target x86_64-linux-gnu %*
```

```batch
@echo off  
%LOCALAPPDATA%\Microsoft\WinGet\Links\zig.exe cc -target x86_64-linux-gnu %*
```

```batch
@echo off  
<zig path> cc -target aarch64-linux-gnu %*
```

--------------------------------

### Configure Gradle plugins

Source: https://gobley.dev/docs/tutorial

Registers the Gobley cargo and uniffi plugins in the build script.

```kotlin
plugins {  
    // Other plugins here  
    id("dev.gobley.cargo") version "0.3.7"  
    id("dev.gobley.uniffi") version "0.3.7"  
    kotlin("plugin.atomicfu") version libs.versions.kotlin  
}  
```

--------------------------------

### Generated Directory Structure

Source: https://gobley.dev/docs/bindgen

The expected directory structure after successfully generating bindings.

```text
<output directory>  
├── androidMain  
│   └── kotlin  
│       └── <namespace name>  
│           └── <namespace name>.android.kt  
├── commonMain  
│   └── kotlin  
│       └── <namespace name>  
│           └── <namespace name>.common.kt  
├── jvmMain  
│   └── kotlin  
│       └── <namespace name>  
│           └── <namespace name>.jvm.kt  
├── nativeInterop  
│   └── headers  
│       └── <namespace name>  
│           └── <namespace name>.h  
├── nativeMain  
│   └── kotlin  
│       └── <namespace name>  
│           └── <namespace name>.native.kt  
└── stubMain  
    └── kotlin  
        └── <namespace name>  
            └── <namespace name>.stub.kt  
```

--------------------------------

### Open Project in VS Code

Source: https://gobley.dev/docs/tutorial-jvm

Commands to open the current directory in Visual Studio Code.

```shell
code .  
# or on macOS  
open -a "Visual Studio Code" .  
```

--------------------------------

### Configure Cargo for Windows cross-compilation

Source: https://gobley.dev/docs/cross-compilation-tips

Configuration snippet for .cargo/config.toml to point to the custom linker batch scripts.

```toml
[target.x86_64-unknown-linux-gnu]  
linker = "C:\\Users\\<user name>\\.cargo\\x86_64-unknown-linux-gnu-cc.bat"  
  
[target.aarch64-unknown-linux-gnu]  
linker = "C:\\Users\\<user name>\\.cargo\\aarch64-unknown-linux-gnu-cc.bat"
```

--------------------------------

### Invoke the Bindgen

Source: https://gobley.dev/docs/bindgen

Run the bindgen command with the required library file, output directory, crate name, and UDL file path.

```bash
gobley-uniffi-bindgen --lib-file <path-to-library-file> --out-dir <output-directory> --crate <crate-name> <path-to-udl-file>  
```

--------------------------------

### Initialize a new Rust library with Cargo

Source: https://gobley.dev/docs/tutorial

Use this command to create a new Rust library crate within your project. It specifies the library type, package name, and disables version control initialization.

```bash
cargo init --lib --name compose-app --vcs none composeApp  

```

--------------------------------

### Configure Cargo.toml for Gobley

Source: https://gobley.dev/docs/tutorial-jvm

Update the Cargo manifest to include UniFFI dependencies and define the library crate type and source path.

```toml
# This part is already added by cargo init.  
[package]  
name = "my-first-gobley-project"  
version = "0.1.0"  
edition = "2024"  
  
[dependencies]  
# We need to add this.  
uniffi = "0.29.4"  
  
# This as well.  
[lib]  
crate-type = ["cdylib"]  
# Put this only if you moved lib.rs.  
path = "src/main/rust/lib.rs"  
```

--------------------------------

### Configure 16 KB page size via Cargo

Source: https://gobley.dev/docs/cross-compilation-tips

Set the RUSTFLAGS in the cargo configuration file for specific Android targets.

```toml
[target.aarch64-linux-android]  
rustflags = ["-C", "link-args=-Wl,-z,max-page-size=16384"]  
  
[target.armv7-linux-androideabi]  
rustflags = ["-C", "link-args=-Wl,-z,max-page-size=16384"]  
  
[target.x86_64-linux-android]  
rustflags = ["-C", "link-args=-Wl,-z,max-page-size=16384"]  
  
[target.i686-linux-android]  
rustflags = ["-C", "link-args=-Wl,-z,max-page-size=16384"]  
```

--------------------------------

### Configure Rust source path

Source: https://gobley.dev/docs/tutorial

Specifies the location of the Rust library source file.

```toml
path = "src/commonMain/rust/lib.rs"
```

--------------------------------

### Create macOS linker shell scripts

Source: https://gobley.dev/docs/cross-compilation-tips

Shell scripts to wrap the Zig compiler for use as a linker in Cargo on macOS.

```bash
#! /bin/sh  
<zig path> cc -target x86_64-linux-gnu "$@"
```

```bash
#! /bin/sh  
/opt/homebrew/bin/zig cc -target x86_64-linux-gnu "$@"
```

```bash
#! /bin/sh  
<zig path> cc -target aarch64-linux-gnu "$@"
```

--------------------------------

### Generate Kotlin Bindings from UDL File

Source: https://gobley.dev/docs/gradle-plugins/uniffi

Configure the UniFFI plugin to generate Kotlin bindings directly from a UDL file. Specify the namespace, build, variant, and the path to the UDL file.

```gradle
uniffi {
    generateFromUdl {
        namespace = "..."
        build = ...
        variant = Variant.Debug
        // The UDL file. Defaults to "${crateDirectory}/src/${crateName}.udl".
        udlFile = layout.projectDirectory.file("rust/src/my_crate.udl")
    }
}

```

--------------------------------

### Use rustup linker

Source: https://gobley.dev/docs/gradle-plugins/rust

Configures the project to use the LLVM linker distributed with rustup to avoid linker errors caused by version mismatches.

```kotlin
import gobley.gradle.rust.dsl.*  
  
kotlin {  
    iosArm64().compilations.getByName("main") {  
        useRustUpLinker()  
    }  
}  
```

--------------------------------

### Apply the Cargo plugin

Source: https://gobley.dev/docs/gradle-plugins/cargo

Include the plugin in your build.gradle.kts file to enable Rust integration.

```kotlin
plugins {  
    kotlin("multiplatform")  
    id("dev.gobley.cargo") version "0.3.7"  
}  
```

--------------------------------

### Configure Cargo for macOS cross-compilation

Source: https://gobley.dev/docs/cross-compilation-tips

Configuration snippet for .cargo/config.toml to point to the custom linker shell scripts.

```toml
[target.x86_64-unknown-linux-gnu]  
linker = "/Users/<user name>/.cargo/x86_64-unknown-linux-gnu-cc.sh"  
  
[target.aarch64-unknown-linux-gnu]  
linker = "/Users/<user name>/.cargo/aarch64-unknown-linux-gnu-cc.sh"
```

--------------------------------

### Specify Rust Toolchain in rust-toolchain.toml

Source: https://gobley.dev/docs/common-development-practices

Create a `rust-toolchain.toml` file in your project's root directory to automatically use a specific Rust toolchain for that project. This overrides the global default set by `rustup` and ensures project-specific versioning.

```toml
[toolchain]
channel = "1.82" # A specific version, "stable", "nighlty", etc.  
```

--------------------------------

### Define Rust source path

Source: https://gobley.dev/docs/tutorial-native

Specify the location of the Rust library source file.

```toml
path = "src/nativeMain/rust/lib.rs"
```

--------------------------------

### Generate Kotlin Bindings from Rust Library

Source: https://gobley.dev/docs/gradle-plugins/uniffi

Use this snippet to generate Kotlin bindings from a Rust library binary. Specify the UDL namespace, the Rust target build, and the build variant.

```gradle
import gobley.gradle.Variant
import gobley.gradle.rust.targets.RustAndroidTarget

plugins {
    kotlin("multiplatform")
    id("dev.gobley.cargo") version "0.3.7"
    id("dev.gobley.uniffi") version "0.3.7"
}

uniffi {
    // Generate the bindings using library mode.
    generateFromLibrary {
        // The UDL namespace as in the UDL file. Defaults to the library crate name.
        namespace = "my_crate"
        // The Rust target of the build to use to generate the bindings. If unspecified, one of the available builds
        // will be automatically selected.
        build = RustAndroidTarget.Arm64
        // The variant of the build that makes the library to use. If unspecified, the UniFFI plugin automatically picks
        // one.
        variant = Variant.Debug
    }
}

```

--------------------------------

### Configure Rust toolchain directory

Source: https://gobley.dev/docs/gradle-plugins/rust

Use the rust block to specify a custom toolchain directory if cargo or rustup are not in the default PATH.

```kotlin
plugins {  
    id("dev.gobley.rust") version "0.3.7"  
}  
  
rust {  
    toolchainDirectory = File("/path/to/my/Rust/toolchain")  
}  
```

--------------------------------

### Configure Android NDK and ABI filters

Source: https://gobley.dev/docs/gradle-plugins/cargo

Customize the NDK version and ABI filters for Android builds.

```kotlin
android {  
    ndkVersion = "26.2.11394342"  
}  
```

```kotlin
android {  
    defaultConfig {  
        ndk.abiFilters += setOf("arm64-v8a", "armeabi-v7a")  
    }  
}  
```

--------------------------------

### Inspect ELF program headers

Source: https://gobley.dev/docs/cross-compilation-tips

Use llvm-readelf to examine the program headers of a compiled shared object file.

```bash
<NDK Root>/toolchains/llvm/prebuilt/linux-x86_64/bin/llvm-readelf -l target/armv7-linux-androideabi/debug/libyour_project.so
```

--------------------------------

### Set executable permissions on macOS

Source: https://gobley.dev/docs/cross-compilation-tips

Commands to make the linker shell scripts executable.

```bash
chmod 555 ~/.cargo/x86_64-unknown-linux-gnu-cc.sh  
chmod 555 ~/.cargo/aarch64-unknown-linux-gnu-cc.sh
```

--------------------------------

### Configure build environment variables

Source: https://gobley.dev/docs/gradle-plugins/cargo

Directly configure environment variables for specific build tasks within the builds block.

```kotlin
import gobley.gradle.cargo.dsl.*  
  
cargo {  
    builds {  
        // Configure Android builds  
        android {  
            debug.buildTaskProvider.configure {  
                additionalEnvironment.put("CLANG", "/path/to/clang")  
            }  
        }  
        // You can configure for other targets as well  
        appleMobile {}  
        desktop {}  
        jvm {}  
        mobile {}  
        native {}  
        posix {}  
        mingw {}  
        linux {}  
        macos {}  
        windows {}  
    }  
}  
```

--------------------------------

### Inspect libSystem.tbd for symbol availability

Source: https://gobley.dev/docs/cross-compilation-tips

Use this command to search for specific symbols within the iOS SDK's libSystem.tbd file to verify version compatibility.

```bash
cat $(xcrun --sdk iphoneos --show-sdk-path)/usr/lib/libSystem.tbd | grep ___chkstk_darwin  
    symbols:         [ '$ld$hide$os10.0$___chkstk_darwin', '$ld$hide$os10.1$___chkstk_darwin',   
                       '$ld$hide$os10.2$___chkstk_darwin', '$ld$hide$os10.3$___chkstk_darwin',   
                       '$ld$hide$os11.0$___chkstk_darwin', '$ld$hide$os11.1$___chkstk_darwin',   
                       '$ld$hide$os11.2$___chkstk_darwin', '$ld$hide$os11.3$___chkstk_darwin',   
                       '$ld$hide$os11.4$___chkstk_darwin', '$ld$hide$os12.0$___chkstk_darwin',   
                       '$ld$hide$os12.1$___chkstk_darwin', '$ld$hide$os7.0$___chkstk_darwin',   
                       '$ld$hide$os7.0$_atomic_thread_fence', '$ld$hide$os7.1$___chkstk_darwin',   
                       '$ld$hide$os7.1$_atomic_thread_fence', '$ld$hide$os8.0$___chkstk_darwin',   
                       '$ld$hide$os8.0$_atomic_thread_fence', '$ld$hide$os8.1$___chkstk_darwin',   
                       '$ld$hide$os8.1$_atomic_thread_fence', '$ld$hide$os8.2$___chkstk_darwin',   
                       '$ld$hide$os8.2$_atomic_thread_fence', '$ld$hide$os8.3$___chkstk_darwin',   
                       '$ld$hide$os8.3$_atomic_thread_fence', '$ld$hide$os9.0$___chkstk_darwin',   
                       '$ld$hide$os9.1$___chkstk_darwin', '$ld$hide$os9.2$___chkstk_darwin',   
                       '$ld$hide$os9.3$___chkstk_darwin', ___atomic_compare_exchange,   
                       ___atomic_store_8, ___chkstk_darwin, ___clzti2, ___divti3,   
    symbols:         [ ____chkstk_darwin, ___is_threaded, ___pthread_init, ___pthread_late_init,
```

--------------------------------

### Apply Gobley Gradle plugins

Source: https://gobley.dev/docs/tutorial-android

Applies the necessary Gobley plugins for building Rust libraries and generating UniFFI bindings in the Android project's build configuration.

```gradle
plugins {  
    // Other plugins here  
    id("dev.gobley.cargo") version "0.3.7"  
    id("dev.gobley.uniffi") version "0.3.7"  
    kotlin("plugin.atomicfu") version libs.versions.kotlin  
}  

```

--------------------------------

### Publish Rust Library to Maven Local

Source: https://gobley.dev/docs/gradle-plugins/cargo

Publish your Rust library to the local Maven repository using the Gradle wrapper. This allows your Android local unit tests to reference the published artifacts.

```bash
./gradlew :your:project:publishToMavenLocal

```

--------------------------------

### Configure iOS Deployment Target in Gradle

Source: https://gobley.dev/docs/cross-compilation-tips

Set the deployment target environment variables within the cargo build configuration in Gradle.

```kotlin
import gobley.gradle.cargo.dsl.appleMobile  
  
cargo {  
    builds.appleMobile {  
        variants {  
            buildTaskProvider.configure {  
                when (rustTarget.cinteropName) {  
                    // Set the deployment target version to the ones you need:  
                    "ios" -> additionalEnvironment.put("IPHONEOS_DEPLOYMENT_TARGET", "16.0.0")  
                    "tvos" -> additionalEnvironment.put("TVOS_DEPLOYMENT_TARGET", "16.0.0")  
                    "watchos" -> additionalEnvironment.put("WATCHOS_DEPLOYMENT_TARGET", "9.0.0")  
                    else -> {}  
                }  
            }  
        }  
    }  
}
```

--------------------------------

### Inspect shared object sections with llvm-readelf

Source: https://gobley.dev/docs/cross-compilation-tips

Use this command to list all sections within a shared object file to verify the presence of debug and symbol information.

```bash
<Android SDK Root>/ndk/<NDK version>/toolchains/llvm/prebuilt/<Host Triplet>/bin/llvm-readelf -S target/<target triplet>/<profile>/libyour_project.so  

```

--------------------------------

### Set Default Rust Toolchain with rustup

Source: https://gobley.dev/docs/common-development-practices

Configure a specific Rust toolchain version for your system using `rustup`. This command adds the specified version and sets it as the default. Be cautious as this affects all Rust projects on your system.

```bash
> rustup target add 1.81  
> rustup default 1.81  
> rustc --version --verbose  
ustc 1.81.0 (eeb90cda1 2024-09-04)  
binary: rustc  
commit-hash: eeb90cda1969383f56a2637cbd3037bdf598841c  
commit-date: 2024-09-04  
host: aarch64-apple-darwin  
release: 1.81.0  
LLVM version: 18.1.7  
```

--------------------------------

### Enable LTO in Cargo

Source: https://gobley.dev/docs/cross-compilation-tips

Enable Link-Time Optimization in the release profile to reduce binary size by pruning unused code.

```toml
[profile.release]  
lto = true  

```

--------------------------------

### Configure mavenCentral() in settings.gradle.kts

Source: https://gobley.dev/docs/gradle-plugins

Add mavenCentral() to the pluginManagement repositories block in your settings.gradle.kts file to enable the Gradle plugins.

```kotlin
pluginManagement {
    repositories {
        mavenCentral()
    }
}

```

--------------------------------

### Clean Gradle Caches on macOS/Linux

Source: https://gobley.dev/docs/common-development-practices

Use these commands to remove Gradle cache directories and build artifacts to free up disk space. Ensure you are in the project root directory before executing.

```bash
find . -name .gradle | xargs rm -rf  
find . -name "build" | grep -v '^./target' | xargs -r rm -rf  
```

--------------------------------

### Enable Code Formatting for Generated Bindings

Source: https://gobley.dev/docs/gradle-plugins/uniffi

Set `formatCode` to `true` within the `uniffi` block to automatically run `ktlint` on the generated Kotlin bindings.

```gradle
uniffi {
    formatCode = true
}

```

--------------------------------

### Configure Cargo package directory

Source: https://gobley.dev/docs/gradle-plugins/cargo

Specify a custom directory for the Cargo package if it is not located in the project root.

```kotlin
cargo {  
    // The Cargo package is located in a `rust` subdirectory.  
    packageDirectory = layout.projectDirectory.dir("rust")  
}  
```

```kotlin
cargo {  
    // This works  
    packageDirectory = layout.projectDirectory.dir("rust/src")  
}  
```

--------------------------------

### Compile with Apple Clang and -fno-stack-check

Source: https://gobley.dev/docs/cross-compilation-tips

Use this command to manually compile a C++ file for iOS with specific architecture and target flags.

```bash
xcrun --sdk iphoneos clang                          \
    -arch arm64                                       \
    -target arm64-apple-ios13.0.0                     \
    -fno-stack-check                                  \
    -isysroot $(xcrun --sdk iphoneos --show-sdk-path) \
    -c -o lib.o                                       \
    lib.cc
```

--------------------------------

### Export Rust Functions and Types with UniFFI

Source: https://gobley.dev/docs/tutorial-android

Use `#[uniffi::export]` and `#[uniffi::Object]` macros to make Rust functions and types available on the Kotlin side. Ensure `uniffi::setup_scaffolding!()` is called to generate necessary Rust code.

```rust
/// This exports this Rust function to the Kotlin side.  
#[uniffi::export]  
fn add(lhs: i32, rhs: i32) -> i32 {  
    lhs + rhs  
}  
  
/// This exports this Rust type to the Kotlin side.  
#[derive(uniffi::Object)]  
struct Greeter {  
    greeting: String  
}  
  
#[uniffi::export]  
impl Greeter {  
   /// Define a constructor to be used on the Kotlin side.  
   #[uniffi::constructor]  
   fn new(greeting: String) -> Self {  
      Self { greeting }  
   }  
  
   /// Define a method to be used on the Kotlin side.  
   fn greet(&self, name: String) -> String {  
      format!("{}, {name}!", self.greeting)  
   }  
}  
  
// This generates extra Rust code required by UniFFI.  
uniffi::setup_scaffolding!();  

```

--------------------------------

### Add Custom Dynamic Library Search Paths for JVM

Source: https://gobley.dev/docs/gradle-plugins/cargo

If your JVM build relies on dynamic libraries located in custom directories, use `dynamicLibrarySearchPaths` to add these paths. This ensures the Cargo plugin can locate and embed the necessary libraries.

```gradle
cargo {
    builds.jvm {
        dynamicLibrarySearchPaths.add(File("/path/to/libraries"))  
        dynamicLibraries.add("foo")  
    }
}

```

--------------------------------

### Configure Cargo.toml for Rust library

Source: https://gobley.dev/docs/tutorial

Modify your Cargo.toml file to include the 'uniffi' dependency and specify the desired crate types for your Rust library. This is essential for integrating with Kotlin.

```toml
# This part is already added by cargo init.  
[package]  
name = "compose-app"  
version = "0.1.0"  
edition = "2024"  
  
[dependencies]  
# We need to add this.  
uniffi = "0.29.4"  
  
# This as well.  
[lib]  
crate-type = ["cdylib", "staticlib"]  

```

--------------------------------

### Configure nightly mode for tier 3 targets

Source: https://gobley.dev/docs/gradle-plugins/cargo

Use the RustTarget.tier function to conditionally enable nightly mode and pass -Zbuild-std for tier 3 targets.

```kotlin
cargo {  
    builds.appleMobile {  
        variants {  
            if (rustTarget.tier(project.rustVersion.get()) >= 3) {  
                buildTaskProvider.configure {  
                    // Pass +nightly to `cargo rustc` (or `cargo build`) to use `-Zbuild-std`.  
                    nightly = true  
                    // Make Cargo build the standard library  
                    extraArguments.add("-Zbuild-std")  
                }  
                // You can configure for the check task as well  
                checkTaskProvider.configure {  
                    nightly = true  
                    extraArguments.add("-Zbuild-std")  
                }  
            }  
        }  
    }  
}  
```
Tokens:
Raw