This PR focuses on documentation updates. All CI requirements have been validated locally where applicable. #809

bindings/ergo-lib-c/LINUX_DEVELOPMENT.md

@@ -0,0 +1,89 @@
+# Linux Development Setup
+
+This guide covers setting up the development environment for sigma-rust on Linux systems.
+
+## Prerequisites
+
+- Fedora/RHEL-based system (tested on Fedora 40)
+- Toolbox installed on your system
+- Git
+
+## Toolbox Setup
+
+1. Create and enter a new development toolbox:
+    ```bash
+    # Create a new toolbox (if not already created)
+    toolbox create --distro fedora --release 40 fedora-40
+
+    # Enter the toolbox
+    toolbox enter fedora-40
+
+    # Verify you're inside the toolbox
+    cat /etc/os-release
+    ```
+
+2. Clone the repository (if not already done):
+    ```bash
+    # Navigate to your preferred directory
+    cd ~/GitIt  # or your preferred directory
+
+    # Clone the repository
+    git clone https://github.com/ergoplatform/sigma-rust.git
+    cd sigma-rust
+    ```
+
+## Development Environment Setup
+
+1. Install system dependencies:
+    ```bash
+    sudo dnf install gcc make cmake git pkg-config
+    ```
+
+2. Install Rust and required components:
+    ```bash
+    # Install Rust
+    curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+    source "$HOME/.cargo/env"
+
+    # Add required targets
+    rustup target add aarch64-apple-ios
+    rustup target add x86_64-apple-ios
+
+    # Install nightly toolchain
+    rustup toolchain install nightly-2024-01-26
+
+    # Install cbindgen
+    cargo install cbindgen
+    ```
+
+3. Build Components:
+    ```bash
+    # Build ergo-lib-c
+    cd bindings/ergo-lib-c
+    cargo build --release --all-features
+
+    # Generate C headers
+    rustup override set nightly
+    cbindgen --config cbindgen.toml --crate ergo-lib-c --output h/ergo_lib.h
+    rustup override set stable
+    ```
+
+## Limitations
+
+- iOS/Swift components cannot be directly tested on Linux
+- Full iOS integration testing is performed via GitHub Actions
+
+## Development Workflow
+
+1. Make changes to Rust components
+2. Build and test locally using the commands above
+3. Commit changes with clear commit messages
+4. Push to GitHub where Actions will perform full iOS integration testing
+
+## Troubleshooting
+
+If you encounter any issues:
+1. Ensure all prerequisites are installed
+2. Verify you're using the correct Rust toolchain
+3. Check the GitHub Actions logs for detailed error messages
+4. Verify you're working inside the toolbox environment

bindings/ergo-lib-ios/LINUX_DEVELOPMENT.md

@@ -0,0 +1,75 @@
+# Linux Development Guide for Ergo iOS Bindings
+
+## Prerequisites
+
+- Fedora/RHEL-based system (tested on Fedora 40)
+- Toolbox or similar container environment (recommended)
+- Rust toolchain
+- cbindgen 0.28.0 or later
+
+## Development Environment Setup
+
+1. Create and enter development toolbox:
+    ```bash
+    toolbox create --distro fedora --release 40 fedora-40
+    toolbox enter fedora-40
+    ```
+
+2. Install system dependencies:
+    ```bash
+    sudo dnf install gcc make cmake git pkg-config
+    ```
+
+3. Install Rust components:
+    ```bash
+    # Install Rust
+    curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+    source "$HOME/.cargo/env"
+
+    # Install required toolchain and targets
+    rustup toolchain install nightly-2024-01-26
+    rustup target add aarch64-apple-ios
+    rustup target add x86_64-apple-ios
+
+    # Install cbindgen
+    cargo install cbindgen
+    ```
+
+## Building Components
+
+1. Build ergo-lib-c:
+    ```bash
+    # From sigma-rust root directory
+    cargo build --release --features rest --features mnemonic_gen -p ergo-lib-c
+    ```
+
+2. Generate C headers:
+    ```bash
+    cd bindings/ergo-lib-c
+    rustup override set nightly-2024-01-26
+    cbindgen --config cbindgen.toml --crate ergo-lib-c --output h/ergo_lib.h
+    rustup override set stable
+    ```
+
+3. Verify build artifacts:
+    ```bash
+    # Check the generated header file
+    ls -l h/ergo_lib.h
+
+    # Check the library
+    ls -l ../../target/release/libergo.*
+    ```
+
+## Limitations
+
+- iOS/Swift components cannot be directly tested on Linux
+- Full iOS integration testing must be performed on macOS
+- This environment is primarily for development and testing of the C bindings
+
+## Troubleshooting
+
+If you encounter any issues:
+1. Ensure all prerequisites are installed
+2. Verify you're using the correct Rust toolchain (nightly-2024-01-26)
+3. Check that all required targets are installed
+4. Verify the paths to build artifacts are correct

bindings/ergo-lib-ios/README.md

