summaryrefslogtreecommitdiffstats
path: root/bitbake/doc/user-manual/user-manual-fetching.xml
diff options
context:
space:
mode:
authorRichard Purdie <richard.purdie@linuxfoundation.org>2014-01-18 15:07:32 +0000
committerRichard Purdie <richard.purdie@linuxfoundation.org>2014-01-27 21:03:23 +0000
commitd0c16f9467e239203be04678b7b5652fd2436833 (patch)
treefa2846e844fa49ebbd00747de6857e59d42a7047 /bitbake/doc/user-manual/user-manual-fetching.xml
parent552d54f2ecadfc6b8af5c2cc8c44d15c23928bef (diff)
downloadpoky-d0c16f9467e239203be04678b7b5652fd2436833.tar.gz
bitbake: user-manual-fetching: Change the file whitespace
(Bitbake rev: 7e32068d1ab4e1f342f70a8338bb8a51fc783da9) Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'bitbake/doc/user-manual/user-manual-fetching.xml')
-rw-r--r--bitbake/doc/user-manual/user-manual-fetching.xml249
1 files changed, 190 insertions, 59 deletions
diff --git a/bitbake/doc/user-manual/user-manual-fetching.xml b/bitbake/doc/user-manual/user-manual-fetching.xml
index 24780454c7..23ff3482dc 100644
--- a/bitbake/doc/user-manual/user-manual-fetching.xml
+++ b/bitbake/doc/user-manual/user-manual-fetching.xml
@@ -1,18 +1,50 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> 2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
3 3
4 <chapter> 4<chapter>
5 <title>File download support</title> 5<title>File download support</title>
6 <section>
7 <title>Overview</title>
8 <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>
9 6
10 <para>The SRC_URI is normally used to 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. 7 <section>
11 </para> 8 <title>Overview</title>
12 9
13 <para>The overall fetch process is that first, fetches are attempted from PREMIRRORS. If those don't work, the original SRC_URI is attempted and if that fails, BitBake will fall back to MIRRORS. 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:</para> 10 <para>
11 BitBake provides support to download files
12 this procedure is called fetching and it handled by the
13 fetch and fetch2 modules.
14 At this point the original fetch code is considered to
15 be replaced by fetch2 and this manual only related
16 to the fetch2 codebase.
17 </para>
14 18
15 <para><screen><varname>PREMIRRORS</varname> ?= "\ 19 <para>
20 The SRC_URI is normally used to
21 tell BitBake which files to fetch.
22 The next sections will describe the available fetchers and
23 their options.
24 Each fetcher honors a set of variables and per
25 URI parameters separated by a <quote>;</quote> consisting of a key and
26 a value.
27 The semantics of the variables and parameters are
28 defined by the fetcher.
29 BitBake tries to have consistent semantics between the
30 different fetchers.
31 </para>
32
33 <para>
34 The overall fetch process is that first, fetches are attempted from
35 PREMIRRORS.
36 If those don't work, the original SRC_URI
37 is attempted
38 and if that fails, BitBake will fall back to
39 MIRRORS.
40 Cross urls are supported, so its possible to mirror
41 a git repository on an http server as a tarball for example.
42 Some example commonly used mirror
43 definitions are:
44 </para>
45
46 <para>
47 <screen><varname>PREMIRRORS</varname> ?= "\
16bzr://.*/.* http://somemirror.org/sources/ \n \ 48bzr://.*/.* http://somemirror.org/sources/ \n \
17cvs://.*/.* http://somemirror.org/sources/ \n \ 49cvs://.*/.* http://somemirror.org/sources/ \n \
18git://.*/.* http://somemirror.org/sources/ \n \ 50git://.*/.* http://somemirror.org/sources/ \n \
@@ -25,68 +57,167 @@ svn://.*/.* http://somemirror.org/sources/ \n"
25<varname>MIRRORS</varname> =+ "\ 57<varname>MIRRORS</varname> =+ "\
26ftp://.*/.* http://somemirror.org/sources/ \n \ 58ftp://.*/.* http://somemirror.org/sources/ \n \
27http://.*/.* http://somemirror.org/sources/ \n \ 59http://.*/.* http://somemirror.org/sources/ \n \
28https://.*/.* http://somemirror.org/sources/ \n"</screen></para> 60https://.*/.* http://somemirror.org/sources/ \n"</screen>
61 </para>
29 62
30 <para>Non-local downloaded output is placed into the directory specified by the <varname>DL_DIR</varname>. 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 <varname>SRC_URI[md5sum]</varname> for the md5 checksum and <varname>SRC_URI[sha256sum]</varname> for the sha256 checksum or as parameters on the SRC_URI such as SRC_URI="http://example.com/foobar.tar.bz2;md5sum=4a8e0f237e961fd7785d19d07fdb994d". If <varname>BB_STRICT_CHECKSUM</varname> is set, any download 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> 63 <para>
64 Non-local downloaded output is placed
65 into the directory specified by the
66 <varname>DL_DIR</varname>.
67 For non local archive downloads the code can verify
68 sha256 and md5 checksums for the download to ensure
69 the file has been downloaded correctly.
70 These may be specified either in the form
71 <varname>SRC_URI[md5sum]</varname>
72 for the md5 checksum and
73 <varname>SRC_URI[sha256sum]</varname>
74 for the sha256 checksum or as parameters on the SRC_URI such as
75 SRC_URI="http://example.com/foobar.tar.bz2;md5sum=4a8e0f237e961fd7785d19d07fdb994d".
76 If <varname>BB_STRICT_CHECKSUM</varname> is set, any download
77 without a checksum will trigger an error message.
78 In cases where multiple files are listed in
79 SRC_URI, the name parameter is used
80 assign names to the urls and these are then specified
81 in the checksums in the form
82 SRC_URI[name.sha256sum].
83 </para>
84 </section>
31 85
32 </section> 86 <section>
87 <title>Local file fetcher</title>
33 88
34 <section> 89 <para>
35 <title>Local file fetcher</title> 90 The URN for the local file fetcher is <emphasis>file</emphasis>.
36 <para>The URN for the local file fetcher is <emphasis>file</emphasis>. The filename can be either absolute or relative. If the filename is relative, <varname>FILESPATH</varname> and failing that <varname>FILESDIR</varname> will be used to find the appropriate relative file. The metadata usually extend these variables to include variations of the values in <varname>OVERRIDES</varname>. Single files and complete directories can be specified. 91 The filename can be either absolute or relative.
92 If the filename is relative,
93 <varname>FILESPATH</varname> and failing that
94 <varname>FILESDIR</varname> will be used to find the
95 appropriate relative file.
96 The metadata usually extend these variables to include
97 variations of the values in <varname>OVERRIDES</varname>.
98 Single files and complete directories can be specified.
37<screen><varname>SRC_URI</varname>= "file://relativefile.patch" 99<screen><varname>SRC_URI</varname>= "file://relativefile.patch"
38<varname>SRC_URI</varname>= "file://relativefile.patch;this=ignored" 100<varname>SRC_URI</varname>= "file://relativefile.patch;this=ignored"
39<varname>SRC_URI</varname>= "file:///Users/ich/very_important_software" 101<varname>SRC_URI</varname>= "file:///Users/ich/very_important_software"
40</screen> 102</screen>
41 </para> 103 </para>
42 </section> 104 </section>
43 105
44 <section> 106 <section>
45 <title>CVS fetcher</title> 107 <title>CVS fetcher</title>
46 <para>The URN for the CVS fetcher is <emphasis>cvs</emphasis>. This fetcher honors the variables <varname>CVSDIR</varname>, <varname>SRCDATE</varname>, <varname>FETCHCOMMAND_cvs</varname>, <varname>UPDATECOMMAND_cvs</varname>. <varname>DL_DIR</varname> specifies where a temporary checkout is saved. <varname>SRCDATE</varname> specifies which date to use when doing the fetching (the special value of "now" will cause the checkout to be updated on every build). <varname>FETCHCOMMAND</varname> and <varname>UPDATECOMMAND</varname> specify which executables to use for the CVS checkout or update.
47 </para>
48 <para>The supported parameters are <varname>module</varname>, <varname>tag</varname>, <varname>date</varname>, <varname>method</varname>, <varname>localdir</varname>, <varname>rsh</varname> and <varname>scmdata</varname>. The <varname>module</varname> specifies which module to check out, the <varname>tag</varname> describes which CVS TAG should be used for the checkout. By default the TAG is empty. A <varname>date</varname> can be specified to override the SRCDATE of the configuration to checkout a specific date. The special value of "now" will cause the checkout to be updated on every build.<varname>method</varname> is by default <emphasis>pserver</emphasis>. If <emphasis>ext</emphasis> is used the <varname>rsh</varname> parameter will be evaluated and <varname>CVS_RSH</varname> will be set. Finally, <varname>localdir</varname> is used to checkout into a special directory relative to <varname>CVSDIR</varname>.
49 108
109 <para>
110 The URN for the CVS fetcher is <emphasis>cvs</emphasis>.
111 This fetcher honors the variables <varname>CVSDIR</varname>,
112 <varname>SRCDATE</varname>, <varname>FETCHCOMMAND_cvs</varname>,
113 <varname>UPDATECOMMAND_cvs</varname>.
114 <varname>DL_DIR</varname> specifies where a
115 temporary checkout is saved.
116 <varname>SRCDATE</varname> specifies which date to
117 use when doing the fetching (the special value of "now"
118 will cause the checkout to be updated on every build).
119 <varname>FETCHCOMMAND</varname> and
120 <varname>UPDATECOMMAND</varname> specify which executables
121 to use for the CVS checkout or update.
122 </para>
123
124 <para>
125 The supported parameters are <varname>module</varname>, <varname>tag</varname>, <varname>date</varname>,
126 <varname>method</varname>, <varname>localdir</varname>, <varname>rsh</varname> and <varname>scmdata</varname>.
127 The <varname>module</varname> specifies which module to check out,
128 the <varname>tag</varname> describes which CVS TAG should be used for
129 the checkout.
130 By default the TAG is empty.
131 A <varname>date</varname> can be specified to override the
132 SRCDATE of the
133 configuration to checkout a specific date.
134 The special value of "now" will cause the checkout to be
135 updated on every build.
136 <varname>method</varname> is by default <emphasis>pserver</emphasis>.
137 If <emphasis>ext</emphasis> is used the <varname>rsh</varname> parameter will be evaluated
138 and <varname>CVS_RSH</varname> will be set.
139 Finally, <varname>localdir</varname> is used to checkout into a special
140 directory relative to <varname>CVSDIR</varname>.
50<screen><varname>SRC_URI</varname> = "cvs://CVSROOT;module=mymodule;tag=some-version;method=ext" 141<screen><varname>SRC_URI</varname> = "cvs://CVSROOT;module=mymodule;tag=some-version;method=ext"
51<varname>SRC_URI</varname> = "cvs://CVSROOT;module=mymodule;date=20060126;localdir=usethat" 142<varname>SRC_URI</varname> = "cvs://CVSROOT;module=mymodule;date=20060126;localdir=usethat"
52</screen> 143</screen>
53 </para> 144 </para>
54 </section> 145 </section>
55 146
56 <section> 147 <section>
57 <title>HTTP/FTP fetcher</title> 148 <title>HTTP/FTP fetcher</title>
58 <para>The URNs for the HTTP/FTP fetcher are <emphasis>http</emphasis>, <emphasis>https</emphasis> and <emphasis>ftp</emphasis>. This fetcher honors the variables <varname>FETCHCOMMAND_wget</varname>. <varname>FETCHCOMMAND</varname> contains the command used for fetching. <quote>${URI}</quote> and <quote>${FILES}</quote> will be replaced by the URI and basename of the file to be fetched. 149
59 </para> 150 <para>
60 <para><screen><varname>SRC_URI</varname> = "http://oe.handhelds.org/not_there.aac" 151 The URNs for the HTTP/FTP fetcher are <emphasis>http</emphasis>, <emphasis>https</emphasis> and <emphasis>ftp</emphasis>.
152 This fetcher honors the variables
153 <varname>FETCHCOMMAND_wget</varname>.
154 <varname>FETCHCOMMAND</varname> contains the command used
155 for fetching.
156 <quote>${URI}</quote> and <quote>${FILES}</quote> will be replaced by the URI and
157 basename of the file to be fetched.
158 </para>
159 <para>
160 <screen><varname>SRC_URI</varname> = "http://oe.handhelds.org/not_there.aac"
61<varname>SRC_URI</varname> = "ftp://oe.handhelds.org/not_there_as_well.aac" 161<varname>SRC_URI</varname> = "ftp://oe.handhelds.org/not_there_as_well.aac"
62<varname>SRC_URI</varname> = "ftp://you@oe.handheld.sorg/home/you/secret.plan" 162<varname>SRC_URI</varname> = "ftp://you@oe.handheld.sorg/home/you/secret.plan"
63</screen></para> 163</screen>
64 </section> 164 </para>
65 165 </section>
66 <section> 166
67 <title>SVN fetcher</title> 167 <section>
68 <para>The URN for the SVN fetcher is <emphasis>svn</emphasis>. 168 <title>SVN fetcher</title>
69 </para> 169 <para>
70 <para>This fetcher honors the variables <varname>FETCHCOMMAND_svn</varname>, <varname>SVNDIR</varname>, <varname>SRCREV</varname>. <varname>FETCHCOMMAND</varname> contains the subversion command. <varname>SRCREV</varname> specifies which revision to use when doing the fetching. 170 The URN for the SVN fetcher is <emphasis>svn</emphasis>.
71 </para> 171 </para>
72 <para>The supported parameters are <varname>proto</varname>, <varname>rev</varname> and <varname>scmdata</varname>. <varname>proto</varname> is the Subversion protocol, <varname>rev</varname> is the Subversion revision. If <varname>scmdata</varname> is set to <quote>keep</quote>, the <quote>.svn</quote> directories will be available during compile-time. 172
73 </para> 173 <para>
74 <para><screen><varname>SRC_URI</varname> = "svn://svn.oe.handhelds.org/svn;module=vip;proto=http;rev=667" 174 This fetcher honors the variables
175 <varname>FETCHCOMMAND_svn</varname>,
176 <varname>SVNDIR</varname>,
177 <varname>SRCREV</varname>.
178 <varname>FETCHCOMMAND</varname> contains the
179 subversion command.
180 <varname>SRCREV</varname> specifies which revision
181 to use when doing the fetching.
182 </para>
183
184 <para>
185 The supported parameters are <varname>proto</varname>, <varname>rev</varname> and <varname>scmdata</varname>.
186 <varname>proto</varname> is the Subversion protocol, <varname>rev</varname> is the
187 Subversion revision.
188 If <varname>scmdata</varname> is set to <quote>keep</quote>, the <quote>.svn</quote> directories will
189 be available during compile-time.
190 </para>
191 <para>
192 <screen><varname>SRC_URI</varname> = "svn://svn.oe.handhelds.org/svn;module=vip;proto=http;rev=667"
75<varname>SRC_URI</varname> = "svn://svn.oe.handhelds.org/svn/;module=opie;proto=svn+ssh;date=20060126" 193<varname>SRC_URI</varname> = "svn://svn.oe.handhelds.org/svn/;module=opie;proto=svn+ssh;date=20060126"
76</screen></para> 194</screen>
77 </section> 195 </para>
78 196 </section>
79 <section>
80 <title>GIT fetcher</title>
81 <para>The URN for the GIT Fetcher is <emphasis>git</emphasis>.
82 </para>
83 <para>The variable <varname>GITDIR</varname> will be used as the base directory where the git tree is cloned to.
84 </para>
85 <para>The parameters are <emphasis>tag</emphasis>, <emphasis>protocol</emphasis> and <emphasis>scmdata</emphasis>. <emphasis>tag</emphasis> is a Git tag, the default is <quote>master</quote>. <emphasis>protocol</emphasis> is the Git protocol to use and defaults to <quote>git</quote> if a hostname is set, otherwise its <quote>file</quote>. If <emphasis>scmdata</emphasis> is set to <quote>keep</quote>, the <quote>.git</quote> directory will be available during compile-time.
86 </para>
87 <para><screen><varname>SRC_URI</varname> = "git://git.oe.handhelds.org/git/vip.git;tag=version-1"
88<varname>SRC_URI</varname> = "git://git.oe.handhelds.org/git/vip.git;protocol=http"
89 </screen></para>
90 </section>
91 197
92 </chapter> 198 <section>
199 <title>GIT fetcher</title>
200 <para>
201 The URN for the GIT Fetcher is <emphasis>git</emphasis>.
202 </para>
203
204 <para>
205 The variable <varname>GITDIR</varname> will be used as the
206 base directory where the git tree is cloned to.
207 </para>
208
209 <para>
210 The parameters are <emphasis>tag</emphasis>, <emphasis>protocol</emphasis> and <emphasis>scmdata</emphasis>.
211 <emphasis>tag</emphasis> is a Git tag, the default is <quote>master</quote>.
212 <emphasis>protocol</emphasis> is the Git protocol to use and defaults to <quote>git</quote>
213 if a hostname is set, otherwise its <quote>file</quote>.
214 If <emphasis>scmdata</emphasis> is set to <quote>keep</quote>, the <quote>.git</quote> directory will be available
215 during compile-time.
216 </para>
217 <para>
218 <screen><varname>SRC_URI</varname> = "git://git.oe.handhelds.org/git/vip.git;tag=version-1"
219<varname>SRC_URI</varname> = "git://git.oe.handhelds.org/git/vip.git;protocol=http"
220 </screen>
221 </para>
222 </section>
223</chapter>