Merge pull request #184 from rage/node-bindings

Node.js bindings

Author: Heliozoa

.github/workflows/test.yml

@@ -2,9 +2,9 @@ name: Run tests
 
 on:
   push:
-    branches: [master, '[0-9]+.[0-9]+']
+    branches: [master, "[0-9]+.[0-9]+"]
   pull_request:
-    branches: [master, '[0-9]+.[0-9]+']
+    branches: [master, "[0-9]+.[0-9]+"]
 
 env:
   RUST_LOG: debug,j4rs=warn
@@ -14,6 +14,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v2
+      - uses: actions/setup-node@v2
+        with:
+          node-version: '16'
       - name: Install depedencies
         run: |
           sudo apt update -y
@@ -38,6 +41,9 @@ jobs:
     runs-on: windows-latest
     steps: # TODO: install missing dependencies and run all tests on windows
       - uses: actions/checkout@v2
+      - uses: actions/setup-node@v2
+        with:
+          node-version: '16'
       - uses: actions/setup-dotnet@v1
         with:
           dotnet-version: "5.0.x"
@@ -52,6 +58,9 @@ jobs:
     runs-on: macos-latest
     steps: # TODO: install missing dependencies and run all tests on macos
       - uses: actions/checkout@v2
+      - uses: actions/setup-node@v2
+        with:
+          node-version: '16'
       - uses: actions/setup-dotnet@v1
         with:
           dotnet-version: "5.0.x"

.github/workflows/upload-binaries.yml

@@ -16,6 +16,9 @@ jobs:
         target: [i686-unknown-linux-gnu, x86_64-unknown-linux-gnu]
     steps:
       - uses: actions/checkout@v2
+      - uses: actions/setup-node@v2
+        with:
+          node-version: '16'
       - uses: GoogleCloudPlatform/github-actions/setup-gcloud@master
         with:
           project_id: ${{ secrets.GCP_PROJECT_ID }}
@@ -24,12 +27,15 @@ jobs:
         run: |
           sudo apt update
           sudo apt install -y gcc-multilib # required to build for 32-bit arch
-      - name: Cargo build
+      - name: Build
         run: |
-          rustup target add i686-unknown-linux-gnu
+          rustup target add ${{ matrix.target }}
           cargo build -p tmc-langs-cli --release --verbose --target ${{ matrix.target }}
+          npm --prefix ./bindings/tmc-langs-node run build -- --release --verbose --target ${{ matrix.target }}
       - name: Deploy
-        run: gsutil cp target/${{ matrix.target }}/release/tmc-langs-cli gs://${{ secrets.GCP_BUCKET }}/tmc-langs-rust/tmc-langs-cli-${{ matrix.target }}-$TAG
+        run: |
+          gsutil cp target/${{ matrix.target }}/release/tmc-langs-cli gs://${{ secrets.GCP_BUCKET }}/tmc-langs-rust/tmc-langs-cli-${{ matrix.target }}-$TAG
+          gsutil cp bindings/tmc-langs-node/ts/functions.node         gs://${{ secrets.GCP_BUCKET }}/tmc-langs-rust/tmc-langs-${{ matrix.target }}-$TAG.node
 
   windows:
     runs-on: windows-latest
@@ -38,25 +44,33 @@ jobs:
         target: [i686-pc-windows-msvc, x86_64-pc-windows-msvc]
     steps:
       - uses: actions/checkout@v2
+      - uses: actions/setup-node@v2
+        with:
+          node-version: '16'
       - uses: GoogleCloudPlatform/github-actions/setup-gcloud@master
         with:
           project_id: ${{ secrets.GCP_PROJECT_ID }}
           service_account_key: ${{ secrets.GCP_SA_KEY }}
-      - name: Cargo build # crt-static is set with RUSTFLAGS to statically link MSVCRT (VCRUNTIME140.dll)
+      - name: Build # crt-static is set with RUSTFLAGS to statically link MSVCRT (VCRUNTIME140.dll)
         run: |
-          rustup target add i686-pc-windows-msvc
+          rustup target add ${{ matrix.target }}
           $env:RUSTFLAGS="-C target-feature=+crt-static"
           cargo build -p tmc-langs-cli --release --verbose --target ${{ matrix.target }}
