Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

cargo-cp-artifact

neon-bindings1.4mMIT0.1.9

Copies compiler artifacts emitted by rustc by parsing Cargo metadata

cargo, rust, neon

readme

cargo-cp-artifact

cargo-cp-artifact is a small command line utility for parsing cargo metadata output and copying a compiler artifact to a desired location.

Installation

npm install -g cargo-cp-artifact

Usage

cargo-cp-artifact --artifact artifact-kind crate-name output-file -- wrapped-command

cargo-cp-artifact accepts a list of crate name and artifact kind to output file mappings and a command to wrap.cargo-cp-artifact will read stdout of the wrapped command and parse it as cargo metadata. Compiler artifacts that match arguments provided will be copied to the target destination.

When wrapping a cargo command, it is necessary to include a json format to --message-format.

Arguments

Multiple arguments are allowed to copy multiple build artifacts.

--artifact

Alias: -a

Followed by three arguments: artifact-kind crate-name output-file

--npm

Alias: -n

Followed by two arguments: artifact-kind output-file

The crate name will be read from the npm_package_name environment variable. If the package name includes a namespace (@namespace/package), the namespace will be removed when matching the crate name (package).

Artifact Kind

Valid artifact kinds are bin, cdylib, and dylib. They may be abbreviated as b, c, and d respectively.

For example, -ac is the equivalent of --artifact cdylib.

Examples

Wrapping cargo

cargo-cp-artifact -a cdylib my-crate lib/index.node -- cargo build --message-format=json-render-diagnostics

Parsing a file

cargo-cp-artifact -a cdylib my-crate lib/index.node -- cat build-output.txt

npm script

package.json

{
    "name": "my-crate",
    "scripts": {
        "build": "cargo-cp-artifact -nc lib/index.node -- cargo build --message-format=json-render-diagnostics"
    }
}
npm run build

# Additional arguments may be passed
npm run build -- --feature=serde

Why does this exist?

At the time of writing, cargo does not include a configuration for outputting a library or binary to a specified location. An --out-dir option exists on nightly, but does not allow specifying the name of the file.

It's surprisingly difficult to reliably find the location of a cargo compiler artifact. It is impacted by many parameters, including:

  • Build profile
  • Target, default or specified
  • Crate name and name transforms

However, cargo can emit metadata on stdout while continuing to provide human readable diagnostics on stderr. The metadata may be parsed to more easily and reliably find the location of compiler artifacts.

cargo-cp-artifact chooses to wrap a command as a child process instead of reading stdin for two reasons:

  1. Removes the need for -o pipefile when integrating with build tooling which may need to be platform agnostic.
  2. Allows additional arguments to be provided when used in an npm script.

changelog

cargo-cp-artifact

0.1.9 supports a breaking change in cargo that converts artifact names from kebab-case to snake_case.

Version 1.0.0

Commitment to Compatibility

The release of Neon 1.0 marks our commitment to backwards-compatibility: starting with 1.0.0, Neon users can be confident that future upgrades to Neon 1.x versions should never require code changes (with the possible exception of safety bugfixes, which we expect to be rare). We also do not anticipate releasing new major versions often and do not have any plans to do so for now.

Breaking Changes

Bug fixes

Other

https://github.com/neon-bindings/neon/pull/1010

  • Relaxed error behavior on missing Node-API symbols. Neon will panic on first use instead of aborting the process at module load time.
  • Bumped dependency versions
  • Changed to edition 2021
  • Updated support matrix to Node 18, 20, and 21

Version 1.0.0-alpha.4

Patch to enable new features flags in docs.rs.

Version 1.0.0-alpha.3

Breaking Changes

  • Removed Managed trait

Improvements

Bug Fixes

Docs

cargo-cp-artifact

