Add docs in README.md

README.md

@@ -0,0 +1,79 @@
+# GitHub Action to Cross Compile Rust Projects
+
+This action lets you easily cross-compile Rust projects using
+[cross](https://github.com/cross-rs/cross).
+
+Here's an example from the release workflor for
+[my tool `precious`](https://github.com/houseabsolute/precious):
+
+```yaml
+jobs:
+  release:
+    name: Release - ${{ matrix.platform.release_for }}
+    strategy:
+      matrix:
+        platform:
+          - release_for: FreeBSD-x86_64
+            os: ubuntu-20.04
+            target: x86_64-unknown-freebsd
+            bin: precious
+            name: precious-FreeBSD-x86_64.tar.gz
+
+          - release_for: Windows-x86_64
+            os: windows-latest
+            target: x86_64-pc-windows-msvc
+            bin: precious.exe
+            name: precious-Windows-x86_64.zip
+
+          - release_for: macOS-x86_64
+            os: macOS-latest
+            target: x86_64-apple-darwin
+            bin: precious
+            name: precious-Darwin-x86_64.tar.gz
+
+            # more release targets here ...
+
+    runs-on: ${{ matrix.platform.os }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+      - name: Build binary
+        uses: houseabsolute/actions-rust-cross@v0
+        with:
+          target: ${{ matrix.platform.target }}
+          args: "--locked --release"
+          strip: true
+
+    # more packaging stuff goes here ...
+```
+
+## Input Parameters
+
+This action takes the following parameters:
+
+| Key            | Type                        | Required? | Description                                                                                                                               |
+| -------------- | --------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `target`       | string                      | yes       | The target triple to compile for. This should be one of the targets listed by running `rustup target list`.                               |
+| `GITHUB_TOKEN` | string                      | no        | Defaults to the value of `${{ github.token }}`.                                                                                           |
+| `args`         | string                      | no        | A string-separated list of arguments to be passed to the `cross build`, like `--release --locked`.                                        |
+| `strip`        | boolean (`true` or `false`) | no        | If this is true, then the resulting binary will be stripped if possible. This is only possible for binaries which weren't cross-compiled. |
+
+## How it Works
+
+Under the hood, this action will compile your binary with either `cargo` or `cross`, depending on
+the host machine and target. For Linux builds, it will always use `cross` except for builds
+targeting an x86 architecture like `x86_64` or `i686`.
+
+On Windows and macOS, it's possible to compile for all supported targets out of the box, so `cross`
+will not be used on those platforms.
+
+If it needs to install `cross`, it will install the latest version by downloading a release using
+[my tool `ubi`](https://github.com/houseabsolute/ubi). This is much faster than using `cargo` to
+build `cross`.
+
+When compiling on Windows, it will do so in a Powershell environment, which can matter in some
+corner cases, like compiling the `openssl` crate with the `vendored` feature.
+
+Finally, it will run `strip` to strip the binary if the `strip` parameter is true. This is only
+possible for builds that are not done via `cross`. In addition, Windows builds for `aarch64` cannot
+be stripped either.