From 127b6b1c8c835d939bbcbe0c62d99703f14b2162 Mon Sep 17 00:00:00 2001 From: Philip Sampaio Date: Wed, 5 Jul 2023 18:19:46 -0300 Subject: [PATCH] Release v0.6.2 --- CHANGELOG.md | 15 ++++++++- PRECOMPILATION_GUIDE.md | 69 +++++++++++++++++++++++++++++++++++--- lib/rustler_precompiled.ex | 7 ++-- mix.exs | 2 +- 4 files changed, 84 insertions(+), 9 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index bc5c018..2e8f515 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.6.2] - 2023-07-05 + +### Added + +- Add support for FreeBSD as a target. + +### Changed + +- Remove `:crypto` from the extra applications list, because `:ssl` already includes it. + +- Update the guide to mention the new way to select a NIF version in Rustler >= 0.29. + ## [0.6.1] - 2023-02-16 ### Changed @@ -139,7 +151,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Add basic features to download and use the precompiled NIFs in a safe way. -[Unreleased]: https://github.com/philss/rustler_precompiled/compare/v0.6.1...HEAD +[Unreleased]: https://github.com/philss/rustler_precompiled/compare/v0.6.2...HEAD +[0.6.2]: https://github.com/philss/rustler_precompiled/compare/v0.6.1...v0.6.2 [0.6.1]: https://github.com/philss/rustler_precompiled/compare/v0.6.0...v0.6.1 [0.6.0]: https://github.com/philss/rustler_precompiled/compare/v0.5.5...v0.6.0 [0.5.5]: https://github.com/philss/rustler_precompiled/compare/v0.5.4...v0.5.5 diff --git a/PRECOMPILATION_GUIDE.md b/PRECOMPILATION_GUIDE.md index 3191dd7..f6e237d 100644 --- a/PRECOMPILATION_GUIDE.md +++ b/PRECOMPILATION_GUIDE.md @@ -32,8 +32,18 @@ repository. ### Configure Targets -Usually we want to build for the most popular targets and the three last NIF versions. NIF versions -are more stable than OTP versions because they only change after two major releases of OTP. +Usually we want to build for the most popular targets and the minimum NIF version supported. + +NIF versions are more stable than OTP versions because they usually change only after two major +releases of OTP. But older versions are compatible with newer versions if they have the same MAJOR +number. For example, the NIF `2.15` is compatible with `2.16` and `2.17`. So you only need to +compile for `2.15` if you want to support these versions. But in case any new feature from the +newer versions is needed, then you can build for both versions as well. + +In Rustler - starting from v0.29 -, it's possible to control which version of NIF is active by +configuring cargo features that have this format: `nif_version_MAJOR_MINOR`. So it's possible +to define features in your project that depends on Rustler features. +More details are in the "Additional configuration before build". For this guide our targets will be the following: @@ -94,8 +104,9 @@ lto = true In addition to that, we also use a tool called [`cross`](https://github.com/rust-embedded/cross) that makes the build easier for some targets (the ones using `use-cross: true` in our example). -We need to tell `cross` to read an environment variable from our "host machine", because `cross` uses -containers to build our software. +For projects using Rustler **before v0.29**, we need to tell `cross` to read an environment variable +from our "host machine", because `cross` uses containers to build our software. + So you need to create the file `Cross.toml` in the NIF directory with the following content: ```toml @@ -105,6 +116,56 @@ passthrough = [ ] ``` +#### Using features to control NIF version in Rustler v0.29 and above + +Since Rustler v0.29, it's possible to control which NIF version is active by using cargo features. +This is a replacement for the `RUSTLER_NIF_VERSION` env var, that is deprecated in v0.30 of +Rustler. + +If your project does not use anything special from newer NIF versions, then you can declare the +Rustler dependency like this: + +```toml +[dependencies] +rustler = { version = "0.29", default-features = false, features = ["derive", "nif_version_2_15"] } +``` + +And in the workflow file, you would specify the `nif-version: 2.15` as usual. + +But in case you want to have newer features from more recent versions of NIF, you can create +features for your project that are used to activate rustler features. These features should +follow the same naming from Rustler, because the CI action is going to use that to activate +the right feature. + +Here is an example of how your `Cargo.toml` would look like: + +```toml +[dependencies] +rustler = { version = "0.29", default-features = false, features = ["derive"] } + +# And then, your features. +[features] +default = ["nif_version_2_15"] +nif_version_2_15 = ["rustler/nif_version_2_15"] +nif_version_2_16 = ["rustler/nif_version_2_16"] +nif_version_2_17 = ["rustler/nif_version_2_17"] +``` + +In your code, you would use these features - like `nif_version_2_17` - to control how your +code is going to be compiled. You can hide some features behind these features. +Even if you don't have anything behind these features, you can still introduce them +if you want to activate an specific NIF version. + +But again, normally it's enough to build for the lowest version supported by the OTP version +that you are targeting. + +The available NIF versions are the following: + +* `2.14` - for OTP 21 and above. +* `2.15` - for OTP 22 and above. +* `2.16` - for OTP 24 and above. +* `2.17` - for OTP 26 and above. + ## The Rustler module We need to tell `RustlerPrecompiled` where to find our NIF files, and we need to tell which version to use. diff --git a/lib/rustler_precompiled.ex b/lib/rustler_precompiled.ex index 11925cd..e688bad 100644 --- a/lib/rustler_precompiled.ex +++ b/lib/rustler_precompiled.ex @@ -51,9 +51,10 @@ defmodule RustlerPrecompiled do available. A NIF version is usually compatible with two OTP minor versions, and an older NIF is usually compatible with newer OTPs. The available versions are the following: - * `2.14` - for OTP 21. - * `2.15` - for OTP 22 and 23. - * `2.16` - for OTP 24 and 25. + * `2.14` - for OTP 21 and above. + * `2.15` - for OTP 22 and above. + * `2.16` - for OTP 24 and above. + * `2.17` - for OTP 26 and above. By default the following NIF versions are configured: diff --git a/mix.exs b/mix.exs index c5f0d5e..9feac6b 100644 --- a/mix.exs +++ b/mix.exs @@ -1,7 +1,7 @@ defmodule RustlerPrecompiled.MixProject do use Mix.Project - @version "0.6.1" + @version "0.6.2" @repo "https://github.com/philss/rustler_precompiled" def project do