Currently the glossary entry for SRC_URI is scant at best:

  "The list of source files - local or remote."

We need a fuller description of this variable.  Fundamentally, I need the following:

  * Correct syntax
  * General use case
  * Weird things that need to be called out about it
  * Parameter descriptions... including "patchdir"

I tried to add Joshua Lock to the CC list as a resource for information but the tool could not find matches for joshua.lock@intel.com or joshua.lock@linux.intel.com.  Not quite sure what the problem is with that.

The SRC_URI tells the system which bits to pull in for the build and *how* to pull them in.

If the recipe only needs to fetch a tarball from the internet to build you'll see a single SRC_URI entry. If it needs to fetch a tarball, apply two patches and include a custom file you'll see 4 entries.

The first piece of the uri is the protocol - it tells BitBake which fetcher to use.

The available protocols are:

o file:// - fetches something from the local machine, usually a file shipped with the metadata. The path is relative to the FILESPATH variable so will search from the following directories, assumed to be a subdirectory of the directory with the recipe file in, in order:

${PF}, ${P}, ${PN}, ${BP}, ${BPN}, files and finally the same directory as the recipe itself.

Just in case those variables aren't documented in the Glossary:

PF - ${PN}-${EXTENDPE}${PV}-${PR} full package name including all version numbers i.e. eglibc-2.13-r20+svnr15508/ and
bash-4.2-r1/

P - ${PN}-${PV} i.e. bash-4.2

PN - package name i.e. bash-native, bash (note P includes the special suffix -native for native recipes, -cross for cross recipes, a multilib suffix for multilib recipes, etc).

BP - ${BPN}-${PV} base package and version (without special suffix)

BPN - base package name (without special suffix or version numbers)

o bzr:// - fetches from a bazaar revision control repository

o git:// - fetches from a git revision control repository

o osc:// - fetches from an OSC (OpenSuse Build service) revision control repository

o repo:// - fetches from a repo (git) repository

o svk:// - fetches from an svk revision control repository

o http:// https:// ftp:// - fetches files from the internet via http, ftp or https

o cvs:// - fetches from a CVS revision control repository

o hg:// - fetches from a mercurial (hg) revision control repository

o p4:// - fetches from a perforce (p4) revision control repository

o ssh:// - fetches files via a secure shell

o svn:// - fetches from a subversion (svn) revision control repository

Here are the options for patch SRC_URI entries:

Standard patch options:
apply - whether or not to apply the patch. Defaults to yes if not explicitly defined.
striplevel - what striplevel to use when applying the patch, defaults to 1 if not explicitly defined.

Patch options specific to recipes building code from a revision control system:
mindate - only apply patch if the SRCDATE is at least mindate
maxdate - only apply patch if the SRCDATE is not later than maxdate
minrev - only apply patch if the SRCREV is at least minrev
maxrev - only apply patch if the SRCREV is no later than maxrev
rev - only apply patch if SRCREV is rev
notrev - only apply patch if SRCREV isn't notrev

Some others worth noting:

* unpack - controls whether or not to unpack the file if it is an archive, 
defaults to yes

* subdir - place the file (or extract its contents) into the specified 
subdirectory of WORKDIR. Useful for unusual tarballs or other archives that 
don't have their files already in a subdirectory within the archive.

* name - a name to be used for association with SRC_URI checksums when you 
have more than one file specified in SRC_URI

Pasted in a few comments from a recent email thread on this topic, more info is required though...

Adding Yu Ke to the bug. He implemented the fetcher2, and may have some design docs to help the documentation.

Hi Nintin,
Are there any updates for this bug?

Thanks,
Alex.

I have added information about the fetch protocols and the SRC_URI options to the glossary definition.  You can see the final at http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-SRC_URI.

Scott

Scott,
  This also should be in the list of additional options

downloadfilename - specifies filename with which, the downloaded file should be stored.

Nitin, 

I have added that option and reset the bug.  See at http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-SRC_URI.

Scott

Scott,
  The new addition looks good to me.