node gyp что это
Разработка нативных расширений для Node.js
В этом материале мы поговорим о важнейших концепциях разработки нативных расширений для Node.js. В частности, здесь будет рассмотрен практический пример создания такого расширения, который вполне может стать вашим первым проектом в этой области.
Основы разработки нативных расширений для Node.js
Если в двух словах рассказать о нативных расширениях для Node.js, можно отметить, что они представляют собой некую логику, реализованную на C++, которую можно вызывать из JavaScript-кода. Здесь стоит прояснить особенности работы Node.js и рассмотреть составные части этой платформы. Важно знать, что, в контексте Node.js, мы можем говорить о двух языках — JavaScript и C++. Всё это можно описать так:
Взаимодействие с нативными расширениями из JS-кода
Понимая этот механизм, мы можем сделать первые шаги в разработке нативных расширений. Но, прежде чем заняться программированием, поговорим об инструментах.
Базовые инструменты
▍Файл binding.gyp
Этот файл позволяет настраивать параметры компиляции нативных расширений. Один из важнейших моментов, которые нам надо определить, заключается в том, какие файлы будут компилироваться, и в том, как мы будем вызывать готовую библиотеку. Структура этого файла напоминает JSON, он содержит настройки цели (target) и исходников (sources) для компиляции.
▍Инструмент node-gyp
▍Инструмент node-bindings
▍API n-api
N-api — это API, созданное средствами C, которое позволяет взаимодействовать с движком абстрактным способом, не зависящим от нижележащей среды исполнения. На наш взгляд, такой подход является результатом развития платформы, в ходе которого предпринимались усилия по портированию Node.js на различные архитектуры.
N-api даёт стабильность и совместимость при работе с различными версиями Node.js. Таким образом, если некое нативное расширение было скомпилировано для Node 8.1, не потребуется компилировать его снова для Node 8.6 или 9.3. Это упрощает жизнь тем, кто занимается поддержкой расширения или участвует в его разработке.
В данный момент n-api находится в экспериментальном состоянии.
▍Инструмент node-addon-api
Модуль node-addon-api даёт в распоряжение разработчика C++-реализацию n-api, которая позволят пользоваться возможностями этого языка.
Первые шаги в мире нативных расширений
Обратите внимание на то, что для этого примера использована платформа Node 9.3.
Для того, чтобы приступить к разработке нативных расширений, мы напишем классическое приложение «Hello World». Идея этого приложения позволяет реализовать его с помощью достаточно простого кода, не перегруженного дополнительной логикой, что даст нам возможность сосредоточиться на основных конструкциях, рассмотреть минимально необходимый код.
Начнём с инициализации npm, что позволит затем установить зависимости.
Теперь устанавливаем зависимости.
На данном этапе нужно создать файл на C++, содержащий логику расширения.
В этом файле имеется три важных части, которые мы рассмотрим, начиная с той, которая находится в нижней части текста.
А вот как выглядит JavaScript-код, в котором подключается расширение и осуществляется работа с ним.
Теперь осталось лишь скомпилировать расширение и запустить JS-файл. Вот как это выглядит.
Компиляция и использование нативного расширения
История нативных расширений для Node.js и полезные материалы
Полагаем, полезно рассказать об истории нативных расширений, так как изучение этого вопроса позволяет исследовать большой объём полезной документации и обнаружить множество примеров. N-api пришло на смену nan. Эта аббревиатура расшифровывается как Native Abstraction for Node.js. Nan — это C++-библиотека, которая не отличается той же гибкостью, что и n-api. Она позволяет, в абстрактном виде, работать с V8, но привязана к релизу V8. В результате, в новых релизах Node.js могут присутствовать изменения V8, которые способны нарушить работу нативных расширений. Решение этой проблемы — одна из причин появления n-api.
Знание о существовании nan позволяет нам исследовать соответствующие примеры и документацию. Всё это может стать полезным источником знаний для тех, кто изучает разработку нативных расширений для Node.js.
Вот список полезных материалов, посвящённых разработке нативных расширений для Node:
Node gyp что это
node-gyp is a cross-platform command-line tool written in Node.js for compiling native addon modules for Node.js. It contains a vendored copy of the gyp-next project that was previously used by the Chromium team, extended to support the development of Node.js native addons.
Note that node-gyp is not used to build Node.js itself.
You can install node-gyp using npm :
Depending on your operating system, you will need to install:
ATTENTION: If your Mac has been upgraded to macOS Catalina (10.15), please read macOS_Catalina.md.
Install the current version of Python from the Microsoft Store package.
Install tools and configuration manually:
If the above steps didn’t work for you, please visit Microsoft’s Node.js Guidelines for Windows for additional tips.
To target native ARM64 Node.js on Windows 10 on ARM, add the components «Visual C++ compilers and libraries for ARM64» and «Visual C++ ATL for ARM64».
Configuring Python Dependency
node-gyp requires that you have installed a compatible version of Python, one of: v3.6, v3.7, v3.8, or v3.9. If you have multiple Python versions installed, you can identify which Python version node-gyp should use in one of the following ways:
If the PYTHON environment variable is set to the path of a Python executable, then that version will be used, if it is a compatible version.
If the NODE_GYP_FORCE_PYTHON environment variable is set to the path of a Python executable, it will be used instead of any of the other configured or builtin Python search paths. If it’s not a compatible version, no further searching will be done.
Build for Third Party Node.js Runtimes
To compile your native addon, first go to its root directory:
The next step is to generate the appropriate project build files for the current platform. Use configure for that:
Note: The configure step looks for a binding.gyp file in the current directory to process. See below for instructions on creating a binding.gyp file.
Now you will have either a Makefile (on Unix platforms) or a vcxproj file (on Windows) in the build/ directory. Next, invoke the build command:
The binding.gyp file
A barebones gyp file appropriate for building a Node.js addon could look like:
The docs directory contains additional documentation on specific node-gyp topics that may be useful if you are experiencing problems installing or building addons using node-gyp.
Some additional resources for Node.js native addons and writing gyp configuration files:
node-gyp responds to the following commands:
node-gyp accepts the following command options:
Use the form npm_config_OPTION_NAME for any of the command options listed above (dashes in option names should be replaced by underscores).
Or this on Windows:
Use the form OPTION_NAME for any of the command options listed above.
node-gyp is available under the MIT license. See the LICENSE file for details.
node-gyp is a cross-platform command-line tool written in Node.js for compiling native addon modules for Node.js. It contains a vendored copy of the gyp-next project that was previously used by the Chromium team, extended to support the development of Node.js native addons.
Note that node-gyp is not used to build Node.js itself.
Features
Installation
You can install node-gyp using npm :
Depending on your operating system, you will need to install:
On Unix
On macOS
ATTENTION: If your Mac has been upgraded to macOS Catalina (10.15), please read macOS_Catalina.md.
On Windows
Install the current version of Python from the Microsoft Store package.
Install tools and configuration manually:
If the above steps didn’t work for you, please visit Microsoft’s Node.js Guidelines for Windows for additional tips.
To target native ARM64 Node.js on Windows 10 on ARM, add the components «Visual C++ compilers and libraries for ARM64» and «Visual C++ ATL for ARM64».
Configuring Python Dependency
node-gyp requires that you have installed a compatible version of Python, one of: v3.6, v3.7, v3.8, or v3.9. If you have multiple Python versions installed, you can identify which Python version node-gyp should use in one of the following ways:
If the PYTHON environment variable is set to the path of a Python executable, then that version will be used, if it is a compatible version.
If the NODE_GYP_FORCE_PYTHON environment variable is set to the path of a Python executable, it will be used instead of any of the other configured or builtin Python search paths. If it’s not a compatible version, no further searching will be done.
Build for Third Party Node.js Runtimes
How to Use
To compile your native addon, first go to its root directory:
The next step is to generate the appropriate project build files for the current platform. Use configure for that:
Note: The configure step looks for a binding.gyp file in the current directory to process. See below for instructions on creating a binding.gyp file.
Now you will have either a Makefile (on Unix platforms) or a vcxproj file (on Windows) in the build/ directory. Next, invoke the build command:
The binding.gyp file
A barebones gyp file appropriate for building a Node.js addon could look like:
Further reading
The docs directory contains additional documentation on specific node-gyp topics that may be useful if you are experiencing problems installing or building addons using node-gyp.
Some additional resources for Node.js native addons and writing gyp configuration files:
Commands
node-gyp responds to the following commands:
Command Options
node-gyp accepts the following command options:
Configuration
Environment variables
Use the form npm_config_OPTION_NAME for any of the command options listed above (dashes in option names should be replaced by underscores).
Or this on Windows:
npm configuration
Use the form OPTION_NAME for any of the command options listed above.
License
node-gyp is available under the MIT license. See the LICENSE file for details.
Node gyp что это
Node.js native addon build tool
You can install with npm :
You will also need to install:
Install tools and configuration manually:
If the above steps didn’t work for you, please visit Microsoft’s Node.js Guidelines for Windows for additional tips.
If you have multiple Python versions installed, you can identify which Python version node-gyp uses by setting the ‘—python’ variable:
If node-gyp is called by way of npm and you have multiple versions of Python installed, then you can set npm ‘s ‘python’ config key to the appropriate value:
To compile your native addon, first go to its root directory:
The next step is to generate the appropriate project build files for the current platform. Use configure for that:
Note: The configure step looks for the binding.gyp file in the current directory to process. See below for instructions on creating the binding.gyp file.
Now you will have either a Makefile (on Unix platforms) or a vcxproj file (on Windows) in the build/ directory. Next invoke the build command:
The «binding.gyp» file
Previously when node had node-waf you had to write a wscript file. The replacement for that is the binding.gyp file, which describes the configuration to build your module in a JSON-like format. This file gets placed in the root of your package, alongside the package.json file.
A barebones gyp file appropriate for building a node addon looks like:
Some additional resources for addons and writing gyp files:
node-gyp responds to the following commands:
node-gyp accepts the following command options:
/.node-gyp)
node-gyp responds to environment variables or npm configuration
Copyright (c) 2012 Nathan Rajlich
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the ‘Software’), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED ‘AS IS’, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Дополнения C++¶
Дополнения являются динамически связанными общими объектами, написанными на C++. В require() функция может загружать аддоны как обычные модули Node.js. Аддоны обеспечивают интерфейс между библиотеками JavaScript и C/C++.
Есть три варианта реализации надстроек: Node-API, nan или прямое использование внутренних библиотек V8, libuv и Node.js. Если нет необходимости в прямом доступе к функциям, которые не предоставляются Node-API, используйте Node-API. Ссылаться на Аддоны C/C++ с Node-API для получения дополнительной информации о Node-API.
Когда Node-API не используется, реализация дополнений усложняется и требует знания нескольких компонентов и API:
V8: библиотека C ++, которую Node.js использует для реализации JavaScript. V8 предоставляет механизмы для создания объектов, вызова функций и т. Д. API V8 документирован в основном в v8.h заголовочный файл ( deps/v8/include/v8.h в дереве исходного кода Node.js), который также доступен онлайн.
libuv: Библиотека C, которая реализует цикл событий Node.js, его рабочие потоки и все асинхронное поведение платформы. Он также служит библиотекой кросс-платформенной абстракции, предоставляя простой POSIX-подобный доступ во всех основных операционных системах ко многим общим системным задачам, таким как взаимодействие с файловой системой, сокетами, таймерами и системными событиями. libuv также предоставляет абстракцию потоков, аналогичную потокам POSIX, для более сложных асинхронных надстроек, которые должны выходить за рамки стандартного цикла обработки событий. Авторам аддонов следует избегать блокировки цикла событий с помощью ввода-вывода или других задач, требующих больших затрат времени, путем разгрузки работы через libuv на неблокирующие системные операции, рабочие потоки или пользовательское использование потоков libuv.
Внутренние библиотеки Node.js. Сам Node.js экспортирует C ++ API, которые могут использовать надстройки, наиболее важным из которых является node::ObjectWrap класс.
Node.js включает другие статически связанные библиотеки, включая OpenSSL. Эти другие библиотеки расположены в deps/ в дереве исходных кодов Node.js. Только символы libuv, OpenSSL, V8 и zlib целенаправленно реэкспортируются с помощью Node.js и могут использоваться в различной степени аддонами. Видеть Связывание с библиотеками, включенными в Node.js для дополнительной информации.
Все следующие примеры доступны для скачать и может использоваться как отправная точка для дополнения.
Привет, мир¶
Этот пример «Hello world» представляет собой простое дополнение, написанное на C ++, которое является эквивалентом следующего кода JavaScript:
Сначала создайте файл hello.cc :
Все надстройки Node.js должны экспортировать функцию инициализации по шаблону:
Нет точки с запятой после NODE_MODULE так как это не функция (см. node.h ).
Контекстно-зависимые надстройки¶
Следующие три переменные могут использоваться внутри тела функции после вызова NODE_MODULE_INIT() :
Выбор в пользу создания надстройки с учетом контекста влечет за собой ответственность за тщательное управление глобальными статическими данными. Поскольку надстройка может загружаться несколько раз, потенциально даже из разных потоков, любые глобальные статические данные, хранящиеся в надстройке, должны быть должным образом защищены и не должны содержать никаких постоянных ссылок на объекты JavaScript. Причина этого в том, что объекты JavaScript действительны только в одном контексте и, вероятно, вызовут сбой при доступе из неправильного контекста или из другого потока, чем тот, в котором они были созданы.
Контекстно-зависимый аддон можно структурировать так, чтобы избежать глобальных статических данных, выполнив следующие шаги:
Это гарантирует, что данные для каждого экземпляра надстройки достигнут каждой привязки, которая может быть вызвана из JavaScript. Данные для каждого экземпляра надстройки также должны передаваться в любые асинхронные обратные вызовы, которые надстройка может создать.
В следующем примере показана реализация надстройки с учетом контекста:
Поддержка рабочих¶
Для загрузки из нескольких сред Node.js, таких как основной поток и рабочий поток, надстройка должна:
Чтобы поддержать Worker потоков, аддонам необходимо очистить все ресурсы, которые они могли выделить, когда такой поток существует. Это может быть достигнуто за счет использования AddEnvironmentCleanupHook() функция:
При необходимости есть дополнительная пара AddEnvironmentCleanupHook() а также RemoveEnvironmentCleanupHook() перегрузки, где обработчик очистки принимает функцию обратного вызова. Это можно использовать для отключения асинхронных ресурсов, таких как любые дескрипторы libuv, зарегистрированные надстройкой.
Следующий addon.cc использует AddEnvironmentCleanupHook :
Протестируйте в JavaScript, запустив:
Строительство¶
После того, как исходный код был написан, он должен быть скомпилирован в двоичный файл. addon.node файл. Для этого создайте файл с именем binding.gyp на верхнем уровне проекта, описывающем конфигурацию сборки модуля в формате, подобном JSON. Этот файл используется узел-гипс, инструмент, написанный специально для компиляции надстроек Node.js.
Однажды binding.gyp файл был создан, используйте node-gyp configure для создания соответствующих файлов сборки проекта для текущей платформы. Это сгенерирует либо Makefile (на платформах Unix) или vcxproj файл (в Windows) в build/ каталог.
Затем вызовите node-gyp build команда для генерации скомпилированного addon.node файл. Это будет помещено в build/Release/ каталог.
Когда используешь npm install для установки надстройки Node.js npm использует собственную версию node-gyp для выполнения того же набора действий, генерируя скомпилированную версию аддона для платформы пользователя по запросу.
После сборки бинарный аддон можно использовать из Node.js, указав require() к построенному addon.node модуль:
В то время как bindings реализация пакета более сложна в том, как он находит дополнительные модули, по сути, он использует try…catch шаблон похож на:
Связывание с библиотеками, включенными в Node.js¶
Node.js использует статически связанные библиотеки, такие как V8, libuv и OpenSSL. Все дополнения должны быть связаны с V8 и могут также связываться с любыми другими зависимостями. Обычно это так же просто, как включение соответствующих #include заявления (например, #include ) а также node-gyp автоматически найдет соответствующие заголовки. Однако следует помнить о нескольких предостережениях:
Когда node-gyp запускается, он обнаружит конкретную версию выпуска Node.js и загрузит либо полный архив исходных текстов, либо только заголовки. Если загружен полный исходный код, надстройки будут иметь полный доступ к полному набору зависимостей Node.js. Однако, если загружены только заголовки Node.js, то будут доступны только символы, экспортированные с помощью Node.js.
Загрузка дополнений с помощью require() ¶
Нативные абстракции для Node.js¶
Каждый из примеров, проиллюстрированных в этом документе, напрямую использует API-интерфейсы Node.js и V8 для реализации надстроек. API V8 может и претерпел кардинальные изменения от одного выпуска V8 к другому (и от одного основного выпуска Node.js к другому). При каждом изменении может потребоваться обновление и перекомпиляция надстроек, чтобы они продолжали работать. График выпуска Node.js разработан таким образом, чтобы минимизировать частоту и влияние таких изменений, но Node.js мало что может сделать для обеспечения стабильности API V8.
В Нативные абстракции для Node.js (или nan ) предоставляют набор инструментов, которые разработчикам аддонов рекомендуется использовать для обеспечения совместимости между прошлыми и будущими выпусками V8 и Node.js. Увидеть nan Примеры для иллюстрации того, как его можно использовать.
Узел-API¶
Создание и поддержка аддона, который выигрывает от стабильности ABI, обеспечиваемой Node-API, несет с собой определенные соображения по реализации.
Чтобы использовать Node-API в приведенном выше примере «Hello world», замените содержимое hello.cc со следующим. Все остальные инструкции остаются прежними.
Доступные функции и способы их использования описаны в Аддоны C / C ++ с Node-API.
Примеры аддонов¶
Ниже приведены несколько примеров надстроек, призванных помочь разработчикам начать работу. В примерах используются API V8. Обратитесь к онлайн Ссылка на V8 для помощи с различными вызовами V8 и V8 Руководство по встраиванию для объяснения нескольких используемых понятий, таких как ручки, области действия, шаблоны функций и т. д.
В каждом из этих примеров используются следующие binding.gyp файл:
Однажды binding.gyp файл готов, примеры дополнений могут быть настроены и собраны с помощью node-gyp :
Аргументы функции¶
Аддоны обычно предоставляют объекты и функции, к которым можно получить доступ из JavaScript, запущенного в Node.js. Когда функции вызываются из JavaScript, входные аргументы и возвращаемое значение должны отображаться в код C / C ++ и из него.
В следующем примере показано, как читать аргументы функции, переданные из JavaScript, и как вернуть результат:
После компиляции пример надстройки может потребоваться и использоваться из Node.js:
Обратные вызовы¶
В надстройках обычной практикой является передача функций JavaScript в функцию C ++ и их выполнение оттуда. В следующем примере показано, как вызывать такие обратные вызовы:
Чтобы проверить это, запустите следующий JavaScript:
В этом примере функция обратного вызова вызывается синхронно.
Фабрика объектов¶
Аддоны могут создавать и возвращать новые объекты из функции C ++, как показано в следующем примере. Объект создается и возвращается со свойством msg который перекликается со строкой, переданной в createObject() :
Чтобы проверить это в JavaScript:
Фабрика функций¶
Упаковка объектов C ++¶
Также можно обернуть объекты / классы C ++ таким образом, чтобы можно было создавать новые экземпляры с помощью JavaScript. new оператор:
Чтобы построить этот пример, myobject.cc файл необходимо добавить в binding.gyp :
Проверьте это с помощью:
Деструктор для объекта-оболочки будет запущен, когда объект будет собран сборщиком мусора. Для тестирования деструктора есть флаги командной строки, которые можно использовать, чтобы сделать возможным принудительную сборку мусора. Эти флаги предоставляются базовым механизмом JavaScript V8. Они могут быть изменены или удалены в любое время. Они не документируются в Node.js или V8, и их никогда не следует использовать вне тестирования.
Во время завершения работы процесса или рабочих потоков деструкторы не вызываются движком JS. Поэтому ответственность за отслеживание этих объектов и обеспечение их надлежащего уничтожения во избежание утечки ресурсов лежит на пользователе.
Фабрика упакованных предметов¶
В качестве альтернативы можно использовать шаблон фабрики, чтобы избежать явного создания экземпляров объекта с помощью JavaScript. new оператор:
Во-первых, createObject() метод реализован в addon.cc :
Реализация в myobject.cc аналогичен предыдущему примеру:
Еще раз, чтобы построить этот пример, myobject.cc файл необходимо добавить в binding.gyp :
Проверьте это с помощью: