Next Generation N-API
Download as PPTX, PDF0 likes599 views
The document outlines a hands-on workshop focused on the next generation of the Node.js N-API, aimed at familiarizing participants with its functionalities, tools, and processes for developing native add-ons. It covers the motivations for adopting N-API, provides comparisons with alternative methods, and details recent updates and improvements made in the past year. Additional resources, project organization tips, and opportunities for individual projects are also provided to support attendees in their learning journey.
Next Generation N-API
- 1. Next Generation N-API A hands-on workshop N-API Team
- 2. Works at Intel Involved with the API working group - Technical Steering Committee (TSC) member - Promises - Exception handling - Environment propagation - Module loading - Wrap/Unwrap - Thread-safe function Gabriel Schulhof @gabrielschulhof gabriel.schulhof@intel.com About Gabriel Schulhof
- 3. IBM Community Lead for Node.js Active Node.js community member - Technical Steering Committee (TSC) member - Community Committee member - n-api, build, security, benchmarking, diagnostics, release, user-feedback, teams and WGs. Michael Dawson @mhdawson1 @mhdawson About Michael Dawson
- 4. President of inspiredware Member of the N-API Team - node-pre-gyp - Prebuild - Documentation Jim Schlight @inspiredware @jschlight About Jim Schlight
- 5. Developer at Packly Member of the N-API Team Nicola Del Gobbo @NickNaso @NickNaso About Nicola Del Gobbo
- 6. Anna Henningsen @addaleax Gabriel Schulhof @gabrielschulhof Hitesh Kanwathirtha @digitalinfinity Jim Schlight @jschlight Michael Dawson @mhdawson Nicola Del Gobbo @NickNaso Kevin Eady @KevinEady Arunesh Chandra @aruneshchandra Taylor Wall @boingoing Anisha Rohra @anisha-rohra Kyle Farnung @kfarnung And many others ... Contributors
- 8. Orientation to N-API Awareness of available tools and processes A good start on your own projects
- 10. 1. Introduction to N-API and node-addon-api 2. Online tutorials 3. Let’s port some modules/individual projects 4. Wrap-up and assessment
- 11. What is a native addon?
- 12. What is a native addon? Node.js addons are dynamically-linked shared objects, written in C or C++, that can be loaded into Node.js using therequire() function, and used just as if they were an ordinaryNode.js module They are used primarily to provide an interface between JavaScript running in Node.js and C/C++ libraries
- 13. What is a native addon?
- 15. Motivations for N-API The API to implement native add-ons has been changed across different version of Node.js Most of the changes were on V8 API and ObjectWrap API and other node internals About 30% of modules depend on a native add-on. A breakage on a native addon could become very important e.g. node-sass
- 16. Motivations for N-API Need an adapter to stay compatible across different versions of Node.js NAN - Native Abstraction for Node.js - API compatibility - Strongly bonded with V8 API - You have to recompile your native add-ons when switching to a different version of Node.js
- 17. Motivations for N-API End user Maintainers
- 18. What’s N-API
- 19. What’s N-API ◎ Abstraction of the underlying JavaScript engine ◎ Defines and exports C types and functions that are independent from the JavaScript engine ◎ A binary-stable ABI
- 20. What’s N-API
- 21. Without N-API Addon Node.js: 6.12.2 V8: 5.1.281 NODE_MODULE_VERSION: 48
- 22. Node.js: 8.9.3 V8: 6.1.534 NODE_MODULE_VERSION: 57 Without N-API ● ABI break ○ At worst, mysterious segfaults ○ At best, addon fails to load ○ NODE_MODULE_VERSION mismatch
- 23. Node.js: no matter V8/ChakraCore: no matter NAPI_VERSION: 1 With N-API
- 24. Node.js: later V8/ChakraCore: no matter NAPI_VERSION: 2 With N-API ● No ABI break ○ NAPI_VERSION is cumulative ○ Addon is forwards compatible
- 27. Context Awareness Cleanup ◎ Unload DSO (one per process) ◎ Unload addon instance data - napi_add_env_cleanup_hook() – N-API 5 - napi_set_instance_data() – experimental ◎ Clean up leftover references created with - napi_wrap() - napi_add_finalizer() – N-API 5 - napi_buffer_create_external() - et. al. GC will not free them! Need to track them and explicitly free them!
- 28. A brief history of N-API
- 29. A brief history of N-API
- 31. N-API and node-addon-api ◎ N-API is C whereas node-addon-api is C++ ◎ node-addon-api not technically part of ABI stable API - Helper to simplify code using C++ - All inline - Only depends on export N-API C functions npm install node-addon-api About 300k downloads / week
- 34. Node-addon-api Versus NAN ◎ Same - Includes a C++ wrapper - Provides common helper functionality - Reduces likelihood of needing to change code for new Node.js versions ◎ Different - Does not use V8 Types - Not tied to a specific JavaScript engine - Preserves compile once/run multiple versions from N-API - Reduces even further likelihood of having to change code
- 35. What happened in the last year core - node-addon-api - tools
- 36. What happened in the last year (core) ◎ N-API 4 - Added thread-safe function ◎ N-API 5 - Added API to manage date object - Finalizer callback (marked as stable) - Optional callback in thread-safe function - Added reference cleanup
- 37. What happened in the last year (node-addon-api) ◎ Improved documentation ◎ Added new asynchronous API - Napi::AsyncContext ◎ Added thread-safe function - Napi::ThreadsafeFunction ◎ Improved AsyncWorker API - See: https://github.com/nodejs/node-addon-api/issues/231 ◎ Added AsyncProgressWorker API - Napi::AsyncProgressWorker ◎ Added API to manage date object - Napi::Date
- 38. What happened in the last year (tools) ◎ Added support for prebuild - A command line tool for easily making prebuilt binaries - https://www.npmjs.com/package/prebuild#n-api-considerations ◎ Added support for cmake-js - Build tool that uses CMake to build the native add-on instead of GYP - https://www.npmjs.com/package/cmake-js#n-api-and-node-addon- api
- 39. How to organize your project
- 40. How to organize your project ◎ build folder contains the intermediary and final build products. ◎ lib folder contains the the JavaScript code that will use the native code to export some features ◎ src folder contains the native C / C++ code ◎ test folder contains the testing code ◎ binding.gyp file that contains all settings to build the native add-on ◎ package.json npm description of your module ◎ package-lock.json used by npm to ensure deployment consistency
- 42. What’s binding.gyp By default Node.js use GYP to build the native add-on(s). Native add-ons are built using node-gyp, a cross platform CLI tool written in Node.js that contains a fork of GYP. GYP https://gyp.gsrc.io node-gyp https://github.com/nodejs/node- gyp There are other build tools like cmake-js
- 43. Add a badge to your project
- 44. Add a badge to your project ◎ Simply add a URL to the top of your README file ◎ Indicates the minimum N-API version your addon supports ◎ Benefits - Identifies your addon as supporting N-API - Makes your addon easier to find ◎ N-API v3 is a good starting point because this is the first version considered as stable API
- 45. Add a badge to your project https://img.shields.io/badge/N--API-v3-green.svg https://img.shields.io/badge/N--API-v4-green.svg https://img.shields.io/badge/N--API-v5-green.svg https://img.shields.io/badge/N--API-experimental- orange.svg
- 46. Online Tutorials
- 47. Online Tutorials ◎ For starting a new add-on module from scratch - napi.inspiredware.com/getting-started/first.html ◎ For starting a new add-on module from scratch with ObjectWrap - napi.inspiredware.com/getting-started/objectwrap.html ◎ For migrating an existing NAN module - napi.inspiredware.com/getting-started/migration.html ◎ Async Worker - napi.inspiredware.com/special-topics/asyncworker.html ◎ Node pre-gyp - napi.inspiredware.com/special-topics/node-pre-gyp.html
- 48. Online Tutorials ◎ Prebuild - napi.inspiredware.com/build-tools/prebuild.html ◎ CMake.js - napi.inspiredware.com/build-tools/cmake-js.html ◎ Thread-Safe Functions - napi.inspiredware.com/special-topics/thread-safe-functions.html ◎ Context awareness - napi.inspiredware.com/special-topics/context-awareness.html
- 49. Opportunity to work on individual projects
- 50. Opportunity to work on individual projects Workshop presenters available for help and questions N-API Tutorial http://bit.ly/2P7HfdK List of add-ons to port http://bit.ly/2P80VxT
- 52. Supporting resources ◎ N-API Documentation - https://nodejs.org/api/n-api.html — The C API - https://github.com/nodejs/node-addon-api — The C++ wrapper ◎ N-API migration assistant - https://github.com/nodejs/node-addon-api/blob/master/doc/conversion-tool.md ◎ Generator - https://www.npmjs.com/package/generator-napi-module ◎ Examples - https://github.com/nodejs/node-addon-examples/ ◎ Node-pre-gyp Documentation - https://github.com/mapbox/node-pre-gyp
- 53. Supporting resources ◎ Prebuild - https://www.npmjs.com/package/prebuild ◎ Prebuildify - https://www.npmjs.com/package/prebuildify ◎ CMake.js - https://www.npmjs.com/package/cmake-js ◎ Other N-API bindings: - Neon https://github.com/neon-bindings/neon (Rust) ◎ Genepi(Automatic generation of N-API wrapper from a C++ library ) - https://github.com/Geode-solutions/genepi
- 54. Wrap-up and assessment ◎ What did you like/not like - Workshop - N-API ◎ Get Involved: - https://github.com/nodejs/abi-stable-node - https://github.com/nodejs/node - https://github.com/nodejs/node-addon-api - Weekly N-API meeting - Monday 08:00 AM Pacific Time (PT)