2013-01-11 17:45:15 +00:00
|
|
|
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
2014-01-18 15:07:32 +00:00
|
|
|
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
|
2013-01-11 17:45:15 +00:00
|
|
|
|
2014-01-18 15:07:32 +00:00
|
|
|
<chapter>
|
|
|
|
<title>File download support</title>
|
2013-01-11 17:45:15 +00:00
|
|
|
|
2014-01-18 15:07:32 +00:00
|
|
|
<section>
|
|
|
|
<title>Overview</title>
|
2013-01-11 17:45:15 +00:00
|
|
|
|
2014-01-18 15:07:32 +00:00
|
|
|
<para>
|
|
|
|
BitBake provides support to download files
|
|
|
|
this procedure is called fetching and it handled by the
|
|
|
|
fetch and fetch2 modules.
|
|
|
|
At this point the original fetch code is considered to
|
|
|
|
be replaced by fetch2 and this manual only related
|
|
|
|
to the fetch2 codebase.
|
|
|
|
</para>
|
2013-01-11 17:45:15 +00:00
|
|
|
|
2014-01-18 15:07:32 +00:00
|
|
|
<para>
|
2014-01-18 15:21:33 +00:00
|
|
|
The <filename>SRC_URI</filename> is normally used to
|
2014-01-18 15:07:32 +00:00
|
|
|
tell BitBake which files to fetch.
|
|
|
|
The next sections will describe the available fetchers and
|
|
|
|
their options.
|
|
|
|
Each fetcher honors a set of variables and per
|
|
|
|
URI parameters separated by a <quote>;</quote> consisting of a key and
|
|
|
|
a value.
|
|
|
|
The semantics of the variables and parameters are
|
|
|
|
defined by the fetcher.
|
|
|
|
BitBake tries to have consistent semantics between the
|
|
|
|
different fetchers.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
The overall fetch process is that first, fetches are attempted from
|
2014-01-18 15:21:33 +00:00
|
|
|
<filename>PREMIRRORS</filename>.
|
|
|
|
If those don't work, the original <filename>SRC_URI</filename>
|
2014-01-18 15:07:32 +00:00
|
|
|
is attempted
|
|
|
|
and if that fails, BitBake will fall back to
|
2014-01-18 15:21:33 +00:00
|
|
|
<filename>MIRRORS</filename>.
|
2014-01-18 15:07:32 +00:00
|
|
|
Cross urls are supported, so its possible to mirror
|
|
|
|
a git repository on an http server as a tarball for example.
|
|
|
|
Some example commonly used mirror
|
|
|
|
definitions are:
|
2014-01-18 15:13:13 +00:00
|
|
|
<literallayout class='monospaced'>
|
|
|
|
PREMIRRORS ?= "\
|
|
|
|
bzr://.*/.* http://somemirror.org/sources/ \n \
|
|
|
|
cvs://.*/.* http://somemirror.org/sources/ \n \
|
|
|
|
git://.*/.* http://somemirror.org/sources/ \n \
|
|
|
|
hg://.*/.* http://somemirror.org/sources/ \n \
|
|
|
|
osc://.*/.* http://somemirror.org/sources/ \n \
|
|
|
|
p4://.*/.* http://somemirror.org/sources/ \n \
|
|
|
|
svk://.*/.* http://somemirror.org/sources/ \n \
|
|
|
|
svn://.*/.* http://somemirror.org/sources/ \n"
|
2014-01-18 15:07:32 +00:00
|
|
|
|
2014-01-18 15:13:13 +00:00
|
|
|
MIRRORS =+ "\
|
|
|
|
ftp://.*/.* http://somemirror.org/sources/ \n \
|
|
|
|
http://.*/.* http://somemirror.org/sources/ \n \
|
|
|
|
https://.*/.* http://somemirror.org/sources/ \n"
|
|
|
|
</literallayout>
|
2014-01-18 15:07:32 +00:00
|
|
|
</para>
|
2013-01-11 17:45:15 +00:00
|
|
|
|
2014-01-18 15:07:32 +00:00
|
|
|
<para>
|
|
|
|
Non-local downloaded output is placed
|
|
|
|
into the directory specified by the
|
2014-01-18 15:21:33 +00:00
|
|
|
<filename>DL_DIR</filename> variable.
|
2014-01-18 15:07:32 +00:00
|
|
|
For non local archive downloads the code can verify
|
|
|
|
sha256 and md5 checksums for the download to ensure
|
|
|
|
the file has been downloaded correctly.
|
|
|
|
These may be specified either in the form
|
2014-01-18 15:21:33 +00:00
|
|
|
<filename>SRC_URI[md5sum]</filename>
|
2014-01-18 15:07:32 +00:00
|
|
|
for the md5 checksum and
|
2014-01-18 15:21:33 +00:00
|
|
|
<filename>SRC_URI[sha256sum]</filename>
|
2014-01-18 15:07:32 +00:00
|
|
|
for the sha256 checksum or as parameters on the SRC_URI such as
|
|
|
|
SRC_URI="http://example.com/foobar.tar.bz2;md5sum=4a8e0f237e961fd7785d19d07fdb994d".
|
2014-01-18 15:21:33 +00:00
|
|
|
If <filename>BB_STRICT_CHECKSUM</filename> is set, any download
|
2014-01-18 15:07:32 +00:00
|
|
|
without a checksum will trigger an error message.
|
|
|
|
In cases where multiple files are listed in
|
|
|
|
SRC_URI, the name parameter is used
|
|
|
|
assign names to the urls and these are then specified
|
|
|
|
in the checksums in the form
|
|
|
|
SRC_URI[name.sha256sum].
|
|
|
|
</para>
|
|
|
|
</section>
|
2013-01-11 17:45:15 +00:00
|
|
|
|
2014-01-18 15:07:32 +00:00
|
|
|
<section>
|
|
|
|
<title>Local file fetcher</title>
|
2013-01-11 17:45:15 +00:00
|
|
|
|
2014-01-18 15:07:32 +00:00
|
|
|
<para>
|
2014-01-18 15:21:33 +00:00
|
|
|
The URN for the local file fetcher is file.
|
2014-01-18 15:07:32 +00:00
|
|
|
The filename can be either absolute or relative.
|
|
|
|
If the filename is relative,
|
2014-01-18 15:21:33 +00:00
|
|
|
<filename>FILESPATH</filename> and failing that
|
|
|
|
<filename>FILESDIR</filename> will be used to find the
|
2014-01-18 15:07:32 +00:00
|
|
|
appropriate relative file.
|
|
|
|
The metadata usually extend these variables to include
|
2014-01-18 15:21:33 +00:00
|
|
|
variations of the values in <filename>OVERRIDES</filename>.
|
2014-01-18 15:07:32 +00:00
|
|
|
Single files and complete directories can be specified.
|
2014-01-18 15:13:13 +00:00
|
|
|
<literallayout class='monospaced'>
|
|
|
|
SRC_URI = "file://relativefile.patch"
|
|
|
|
SRC_URI = "file://relativefile.patch;this=ignored"
|
|
|
|
SRC_URI = "file:///Users/ich/very_important_software"
|
|
|
|
</literallayout>
|
2014-01-18 15:07:32 +00:00
|
|
|
</para>
|
|
|
|
</section>
|
2013-01-11 17:45:15 +00:00
|
|
|
|
2014-01-18 15:07:32 +00:00
|
|
|
<section>
|
|
|
|
<title>CVS fetcher</title>
|
2013-01-11 17:45:15 +00:00
|
|
|
|
2014-01-18 15:07:32 +00:00
|
|
|
<para>
|
2014-01-18 15:21:33 +00:00
|
|
|
The URN for the CVS fetcher is cvs.
|
|
|
|
This fetcher honors the variables <filename>CVSDIR</filename>,
|
|
|
|
<filename>SRCDATE</filename>, <filename>FETCHCOMMAND_cvs</filename>,
|
|
|
|
<filename>UPDATECOMMAND_cvs</filename>.
|
|
|
|
<filename>DL_DIR</filename> specifies where a
|
2014-01-18 15:07:32 +00:00
|
|
|
temporary checkout is saved.
|
2014-01-18 15:21:33 +00:00
|
|
|
<filename>SRCDATE</filename> specifies which date to
|
2014-01-18 15:07:32 +00:00
|
|
|
use when doing the fetching (the special value of "now"
|
|
|
|
will cause the checkout to be updated on every build).
|
2014-01-18 15:21:33 +00:00
|
|
|
<filename>FETCHCOMMAND</filename> and
|
|
|
|
<filename>UPDATECOMMAND</filename> specify which executables
|
2014-01-18 15:07:32 +00:00
|
|
|
to use for the CVS checkout or update.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2014-01-18 15:21:33 +00:00
|
|
|
The supported parameters are module, tag, date,
|
|
|
|
method, localdir, rshand scmdata.
|
|
|
|
The module specifies which module to check out,
|
|
|
|
the tag describes which CVS TAG should be used for
|
2014-01-18 15:07:32 +00:00
|
|
|
the checkout.
|
2014-01-18 15:21:33 +00:00
|
|
|
By default, the TAG is empty.
|
|
|
|
A date can be specified to override the
|
|
|
|
<filename>SRCDATE</filename> of the
|
2014-01-18 15:07:32 +00:00
|
|
|
configuration to checkout a specific date.
|
|
|
|
The special value of "now" will cause the checkout to be
|
|
|
|
updated on every build.
|
2014-01-18 15:21:33 +00:00
|
|
|
method is by default pserver.
|
|
|
|
If ext is used the rsh parameter will be evaluated
|
|
|
|
and <filename>CVS_RSH</filename> will be set.
|
|
|
|
Finally, localdir is used to checkout into a special
|
|
|
|
directory relative to <filename>CVSDIR</filename>.
|
2014-01-18 15:13:13 +00:00
|
|
|
<literallayout class='monospaced'>
|
|
|
|
SRC_URI = "cvs://CVSROOT;module=mymodule;tag=some-version;method=ext"
|
|
|
|
SRC_URI = "cvs://CVSROOT;module=mymodule;date=20060126;localdir=usethat"
|
|
|
|
</literallayout>
|
2014-01-18 15:07:32 +00:00
|
|
|
</para>
|
|
|
|
</section>
|
|
|
|
|
|
|
|
<section>
|
|
|
|
<title>HTTP/FTP fetcher</title>
|
|
|
|
|
|
|
|
<para>
|
2014-01-18 15:21:33 +00:00
|
|
|
The URNs for the HTTP/FTP fetcher are http, https and ftp.
|
2014-01-18 15:07:32 +00:00
|
|
|
This fetcher honors the variables
|
2014-01-18 15:21:33 +00:00
|
|
|
<filename>FETCHCOMMAND_wget</filename>.
|
|
|
|
<filename>FETCHCOMMAND</filename> contains the command used
|
2014-01-18 15:07:32 +00:00
|
|
|
for fetching.
|
|
|
|
<quote>${URI}</quote> and <quote>${FILES}</quote> will be replaced by the URI and
|
|
|
|
basename of the file to be fetched.
|
2014-01-18 15:13:13 +00:00
|
|
|
<literallayout class='monospaced'>
|
|
|
|
SRC_URI = "http://oe.handhelds.org/not_there.aac"
|
|
|
|
SRC_URI = "ftp://oe.handhelds.org/not_there_as_well.aac"
|
|
|
|
SRC_URI = "ftp://you@oe.handheld.sorg/home/you/secret.plan"
|
|
|
|
</literallayout>
|
2014-01-18 15:07:32 +00:00
|
|
|
</para>
|
|
|
|
</section>
|
|
|
|
|
|
|
|
<section>
|
|
|
|
<title>SVN fetcher</title>
|
|
|
|
<para>
|
2014-01-18 15:21:33 +00:00
|
|
|
The URN for the SVN fetcher is svn.
|
2014-01-18 15:07:32 +00:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
This fetcher honors the variables
|
2014-01-18 15:21:33 +00:00
|
|
|
<filename>FETCHCOMMAND_svn</filename>,
|
|
|
|
<filename>SVNDIR</filename>,
|
|
|
|
<filename>SRCREV</filename>.
|
|
|
|
<filename>FETCHCOMMAND</filename> contains the
|
2014-01-18 15:07:32 +00:00
|
|
|
subversion command.
|
2014-01-18 15:21:33 +00:00
|
|
|
<filename>SRCREV</filename> specifies which revision
|
2014-01-18 15:07:32 +00:00
|
|
|
to use when doing the fetching.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2014-01-18 15:21:33 +00:00
|
|
|
The supported parameters are proto, rev and scmdata.
|
|
|
|
proto is the Subversion protocol, rev is the
|
2014-01-18 15:07:32 +00:00
|
|
|
Subversion revision.
|
2014-01-18 15:21:33 +00:00
|
|
|
If scmdata is set to <quote>keep</quote>, the <quote>.svn</quote> directories will
|
2014-01-18 15:07:32 +00:00
|
|
|
be available during compile-time.
|
2014-01-18 15:13:13 +00:00
|
|
|
<literallayout class='monospaced'>
|
|
|
|
SRC_URI = "svn://svn.oe.handhelds.org/svn;module=vip;proto=http;rev=667"
|
|
|
|
SRC_URI = "svn://svn.oe.handhelds.org/svn/;module=opie;proto=svn+ssh;date=20060126"
|
|
|
|
</literallayout>
|
2014-01-18 15:07:32 +00:00
|
|
|
</para>
|
|
|
|
</section>
|
2013-01-11 17:45:15 +00:00
|
|
|
|
2014-01-18 15:07:32 +00:00
|
|
|
<section>
|
|
|
|
<title>GIT fetcher</title>
|
|
|
|
<para>
|
2014-01-18 15:21:33 +00:00
|
|
|
The URN for the GIT Fetcher is git.
|
2014-01-18 15:07:32 +00:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2014-01-18 15:21:33 +00:00
|
|
|
The variable <filename>GITDIR</filename> will be used as the
|
2014-01-18 15:07:32 +00:00
|
|
|
base directory where the git tree is cloned to.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2014-01-18 15:21:33 +00:00
|
|
|
The parameters are tag, protocol and scmdata.
|
|
|
|
tag is a Git tag, the default is <quote>master</quote>.
|
|
|
|
protocol is the Git protocol to use and defaults to <quote>git</quote>
|
2014-01-18 15:07:32 +00:00
|
|
|
if a hostname is set, otherwise its <quote>file</quote>.
|
2014-01-18 15:21:33 +00:00
|
|
|
If scmdata is set to <quote>keep</quote>, the <quote>.git</quote> directory will be available
|
2014-01-18 15:07:32 +00:00
|
|
|
during compile-time.
|
2014-01-18 15:13:13 +00:00
|
|
|
<literallayout class='monospaced'>
|
|
|
|
SRC_URI = "git://git.oe.handhelds.org/git/vip.git;tag=version-1"
|
|
|
|
SRC_URI = "git://git.oe.handhelds.org/git/vip.git;protocol=http"
|
|
|
|
</literallayout>
|
2014-01-18 15:07:32 +00:00
|
|
|
</para>
|
|
|
|
</section>
|
|
|
|
</chapter>
|