You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
* update documentation and changelog
* add example link
* fix PR number
* reword local dev instructions
* add changes based on feedback
* fix typo
* move legacy runtime back to top
* add missing punctation
* Update README.md
Co-authored-by: Douglas Parsons <dglsparsons@users.noreply.github.com>
* add full `Cargo.toml`
---------
Co-authored-by: Douglas Parsons <dglsparsons@users.noreply.github.com>
Copy file name to clipboardExpand all lines: README.md
+53-42Lines changed: 53 additions & 42 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -20,9 +20,13 @@ Community-maintained package to support using [Rust](https://www.rust-lang.org/)
20
20
21
21
The below documentation is for the `vercel_runtime` crate (in beta). If you are looking for the legacy runtime instructions using `vercel_lambda` see [tree/a9495a0](https://github.com/vercel-community/rust/tree/a9495a0f0d882a36ea165f1629fcc79c30bc3108).
22
22
23
-
## Usage
23
+
## Getting Started
24
24
25
-
First, you'll need a `vercel.json` file in your project:
25
+
> Please ensure [Vercel CLI](https://vercel.com/docs/cli#installing-vercel-cli) and the Rust toolchain is already installed on your system. We recommended setting up Rust with [rustup](https://rustup.rs/).
26
+
27
+
[Prefer looking at examples?](https://github.com/vercel-community/rust/tree/main/examples)
28
+
29
+
**Step 1** - Add a `vercel.json` file to your project.
26
30
27
31
```json
28
32
{
@@ -34,9 +38,11 @@ First, you'll need a `vercel.json` file in your project:
34
38
}
35
39
```
36
40
37
-
A Vercel Function will be created for every file that matches `api/**/*.rs`.
41
+
This turns every file matching `api/**/*.rs` into a Vercel Function.
38
42
39
-
Example:
43
+
> **Note:** The npm dependency `vercel-rust` defined in [functions](https://vercel.com/docs/concepts/projects/project-configuration#functions)**does not** have to be installed manually.
44
+
45
+
**Step 2** - Create a function. As an example, here is `api/handler.rs`.
# Note that you need to provide unique names for each binary
85
-
[[bin]]
86
-
name = "user-id"
87
-
path = "api/user/[id].rs"
93
+
# Note that you need to provide unique names for each binary:
94
+
# [[bin]]
95
+
# name = "user-id"
96
+
# path = "api/user/[id].rs"
97
+
#
98
+
# [[bin]]
99
+
# name = "group-id"
100
+
# path = "api/group/[id].rs"
101
+
```
88
102
89
-
[[bin]]
90
-
name = "group-id"
91
-
path = "api/group/[id].rs"
103
+
**Step 4** - Create a `.vercelignore` in the root directory of your project to ignore build artifacts.
92
104
93
-
# --snip--
105
+
```shell
106
+
target/
94
107
```
95
108
109
+
**Step 5** - You're all set. Run `vercel dev` to develop your project locally. You can connect a Git repository to Vercel, or use `vercel` to start deploying your project on Vercel.
110
+
111
+
## Advanced Usage
112
+
113
+
### Toolchain Overrides
114
+
115
+
An example on how this can be achieved is using a `rust-toolchain` file adjacent to your `Cargo.toml`. Please refer to [Rust Documentation](https://rust-lang.github.io/rustup/overrides.html#the-toolchain-file) for more details.
116
+
96
117
### Dependencies
97
118
98
-
This Builder supports installing dependencies defined in the `Cargo.toml` file.
119
+
By default builder module supports installing dependencies defined in the `Cargo.toml` file.
99
120
100
-
Furthermore, more system dependencies can be installed at build time with the presence of a shell `build.sh` file in the same directory as the entrypoint file.
121
+
More system dependencies can be installed at build time with the presence of a shell `build.sh` file in the root directory of your project.
101
122
102
-
## Prebuilt Deployments
123
+
###Prebuilt Deployments
103
124
104
-
When creating a prebuilt deployment, the build output must be for x86_64 linux. To do this, create a Cargo build configuration at `.cargo/config.toml` with the following contents:
125
+
When creating a prebuilt deployment, the build output must be for `x86_64 linux`. To do this, create a Cargo build configuration at `.cargo/config.toml` with the following contents:
You then can build the file and trigger the deployment with the Vercel CLI.
137
+
You then can build the file and trigger the deployment via [Vercel CLI](https://vercel.com/docs/cli#installing-vercel-cli).
117
138
118
139
```shell
119
140
vercel build && vercel deploy --prebuilt
120
141
```
121
142
122
-
##Local Development
143
+
### Musl/Static linking
123
144
124
-
With `vercel dev` and `vercel-rust`, you can develop your Rust-based lambdas on your own machine.
145
+
Unfortunately, the AWS Lambda Runtime for Rust relies (tangentially) on `proc_macro`, which won't compile on musl targets. Without `musl`, all linking must be dynamic. If you have a crate that relies on system libraries like `postgres` or `mysql`, you can include those library files with the `includeFiles` config option and set the proper environment variables, config, etc. that you need to get the library to compile.
125
146
126
-
During local development with `vercel dev`, ensure `rust` and `cargo` are already installed and available in your `PATH`, since they will not be installed automatically. The recommended way to install is with [rustup](https://rustup.rs/).
147
+
For more information, please see [this issue](https://github.com/mike-engel/vercel-rust/issues/2).
127
148
128
149
## Contributing
129
150
@@ -137,29 +158,19 @@ pnpm install
137
158
cargo fetch
138
159
```
139
160
140
-
## Invocation Flowchart
161
+
### Builder Module
162
+
163
+
The _npm_ module `vercel-rust` is implementing an interface which is primarily taking care of spawning a development server, caching between consecutive builds, and running the compilation. You can read more about the in-depths of implementing a builder [here](https://github.com/vercel/vercel/blob/main/DEVELOPING_A_RUNTIME.md).
164
+
165
+
Note that this dependency **does not** have to be installed manually as it is pulled automatically.
166
+
167
+
### Runtime Crate
168
+
169
+
The crate `vercel_runtime` is what you will consume in your Rust functions. As the name suggests, the runtime crate takes care of everything that happens during run-time. In specific it takes care of creating a [Tower](https://docs.rs/tower/latest/tower/trait.Service.html) service, which expects a specific handler signature. The flow of an invocation can be visualized as the following:
C --> |"Ok(r) => process_response(r)"| D["Response"]
147
176
```
148
-
149
-
## FAQ
150
-
151
-
<details>
152
-
<summary>How to specify toolchain overrides</summary>
153
-
154
-
An example on how this can be achieved is using a `rust-toolchain` file adjacent to your `Cargo.toml`. Please refer to [Rust Documentation](https://rust-lang.github.io/rustup/overrides.html#the-toolchain-file) for more details.
155
-
156
-
</details>
157
-
158
-
<details>
159
-
<summary>Can I use musl/static linking?</summary>
160
-
161
-
Unfortunately, the AWS Lambda Runtime for Rust relies (tangentially) on `proc_macro`, which won't compile on musl targets. Without `musl`, all linking must be dynamic. If you have a crate that relies on system libraries like `postgres` or `mysql`, you can include those library files with the `includeFiles` config option and set the proper environment variables, config, etc. that you need to get the library to compile.
162
-
163
-
For more information, please see [this issue](https://github.com/mike-engel/vercel-rust/issues/2).
0 commit comments