-
-
Notifications
You must be signed in to change notification settings - Fork 157
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs: Add proto v0.14 blog post. (#994)
* First pass. * Update examples. * Add blog post. * Add new section.
- Loading branch information
Showing
6 changed files
with
127 additions
and
38 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,73 @@ | ||
| --- | ||
| slug: proto-v0.14 | ||
| title: proto v0.14 - Node.js and Rust now powered by WASM plugins | ||
| authors: [milesj] | ||
| tags: [proto, wasm, plugin] | ||
| --- | ||
|
|
||
| With this release, we've finished our migration to a WASM based plugin architecture. | ||
|
|
||
| <!--truncate--> | ||
|
|
||
| ## Full migration to WASM | ||
|
|
||
| In [our last release](./proto-v0.13), we migrated the Bun, Deno, and Go plugins to WASM. In this | ||
| release, we're excited to announce that we have completed our WASM migration by also converting | ||
| Node.js (and npm, etc) and Rust to WASM plugins. We've also updated our TOML plugin layer to use | ||
| WASM under the hood. | ||
|
|
||
| With this, 100% of our tools are now powered by WASM, and the APIs are stable enough for you, the | ||
| consumers, to build your own plugins! We have plans for additional APIs in the next release, | ||
| primarily installing and uninstall globals, and a hooks system, so look forward to that! To learn | ||
| more about our official plugins, check out the their repositories! | ||
|
|
||
| - [Bun](https://github.com/moonrepo/bun-plugin) | ||
| - [Deno](https://github.com/moonrepo/deno-plugin) | ||
| - [Go](https://github.com/moonrepo/go-plugin) | ||
| - [Node](https://github.com/moonrepo/node-plugin) | ||
| - [Rust](https://github.com/moonrepo/rust-plugin) | ||
| - [Schema](https://github.com/moonrepo/schema-plugin) | ||
|
|
||
| This release may seem light, but we | ||
| [rewrote the entire core](https://github.com/moonrepo/proto/pull/161) from the ground up to support | ||
| a pure plugin based architecture. This was a lot of work, but our implementation is far easier to | ||
| work with, and more robust. As part of this process, we improved version and range handling, archive | ||
| unpacking, and much more! | ||
|
|
||
| > Because of the rewrite, we may have introduced a few bugs. Please report any issues! | ||
|
|
||
| ## Breaking changes for TOML plugins | ||
|
|
||
| In preparation for the next release, and as clean up during the rewrite, we've made a few breaking | ||
| changes to the TOML schema, primarily around global handling. To start, this old code: | ||
|
|
||
| ```toml | ||
| [install] | ||
| globals-dir = ["$PROTOSTAR_HOME/bin", "$HOME/.protostar/bin"] | ||
| global-args = ["install", "--force", "{dependency}"] | ||
| ``` | ||
|
|
||
| Can now be rewritten as: | ||
|
|
||
| ```toml | ||
| [globals] | ||
| lookup-dirs = ["$PROTOSTAR_HOME/bin", "$HOME/.protostar/bin"] | ||
| install-args = ["install", "--force", "{dependency}"] | ||
| ``` | ||
|
|
||
| And lastly, the `install.unpack` setting has been removed. We believe our installation layer is | ||
| smart enough to unpack or move files automatically. | ||
|
|
||
| ## Other changes | ||
|
|
||
| View the [official release](https://github.com/moonrepo/proto/releases/tag/v0.14.0) for a full list | ||
| of changes. | ||
|
|
||
| - Versions defined in `.prototools` must be fully-qualified semantic versions. Partial versions | ||
| (missing patch or minor) are no longer supported. This may change in the future based on feedback. | ||
| - Tool and plugin names must now be in kebab-case. | ||
| - Node | ||
| - Yarn 2+ is now installed using `@yarnpkg/cli-dist`. We no longer downgrade to the latest v1. | ||
| - Will no longer detect a version from `engines` in `package.json`. | ||
| - Rust | ||
| - Will now detect a version/channel from `rust-toolchain.toml` and `rust-toolchain`. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -208,6 +208,7 @@ we'll use [Deno](https://deno.land/[email protected]/tools/script_installer). | |
| #[plugin_fn] | ||
| pub fn locate_bins(Json(_): Json<LocateBinsInput>) -> FnResult<Json<LocateBinsOutput>> { | ||
| Ok(Json(LocateBinsOutput { | ||
| fallback_last_globals_dir: true, | ||
| globals_lookup_dirs: vec!["$DENO_INSTALL_ROOT/bin".into(), "$HOME/.deno/bin".into()], | ||
| ..LocateBinsOutput::default() | ||
| })) | ||
|
|
@@ -224,7 +225,7 @@ versions to actually be installed. To provide a list of versions and language sp | |
| #[plugin_fn] | ||
| pub fn load_versions(Json(_): Json<LoadVersionsInput>) -> FnResult<Json<LoadVersionsOutput>> { | ||
| let mut output = LoadVersionsOutput::default(); | ||
| let response: Vec<NodeDistVersion> = fetch_url("https://nodejs.org/dist/index.json")?; | ||
| let response: Vec<NodeDistVersion> = fetch_url_with_cache("https://nodejs.org/dist/index.json")?; | ||
|
|
||
| for (index, item) in response.iter().enumerate() { | ||
| let version = Version::parse(&item.version[1..])?; // Starts with v | ||
|
|
@@ -323,19 +324,21 @@ shims to be created. By default, proto _will always_ create a global shim of the | |
|
|
||
| Global shims are optional scripts that are available on `PATH` as they are generated in the | ||
| `~/.proto/bin` directory, and can be defined with the `global_shims` parameter. This param is a hash | ||
| map, where the key is the shim file name, and the value is a relative path (from the tool's | ||
| directory) to a binary to execute. | ||
| map, where the key is the shim file name, and the value is a configuration object. | ||
|
|
||
| ```rust | ||
| #[plugin_fn] | ||
| pub fn create_shims(Json(input): Json<CreateShimsInput>) -> FnResult<Json<CreateShimsOutput>> { | ||
| let mut global_shims = HashMap::new(); | ||
|
|
||
| global_shims.insert("npx".into(), if input.env.os == HostOS::Windows { | ||
| "npx.cmd".into() | ||
| } else { | ||
| "bin/npx".into() | ||
| }); | ||
| global_shims.insert( | ||
| "npx".into(), | ||
| ShimConfig::global_with_alt_bin(if input.env.os == HostOS::Windows { | ||
| "npx.cmd".into() | ||
| } else { | ||
| "bin/npx".into() | ||
| }), | ||
| ); | ||
|
|
||
| Ok(Json(CreateShimsOutput { | ||
| global_shims, | ||
|
|
@@ -344,6 +347,19 @@ pub fn create_shims(Json(input): Json<CreateShimsInput>) -> FnResult<Json<Create | |
| } | ||
| ``` | ||
|
|
||
| Furthermore, if you'd prefer to _not_ create a primary global shim at all, enable the | ||
| `no_primary_global` field. | ||
|
|
||
| ```rust | ||
| #[plugin_fn] | ||
| pub fn create_shims(Json(input): Json<CreateShimsInput>) -> FnResult<Json<CreateShimsOutput>> { | ||
| Ok(Json(CreateShimsOutput { | ||
| no_primary_global: true, | ||
| ..CreateShimsOutput::default() | ||
| })) | ||
| } | ||
| ``` | ||
|
|
||
| ## Testing | ||
|
|
||
| The best way to test the plugin is to execute it through `proto` directly. To do this, you'll need | ||
|
|
@@ -394,8 +410,7 @@ output is correct. This can be achieved by creating a plugin instance with `crea | |
| calling the appropriate method. | ||
|
|
||
| ```rust | ||
| use proto_pdk::*; | ||
| use proto_pdk_test_utils::create_plugin; | ||
| use proto_pdk_test_utils::*; | ||
| use starbase_sandbox::create_empty_sandbox; | ||
|
|
||
| #[test] | ||
|
|
@@ -430,8 +445,7 @@ To test downloading and installing, use `generate_download_install_tests!`. This | |
| plugin ID and a real version to test with. | ||
|
|
||
| ```rust | ||
| use proto_pdk::*; | ||
| use proto_pdk_test_utils::{create_plugin, generate_download_install_tests}; | ||
| use proto_pdk_test_utils::*; | ||
| use starbase_sandbox::create_empty_sandbox; | ||
|
|
||
| generate_download_install_tests!("id", "1.2.3"); | ||
|
|
@@ -523,6 +537,8 @@ Some helpful resources for learning about and building plugins. | |
| - [Go](https://github.com/moonrepo/go-plugin) | ||
| - [Node](https://github.com/moonrepo/node-plugin) | ||
| - [npm, pnpm, yarn](https://github.com/moonrepo/node-plugin) | ||
| - [Rust](https://github.com/moonrepo/rust-plugin) | ||
| - [Schema](https://github.com/moonrepo/schema-plugin) | ||
| - Plugin development kit | ||
| - [`proto_pdk` docs](https://docs.rs/proto_pdk/) | ||
| - [`proto_pdk_test_utils` docs](https://docs.rs/proto_pdk_test_utils/) | ||