v1.0.0: use cargo zigbuild (#4)

* Checkin changes

* Checkin changes

* Change default target to `aarch64-unknown-linux-gnu`
* Build with `cargo zigbuild` instead of `cross`
* Remove logic to run `cargo check`, as it appears `zigbuild` already does this 👍

* Remove `checkCode` function as its not needed now

* Rename `cross` to `cargo-zigbuild`

* Update docs

* Update docs

* Update docs

* Fix letter

* Fix letter

* Update docs

* Update docs

* Update docs

* Update docs

* Update docs

* Update docs

* Update docs

* Update stuff

* Update CHANGELOG.md

* Update docs to mention how to install with `cross`

* Update links

* Bump version

Author: cb-rnag

CHANGELOG.md

@@ -11,6 +11,17 @@ Possible header types:
 
 ## [Unreleased]
 
+## v1.0.0 (2022-03-21)
+
+## Breaking Changes
+
+-   Switch to use [`cargo-zigbuild`] -- instead of `cross` -- for building Rust code.
+-   Switch the default build architecture from `x86_64` to `arm64`; this package now uses **aarch64-unknown-linux-gnu** as the default build target for AWS Lambda functions, mainly as I've found this architecture to be slightly more performant in general use cases.
+-   Do not run `cargo check`, as it appears _cargo-zigbuild_ automatically runs this check.
+-   Update `cdk-examples/` with an example of how to conditionally run a code block (more than one statement) when a feature is enabled.
+
+[`cargo-zigbuild`]: https://github.com/messense/cargo-zigbuild
+
 ## v0.4.0 (2022-03-08)
 
 ### Features

README.md

@@ -21,40 +21,55 @@
 
 This library provides a construct for a Rust Lambda function.
 
-It uses [Docker] and [`cross`] under the hood, and follows best practices as outlined
+It uses [`cargo-zigbuild`] under the hood, and follows best practices as outlined
 in the [official AWS documentation].
 
-[docker]: https://www.docker.com/get-started
-[`cross`]: https://github.com/rust-embedded/cross
-[official aws documentation]: https://docs.aws.amazon.com/sdk-for-rust/latest/dg/lambda.html
+[`cargo-zigbuild`]: https://github.com/messense/cargo-zigbuild
+[official aws documentation]: https://github.com/awslabs/aws-lambda-rust-runtime#building-and-deploying-your-lambda-functions
 
 ## Rust Function
 
 The `RustFunction` construct creates a Lambda function with automatic bundling and compilation of Rust code.
 
 ## Getting Started
 
-1. Install the [npm](https://nodejs.org/) package:
+1. Install the [npm] package:
 
     ```shell
     $ npm i rust.aws-cdk-lambda
     ```
 
-2) Use [`cargo`] to install _rust-embedded/cross_:
+2. Install the **aarch64-unknown-linux-gnu** toolchain with Rustup by running:
 
     ```shell
-    $ cargo install cross
+    $ rustup target add aarch64-unknown-linux-gnu
     ```
 
-3. Install the **x86_64-unknown-linux-gnu** toolchain with Rustup by running:
+3)  Install [Zig], using the instructions in their [installation guide] or via one of the options below.
+
+    1. Using [pip] (Python 3 required):
+
+        ```shell
+        $ pip install ziglang
+        ```
+
+    2. Using [npm]:
+
+        ```shell
+        $ npm install -g @ziglang/cli
+        ```
+
+4)  Use [`cargo`] to install _messense/cargo-zigbuild_:
 
     ```shell
-    $ rustup target add x86_64-unknown-linux-gnu
+    $ cargo install cargo-zigbuild
     ```
 
-Finally, ensure you have [Docker] installed and running, as it will be used by `cross` to compile Rust code for deployment.
-
+[npm]: https://nodejs.org/
+[pip]: https://pip.pypa.io/en/stable/
 [`cargo`]: https://www.rust-lang.org/
+[zig]: https://ziglang.org/
+[installation guide]: https://ziglang.org/learn/getting-started/#installing-zig
 
 ## Examples
 
