Bug 10098

Assigning to Brendan.  Can you come up with a short paragraph for Scott to add to the documentation please?

One tricky thing here is we will need to describe just the parts of the functionality that are implemented in bitbake. Of course as usual we can give examples from OE but for the most part it should stick to what's in bitbake itself.

This is where we could additionally do with some task-based documentation about how to add an npm module (to go in the dev manual or the "cookbook") which can cover everything including the functionality we have in devtool add / recipetool create specifically to support creating recipes for npm modules.

I'm building ON Brendan's article at https://wiki.yoctoproject.org/wiki/TipsAndTricks/NPM. This is not intended to be task orientated, Paul's idea for a Cookbook article will do that.

I am putting some design notes in here for the docs as this will be a little more complicated fix:

 * Update the "Fetching Code" section within the "Writing a New Recipe" section
   of the dev-manual - http://www.yoctoproject.org/docs/2.3/dev-manual/dev-manual.html#new-recipe-fetching-code.  We need to point to the BB
   manual at least to reference the section on fetchers.

 * I need to add the "npm" fetcher to the list of other fetchers that appear
   documented in the BB manual here - http://www.yoctoproject.org/docs/2.3/bitbake-user-manual/bitbake-user-manual.html#bb-fetchers.  I am putting 
   the "npm" fetcher in the list of "other" fetchers at the bottom.  The 
   focus will be more on how to use this within OE leaving a non-biased 
   BB mention pretty sparse.  I will likely just reference the appropriate
   sections in the YP mainstream docs.  Will probably note that the "npm"
   fetcher won't even work unless you have the node.js packages on your system.

 * Probably should also reference the BB fetcher section from this section in 
   the ref-manual - http://www.yoctoproject.org/docs/2.3/ref-manual/ref-manual.html#scms.

 * The section on the "npm.class" could use some more information.  At the 
   least it will point to wherever I get that wiki information incorporated
   into the YP docs.

 * Seems like the reference section for the "do_fetch" task needs some 
   attention - http://www.yoctoproject.org/docs/2.3/ref-manual/ref-manual.html#ref-tasks-fetch

 * The variable description for SRC_URI does not list "npm".  I need to add
   it here http://www.yoctoproject.org/docs/2.3/ref-manual/ref-manual.html#var-SRC_URI.  

 * Could add a note here http://www.yoctoproject.org/docs/2.3/sdk-manual/sdk-manual.html#sdk-devtool-use-devtool-upgrade-to-create-a-version-of-the-recipe-that-supports-a-newer-version-of-the-software to reference into the 
   fetcher section of the BB manual.

 * Work the wiki information from here https://wiki.yoctoproject.org/wiki/TipsAndTricks/NPM into the YP docs?  Not sure on this one.  Cookbook
   article instead? The issue with putting this in the YP docs is there 
   is no real area that focuses on the other fetchers in the YP docs. 
   Fetchers are mentioned but never really hammered on.

Henry, 

The wike page https://wiki.yoctoproject.org/wiki/TipsAndTricks/NPM goes into pretty good detail on using the npm fetcher.  Is this information going to end up as a cookbook article?  The reason I ask is I am trying to figure out where you would put it if it were to be in the mainstream YP docs.

Thanks,
Scott

I need some feedback on my items in Comment 4.  I would like to begin implementing these things across the YP manual set.  Can I make the changes I have outlined in Comment 4?

Thanks,
Scott

Proposals in comment #4 seem good, but I'd defer to Paul.

https://wiki.yoctoproject.org/wiki/TipsAndTricks/NPM started out as a tips and tricks article, but I beefed it up too much. It may be better suited as a cookbook article, or even better, a section in the dev manual. Scott - I'd value your opinion.

