docs

Author: softprops

README.md

@@ -1,7 +1,7 @@
 # serverless rust [![Build Status](https://github.com/softprops/serverless-rust/workflows/Main/badge.svg)](https://github.com/softprops/serverless-rust/actions) [![npm](https://img.shields.io/npm/v/serverless-rust.svg)](https://www.npmjs.com/package/serverless-rust)
 
 
-> A ⚡ [Serverless framework](https://www.serverless.com/) ⚡ plugin for [Rustlang](https://www.rust-lang.org/en-US/) applications 🦀
+> A ⚡ [Serverless framework](https://www.serverless.com/framework/docs/) ⚡ plugin for [Rustlang](https://www.rust-lang.org/) applications 🦀
 
 ## 📦 Install
 
@@ -39,7 +39,7 @@ functions:
           method: GET
 ```
 
-> 💡 The Rust Lambda runtime requires a binary named `bootstrap`. This plugin renames the binary cargo builds to `bootstrap` for you before packaging. You do **not** need to do this manually in your Cargo configuration.
+> 💡 The Rust Lambda runtime requires a binary named `bootstrap`. This plugin renames the binary cargo builds to `bootstrap` for you before packaging. You do **not** need to do this manually in your Cargo.toml configuration file.
 
 ## 🖍️ customize
 
@@ -57,11 +57,51 @@ custom:
     dockerTag: 'some-custom-tag'
     #  custom docker image
     dockerImage: 'dockerUser/dockerRepo'
+```
+
+### 🥼 (experimental) local builds
+
+While it's useful to have a build environment match your deployment
+environment dockerized builds do come with some notable tradeoffs.
+The external dependency on docker itself often causes friction in an added dependency to your build. If you wish to build lambda's locally, this plugin also supports an experimental `dockerless` mode. 
+
+```diff
+custom:
+  # this section allows for customization of the default
+  # serverless-rust plugin settings
+  rust:
+    # flags passed to cargo
+    cargoFlags: '--features enable-awesome'
     # experimental! when set to true, artifacts are built locally outside of docker
-    dockerless: true
++   dockerless: true
 ```
 
-> Note. `dockerless` mode is experimental. Windows and OSX will both have to install a separate target with `rustup target add x86_64-unknown-linux-musl`
+This will build and link your lambda as a static binary that can be deployed in to the lambda execution environment as a static binary using [MUSL](https://doc.rust-lang.org/edition-guide/rust-2018/platform-and-target-support/musl-support-for-fully-static-binaries.html).
+
+In order to use this mode its expected that you install the `x86_64-unknown-linux-musl` target on all platforms locally with
+
+```sh
+$ rustup target add x86_64-unknown-linux-musl
+```
+
+On linux platforms, you will need to install musl-tools
+
+```sh
+$ sudo apt-get update && sudo apt-get install -y musl-tools
+```
+
+On Mac OSX, you will need to install a MUSL cross compilation toolchain
+
+```sh
+$ brew install filosottile/musl-cross/musl-cross
+```
+
+Using MUSL comes with some other notable tradeoffs. One of which is complications that arise when depending on dynamically linked dependencies.
+
+* With OpenSSL bindings which you can safely replace is with [rustls](https://github.com/ctz/rustls) or [vendor it](https://docs.rs/openssl/0.10.29/openssl/#vendored)
+* Other known issues have been reported with [backtrace](https://github.com/KodrAus/rust-cross-compile#limitations). 
+
+If you find other MUSL specific issues, please reported them by [opening an issue](https://github.com/softprops/serverless-rust/issues/new?template=bug_report.md).
 
 ### 🎨 Per function customization