@@ -105,15 +120,26 @@ All other properties of `lambda.Function` are supported, see also the [AWS Lambd
 
 When bundling the code, the `RustFunction` runs the following steps in order:
 
--   First it runs `cargo check` to confirm that the Rust code can compile.
-    Note that this is an optional step, and [can be disabled](#settings) as mentioned below.
+-   First it runs `cargo zigbuild`, and passes in the `--release` and `--target` flags, so it compiles for a Lambda environment - which defaults to the **aarch64-unknown-linux-gnu** target, as mentioned above. Note that _zigbuild_ does initially confirm that the Rust code can compile.
 
--   Next it calls `cross build`, and passes in the `--release` and `--target` flags, so it compiles for a Lambda environment - which defaults to the **x86_64-unknown-linux-gnu** target, as mentioned above.
-
--   Finally, it copies the release app binary from the `target/` folder to a file named `bootstrap`, which the Lambda custom runtime environment looks for. It adds this new file under the _build directory_, which defaults to a `.build/` folder under the directory where `cdk` was invoked.
+-   Next, it copies the release app binary from the `target/` folder to a file named `bootstrap`, which the Lambda custom runtime environment looks for. It adds this new file under the _build directory_, which defaults to a `.build/` folder under the directory where `cdk` was invoked.
 
 -   The directory path to the executable is then passed in to `lambda.Code.fromAsset`, which creates a _zip file_ from the release binary asset.
 
+## Use `cross` for Deployment
+
+If you instead prefer to use [Docker] and [`cross`] for deployment, as outlined
+in the [official AWS docs], you can install and use the [latest `v0.x`] release instead:
+
+```shell
+$ npm i rust.aws-cdk-lambda@0.4.0
+```
+
+[docker]: https://www.docker.com/get-started
+[`cross`]: https://github.com/rust-embedded/cross
+[official aws docs]: https://docs.aws.amazon.com/sdk-for-rust/latest/dg/lambda.html
+[latest `v0.x`]: https://github.com/rnag/rust.aws-cdk-lambda/releases/tag/0.4.0
+
 ## Multiple Rust Lambdas
 
 Assuming you have a CDK project with more than one Rust
@@ -222,7 +248,7 @@ In the `Cargo.toml`, create a new `features` section:
 my-feature = [] # feature has no explicit dependencies
 ```
 
-In your code, add the line `#[cfg(feature="my-feature")]` before a function declaration, or before a statement to execute.
+In your code, add the line `#[cfg(feature = "my-feature")]` before a function declaration, or before a statement to execute.
 
 In your CDK code in the `lib/` folder, add the following line:
 
@@ -239,7 +265,7 @@ In your code, add a call to the `env!()` macro:
 
 ```rust
 // Retrieve an environment variable set at build (compile) time.
-let build_value = env!("MY_BUILD_VAR");
+const BUILD_VALUE: &str = env!("MY_BUILD_VAR");
 ```
 
 In your CDK code in the `lib/` folder, add the following line:
@@ -260,16 +286,16 @@ Below lists some commonly used properties you can pass in to the `RustFunction`
 
 | Name               | Description                                                                                                                                                                                                                                                                                                                                                                                     |
 | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `target`           | Build target to cross-compile to. Defaults to the target for the **x86_64** architecture, `x86_64-unknown-linux-gnu`.                                                                                                                                                                                                                                                                           |
+| `target`           | Build target to cross-compile to. Defaults to the target for the **arm64** architecture, `aarch64-unknown-linux-gnu`.                                                                                                                                                                                                                                                                           |
 | `directory`        | Entry point where the project's main `Cargo.toml` is located. By default, the construct will use directory where `cdk` was invoked as the directory where Cargo files are located.                                                                                                                                                                                                              |
 | `buildDir`         | Default Build directory, which defaults to a `.build` folder under the project's root directory.                                                                                                                                                                                                                                                                                                |
 | `bin`              | Executable name to pass to `--bin`                                                                                                                                                                                                                                                                                                                                                              |
 | `package`          | Workspace package name to pass to `--package`                                                                                                                                                                                                                                                                                                                                                   |
 | `setupLogging`     | Determines whether we want to set up [library logging](https://rust-lang-nursery.github.io/rust-cookbook/development_tools/debugging/config_log.html) - i.e. set the `RUST_LOG` environment variable - for the lambda function.<br><br>The format defaults to `warn,module_name=debug`, which means that the default log level is `warn`, and the executable or library's log level is `debug`. |
 |                    |
 | `features`         | A list of features to activate when compiling Rust code. These must also be added to the `Cargo.toml` file.                                                                                                                                                                                                                                                                                     |
-| `buildEnvironment` | Key-value pairs that are passed in at compile time, i.e. to `cargo build` or `cross build`. This differs from `environment`, which determines the environment variables which are set on the AWS Lambda function itself.                                                                                                                                                                        |
-| `extraBuildArgs`   | Additional arguments that are passed in at build time to both `cargo check` and `cross build`. For example, [`--all-features`].                                                                                                                                                                                                                                                                 |
+| `buildEnvironment` | Key-value pairs that are passed in at compile time, i.e. to `cargo build` or `cargo zigbuild`. This differs from `environment`, which determines the environment variables which are set on the AWS Lambda function itself.                                                                                                                                                                     |
+| `extraBuildArgs`   | Additional arguments that are passed in at build time to `cargo zigbuild`. For example, [`--all-features`].                                                                                                                                                                                                                                                                                     |
 
 ## Settings
 
@@ -284,10 +310,9 @@ Below are some useful _global_ defaults which can be set for all Rust Lambda Fun
 | Name                 | Description                                                                                                                                                                                                                                 |
 | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `BUILD_INDIVIDUALLY` | Whether to build each executable individually, either via `--bin` or `--package`.                                                                                                                                                           |
-| `RUN_CARGO_CHECK`    | Whether to run `cargo check` to validate Rust code before building it with `cross`. Defaults to _true_.                                                                                                                                     |
 | `DEFAULT_LOG_LEVEL`  | Log Level for non-module libraries. Note that this value is only used when `RustFunctionProps.setupLogging` is enabled. Defaults to `warn`.                                                                                                 |
 | `MODULE_LOG_LEVEL`   | Log Level for a module (i.e. the executable). Note that this value is only used when `RustFunctionProps.setupLogging` is enabled. Defaults to `debug`.                                                                                      |
 | `WORKSPACE_DIR`      | Sets the root workspace directory. By default, the workspace directory is assumed to be the directory where `cdk` was invoked.<br><br>This directory should contain at the minimum a `Cargo.toml` file which defines the workspace members. |
 | `FEATURES`           | A list of features to activate when compiling Rust code. These must also be added to the `Cargo.toml` file.                                                                                                                                 |
-| `BUILD_ENVIRONMENT`  | Key-value pairs that are passed in at compile time, i.e. to `cargo build` or `cross build`. This differs from `environment`, which determines the environment variables which are set on the AWS Lambda function itself.                    |
-| `EXTRA_BUILD_ARGS`   | Additional arguments that are passed in at build time to both `cargo check` and `cross build`. For example, [`--all-features`].                                                                                                             |
+| `BUILD_ENVIRONMENT`  | Key-value pairs that are passed in at compile time, i.e. to `cargo build` or `cargo zigbuild`. This differs from `environment`, which determines the environment variables which are set on the AWS Lambda function itself.                 |
+| `EXTRA_BUILD_ARGS`   | Additional arguments that are passed in at build time to both `cargo zigbuild`. For example, [`--all-features`].                                                                                                                            |

cdk-examples/README.md

@@ -17,12 +17,12 @@ cd my-app
 npm i
 ```
 
-Next, ensure that you have [Docker](https://www.docker.com/get-started) running. You will need this to deploy with [`cross`](https://github.com/cross-rs/cross).
-If you don't have `cross` installed, refer to the [Getting Started](https://github.com/rnag/rust.aws-cdk-lambda#getting-started) section in docs for more info on getting set up.
+Next, ensure that you have [`cargo-zigbuild`](https://github.com/messense/cargo-zigbuild) installed. You will need this to cross-compile Rust code for deployment via `cdk`.
+If you don't have `cargo-zigbuild` installed, refer to the [Getting Started](https://github.com/rnag/rust.aws-cdk-lambda#getting-started) section in docs for more info on getting set up.
 
 Now you can deploy the app with `cdk`:
 
-> Note: on an initial run, it may take a _really_ long time on the compilation step with `cross`. In my case, it sometimes took up to _12 minutes_! But don't worry, any subsequent deployments should be overall faster.
+> Note: on an initial run, it may take a _really_ long time on the compilation step with `cargo-zigbuild`. In my case, it sometimes took up to _12 minutes_! But don't worry, any subsequent deployments should be overall faster.
 
 ```shell
 npx cdk deploy

cdk-examples/rust-bins/lib/rust-bins-stack.ts

@@ -25,7 +25,7 @@ export class RustBinsStack extends Stack {
         // Settings.BUILD_INDIVIDUALLY = true;
 
         // Uncomment to cross-compile Rust code to a different Lambda architecture.
-        // Settings.TARGET = 'aarch64-unknown-linux-gnu';
+        // Settings.TARGET = 'x86_64-unknown-linux-gnu';
 
         const bucket = new s3.Bucket(this, 'RustBinsBucket', {
             blockPublicAccess: BlockPublicAccess.BLOCK_ALL,

cdk-examples/rust-bins/src/bin/my_lambda1/main.rs

@@ -33,6 +33,16 @@ pub(crate) async fn my_handler(event: Request, ctx: Context) -> Response {
     // in the CDK code in the `lib/` folder.
     utils::log_enabled_features();
 
+    #[cfg(feature = "my-prod-feature")]
+    {
+        debug!("Now running in a PROD environment (my-prod-feature). Beep... Boop.");
+        let answer = systems::system_a::do_stuff_from_system_a();
+        info!(
+            "The answer to life, the universe, and everything is: {}",
+            answer
+        );
+    }
+
     let bucket_name = var("BUCKET_NAME")
         .expect("A BUCKET_NAME must be set in this app's Lambda environment variables.");
 

cdk-examples/rust-standalone/src/main.rs

@@ -75,11 +75,21 @@ pub(crate) async fn my_handler(event: Request, ctx: Context) -> Response {
     info!("Congrats! The 1st feature (my-first-feature) is enabled.");
 
     #[cfg(feature = "my-second-feature")]
-    info!("Congrats! The 2nd feature (my-second-feature) is enabled.");
+    {
+        info!("Congrats! The 2nd feature (my-second-feature) is enabled.");
+
+        debug!(
+            "This is a debug message. This line is included to show that we can \
+            conditionally run more than one statement when a feature is enabled."
+        );
+    }
 
     // retrieve an environment variable set at build (compile) time.
     let build_env_var = env!("MY_BUILD_ENV_VAR");
-    debug!("Resolved compile-time value of `MY_BUILD_ENV_VAR`: {}", build_env_var);
+    debug!(
+        "Resolved compile-time value of `MY_BUILD_ENV_VAR`: {}",
+        build_env_var
+    );
 
     // retrieve an environment variable set in the lambda.
     let bucket_name = var("BUCKET_NAME")

cdk-examples/rust-workspaces/lib/rust-workspaces-stack.ts

@@ -28,7 +28,7 @@ export class RustWorkspacesStack extends Stack {
         // Settings.BUILD_INDIVIDUALLY = true;
 
         // Uncomment to cross-compile Rust code to a different Lambda architecture.
-        // Settings.TARGET = 'aarch64-unknown-linux-gnu';
+        // Settings.TARGET = 'x86_64-unknown-linux-gnu';
 
         const bucket = new s3.Bucket(this, 'RustWorkspacesBucket', {
             blockPublicAccess: BlockPublicAccess.BLOCK_ALL,

cdk-examples/rust-workspaces/my_lambdas/my_lambda1/src/main.rs

@@ -33,6 +33,16 @@ pub(crate) async fn my_handler(event: Request, ctx: Context) -> Response {
     // in the CDK code in the `lib/` folder.
     utils::log_enabled_features();
 
+    #[cfg(feature = "my-prod-feature")]
+    {
+        debug!("Now running in a PROD environment (my-prod-feature). Beep... Boop.");
+        let answer = systems::system_a::do_stuff_from_system_a();
+        info!(
+            "The answer to life, the universe, and everything is: {}",
+            answer
+        );
+    }
+
     let bucket_name = var("BUCKET_NAME")
         .expect("A BUCKET_NAME must be set in this app's Lambda environment variables.");