@@ -1,84 +1,96 @@
+```markdown
 # Swift wrapper for [C bindings](../ergo-lib-c) of ergo-lib.
 
+## Development Environments
+
+- **iOS/macOS**: Follow the instructions below (requires verification on macOS)
+- **Linux**: See [Linux Development Guide](LINUX_DEVELOPMENT.md) for Linux-specific setup
+
+## Prerequisites
+
+- Xcode 15 or later (macOS only)
+- Rust toolchain with specific targets
+- cbindgen 0.28.0 or later
 
 ## Build instructions
 
-First build `ergo-lib-c`:
+1. Build `ergo-lib-c`:
 ```shell
 cargo build --release --features rest --features mnemonic_gen -p ergo-lib-c
 ```
-adding:
-- `--target x86_64-apple-ios` for iPhone simulator on Intel macs,
-- `--target aarch64-apple-ios` for iPhone on Apple silicon macs,
-- `--target aarch64-apple-ios-sim` for iPhone simulator on Apple silicon macs.
 
-To install a target run `rustup target add <target>` using triple for target from the list above.
+2. Add required targets:
+```shell
+# For iPhone simulator on Intel macs
+rustup target add x86_64-apple-ios
+
+# For iPhone on Apple silicon macs
+rustup target add aarch64-apple-ios
 
-This creates a static library under `<project_root_directory>/target/release`. Next we use `cbindgen`
-to generate C-headers.
-**Important:** we need a nightly version of `rustc` for this step, as we use macros to generate
-*portions of the C-bindings. `cbindgen` can't 'see' through the macros so the nightly compiler is
-used to expand the macros before `cbindgen` passes over the code.
+# For iPhone simulator on Apple silicon macs
+rustup target add aarch64-apple-ios-sim
+```
 
+3. Generate C headers:
 ```shell
 cd bindings/ergo-lib-c
-rustup override set nightly
+rustup override set nightly-2024-01-26
 cbindgen --config cbindgen.toml --crate ergo-lib-c --output h/ergo_lib.h
 rustup override set stable
 ```
 
-
-To build this project we need to point `swift` to this directory for linking.
+4. Build Swift project:
 ```shell
 cd ../ergo-lib-ios
 swift build -Xlinker -L../../target/release/
 ```
 
-To run tests we must also pass in the library directory:
+5. Run tests:
 ```shell
 swift test -Xlinker -L../../target/release/ --skip RestNodeApiTests --skip RestNodeApiIntegrationTests
 ```
-The `RestNodeApiTests` assume you have an ergo node running on localhost.
-
+Note: `RestNodeApiTests` require an ergo node running on localhost.
 
-### Building Xcode 13 project for `iPhoneSimulator` 
+### Building Xcode 15 project for iPhone Simulator
 
-Make sure `ergo-lib-c` is built as described above.
-
-Starting at the root of the `sigma-rust` repository, type:
+1. Ensure `ergo-lib-c` is built (steps 1-3 above)
 
+2. Generate Xcode project:
 ```shell
 cd bindings/ergo-lib-ios
 swift package generate-xcodeproj
 xcodebuild -project ./ErgoLib.xcodeproj -xcconfig ./Config/iPhoneSimulator_{arm|intel}.xcconfig -sdk iphonesimulator
 ```
+Choose `arm` or `intel` based on your Mac's architecture.
 
-choosing either `arm` or `intel` in the last line depending on your mac's architecture.
-
-Then double click `ErgoLib.xcodeproj` which opens Xcode. You need to manually point the linker towards the directory where the `ergo-lib` static library resides. Refer to the following image: 
-
-![image](xcode_linker_settings.png)
-
-Set `Other Linker Flags` to be `-L/absolute/path/to/sigma-rust/target/release` for x86_64 and ` -L/absolute/path/to/sigma-rust/target/aarch64-apple-ios-sim/release` for simulator on Apple silicon macs. The project can now be built.
+3. Configure Xcode project:
+- Open `ErgoLib.xcodeproj`
+- Set linker flags:
+  - For Intel Macs: `-L/absolute/path/to/sigma-rust/target/release`
+  - For Apple Silicon Macs: `-L/absolute/path/to/sigma-rust/target/aarch64-apple-ios-sim/release`
 
-### Building Xcode 13 project for `iPhone(iOS)`
-
-First we need to build an ARM64 target for `ergo-lib-c`: 
+### Building Xcode 15 project for iPhone (iOS)
 
+1. Build ARM64 target:
 ```shell
 rustup target add aarch64-apple-ios
 cargo build --release --target=aarch64-apple-ios -p ergo-lib-c
 ```
 
-Next starting at the root of the `sigma-rust` repository, type:
-
+2. Generate Xcode project:
 ```shell
 cd bindings/ergo-lib-ios
 swift package generate-xcodeproj
 xcodebuild -project ./ErgoLib.xcodeproj -xcconfig ./Config/iPhoneOS.xcconfig -sdk iphoneos
 ```
 
-Next navigate in Xcode to `Build Settings` as indicated by 1 and 2 in the picture below. Set the fields `Base SDK`, `Excluded Architecture` and `Supported Platforms` **exactly** as pictured by 3 and 4.
-![image](xcode_ios_settings.png)
+3. Configure Xcode settings:
+- Open Build Settings
+- Set:
+  - Base SDK: iOS
+  - Excluded Architecture: arm64 (for simulator builds)
+  - Supported Platforms: iOS
+- Set Other Linker Flags: `-L/absolute/path/to/sigma-rust/aarch64-apple-ios/release`
 
-Then set `Other Linker Flags` to be `-L/absolute/path/to/sigma-rust/aarch64-apple-ios/release`. Finally we can build the project.
+Note: iOS build instructions require verification on macOS with Xcode 15.
+```