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