+          npm run --prefix ./bindings/tmc-langs-node build -- --release --verbose --target ${{ matrix.target }}
       - name: Deploy
         run: |
           $env:python_version=$(python -c 'import sys; print(\".\".join(map(str, sys.version_info[:3])))')
           $env:CLOUDSDK_PYTHON="C:\hostedtoolcache\windows\Python\$env:python_version\x64\python"
           gsutil cp target/${{ matrix.target }}/release/tmc-langs-cli.exe gs://${{ secrets.GCP_BUCKET }}/tmc-langs-rust/tmc-langs-cli-${{ matrix.target }}-$Env:TAG.exe
+          gsutil cp bindings/tmc-langs-node/ts/functions.node             gs://${{ secrets.GCP_BUCKET }}/tmc-langs-rust/tmc-langs-${{ matrix.target }}-$Env:TAG.node
 
   macos:
     runs-on: macos-latest
     steps:
       - uses: actions/checkout@v2
+      - uses: actions/setup-node@v2
+        with:
+          node-version: '16'
       - uses: GoogleCloudPlatform/github-actions/setup-gcloud@master
         with:
           project_id: ${{ secrets.GCP_PROJECT_ID }}
@@ -66,7 +80,9 @@ jobs:
       - name: Sign
         run: codesign --force -s - target/release/tmc-langs-cli
       - name: Deploy
-        run: gsutil cp target/release/tmc-langs-cli gs://${{ secrets.GCP_BUCKET }}/tmc-langs-rust/tmc-langs-cli-x86_64-apple-darwin-$TAG
+        run: |
+          gsutil cp target/release/tmc-langs-cli              gs://${{ secrets.GCP_BUCKET }}/tmc-langs-rust/tmc-langs-cli-x86_64-apple-darwin-$TAG
+          gsutil cp bindings/tmc-langs-node/ts/functions.node gs://${{ secrets.GCP_BUCKET }}/tmc-langs-rust/tmc-langs-x86_64-apple-darwin-$TAG.node
 
   arm:
     runs-on: ubuntu-18.04
@@ -75,6 +91,9 @@ jobs:
         target: [aarch64-unknown-linux-gnu, armv7-unknown-linux-gnueabihf]
     steps:
       - uses: actions/checkout@v2
+      - uses: actions/setup-node@v2
+        with:
+          node-version: '16'
       - uses: GoogleCloudPlatform/github-actions/setup-gcloud@master
         with:
           project_id: ${{ secrets.GCP_PROJECT_ID }}
@@ -84,5 +103,8 @@ jobs:
           rustup target add ${{ matrix.target }}
           cargo install cross
           cross build -p tmc-langs-cli --release --verbose --target ${{ matrix.target }}
+          npm --prefix ./bindings/tmc-langs-node run cross --release --verbose --target ${{ matrix.target }}
       - name: Deploy
-        run: gsutil cp target/${{ matrix.target }}/release/tmc-langs-cli gs://${{ secrets.GCP_BUCKET }}/tmc-langs-rust/tmc-langs-cli-${{ matrix.target }}-$TAG
+        run: |
+          gsutil cp target/${{ matrix.target }}/release/tmc-langs-cli gs://${{ secrets.GCP_BUCKET }}/tmc-langs-rust/tmc-langs-cli-${{ matrix.target }}-$TAG
+          gsutil cp bindings/tmc-langs-node/ts/functions.node         gs://${{ secrets.GCP_BUCKET }}/tmc-langs-rust/tmc-langs-${{ matrix.target }}-$TAG.node

CONTRIBUTING.md

