Merge pull request #53 from mischov/chore/rustler-precompilation

Precompile NIFs

Author: mischov

.github/workflows/tests.yml renamed to .github/workflows/ci.yml

@@ -1,49 +1,58 @@
-name: tests
+name: CI
 
-on: [push, pull_request]
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: ["**"]
 
 jobs:
-  check-elixir-formatting:
-    name: Check Elixir formatting
+  check-formatting:
+    name: Check formatting
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
+
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: rustfmt
 
       - name: Set up Elixir
         uses: erlef/setup-beam@v1
         with:
-          otp-version: '25.0'
-          elixir-version: '1.14.0'
+          otp-version: 25.0
+          elixir-version: 1.14.0
 
-      - name: Check formatting
+      - name: Check Rust formatting
+        working-directory: native/meeseeks_html5ever_nif
+        run: cargo fmt --all -- --check
+
+      - name: Check Elixir formatting
         run: mix format --check-formatted
 
+
   test-elixir:
-    name: Test with OTP ${{ matrix.otp }} and Elixir ${{ matrix.elixir }}
-    # TODO change this to ubuntu-latest after OTP 23 is deprecated, see
-    # https://github.com/erlef/setup-beam#compatibility-between-operating-system-and-erlangotp
-    # for compatibility
-    runs-on: ubuntu-20.04
+    name: Test Elixir ${{ matrix.elixir }} / OTP ${{ matrix.otp }}
 
     env:
       MIX_ENV: test
+      MEESEEKS_HTML5EVER_BUILD: "1"
 
     strategy:
       fail-fast: false
       matrix:
         include:
-          - otp: '23.0'
-            elixir: '1.12.0'
-          - otp: '23.0'
-            elixir: '1.14.3'
-          - otp: '24.0'
-            elixir: '1.12.0'
-          - otp: '24.0'
-            elixir: '1.14.3'
-          - otp: '25.0'
-            elixir: '1.13.4'
-          - otp: '25.0'
-            elixir: '1.14.3'
+          - elixir: 1.12.0
+            otp: 23.0
+          - elixir: 1.13.0
+            otp: 24.0
+          - elixir: 1.14.0
+            otp: 25.0
+
+    # TODO change this to ubuntu-latest after OTP 23 is deprecated, see
+    # https://github.com/erlef/setup-beam#compatibility-between-operating-system-and-erlangotp
+    # for compatibility
+    runs-on: ubuntu-20.04
 
     steps:
       - uses: actions/checkout@v3
@@ -58,36 +67,40 @@ jobs:
           elixir-version: ${{ matrix.elixir }}
 
       - name: Retrieve cached Rust dependencies
-        uses: actions/cache@v2
+        uses: actions/cache@v3
         id: cargo-cache
         with:
           path: ~/.cargo
           key: ${{ runner.os }}-${{ matrix.otp }}-${{ matrix.elixir }}-cargo-${{ hashFiles(format('{0}{1}', github.workspace, '/mix.lock')) }}
           restore-keys: |
              ${{ runner.os }}-${{ matrix.otp }}-${{ matrix.elixir }}-cargo-
+
       - name: Retrieve cached Elixir dependencies
-        uses: actions/cache@v2
+        uses: actions/cache@v3
         id: mix-cache
         with:
           path: deps
           key: ${{ runner.os }}-${{ matrix.otp }}-${{ matrix.elixir }}-mix-${{ hashFiles(format('{0}{1}', github.workspace, '/mix.lock')) }}
           restore-keys: |
             ${{ runner.os }}-${{ matrix.otp }}-${{ matrix.elixir }}-mix-
+
       - name: Retrieve cached Elixir build
-        uses: actions/cache@v2
+        uses: actions/cache@v3
         id: build-cache
         with:
           path: _build
           key: ${{ runner.os }}-${{ matrix.otp }}-${{ matrix.elixir }}-build-${{ github.sha }}
           restore-keys: |
             ${{ runner.os }}-${{ matrix.otp }}-${{ matrix.elixir }}-build-
+
       - name: Install Elixir dependencies
         if: steps.mix-cache.outputs.cache-hit != 'true'
         run: |
           mix local.rebar --force
           mix local.hex --force
           mix deps.get
           mix deps.compile
+
       - name: Compile Elixir
         run: mix compile
 

.github/workflows/release.yml

