From 0eba9c993a23a82c7de262b3c421d74f10bfdc79 Mon Sep 17 00:00:00 2001 From: OscarTHZhang Date: Thu, 12 Sep 2024 14:50:29 -0700 Subject: [PATCH] Documentation Improvement (#73) Cleaned up README.md to exclude development-specific sections and created a new markdown file DEVELOPMENT.md dedicated to track development notes. --- DEVELOPMENT.md | 39 ++++++++++++++++++++ README.md | 88 +++++++++++++++++++++------------------------ docs/development.md | 28 --------------- 3 files changed, 79 insertions(+), 76 deletions(-) create mode 100644 DEVELOPMENT.md delete mode 100644 docs/development.md diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md new file mode 100644 index 0000000..f8fca92 --- /dev/null +++ b/DEVELOPMENT.md @@ -0,0 +1,39 @@ +# Development +The following information is intended for contributers. + +## Getting Started +Go through the [README.md](./README.md) and install Service Fabric Runtime on either Windows, Ubuntu, or Ubuntu on WSL. + +## Rust Build +To compile and run Rust examples, run the following from repo root: +```sh +# Compile Rust SDK +cargo build +# Run sample client executable in crates\samples\client\src\main.rs +cargo run -p samples_client +``` + +## Other Targets +* Build tcp echo service fabric singlton application (part of default build). + * `cmake --build build --target build_rust_sample_echomain` +* Test the echoapp in local cluster (Windows) + * Add app to cluster `.\scripts\echomain_ctl.ps1 -Action Add` + * Run echo powershell to talk to the app `.\scripts\echomain_ctl.ps1 -Action Echo` + * Remove app from cluster `.\scripts\echomain_ctl.ps1 -Action Remove` +* Build tcp echo stateful service fabric single partition application (part of default build). + * `cmake --build build --target build_rust_sample_echomain_stateful` + +## Rust Code Generation +Rust wrapper is generated by windows bindgen from winmd file, which is provided here [ServiceFabric.winmd](https://github.com/Azure/service-fabric-metadata/tree/main/.windows/winmd) +* Generate Service Fabric Rust SDK code only (will build generate_winmd first) +```sh +cmake --build build --target generate_rust +# or run +cargo run -p tools_api +``` + +## Notes +1. GCC ld linker has problems with SF .so file so we use lld from LLVM/Clang which is configured in `.cargo/config.toml` +2. `fabric_pal.so` is needed to be able to provide Windows C functions needed by windows-rs. Code is checked-in in `/bintemp` folder. + + diff --git a/README.md b/README.md index 4078ae4..d344b73 100644 --- a/README.md +++ b/README.md @@ -1,68 +1,60 @@ -# service-fabric-rs +# Service Fabric Rust SDK ![ci](https://github.com/Azure/service-fabric-rs/actions/workflows/build.yaml/badge.svg) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://raw.githubusercontent.com/Azure/service-fabric-rs/main/LICENSE) -Service Fabric Rust SDK. - Build Service Fabric Reliable Services in Rust. Service Fabric is open sourced on github: `https://github.com/microsoft/service-fabric`. The latest open sourced version of SF is `6.4`. This SDK only provides `6.4` functionalities. New functionalities in newer versions is are not accessible in this SDK. -The Fabric runtime and client are accessible from the dlls installed from service fabric runtime. -The c headers are generated from open sourced idls in repo [service-fabric](https://github.com/microsoft/service-fabric/tree/master/src/prod/src/idl/public) +The FabricRuntime and FabricClient are accessible from the DLLs installed from Service Fabric Runtime. The C header files are generated from open-sourced IDLs in repo [service-fabric](https://github.com/microsoft/service-fabric/tree/master/src/prod/src/idl/public) This lib is in alpha state, and apis are subjected to change. -## dependencies -* Install service fabric runtime. See [get-started](https://learn.microsoft.com/en-us/azure/service-fabric/service-fabric-get-started) -* rust compiler -### Windows -* Visual Studio msvc tool chain. -### Linux -* `lld` from llvm +## Getting Started - Windows +* Install Service Fabric Runtime for Windows. See [Prepare your development environment on Windows](https://learn.microsoft.com/en-us/azure/service-fabric/service-fabric-get-started) +* Install [Visual Studio](https://visualstudio.microsoft.com/) with "Desktop development with C++" to include MSVC toolchain -## dev dependencies -* [service-fabric-cpp](https://github.com/youyuanwu/service-fabric-cpp) (fetched automatically by cmake) and its dependencies +## Getting Started - Ubuntu +Note: Service Fabric currently only supports Ubuntu 18.04 LTS and Ubuntu 20.04 LTS. -## Quick Start/Build -Build all rust lib and examples. -``` -cmake . -B build -cmake --build build +* Install Service Fabric Runtime for Linux (Ubuntu). See [Prepare your development environment on Linux](https://learn.microsoft.com/en-us/azure/service-fabric/service-fabric-get-started-linux?tabs=sdksetupubuntu%2Clocalclusteroneboxcontainer) +* Following the documentation, proceed to **Manual installation** and skip **Step 6. Add Azul JDK Key**.. + +## Getting Started - Ubuntu on WSL +The setup is similar to the regular Ubuntu setup, but with some twicks to avoid Service Fabric installer to search for Windows mount paths, which can slow down installation. + +Remove `/mnt/c` paths to speed up installation by adding the following to `/etc/wsl.conf` and restart WSL to apply the changes: +```sh +# Remove windows path +[interop] +appendWindowsPath = false + +# Do not mount windows drive +[automount] +enabled = false ``` -* For linux, vscode devcontainer is maintained for development. -## Build details -### Setup prerequisite non-rust build dependencies -* cmake configure `cmake . -B build` - * This downloads idl files. (TODO: optimize this.) -* cmake build `cmake --build build` - * Generates fabric import libs for fabric dlls from fabric dlls installed with fabric runtime. - * Build all rust examples. +Now, proceed to the regular Ubuntu setup: [Getting Started - Ubuntu](#Getting-Started---Ubuntu) + +Edit the `/etc/wsl.conf` to the following to re-enable automount and restart WSL to apply the changes: +```sh +# Remove windows path +[interop] +appendWindowsPath = false -### Rust build -You can use cargo to do rust only targets. -* Compile or run rust example - * compile rust sdk `cargo build` - * run sample client executable `cargo run -p samples_client`. source code is in `crates\samples\client\src\main.rs` -### Other targets -* Build tcp echo service fabric singlton application (part of default build). - * `cmake --build build --target build_rust_sample_echomain` -* Test the echoapp in local cluster (Windows) - * Add app to cluster `.\scripts\echomain_ctl.ps1 -Action Add` - * Run echo powershell to talk to the app `.\scripts\echomain_ctl.ps1 -Action Echo` - * Remove app from cluster `.\scripts\echomain_ctl.ps1 -Action Remove` -* Build tcp echo stateful service fabric single partition application (part of default build). - * `cmake --build build --target build_rust_sample_echomain_stateful` +# Mount windows drive +[automount] +enabled = true +``` -## Rust code generation -If you are a user of this lib you can ignore this section. -Rust wrapper is generated by windows bindgen from winmd file, which is provided here [ServiceFabric.winmd](https://github.com/youyuanwu/fabric-metadata/tree/main/.windows/winmd) -### Run code generation -* Generate service fabric rust sdk code only(will build generate_winmd first) - * `cmake --build build --target generate_rust` or run `cargo run -p tools_api` +## Quick Build +Build all Rust libraries and examples +```sh +cmake . -B build +cmake --build build +``` -# License +## License Microsoft MIT license \ No newline at end of file diff --git a/docs/development.md b/docs/development.md deleted file mode 100644 index 204a933..0000000 --- a/docs/development.md +++ /dev/null @@ -1,28 +0,0 @@ -* MISC -``` - .\build\_deps\service_fabric_cpp-src\scripts\echomain_ctl.ps1 -Action Add -``` - -* Linux -Use vscode dev container. It has all deps installed. - -* Notes - * gcc ld linker has problems with SF .so so we use lld from clang which is configured in .cargo config. - * fabric_pal.so is needed to be able to provide windows C functions needed by windows-rs. Code is checked-in in /bintemp folder. - -* WSL -Install SF in WSL maybe slow due to windows paths in /mnt/c are searched. -Change the following to remove /mnt/c etc paths -```sh -$ sudo nano /etc/wsl.conf -``` -add section -```conf -# This removes windows path -[interop] -appendWindowsPath = false -# This do not mount windows drive -[automount] -enabled = false -``` -Mount is needed to use vscode wsl. So after install sf the automount section needs to be removed to use vscode wsl.