@@ -4,6 +4,8 @@ Install Rust according to https://www.rust-lang.org/tools/install
 
 Install [zstd](https://github.com/facebook/zstd). For example, on Ubuntu you need the package `libzstd1`. For Windows, download the appropriate archive from the [releases](https://github.com/facebook/zstd/releases), extract it and add the extracted directory to your PATH.
 
+Install [Node.js and npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm).
+
 ```bash
 git clone [email protected]:rage/tmc-langs-rust.git
 cd tmc-langs-rust
@@ -14,8 +16,13 @@ If you have any troubles building the project, please do make an issue!
 
 ## Testing
 
+To run tests for all included projects, run the `run-tests.sh` script.
+```bash
+bash run-tests.sh
+```
+To run tests for the Node.js bindings run
 ```bash
-cargo test
+npm --prefix bindings/tmc-langs-node/ run jest
 ```
 
 ## Formatting and linting

Cargo.toml

@@ -1,16 +1,25 @@
 [workspace]
 members =[
+    # core libraries
     "tmc-client",
     "tmc-langs",
     "tmc-langs-cli",
     "tmc-langs-framework",
     "tmc-langs-plugins",
     "tmc-langs-util",
 
+    # language plugins
     "plugins/csharp",
     "plugins/java",
     "plugins/make",
     "plugins/notests",
     "plugins/python3",
     "plugins/r",
+
+    # bindings to other languages
+    "bindings/tmc-langs-node",
+
+    # test helpers
+    "tmc-server-mock",
 ]
+resolver = "2"

README.md

@@ -4,7 +4,7 @@ TMC-langs provides an interface that encapsulates everything needed to support a
 
 ## Documentation
 
-Documentation for the latest release is available at https://rage.github.io/tmc-langs-rust
+Documentation for the latest release is available at https://rage.github.io/tmc-langs-rust. Documentation is automatically built and deployed when creating a GitHub release.
 
 Additional documentation for other aspects of TMC such as configuration file formats is included in the [docs](./docs) directory.
 
@@ -14,6 +14,10 @@ Additional documentation for other aspects of TMC such as configuration file for
 
 A "frontend" for tmc-langs. A binary CLI client for TMC-langs for IDEs. Intended to be used programmatically, for a CLI meant for manual use see [tmc-cli-rust](https://github.com/rage/tmc-cli-rust).
 
+### bindings/tmc-langs-node
+
+Bindings for using tmc-langs from Node.js.
+
 ### tmc-langs
 
 The "backend". A library that provides a convenient API for implementing different frontends. A frontend (such as a CLI) should only depend on this library. The other libraries are considered internal.
@@ -69,6 +73,7 @@ A TMC plugin for R.
 - Armv7 (armv7-unknown-linux-gnueabihf)
 
 ## Contributing
+
 See [CONTRIBUTING](CONTRIBUTING.md).
 
 ## License

bindings/tmc-langs-node/.gitignore

@@ -0,0 +1,5 @@
+ts/functions.node
+**/target
+**/node_modules
+**/.DS_Store
+npm-debug.log*

bindings/tmc-langs-node/Cargo.toml

@@ -0,0 +1,31 @@
+[package]
+name = "tmc-langs-node"
+version = "0.1.0"
+authors = ["University of Helsinki <[email protected]>", "Daniel Martinez <[email protected]>"]
+edition = "2018"
+license = "MIT OR Apache-2.0"
+exclude = ["index.node"]
+
+[lib]
+crate-type = ["cdylib"]
+
+[dependencies.neon]
+version = "0.8"
+default-features = false
+features = ["napi-6", "default-panic-hook"]
+
+[dependencies]
+tmc-langs = { path = "../../tmc-langs", features = ["ts"] }
+
+base64 = "0.13"
+env_logger = "0.8"
+serde = "1"
+serde_json = "1"
+thiserror = "1"
+ts-rs = { git = "https://github.com/Heliozoa/ts-rs/", branch = "ext" }
+
+[dev-dependencies]
+log = "0.4"
+once_cell = "1"
+simple_logger = "1"
+tmc-server-mock = { path = "../../tmc-server-mock" }

bindings/tmc-langs-node/README.md

@@ -0,0 +1,39 @@
+# tmc-langs-node
+
+Provides bindings to tmc-langs for Node.js. This project was bootstrapped by [create-neon](https://www.npmjs.com/package/create-neon).
+
+## TypeScript definitions
+
+You can find TypeScript files that can be used with the Node module in the `./ts` directory. `tmc.ts` is the main module which contains a `Tmc` class for using tmc-langs and re-exports the other modules. `generated.d.ts` contains type definitions for the relevant tmc-langs types like `ExercisePackagingConfiguration` and re-exported by `tmc.ts` as `langs`. `functions.d.ts` contains the types for the actual Node module and is wrapped by `tmc.ts`.
+
+## Installing tmc-langs-node
+
+Installing tmc-langs-node requires a [supported version of Node and Rust](https://github.com/neon-bindings/neon#platform-support).
+
+You can install the project with npm. In the project directory, run:
+
+```sh
+$ npm install
+```
+
+This fully installs the project, including installing any dependencies and running the build.
+
+## Building tmc-langs-node
+
+If you have already installed the project and only want to run the build, run:
+
+```sh
+$ npm run build
+```
+
+This command uses the [cargo-cp-artifact](https://github.com/neon-bindings/cargo-cp-artifact) utility to run the Rust build and copy the built library into `./ts/functions.node`.
+
+## Deployment
+
+Node modules for the supported targets are built and deployed to Google Cloud when creating a GitHub release. The binaries are available at https://download.mooc.fi/tmc-langs-rust/, with each binary following the file name format `tmc-langs-{target}-{version}.node`. For a list of targets see the README at the repository root. For example, The 64-bit Linux binary for version 0.5.0 is available at https://download.mooc.fi/tmc-langs-rust/tmc-langs-x86_64-unknown-linux-gnu-0.5.0.node.
+
+### Node module
+
+The Node addon—i.e., a binary Node module—generated by building the project. This is the main module for this package, as dictated by the `"main"` key in `package.json`.
+
+Under the hood, a [Node addon](https://nodejs.org/api/addons.html) is a [dynamically-linked shared object](https://en.wikipedia.org/wiki/Library_(computing)#Shared_libraries). The `"build"` script produces this file by copying it from within the `target/` directory, which is where the Rust build produces the shared object.

bindings/tmc-langs-node/babel.config.js

@@ -0,0 +1,6 @@
+module.exports = {
+  presets: [
+    ["@babel/preset-env", { targets: { node: "current" } }],
+    "@babel/preset-typescript",
+  ],
+};

bindings/tmc-langs-node/jest/maven-exercise/.classpath

@@ -0,0 +1,44 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<classpath>
+	<classpathentry kind="src" output="target/classes" path="src/main/java">
+		<attributes>
+			<attribute name="optional" value="true"/>
+			<attribute name="maven.pomderived" value="true"/>
+		</attributes>
+	</classpathentry>
+	<classpathentry kind="src" output="target/test-classes" path="src/test/java">
+		<attributes>
+			<attribute name="optional" value="true"/>
+			<attribute name="maven.pomderived" value="true"/>
+			<attribute name="test" value="true"/>
+		</attributes>
+	</classpathentry>
+	<classpathentry kind="con" path="org.eclipse.jdt.launching.JRE_CONTAINER/org.eclipse.jdt.internal.debug.ui.launcher.StandardVMType/JavaSE-1.6">
+		<attributes>
+			<attribute name="maven.pomderived" value="true"/>
+		</attributes>
+	</classpathentry>
+	<classpathentry kind="con" path="org.eclipse.m2e.MAVEN2_CLASSPATH_CONTAINER">
+		<attributes>
+			<attribute name="maven.pomderived" value="true"/>
+		</attributes>
+	</classpathentry>
+	<classpathentry kind="src" path="target/generated-sources/annotations">
+		<attributes>
+			<attribute name="optional" value="true"/>
+			<attribute name="maven.pomderived" value="true"/>
+			<attribute name="ignore_optional_problems" value="true"/>
+			<attribute name="m2e-apt" value="true"/>
+		</attributes>
+	</classpathentry>
+	<classpathentry kind="src" output="target/test-classes" path="target/generated-test-sources/test-annotations">
+		<attributes>
+			<attribute name="optional" value="true"/>
+			<attribute name="maven.pomderived" value="true"/>
+			<attribute name="ignore_optional_problems" value="true"/>
+			<attribute name="m2e-apt" value="true"/>
+			<attribute name="test" value="true"/>
+		</attributes>
+	</classpathentry>
+	<classpathentry kind="output" path="target/classes"/>
+</classpath>