0.1.8 fixes sending additional arguments on Windows (https://github.com/neon-bindings/neon/pull/972).

Version 1.0.0-alpha.2

Breaking Changes

neon::object::This

https://github.com/neon-bindings/neon/pull/918

Trait neon::object::This has been removed. This was primarily added for use with the declare_types! macro to generate classes. The macro was removed and This is no longer needed. Additionally, the This argument on JsFunction was found to be invalid because it asserted at compile time a type for this that could change at runtime. (Note that this was not unsound because the type would be checked by Node-API and result in a panic.)

JsFunction::this

https://github.com/neon-bindings/neon/pull/918

JsFunction::this was changed to perform a downcast and be fallible. This is in line with similar APIs (e.g., Object::get). Additionally, an infallible version, JsValue::this_value was added that does not perform a downcast.

Added Feature flag for external buffers

https://github.com/neon-bindings/neon/pull/937

Electron began using pointer compression on JavaScript values that is incompatible with external buffers. As a preventative measure, JsArrayBuffer::external and JsBuffer::external have been placed behind a feature flag that warns of Electron incompatibility.

Improvements

Bug Fixes

Docs

cargo-cp-artifact

0.1.7 includes a fix to unlink .node files before copying to address common code signing errors on macOS (https://github.com/neon-bindings/neon/pull/921).

Version 1.0.0-alpha.1

Pre-release of a major milestone for Neon. 1.0.

Breaking Changes

Major

Minor

Features

Bug Fixes

Docs

Internal

Version 0.10.1

Fix a soundness hole in JsArrayBuffer::external and JsBuffer::external (https://github.com/neon-bindings/neon/pull/897).

Thanks to @Cassy343 for finding the issue!

In previous versions of Neon, it was possible to create a JsArrayBuffer or JsBuffer that references data without the 'static lifetime.

pub fn soundness_hole(mut cx: FunctionContext) -> JsResult<JsArrayBuffer> {
    let mut data = vec![0u8, 1, 2, 3];

    // Creating an external from `&mut [u8]` instead of `Vec<u8>` since there is a blanket impl
    // of `AsMut<T> for &mut T`
    let buf = JsArrayBuffer::external(&mut cx, data.as_mut_slice());

    // `buf` is still holding a reference to `data`!
    drop(data);

    Ok(buf)
}

Version 0.10

See the Neon 0.10 Migration Guide for more details about new features and breaking changes.

Features

Minor Improvements

Fixes

Internal Improvements

Version 0.9.1

Version 0.9.0

Performance

Channel, formerly EventQueue, are now cloneable. Clones share a backing queue to take advantage of an optimization in Node threadsafe functions. Additionally, when specifying Node API 6 or higher (napi-6), calling cx.channel() will return a shared queue (https://github.com/neon-bindings/neon/pull/739).

The change may cause a performance regression in some pathological use cases (https://github.com/neon-bindings/neon/issues/762).

Deprecation

EventQueue and EventQueueError have been renamed to Channel and ChannelError respectively to clarify their function and similarity to Rust channels. The types are available as deprecated aliases (https://github.com/neon-bindings/neon/pull/752).

Docs

Fixes

Version 0.8.3

Version 0.8.2

Version 0.8.1

Version 0.8.0

Fixes

Features

Improvements

Housekeeping

Version 0.7.1

Features

Fixes

Version 0.7.0

N-API

Version Selection

Neon supports a large number of different Node versions which may have different N-API requirements. Neon now supports selecting the minimum required N-API version required by a module. For example, for N-API Version 4:

neon = { version = "0.7", default-features = false, features = ["napi-4"] }

If the Neon module is loaded in an older version of Node that does not support that N-API version, a panic message will inform the user.

Threadsafe Functions

A prerelease version of EventQueue for calling into the main JavaScript thread from Rust threads can be enabled with the event-queue-api feature flag. The API is considered unstable and may change in the future until the RFC is merged.

Version 0.6.0

The cx.try_catch(..) API has been updated to return T: Sized instead of T: Value (https://github.com/neon-bindings/neon/pull/631). This API is strictly more powerful and allows users to return both JavaScript and Rust values from try_catch closures.

N-API

Version 0.5.3

Bug Fixes

Upgrade node-gyp (https://github.com/neon-bindings/neon/pull/623)

  • Fix Windows Node 15
  • Fix Apple M1

Features

Added neon::main macro as a replacement for register_module! (https://github.com/neon-bindings/neon/pull/636)

Known Issues

Builds occassionally fail with Windows, Node 15 and npm 7 (https://github.com/neon-bindings/neon/issues/642)

Version 0.5.2

CLI

Added support for additional arguments passed to cargo build. Resolves https://github.com/neon-bindings/neon/issues/471.

neon build --release -- --features awesome

N-API

Version 0.5.1

Performance

  • smallvec is used for collecting arguments and yields a small performance gain when calling JsFunction

Broader Support

Thanks to @staltz, neon now builds for both iOS and Android with nodejs-mobile.

Version 0.5.0

Re-publish

Versions 0.4.1 and 0.4.2 included a breaking change in neon-runtime. At the time, this was considered acceptable because neon-runtime is considered an internal crate and not part of the public API. However, it was discovered, after publishing, that neon-serde, a commonly used crate in the neon ecosystem, contained a direct dependency on neon-runtime. In order to best support users, versions 0.4.1 and 0.4.2 were "yanked" and re-published as 0.5.0.

Additionally, the team is working with the authors of neon-serde to remove the dependency on neon-runtime to prevent future issues.

Bug Fixes

Version 0.4.2

Unpublished / Yanked

Bug Fixes

  • Fix memory leak and race condition in EventHandler

Version 0.4.1

Unpublished / Yanked

Features

Try Catch

Added the cx.try_catch API of RFC 29. This feature is behind the try-catch-api feature flag.

Bug Fixes

CI Improvements

The Neon Project now uses Github Actions thanks to @lhr0909! As part of this change, CI now runs on all of our supported platforms (macOS, Windows, linux) and Node versions.

Version ✨0.4✨ 🎉

EventHandler API

The EventHandler API is a new feature for scheduling work on the javascript main thread from other threads. Big thanks to @geovie for the RFC and implementation.

This feature is currently unstable and gated by a event-handler-api feature flag.

Improvements

  • New project template updated for Rust 2018

Bug Fixes

  • Workaround for nodejs/node-gyp#1933
  • Docs build fixed
  • Temporarily disable static tests which keep breaking CI

N-API

  • Context/Isolate threading
  • Scopes
  • Strings
  • Primitive values (numbers, undefined, null, boolean)

Version 0.3.3

Hot fix for neon build in projects with many dependencies.

Version 0.3.2

Bug fixes and Small Features

  • Disable node module registration on test build, allowing cargo test to be used on neon modules
  • Added support for alternate CARGO_TARGET_DIR locations (e.g., workspaces)
  • Added macros to neon::prelude to improve ergonomics in Rust 2018
  • Link win_delay_hook when building with electron-build-env, fixing Windows Electron
  • Fixed missing __cxa_pure_virtual on Linux
  • Copy native files into OUT_DIR and build there to fix cargo publish and follow best practices
  • Eliminated mem::uniitialized() usage, reducing warnings and fixing an instance of undefined behavior

Potentially Breaking

The macOS link arguments were moved from neon-cli to neon-build. This is more idiomatic, but makes neon-build required for macOS builds where it was unnecessary before.

Since neon-build has been included in the project template since 0.1 this change was not deemed significant enough to warrant a major revision.

N-API

Neon 0.3.2 lays the groundwork for the next major revision. Development of Neon against an ABI stable Node API (N-API) will occur on main.

  • Added legacy-runtime and n-api feature flags for toggling neon runtime
  • Moved the legacy runtime to nodejs-sys crate
  • Stubbed required n-api implementation
  • Added feature flag to neon-cli to help configuring n-api projects

Version 0.3.1

  • Build v0.3 project templates by default in the CLI

Version 0.3

Breaking Changes

Bug Fixes

Improvements

Version ✨0.2✨ 🎉

See the Neon 0.2 Migration Guide for documentation on migrating your projects from the Neon 0.1.x series to Neon 0.2, and please let us know if you need help!

  • Release automation (#318)
  • New ArrayBuffer views API -- see RFC 5 (#306)
  • VM 2.0 -- see RFC 14 (#306)
  • New JsString constructor -- see RFC 21 (#322)
  • Eliminated JsInteger, JsVariant, callee() -- see RFC 22 (#323)
  • Renamed Key to PropertyKey and its method names -- see RFC 22 (#323)
  • Module reorganization -- see RFC 20 (#324)
  • New JsError API -- see RFC 23 (#325)
  • Eliminated ToJsString API -- see RFC 22 (#326)
  • Eliminated NEON_NODE_ABI env var -- see RFC 22 (#327)
  • Default to release builds -- see RFC 22 (#328)
  • Made Buffer construction safe by default (#329, #331)
  • Made Throw not implement std::error::Error to avoid accidental suppression, thanks to @kjvalencik (#334)
  • Fixed a bug causing unnecessary rebuilds, thanks to @kjvalencik (#343)
  • Fixed a soundness bug in the Task API, thanks to @kjvalencik (#335)

Version 0.1.23

Version 0.1.22

  • Reinstate JsInteger (although it's deprecated) for now, to be removed in 0.2. (#279)

Version 0.1.21

Version 0.1.20

  • Background task API (#214).
  • Fixes to Windows builds (#221, #227), thanks to @hone's tenacious troubleshooting.

Version 0.1.19

Version 0.1.18

Version 0.1.17

Version 0.1.16

Version 0.1.15 (2017-05-21)

  • Better Electron support in CLI's build process.
  • Better support for Electron via the artifacts file (neon-bindings/neon-cli#52).

Version 0.1.14 (2017-04-02)

  • Ensure failing tests break the build (#191)
  • Catch Rust panics and convert them to JS exceptions (#192)
  • Implement Error for Throw (#201)
  • Clean up the CLI and allow neon build to optionally take module names (neon-bindings/neon-cli#48).

Version 0.1.13 (2017-02-17)

  • More robust build scripts for neon-runtime, fixing Homebrew node installations (see #189)

Version 0.1.12 (2017-02-16)

Version 0.1.11 (2016-08-08)

Version 0.1.10 (2016-05-11)

Incompatible Changes

  • The JsTypeError type is gone, and replaced by the more general JsError type.
  • neon::js::error::JsTypeError::throw(msg) is now neon::js::error::JsError::throw(neon::js::error::kind::TypeError, msg)