[PATCH v2] doc: bitbake-user-manual: document npm and npmsw fetchers

[PATCH v2] doc: bitbake-user-manual: document npm and npmsw fetchers

[michael.opdenacker]

From: Michael Opdenacker <michael.opdenacker@bootlin.com>

This addresses bug [YOCTO #10098]

Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>

---

* Changes in V2:

  - Fix typos in the names of explicit targets ("nmp" instead of "npm")
  - Simplify the reference to the "nmpsw" section:
    no need to use a complex reference when you can directly use
    a target ("`target`_" as defined in ".. _target:")
---
 .../bitbake-user-manual-fetching.rst          | 76 ++++++++++++++++++-
 1 file changed, 74 insertions(+), 2 deletions(-)

diff --git a/doc/bitbake-user-manual/bitbake-user-manual-fetching.rst b/doc/bitbake-user-manual/bitbake-user-manual-fetching.rst
index f9d9e617..bb521f63 100644
--- a/doc/bitbake-user-manual/bitbake-user-manual-fetching.rst
+++ b/doc/bitbake-user-manual/bitbake-user-manual-fetching.rst
@@ -704,6 +704,80 @@ Here is an example URL::
 
    SRC_URI = "crate://crates.io/glob/0.2.11"
 
+.. _npm-fetcher:
+
+NPM Fetcher (``npm://``)
+------------------------
+
+This submodule fetches source code from an
+`NPM <https://en.wikipedia.org/wiki/Npm_(software)>`__
+Javascript package registry.
+
+The format for the :term:`SRC_URI` setting must be::
+
+   SRC_URI = "npm://some.registry.url;OptionA=xxx;OptionB=xxx;..."
+
+This fetcher supports the following parameters:
+
+-  *"package":* The NPM package name. This is a mandatory parameter.
+
+-  *"version":* The NPM package version. This is a mandatory parameter.
+
+-  *"downloadfilename":* Specifies the filename used when storing the downloaded file.
+
+-  *"destsuffix":* Specifies the directory to use to unpack the package (default: ``npm``).
+
+Note that NPM fetcher only fetches the package source itself. The dependencies
+can be fetched through the `npmsw-fetcher`_.
+
+Here is an example URL with both fetchers::
+
+   SRC_URI = " \
+       npm://registry.npmjs.org/;package=cute-files;version=${PV} \
+       npmsw://${THISDIR}/${BPN}/npm-shrinkwrap.json \
+       "
+
+See :yocto_docs:`Creating Node Package Manager (NPM) Packages
+</dev-manual/common-tasks.html#creating-node-package-manager-npm-packages>`
+in the Yocto Project manual for details about using
+:yocto_docs:`devtool <https://docs.yoctoproject.org/ref-manual/devtool-reference.html>`
+to automatically create a recipe from an NPM URL.
+
+.. _npmsw-fetcher:
+
+NPM shrinkwrap Fetcher (``npmsw://``)
+-------------------------------------
+
+This modules fetches source code from an
+`NPM shrinkwrap <https://docs.npmjs.com/cli/v8/commands/npm-shrinkwrap>`__
+description file, which lists the dependencies
+of an NPM package while locking their versions.
+
+The format for the :term:`SRC_URI` setting must be::
+
+   SRC_URI = "npmsw://some.registry.url;OptionA=xxx;OptionB=xxx;..."
+
+This fetcher supports the following parameters:
+
+-  *"dev":* Set this parameter to ``1`` to install "devDependencies".
+
+-  *"destsuffix":* Specifies the directory to use to unpack the dependencies
+   (``${S}`` by default).
+
+Note that the shrinkwrap file can also be provided by the recipe for
+the package which has such dependencies, for example::
+
+   SRC_URI = " \
+       npm://registry.npmjs.org/;package=cute-files;version=${PV} \
+       npmsw://${THISDIR}/${BPN}/npm-shrinkwrap.json \
+       "
+
+Such a file can be automatically be generated using
+:yocto_docs:`devtool <https://docs.yoctoproject.org/ref-manual/devtool-reference.html>`
+as described in the :yocto_docs:`Creating Node Package Manager (NPM) Packages
+</dev-manual/common-tasks.html#creating-node-package-manager-npm-packages>`
+section of the Yocto Project.
+
 Other Fetchers
 --------------
 
@@ -713,8 +787,6 @@ Fetch submodules also exist for the following:
 
 -  Mercurial (``hg://``)
 
--  npm (``npm://``)
-
 -  OSC (``osc://``)
 
 -  Secure FTP (``sftp://``)
-- 
2.34.1

Re: [bitbake-devel] [PATCH v2] doc: bitbake-user-manual: document npm and npmsw fetchers

[Ulrich Ölmann]

Hi Michael,

just some typo fixes I stumbled across.

On Tue, Jun 21 2022 at 19:54 +0200, "Michael Opdenacker via lists.openembedded.org" <michael.opdenacker=bootlin.com@lists.openembedded.org> wrote:
> From: Michael Opdenacker <michael.opdenacker@bootlin.com>
>
> This addresses bug [YOCTO #10098]
>
> Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
>
> ---
>
> * Changes in V2:
>
>   - Fix typos in the names of explicit targets ("nmp" instead of "npm")
>   - Simplify the reference to the "nmpsw" section:
>     no need to use a complex reference when you can directly use
>     a target ("`target`_" as defined in ".. _target:")
> ---
>  .../bitbake-user-manual-fetching.rst          | 76 ++++++++++++++++++-
>  1 file changed, 74 insertions(+), 2 deletions(-)
>
> diff --git a/doc/bitbake-user-manual/bitbake-user-manual-fetching.rst b/doc/bitbake-user-manual/bitbake-user-manual-fetching.rst
> index f9d9e617..bb521f63 100644
> --- a/doc/bitbake-user-manual/bitbake-user-manual-fetching.rst
> +++ b/doc/bitbake-user-manual/bitbake-user-manual-fetching.rst
> @@ -704,6 +704,80 @@ Here is an example URL::
>  
>     SRC_URI = "crate://crates.io/glob/0.2.11"
>  
> +.. _npm-fetcher:
> +
> +NPM Fetcher (``npm://``)
> +------------------------
> +
> +This submodule fetches source code from an
> +`NPM <https://en.wikipedia.org/wiki/Npm_(software)>`__
> +Javascript package registry.
> +
> +The format for the :term:`SRC_URI` setting must be::
> +
> +   SRC_URI = "npm://some.registry.url;OptionA=xxx;OptionB=xxx;..."
> +
> +This fetcher supports the following parameters:
> +
> +-  *"package":* The NPM package name. This is a mandatory parameter.
> +
> +-  *"version":* The NPM package version. This is a mandatory parameter.
> +
> +-  *"downloadfilename":* Specifies the filename used when storing the downloaded file.
> +
> +-  *"destsuffix":* Specifies the directory to use to unpack the package (default: ``npm``).
> +
> +Note that NPM fetcher only fetches the package source itself. The dependencies
> +can be fetched through the `npmsw-fetcher`_.
> +
> +Here is an example URL with both fetchers::
> +
> +   SRC_URI = " \
> +       npm://registry.npmjs.org/;package=cute-files;version=${PV} \
> +       npmsw://${THISDIR}/${BPN}/npm-shrinkwrap.json \
> +       "
> +
> +See :yocto_docs:`Creating Node Package Manager (NPM) Packages
> +</dev-manual/common-tasks.html#creating-node-package-manager-npm-packages>`
> +in the Yocto Project manual for details about using
> +:yocto_docs:`devtool <https://docs.yoctoproject.org/ref-manual/devtool-reference.html>`
> +to automatically create a recipe from an NPM URL.
> +
> +.. _npmsw-fetcher:
> +
> +NPM shrinkwrap Fetcher (``npmsw://``)
> +-------------------------------------
> +
> +This modules fetches source code from an

s/This modules fetches/This module fetches/

> +`NPM shrinkwrap <https://docs.npmjs.com/cli/v8/commands/npm-shrinkwrap>`__
> +description file, which lists the dependencies
> +of an NPM package while locking their versions.
> +
> +The format for the :term:`SRC_URI` setting must be::
> +
> +   SRC_URI = "npmsw://some.registry.url;OptionA=xxx;OptionB=xxx;..."
> +
> +This fetcher supports the following parameters:
> +
> +-  *"dev":* Set this parameter to ``1`` to install "devDependencies".
> +
> +-  *"destsuffix":* Specifies the directory to use to unpack the dependencies
> +   (``${S}`` by default).
> +
> +Note that the shrinkwrap file can also be provided by the recipe for
> +the package which has such dependencies, for example::
> +
> +   SRC_URI = " \
> +       npm://registry.npmjs.org/;package=cute-files;version=${PV} \
> +       npmsw://${THISDIR}/${BPN}/npm-shrinkwrap.json \
> +       "
> +
> +Such a file can be automatically be generated using

s/can be automatically/can automatically/

Best regards
Ulrich


> +:yocto_docs:`devtool <https://docs.yoctoproject.org/ref-manual/devtool-reference.html>`
> +as described in the :yocto_docs:`Creating Node Package Manager (NPM) Packages
> +</dev-manual/common-tasks.html#creating-node-package-manager-npm-packages>`
> +section of the Yocto Project.
> +
>  Other Fetchers
>  --------------
>  
> @@ -713,8 +787,6 @@ Fetch submodules also exist for the following:
>  
>  -  Mercurial (``hg://``)
>  
> --  npm (``npm://``)
> -
>  -  OSC (``osc://``)
>  
>  -  Secure FTP (``sftp://``)
-- 
Pengutronix e.K.                           | Ulrich Ölmann               |
Industrial Linux Solutions                 | http://www.pengutronix.de/  |
Peiner Str. 6-8, 31137 Hildesheim, Germany | Phone: +49-5121-206917-0    |
Amtsgericht Hildesheim, HRA 2686           | Fax:   +49-5121-206917-5555 |