v1.2.0: add "skip build" option and functionality (rnag#14)

* package version updates * allow options to skip build step * fix so we don't build when `cdk destroy` etc. is run * update Settings with `SKIP_BUILD` * check for `build` context value passed when invoking `cdk` * update sample CDK apps to use `swc` when deploying `cdk` -- minor optimization * update docs * update CHANGELOG.md etc * Update CHANGELOG.md * update docs
codemonger-io · Feb 4, 2023 · eadbe2f · eadbe2f
1 parent 73b8cdb
commit eadbe2f
Show file tree

Hide file tree

Showing 21 changed files with 21,306 additions and 21,510 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -11,17 +11,40 @@ Possible header types:
 
 ## [Unreleased]
 
+## v1.2.0 (2023-02-03)
+
+### Bug Fixes
+
+-   `RustFunction` should not execute `cargo lambda` when certain `cdk` sub-commands are invoked, such as:
+    -   `destroy`
+    -   `list`
+    -   etc.
+-   _Potential_ bug-fix (unconfirmed): The library should not execute `cargo lambda` when a project has multiple stacks, and the stack being deployed doesn't include any `RustFunction` constructs.
+
+### Features
+
+-   Add parameters to `Settings`:
+    -   `SKIP_BUILD`
+-   Update docs to mention how to _skip_ the build step by passing in the `build` context flag when invoking a `cdk` command. For example:
+    ```shell
+    cdk synth -c build=0
+    ```
+-   Update developer docs used for local testing, as I determined a newish approach with `npm link` can be used, as outlined in [this article].
+-   Enable `swc` in all sample CDK apps, in order to improve the overall [performance of `ts-node`](https://typestrong.org/ts-node/docs/performance) when `cdk` is run.
+
+[this article]: https://stackoverflow.com/a/18778516/10237506
+
 ## v1.1.3 (2022-03-28)
 
-## Breaking Changes
+### Breaking Changes
 
 -   Switch to use [`cargo-lambda`] -- which abstracts away `cargo-zigbuild` -- for
     building Rust code; technically this is not a _breaking_ change, but it **will** require
     the package to be installed with `cargo`.
 
 [`cargo-lambda`]: https://crates.io/crates/cargo-lambda
 
-## Features
+### Features
 
 -   [zig] can now be installed via the `--save-optional` flag when installing this package:
     ```shell
@@ -35,7 +58,7 @@ Possible header types:
 
 ## v1.0.0 (2022-03-21)
 
-## Breaking Changes
+### 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.

diff --git a/README.md b/README.md
@@ -290,12 +290,14 @@ import { Settings } from 'rust.aws-cdk-lambda';
 
 Below are some useful _global_ defaults which can be set for all Rust Lambda Functions in a CDK app.
 
-| Name                 | Description                                                                                                                                                                                                                                 |
-| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `BUILD_INDIVIDUALLY` | Whether to build each executable individually, either via `--bin` or `--package`.                                                                                                                                                           |
-| `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 `cargo lambda`. 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 lambda`. For example, [`--all-features`].                                                                                                                              |
+| Name                 | Description                                                                                                                                                                                                                                                                                                                                                                                       |
+| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `BUILD_INDIVIDUALLY` | Whether to build each executable individually, either via `--bin` or `--package`.                                                                                                                                                                                                                                                                                                                 |
+| `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 `cargo lambda`. 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 lambda`. For example, [`--all-features`].                                                                                                                                                                                                                                                                                    |
+| `SKIP_BUILD`         | Whether to skip building Rust Lambdas -- e.g. skip the compile step with `cargo lambda`.<br><br>Alternatively, this can be set in the `build` context, when invoking `cdk` -- for example:<br>`$ cdk synth -c build=[T \| true \| 1 \| Y \| yes \| ok \| on]`<br>Any values other than the listed evaluate to `false`. So, this would skip the build step on `synth`:<br>`$ cdk synth -c build=0` |
+|                      |
diff --git a/cdk-examples/README.md b/cdk-examples/README.md
@@ -64,6 +64,8 @@ echo '\n# Rust lambda build directory\n.build' >> .gitignore
 
 ## Local Development and Testing
 
+> _Note_: See the [New Approach](#new-approach) below which obviates the need to update the `import` statements.
+
 In case it's desirable to uncomment the following import in the `lib/` folder of a sample CDK app, for local testing purposes:
 
 ```ts
@@ -87,3 +89,53 @@ For example, here are the important ones you'd need to verify:
 ├── [email protected]
 ├── [email protected]
 ```
+
+### New Approach
+
+As per [this article](https://stackoverflow.com/a/18778516/10237506) I found that explains how a local module can be installed with `npm link`, this is a slightly different approach to commenting out and then un-commenting an `import` statement as mentioned above.
+
+This does also have a few unavoidable side-effects, but hopefully such a method should yield an overall better (developer) experience.
+
+Here then, is the updated approach which leverages `npm link` under the hood to locally install an NPM module.
+
+First, `cd` into the local directory of a sample CDK app.
+
+Within this folder, run the npm script `link` (alias: `l`) to automatically link to the local `rust.aws-cdk-lambda` module -- i.e. the project folder two levels up:
+
+```shell
+npm run l
+```
+
+If all is well, you should see that the _linking_ is successful.
+
+To confirm:
+
+```shell
+npm list
+```
+
+The result should be something like:
+
+```plaintext
+...
+├── [email protected] -> ./../..
+...
+```
+
+That means everything is set up correctly! CDK code should reference the definitions under `../../dist/`, i.e. under the root folder.
+
+Next -- open a new terminal window, and from the project root folder `$root`, run the following command:
+
+```shell
+npm run watch
+```
+
+This will listen for any changes to the project TypeScript code, and automatically run `tsc` to down-compile it to JS code, which it places in the `dist/` folder.
+
+These changes will also be reflected in the sample CDK project, thanks to `npm link` which was run earlier.
+
+To _unlink_ the local module and use the remote one installed as a dependency listed in the `package.json`, simply run the following from the root of a sample CDK app:
+
+```shell
+npm run ul
+```