summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
Diffstat
-rw-r--r--documentation/dev-manual/dev-manual-common-tasks.xml289
-rw-r--r--documentation/dev-manual/figures/cute-files-npm-example.pngbin0 -> 26248 bytes
2 files changed, 289 insertions, 0 deletions
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 @@
8979 <listitem><para> 8979 <listitem><para>
8980 <link linkend='testing-packages-with-ptest'>Setting up and running package test (ptest)</link> 8980 <link linkend='testing-packages-with-ptest'>Setting up and running package test (ptest)</link>
8981 </para></listitem> 8981 </para></listitem>
8982 <listitem><para>
8983 <link linkend='creating-node-package-manager-npm-packages'>Creating Node Package Manager (NPM) Packages</link>
8984 </para></listitem>
8982 </itemizedlist> 8985 </itemizedlist>
8983 </para> 8986 </para>
8984 8987
@@ -10407,6 +10410,292 @@
10407 </para> 10410 </para>
10408 </section> 10411 </section>
10409 </section> 10412 </section>
10413
10414 <section id='creating-node-package-manager-npm-packages'>
10415 <title>Creating Node Package Manager (NPM) Packages</title>
10416
10417 <para>
10418 <ulink url='https://en.wikipedia.org/wiki/Npm_(software)'>NPM</ulink>
10419 is a package manager for the JavaScript programming
10420 language.
10421 The Yocto Project supports the NPM
10422 <ulink url='&YOCTO_DOCS_BB_URL;#bb-fetchers'>fetcher</ulink>.
10423 You can use this fetcher in combination with
10424 <ulink url='&YOCTO_DOCS_REF_URL;#ref-devtool-reference'><filename>devtool</filename></ulink>
10425 to create recipes that produce NPM packages.
10426 </para>
10427
10428 <para>
10429 Two workflows exist that allow you to create NPM packages
10430 using <filename>devtool</filename>: the NPM registry modules
10431 method and the NPM project code method.
10432 <note>
10433 While it is possible to create NPM recipes manually,
10434 using <filename>devtool</filename> is far simpler.
10435 </note>
10436 Additionally, some requirements and caveats exist.
10437 </para>
10438
10439 <section id='npm-package-creation-requirements'>
10440 <title>Requirements and Caveats</title>
10441
10442 <para>
10443 You need to be aware of the following before using
10444 <filename>devtool</filename> to create NPM packages:
10445 <itemizedlist>
10446 <listitem><para>
10447 Of the two methods that you can use
10448 <filename>devtool</filename> to create NPM
10449 packages, the registry approach is slightly
10450 simpler.
10451 However, you might consider the project
10452 approach because you do not have to publish
10453 your module in the NPM registry
10454 (<ulink url='https://docs.npmjs.com/misc/registry'><filename>npm-registry</filename></ulink>),
10455 which is NPM's public registry.
10456 </para></listitem>
10457 <listitem><para>
10458 Be familiar with
10459 <ulink url='&YOCTO_DOCS_REF_URL;#ref-devtool-reference'><filename>devtool</filename></ulink>.
10460 </para></listitem>
10461 <listitem><para>
10462 The NPM host tools need the native
10463 <filename>nodejs-npm</filename> package, which
10464 is part of the OpenEmbedded environment.
10465 You need to get the package by cloning the
10466 <ulink url='https://github.com/openembedded/meta-openembedded'></ulink>
10467 repository out of GitHub.
10468 Be sure to add the path to your local copy to
10469 your <filename>bblayers.conf</filename> file.
10470 </para></listitem>
10471 <listitem><para>
10472 <filename>devtool</filename> cannot detect
10473 native libraries in module dependencies.
10474 Consequently, you must manually add packages
10475 to your recipe.
10476 </para></listitem>
10477 <listitem><para>
10478 While deploying NPM packages,
10479 <filename>devtool</filename> cannot determine
10480 which dependent packages are missing on the
10481 target (e.g. the node runtime
10482 <filename>nodejs</filename>).
10483 Consequently, you need to find out what
10484 files are missing and be sure they are on the
10485 target.
10486 </para></listitem>
10487 <listitem><para>
10488 Although you might not need NPM to run your
10489 node package, it is useful to have NPM on your
10490 target.
10491 The NPM package name is
10492 <filename>nodejs-npm</filename>.
10493 </para></listitem>
10494 </itemizedlist>
10495 </para>
10496 </section>
10497
10498 <section id='npm-using-the-registry-modules-method'>
10499 <title>Using the Registry Modules Method</title>
10500
10501 <para>
10502 This section presents an example that uses the
10503 <filename>cute-files</filename> module, which is a
10504 file browser web application.
10505 <note>
10506 You must know the <filename>cute-files</filename>
10507 module version.
10508 </note>
10509 </para>
10510
10511 <para>
10512 The first thing you need to do is use
10513 <filename>devtool</filename> and the NPM fetcher to
10514 create the recipe:
10515 <literallayout class='monospaced'>
10516 $ devtool add "npm://registry.npmjs.org;name=cute-files;version=1.0.2"
10517 </literallayout>
10518 The <filename>devtool add</filename> command runs
10519 <filename>recipetool create</filename> and uses the
10520 same fetch URI to download each dependency and capture
10521 license details where possible.
10522 The result is a generated recipe.
10523 </para>
10524
10525 <para>
10526 The recipe file is fairly simple and contains every
10527 license that <filename>recipetool</filename> finds
10528 and includes the licenses in the recipe's
10529 <ulink url='&YOCTO_DOCS_REF_URL;#var-LIC_FILES_CHKSUM'><filename>LIC_FILES_CHKSUM</filename></ulink>
10530 variables.
10531 You need to examine the variables and look for those
10532 with "unknown" in the
10533 <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE'><filename>LICENSE</filename></ulink>
10534 field.
10535 You need to track down the license information for
10536 "unknown" modules and manually add the information to the
10537 recipe.
10538 </para>
10539
10540 <para>
10541 <filename>recipetool</filename> creates "shrinkwrap" and
10542 "lockdown" files for your recipe.
10543 Shrinkwrap files capture the version of all dependent
10544 modules.
10545 Many packages do not provide shrinkwrap files.
10546 <filename>recipetool</filename> create a shrinkwrap
10547 file as it runs.
10548 You can replace the shrinkwrap file with your own file
10549 by setting the <filename>NPM_SHRINKWRAP</filename>
10550 variable.
10551 </para>
10552
10553 <para>
10554 Lockdown files contain the checksum for each module
10555 to determine if your users download the same files when
10556 building with a recipe.
10557 Lockdown files ensure that dependencies have not been
10558 changed and that your NPM registry is still providing
10559 the same file.
10560 <note>
10561 A package is created for each sub-module.
10562 This policy is the only practical way to have the
10563 licenses for all of the dependencies represented
10564 in the license manifest of the image.
10565 </note>
10566 </para>
10567
10568 <para>
10569 The <filename>devtool edit-recipe</filename> command
10570 lets you take a look at the recipe:
10571 <literallayout class='monospaced'>
10572 $ devtool edit-recipe cute-files
10573 SUMMARY = "Turn any folder on your computer into a cute file browser, available on the local network."
10574 LICENSE = "BSD-3-Clause &amp; Unknown &amp; MIT &amp; ISC"
10575 LIC_FILES_CHKSUM = "file://LICENSE;md5=71d98c0a1db42956787b1909c74a86ca \
10576 file://node_modules/content-disposition/LICENSE;md5=c6e0ce1e688c5ff16db06b7259e9cd20 \
10577 file://node_modules/express/LICENSE;md5=5513c00a5c36cd361da863dd9aa8875d \
10578 ...
10579
10580 SRC_URI = "npm://registry.npmjs.org;name=cute-files;version=${PV}"
10581 NPM_SHRINKWRAP := "${THISDIR}/${PN}/npm-shrinkwrap.json"
10582 NPM_LOCKDOWN := "${THISDIR}/${PN}/lockdown.json"
10583 inherit npm
10584 # Must be set after inherit npm since that itself sets S
10585 S = "${WORKDIR}/npmpkg"
10586
10587 LICENSE_${PN}-content-disposition = "MIT"
10588 ...
10589 LICENSE_${PN}-express = "MIT"
10590 LICENSE_${PN} = "MIT"
10591 </literallayout>
10592 Three key points exist in the previous example:
10593 <itemizedlist>
10594 <listitem><para>
10595 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
10596 uses the NPM scheme so that the NPM fetcher
10597 is used.
10598 </para></listitem>
10599 <listitem><para>
10600 <filename>recipetool</filename> collects all
10601 the license information.
10602 If a sub-module's license is unavailable,
10603 the sub-module's name appears in the comments.
10604 </para></listitem>
10605 <listitem><para>
10606 The <filename>inherit npm</filename> statement
10607 causes the
10608 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-npm'><filename>npm</filename></ulink>
10609 class to package up all the modules.
10610 </para></listitem>
10611 </itemizedlist>
10612 </para>
10613
10614 <para>
10615 You can run the following command to build the
10616 <filename>cute-files</filename> package:
10617 <literallayout class='monospaced'>
10618 $ devtool build cute-files
10619 </literallayout>
10620 Remember that <filename>nodejs</filename> must be
10621 installed on the target before your package.
10622 </para>
10623
10624 <para>
10625 Assuming 192.168.7.2 for the target's IP address, use
10626 the following command to deploy your package:
10627 <literallayout class='monospaced'>
10628 $ devtool deploy-target -s cute-files root@192.168.7.2
10629 </literallayout>
10630 Once the package is installed on the target, you can
10631 test the application:
10632 <note>
10633 Because of a know issue, you cannot simply run
10634 <filename>cute-files</filename> as you would if you
10635 had run <filename>npm install</filename>.
10636 </note>
10637 <literallayout class='monospaced'>
10638 $ cd /usr/lib/node_modules/cute-files
10639 $ node cute-files.js
10640 </literallayout>
10641 On a browser, go to
10642 <filename>http://192.168.7.2:3000</filename> and you
10643 see the following:
10644 <imagedata fileref="figures/cute-files-npm-example.png" align="center" width="6in" depth="4in" />
10645 </para>
10646
10647 <para>
10648 You can find the recipe in
10649 <filename>workspace/recipes/cute-files</filename>.
10650 You can use the recipe in any layer you choose.
10651 </para>
10652 </section>
10653
10654 <section id='npm-using-the-npm-projects-method'>
10655 <title>Using the NPM Projects Code Method</title>
10656
10657 <para>
10658 Although it is useful to package modules already in the
10659 NPM registry, adding <filename>node.js</filename> projects
10660 under development is a more common developer use case.
10661 </para>
10662
10663 <para>
10664 This section covers the NPM projects code method, which is
10665 very similar to the "registry" approach described in the
10666 previous section.
10667 In the NPM projects method, you provide
10668 <filename>devtool</filename> with an URL that points to the
10669 source files.
10670 </para>
10671
10672 <para>
10673 Replicating the same example, (i.e.
10674 <filename>cute-files</filename>) use the following command:
10675 <literallayout class='monospaced'>
10676 $ devtool add https://github.com/martinaglv/cute-files.git
10677 </literallayout>
10678 The recipe this command generates is very similar to the
10679 recipe created in the previous section.
10680 However, the <filename>SRC_URI</filename> looks like the
10681 following:
10682 <literallayout class='monospaced'>
10683 SRC_URI = "git://github.com/martinaglv/cute-files.git;protocol=https \
10684 npm://registry.npmjs.org;name=commander;version=2.9.0;subdir=node_modules/commander \
10685 npm://registry.npmjs.org;name=express;version=4.14.0;subdir=node_modules/express \
10686 npm://registry.npmjs.org;name=content-disposition;version=0.3.0;subdir=node_modules/content-disposition \
10687 "
10688 </literallayout>
10689 In this example, the main module is taken from the Git
10690 repository and dependents are taken from the NPM registry.
10691 Other than those differences, the recipe is basically the
10692 same between the two methods.
10693 You can build and deploy the package exactly as described
10694 in the previous section that uses the registry modules
10695 method.
10696 </para>
10697 </section>
10698 </section>
10410 </section> 10699 </section>
10411 10700
10412 <section id='efficiently-fetching-source-files-during-a-build'> 10701 <section id='efficiently-fetching-source-files-during-a-build'>
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
--- /dev/null
+++ b/documentation/dev-manual/figures/cute-files-npm-example.png
Binary files differ
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2025-12-07 19:46:53 +0000