@@ -0,0 +1,77 @@
+name: Release
+
+on:
+  push:
+    branches:
+      # Run for pushes to main
+      - main
+    paths:
+      # If files in "native/" change
+      - "native/**"
+      # Or if this file changes
+      - ".github/workflows/release.yml"
+    tags:
+      # Or run for any tag
+      - "**"
+
+jobs:
+  precompile_nifs:
+    name: Precompile NIF ${{ matrix.nif }} - ${{ matrix.job.target }} (${{ matrix.job.os }})
+
+    strategy:
+      fail-fast: false
+      matrix:
+        nif: ["2.15", "2.16"]
+        job:
+          - { target: arm-unknown-linux-gnueabihf , os: ubuntu-20.04 , use-cross: true }
+          - { target: aarch64-unknown-linux-gnu   , os: ubuntu-20.04 , use-cross: true }
+          - { target: aarch64-unknown-linux-musl  , os: ubuntu-20.04 , use-cross: true }
+          - { target: aarch64-apple-darwin        , os: macos-11      }
+          - { target: riscv64gc-unknown-linux-gnu , os: ubuntu-20.04 , use-cross: true }
+          - { target: x86_64-apple-darwin         , os: macos-11      }
+          - { target: x86_64-unknown-linux-gnu    , os: ubuntu-20.04  }
+          - { target: x86_64-unknown-linux-musl   , os: ubuntu-20.04 , use-cross: true }
+          - { target: x86_64-pc-windows-gnu       , os: windows-2019  }
+          - { target: x86_64-pc-windows-msvc      , os: windows-2019  }
+
+    runs-on: ${{ matrix.job.os }}
+
+    steps:
+      - name: Checkout source code
+        uses: actions/checkout@v3
+
+      - name: Extract project version
+        shell: bash
+        run: |
+          # Get the project version from mix.exs
+          echo "PROJECT_VERSION=$(sed -n 's/^  @version "\(.*\)"/\1/p' mix.exs | head -n1)" >> $GITHUB_ENV
+
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          toolchain: stable
+          target: ${{ matrix.job.target }}
+
+      - name: Build the project
+        id: build-crate
+        uses: philss/rustler-precompiled-action@v1.0.0
+        with:
+          project-name: meeseeks_html5ever_nif
+          project-version: ${{ env.PROJECT_VERSION }}
+          target: ${{ matrix.job.target }}
+          nif-version: ${{ matrix.nif }}
+          use-cross: ${{ matrix.job.use-cross }}
+          project-dir: "native/meeseeks_html5ever_nif"
+
+      - name: Artifact upload
+        uses: actions/upload-artifact@v3
+        with:
+          name: ${{ steps.build-crate.outputs.file-name }}
+          path: ${{ steps.build-crate.outputs.file-path }}
+
+      - name: Publish archives and packages
+        uses: softprops/action-gh-release@v1
+        with:
+          files: |
+            ${{ steps.build-crate.outputs.file-path }}
+        if: startsWith(github.ref, 'refs/tags/')

.gitignore