(In reply to comment #4)
Most of this looks OK.

>  * Could add a note here
> http://www.yoctoproject.org/docs/2.3/sdk-manual/sdk-manual.html#sdk-devtool-
> use-devtool-upgrade-to-create-a-version-of-the-recipe-that-supports-a-newer-
> version-of-the-software to reference into the 
>    fetcher section of the BB manual.

I'm not sure how it applies - can you explain? Right now devtool upgrade doesn't support changing SRC_URI and it doesn't have any specific handling for npm recipes.
 
>  * Work the wiki information from here
> https://wiki.yoctoproject.org/wiki/TipsAndTricks/NPM into the YP docs?  Not
> sure on this one.  Cookbook
>    article instead? The issue with putting this in the YP docs is there 
>    is no real area that focuses on the other fetchers in the YP docs. 
>    Fetchers are mentioned but never really hammered on.

This brings us back to my comment on bug 8909. We need a place where we can talk about the various fetchers in detail, and that place is not the variable glossary.

(In reply to comment #8)
> (In reply to comment #4)
> Most of this looks OK.
> 
> >  * Could add a note here
> > http://www.yoctoproject.org/docs/2.3/sdk-manual/sdk-manual.html#sdk-devtool-
> > use-devtool-upgrade-to-create-a-version-of-the-recipe-that-supports-a-newer-
> > version-of-the-software to reference into the 
> >    fetcher section of the BB manual.
> 
> I'm not sure how it applies - can you explain? Right now devtool upgrade
> doesn't support changing SRC_URI and it doesn't have any specific handling
> for npm recipes.

For this note Paul I was simply thinking of referencing the fetcher sections in the BB manual because the general introduction of that section in the SDK manual talks about fetchers in general.  So my thinking was to have a link into the fetcher section of the BB manual in general.

>  
> >  * Work the wiki information from here
> > https://wiki.yoctoproject.org/wiki/TipsAndTricks/NPM into the YP docs?  Not
> > sure on this one.  Cookbook
> >    article instead? The issue with putting this in the YP docs is there 
> >    is no real area that focuses on the other fetchers in the YP docs. 
> >    Fetchers are mentioned but never really hammered on.
> 
> This brings us back to my comment on bug 8909. We need a place where we can
> talk about the various fetchers in detail, and that place is not the
> variable glossary.

I agree here... it should not be part of the glossary.  I think we need a cookbook item.

Assigning to Scott. Necessary content should be in https://wiki.yoctoproject.org/wiki/TipsAndTricks/NPM

Hi, 

I am going to implement the solutions I pointed out in Comment 4.  We will take the wiki information and create a section in the dev manual somewhere.

Scott

Hi, 

I have created a new section in the dev-manual called "Creating Node Package Manager (NPM) Packages" that takes the information in the https://wiki.yoctoproject.org/wiki/TipsAndTricks/NPM wiki to the YP Docs.  The section in the docs is https://yoctoproject.org/docs/2.8/dev-manual/dev-manual.html#creating-node-package-manager-npm-packages.

Once this is settled, I will be sure to get proper cross-referencing to this section from various other areas in the YP

Sorry - magic combination inadvertently and accidentally applied to post my comment too early....

Reposting in part with conclusion....


-------------

Hi, 

I have created a new section in the dev-manual called "Creating Node Package Manager (NPM) Packages" that takes the information in the https://wiki.yoctoproject.org/wiki/TipsAndTricks/NPM wiki to the YP Docs.  The section in the docs is https://yoctoproject.org/docs/2.8/dev-manual/dev-manual.html#creating-node-package-manager-npm-packages.

Once this is settled, I will be sure to get proper cross-referencing to this section from various other areas in the YP documentation that relate.

Please review.

Thanks.

Hi, 

I have addressed everything I can for this issue.  There is the new primary section in the dev-manual that describes how to create NPM packages.

I have provided an update to the npm.bbclass section that links back to the new sction mentioned above.

I have made sure all references to NPM that exist in the YP manual set that could sanely reference to the BB manual or the new section do so.

Here are some references:

 * https://yoctoproject.org/docs/2.8/dev-manual/dev-manual.html#creating-node-package-manager-npm-packages

 * https://yoctoproject.org/docs/2.8/sdk-manual/sdk-manual.html#sdk-devtool-use-devtool-upgrade-to-create-a-version-of-the-recipe-that-supports-a-newer-version-of-the-software. 2nd paragraph under the note now references the BB manual.

 * https://yoctoproject.org/docs/2.8/ref-manual/ref-manual.html#ref-classes-npm. Updated the npm.bbclass section to point back to the new section on creating NPM packages.

You can search for "npm" in the mega-manual for others.

Thanks,
Scott

This defect seems to be in review per Scott's last comment. It's possible this could be closed. Who is the best person to review and let me know the status?

npm is listed in the "other fetchers" section of the bitbake manual without any documentation. It should at least have a link to the npm article in the dev manual.

fetcher: https://www.yoctoproject.org/docs/current/bitbake-user-manual/bitbake-user-manual.html#other-fetchers
npm: https://www.yoctoproject.org/docs/3.0/dev-manual/dev-manual.html#creating-node-package-manager-npm-packages

I'm longer working with Yocto, but in my opinion, this can't be closed until bitbake manual is updated to point developers to the existing information on how to use npm fetcher.

Thanks, Henry. I'll set for 3.1 M4. I'll add a link as a minimum per your recommendation.

Hi Henry, good to hear from you! :)

I've added Jean-Marie to cc, he just rewrote a large part of how the npm fetcher works. I'm hoping he might be able to help Mark figure out what we need to do to fix the docs to match the new code?

The npm and nmpsw fetchers are now documented in Bitbake's manual:
https://git.openembedded.org/bitbake/commit/?id=cca7999586317435d79bf53df4359cdd8bfadff4

The important bits from the wiki page have since long been included in the Yocto docs: https://docs.yoctoproject.org/dev-manual/common-tasks.html#creating-node-package-manager-npm-packages

Closing this bug as fixed.