misc document improvement and restructuring

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.
+
+

README.md

@@ -1,68 +1,58 @@
-# 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
+<em>Note: Service Fabric currently only supports Ubuntu 18.04 LTS and Ubuntu 20.04 LTS.</em>
 
-## 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
+# This removes windows path
+[interop]
+appendWindowsPath = false
+# This 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)
 
-### 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`    
+Edit the `/etc/wsl.conf` to the following and restart WSL to apply the changes:
+```sh
+# This removes windows path
+# [interop]
+# appendWindowsPath = false
+# This do not mount windows drive
+[automount]
+enabled = false
+```
 
-## 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