Bug 9933

Summary:	Suggested additions to the DEPENDS documentation
Product:	[Documentation] Reference	Reporter:	ulfalizer
Component:	handbook	Assignee:	Scott Rifenbark <srifenbark>
Status:	RESOLVED FIXED	QA Contact:
Severity:	enhancement
Priority:	Medium	CC:	poky.doc.watcher, poky.watcher, sgw, srifenbark
Version:	2.3
Target Milestone:	2.2 M3
Hardware:	x86
OS:	Multiple
Whiteboard:	18 July 2016: RESOLVED
OS type for building Yocto:	---	Type of Regression:	---
Verified:		Documentation change:	Done (doc changes complete)

Description ulfalizer 2016-07-14 07:16:34 UTC

Hello,

I suggest adding the following two notes to the DEPENDS glossary entry. Both are things I've seen a lot of confusion over. That precompiled components might still need DEPENDS is subtle and has caused many build failures here.

...

Here, the dependency is such that the do_configure task for recipe "a" depends on the do_populate_sysroot task of recipe "b". This means anything that recipe "b" puts into sysroot is available when recipe "a" is configuring itself.

NEW NOTE:
DEPENDS is a list of recipe names (or, to be precise, a list of
(PROVIDES)[http://www.yoctoproject.org/docs/2.2/bitbake-user-manual/bitbake-user-manual.html#var-PROVIDES]
names, though these usually match recipe names). Putting a package name such as
"foo-dev" in DEPENDS is nonsensical. Put "foo" instead, as this will put files
from all the packages that make up foo - including those from foo-dev - into
the sysroot.

NEW NOTE:
Counterintuitively, DEPENDS is often necessary even for recipes that install
precompiled components. For example, if libfoo is a precompiled library that
links against libbar, then linking against libfoo requires both libfoo and
libbar to be available in the sysroot. Without a DEPENDS from the recipe that
installs libfoo to the recipe that installs libbar, other recipes might fail to
link against libfoo.

For information on runtime dependencies, see the RDEPENDS variable. You can also see the "Tasks" and "Dependencies" sections in the BitBake User Manual for additional information on tasks and dependencies.

Comment 1 Scott Rifenbark 2016-07-14 19:36:31 UTC

Ulf, 

Added the notes with a bit of compliance for the manual's style.  Check it out for me and let me know:

http://www.yoctoproject.org/docs/2.2/ref-manual/ref-manual.html#var-DEPENDS

Thanks, 
Scott

Comment 2 ulfalizer 2016-07-15 05:56:20 UTC

(In reply to comment #1)
> Ulf, 
> 
> Added the notes with a bit of compliance for the manual's style.  Check it
> out for me and let me know:
> 
> http://www.yoctoproject.org/docs/2.2/ref-manual/ref-manual.html#var-DEPENDS
> 
> Thanks, 
> Scott

Some feedback below.

First note:

  - I'd remove the quotes and use code formatting instead in two places:

      DEPENDS is a list of recipe names. Or, to be more precise, it is a list
      of PROVIDES names, which usually match recipe names. Putting a package
      name such as "foo-dev" in DEPENDS does not make sense. Use "foo" instead,
      as this will put files from all the packages that make up
      *<code>foo</code>* - including those from *<code>foo-dev</code>* - into
      the sysroot.

    The changes are surrounded by *. foo and foo-dev refer directly to the
    recipe and the package there rather than being strings.

  - The hyphens in "- including those from <code>foo-dev</code> -" could be
    turned into dashes.


Second note:

  - s/counter intuitively/counterintuitively/?

  - I'd use code formatting everywhere for libfoo and libbar in this note.
    Search for e.g. "glibc" to see the format I'm thinking of.

Comment 3 Scott Rifenbark 2016-07-16 18:53:23 UTC

Ulf, 

I fixed things up.  Initially, I did not thing "counterintuitively" would fly as a word but I checked into it and it is :)

Also, I am dumping the dashes for a clause.  I don't really like setting things off with dashes or hyphens and try to avoid it.  

Formatting is fixed.

thanks,
Scott

http://www.yoctoproject.org/docs/2.2/ref-manual/ref-manual.html#var-DEPENDS

Comment 4 ulfalizer 2016-07-17 08:01:33 UTC

Looks good to me now. Thanks!

Comment 5 Scott Rifenbark 2016-07-18 17:09:11 UTC

Thanks, 

Resetting the bug to RESOLVED and the doc flag to "Done."

Scott