@@ -22,3 +22,6 @@ erl_crash.dump
 /priv/native
 
 /native/*/target
+
+# The checksum files for precompiled NIFs
+checksum-*.exs

CHANGELOG.md

@@ -6,12 +6,13 @@
 
   * No longer support Elixir versions under 1.12 or Erlang/OTP versions under 23.0
   * Support Elixir 1.13 and 1.14 and Erlang/OTP 25.0
-  * Use Rustler v0.27
 
 ### Enhancements
 
   * Use Rust 2018 edition
-  * Update to latest versions of `html5ever`, `xml5ever`, and `rustler`
+  * Update to Rustler `v0.27`
+  * Update to latest versions of Html5ever and Xml5ever
+  * Use `rustler_precompiled` to precompile NIFs
 
 ### Fixes
 

README.md

@@ -9,10 +9,6 @@ Originally a fork of Hansihe's [html5ever_elixir](https://github.com/hansihe/htm
 
 Meeseeks_Html5ever requires a minimum combination of Elixir 1.12.0 and Erlang/OTP 23.0, and is tested with a maximum combination of Elixir 1.14.0 and Erlang/OTP 25.0.
 
-## Dependencies
-
-Meeseeks_Html5ever depends on the Rust library [html5ever](https://github.com/servo/html5ever), and you will need to have the Rust compiler [installed](https://www.rust-lang.org/en-US/install.html).
-
 ## Installation
 
 Ensure Rust is installed, then add Meeseeks_Html5ever to your `mix.exs`:
@@ -27,6 +23,29 @@ end
 
 Finally, run `mix deps.get`.
 
+## Dependencies
+
+Meeseeks_Html5ever depends on the Rust library [html5ever](https://github.com/servo/html5ever), providing a Rustler-based NIF to interface with it.
+
+You do not need to have Rust installed because the library will attempt to download a precompiled NIF file.
+
+To force compilation you can either set the `MEESEEKS_HTML5EVER_BUILD` environment variable to `true` or `1`, or add the following application configuration
+
+```elixir
+config :meeseeks_html5ever, MeeseeksHtml5ever, build_from_source: true
+```
+
+If you want to force compilation you will need to have the Rust compiler [installed](https://www.rust-lang.org/en-US/install.html), and will need to add Rustler to your dependencies.
+
+```elixir
+def deps do
+  [
+    {:meeseeks_html5ever, "~> 0.13.1"},
+    {:rustler, ">= 0.0.0", optional: true}
+  ]
+end
+```
+
 ## Contributing
 
 If you are interested in contributing please read the [contribution guidelines](CONTRIBUTING.md).

RELEASE_CHECKLIST.md

@@ -0,0 +1,20 @@
+# Release checklist
+
+In order to release a new version to Hex.pm we first need to:
+
+1. Write the changes in the `CHANGELOG.md` file
+1. Create a release branch named `release/<version>`
+1. Update the `README.md`, `CHANGELOG.md`, `mix.exs`, and `Cargo.toml` with the new version
+1. Commit with message `Release <version>`
+1. Merge PR to `main`
+1. Tag main with `git tag <version>`
+1. Push tag with `git push origin <version>`
+1. Wait for the CI to build all release files
+1. Run `mix rustler.download MeeseeksHtml5ever.Native --all --print`
+1. Copy the output of the mix task and add to the release notes
+1. Run `mix hex.publish` and **make sure the checksum file is present**
+in the list of files to be published.
+
+It's important to ensure that we publish the checksum file with the
+package because otherwise the users won't be able to use the lib
+with precompiled files. They will need to always enforce compilation.

config/config.exs

@@ -3,6 +3,20 @@ defmodule MeeseeksHtml5ever do
   MeeseeksHtml5ever is intended for internal use by
   [Meeseeks](https://github.com/mischov/meeseeks), and parses HTML or XML into
   a `Meeseeks.Document`.
+
+  By default this lib will try to use a precompiled NIF from the GitHub
+  releases page. This way you don't need to have the Rust toolchain installed.
+  In case no precompiled file is found and the Mix env is production then an
+  error is raised.
+
+  You can force the compilation to occur by setting the value of the
+  `MEESEEKS_HTML5EVER_BUILD` environment variable to "true" or "1".
+  Alternatively you can also set the application env `:build_from_source` to
+  `true` in order to force the build:
+
+  ```
+  config :meeseeks_html5ever, MeeseeksHtml5ever, build_from_source: true
+  ```
   """
 
   @doc """

lib/meeseeks_html5ever.ex

@@ -1,19 +1,23 @@
 defmodule MeeseeksHtml5ever.Native do
   @moduledoc false
 
-  use Rustler, otp_app: :meeseeks_html5ever, crate: :meeseeks_html5ever_nif
+  mix_config = Mix.Project.config()
+  version = mix_config[:version]
+  github_url = mix_config[:package][:links]["GitHub"]
+  env_config = Application.compile_env(:meeseeks_html5ever, MeeseeksHtml5ever, [])
 
-  defmodule NifNotLoadedError do
-    @moduledoc false
-
-    defexception message: "nif not loaded"
-  end
+  use RustlerPrecompiled,
+    otp_app: :meeseeks_html5ever,
+    crate: "meeseeks_html5ever_nif",
+    mode: :release,
+    base_url: "#{github_url}/releases/download/v#{version}",
+    force_build:
+      System.get_env("MEESEEKS_HTML5EVER_BUILD") in ["1", "true"] or
+        env_config[:build_from_source],
+    version: version
 
   def parse_html(_binary), do: err()
-
   def parse_xml(_binary), do: err()
 
-  defp err() do
-    :erlang.nif_error(%NifNotLoadedError{})
-  end
+  defp err(), do: :erlang.nif_error(:nif_not_loaded)
 end