diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml index b2a13ed87b..4f06aac976 100644 --- a/documentation/dev-manual/dev-manual-common-tasks.xml +++ b/documentation/dev-manual/dev-manual-common-tasks.xml @@ -8979,6 +8979,9 @@ Setting up and running package test (ptest) + + Creating Node Package Manager (NPM) Packages + @@ -10407,6 +10410,292 @@ + +
+ Creating Node Package Manager (NPM) Packages + + + NPM + is a package manager for the JavaScript programming + language. + The Yocto Project supports the NPM + fetcher. + You can use this fetcher in combination with + devtool + to create recipes that produce NPM packages. + + + + Two workflows exist that allow you to create NPM packages + using devtool: the NPM registry modules + method and the NPM project code method. + + While it is possible to create NPM recipes manually, + using devtool is far simpler. + + Additionally, some requirements and caveats exist. + + +
+ Requirements and Caveats + + + You need to be aware of the following before using + devtool to create NPM packages: + + + Of the two methods that you can use + devtool to create NPM + packages, the registry approach is slightly + simpler. + However, you might consider the project + approach because you do not have to publish + your module in the NPM registry + (npm-registry), + which is NPM's public registry. + + + Be familiar with + devtool. + + + The NPM host tools need the native + nodejs-npm package, which + is part of the OpenEmbedded environment. + You need to get the package by cloning the + + repository out of GitHub. + Be sure to add the path to your local copy to + your bblayers.conf file. + + + devtool cannot detect + native libraries in module dependencies. + Consequently, you must manually add packages + to your recipe. + + + While deploying NPM packages, + devtool cannot determine + which dependent packages are missing on the + target (e.g. the node runtime + nodejs). + Consequently, you need to find out what + files are missing and be sure they are on the + target. + + + Although you might not need NPM to run your + node package, it is useful to have NPM on your + target. + The NPM package name is + nodejs-npm. + + + +
+ +
+ Using the Registry Modules Method + + + This section presents an example that uses the + cute-files module, which is a + file browser web application. + + You must know the cute-files + module version. + + + + + The first thing you need to do is use + devtool and the NPM fetcher to + create the recipe: + + $ devtool add "npm://registry.npmjs.org;name=cute-files;version=1.0.2" + + The devtool add command runs + recipetool create and uses the + same fetch URI to download each dependency and capture + license details where possible. + The result is a generated recipe. + + + + The recipe file is fairly simple and contains every + license that recipetool finds + and includes the licenses in the recipe's + LIC_FILES_CHKSUM + variables. + You need to examine the variables and look for those + with "unknown" in the + LICENSE + field. + You need to track down the license information for + "unknown" modules and manually add the information to the + recipe. + + + + recipetool creates "shrinkwrap" and + "lockdown" files for your recipe. + Shrinkwrap files capture the version of all dependent + modules. + Many packages do not provide shrinkwrap files. + recipetool create a shrinkwrap + file as it runs. + You can replace the shrinkwrap file with your own file + by setting the NPM_SHRINKWRAP + variable. + + + + Lockdown files contain the checksum for each module + to determine if your users download the same files when + building with a recipe. + Lockdown files ensure that dependencies have not been + changed and that your NPM registry is still providing + the same file. + + A package is created for each sub-module. + This policy is the only practical way to have the + licenses for all of the dependencies represented + in the license manifest of the image. + + + + + The devtool edit-recipe command + lets you take a look at the recipe: + + $ devtool edit-recipe cute-files + SUMMARY = "Turn any folder on your computer into a cute file browser, available on the local network." + LICENSE = "BSD-3-Clause & Unknown & MIT & ISC" + LIC_FILES_CHKSUM = "file://LICENSE;md5=71d98c0a1db42956787b1909c74a86ca \ + file://node_modules/content-disposition/LICENSE;md5=c6e0ce1e688c5ff16db06b7259e9cd20 \ + file://node_modules/express/LICENSE;md5=5513c00a5c36cd361da863dd9aa8875d \ + ... + + SRC_URI = "npm://registry.npmjs.org;name=cute-files;version=${PV}" + NPM_SHRINKWRAP := "${THISDIR}/${PN}/npm-shrinkwrap.json" + NPM_LOCKDOWN := "${THISDIR}/${PN}/lockdown.json" + inherit npm + # Must be set after inherit npm since that itself sets S + S = "${WORKDIR}/npmpkg" + + LICENSE_${PN}-content-disposition = "MIT" + ... + LICENSE_${PN}-express = "MIT" + LICENSE_${PN} = "MIT" + + Three key points exist in the previous example: + + + SRC_URI + uses the NPM scheme so that the NPM fetcher + is used. + + + recipetool collects all + the license information. + If a sub-module's license is unavailable, + the sub-module's name appears in the comments. + + + The inherit npm statement + causes the + npm + class to package up all the modules. + + + + + + You can run the following command to build the + cute-files package: + + $ devtool build cute-files + + Remember that nodejs must be + installed on the target before your package. + + + + Assuming 192.168.7.2 for the target's IP address, use + the following command to deploy your package: + + $ devtool deploy-target -s cute-files root@192.168.7.2 + + Once the package is installed on the target, you can + test the application: + + Because of a know issue, you cannot simply run + cute-files as you would if you + had run npm install. + + + $ cd /usr/lib/node_modules/cute-files + $ node cute-files.js + + On a browser, go to + http://192.168.7.2:3000 and you + see the following: + + + + + You can find the recipe in + workspace/recipes/cute-files. + You can use the recipe in any layer you choose. + +
+ +
+ Using the NPM Projects Code Method + + + Although it is useful to package modules already in the + NPM registry, adding node.js projects + under development is a more common developer use case. + + + + This section covers the NPM projects code method, which is + very similar to the "registry" approach described in the + previous section. + In the NPM projects method, you provide + devtool with an URL that points to the + source files. + + + + Replicating the same example, (i.e. + cute-files) use the following command: + + $ devtool add https://github.com/martinaglv/cute-files.git + + The recipe this command generates is very similar to the + recipe created in the previous section. + However, the SRC_URI looks like the + following: + + SRC_URI = "git://github.com/martinaglv/cute-files.git;protocol=https \ + npm://registry.npmjs.org;name=commander;version=2.9.0;subdir=node_modules/commander \ + npm://registry.npmjs.org;name=express;version=4.14.0;subdir=node_modules/express \ + npm://registry.npmjs.org;name=content-disposition;version=0.3.0;subdir=node_modules/content-disposition \ + " + + In this example, the main module is taken from the Git + repository and dependents are taken from the NPM registry. + Other than those differences, the recipe is basically the + same between the two methods. + You can build and deploy the package exactly as described + in the previous section that uses the registry modules + method. + +
+
diff --git a/documentation/dev-manual/figures/cute-files-npm-example.png b/documentation/dev-manual/figures/cute-files-npm-example.png new file mode 100644 index 0000000000..1ebe74f535 Binary files /dev/null and b/documentation/dev-manual/figures/cute-files-npm-example.png differ