summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorRichard Purdie <richard.purdie@linuxfoundation.org>2014-01-18 15:24:18 +0000
committerRichard Purdie <richard.purdie@linuxfoundation.org>2014-01-27 21:03:23 +0000
commit1669f39e470fb3c66097b2e4a62e14d67c8b7e4d (patch)
treee3c727f8e86d4426164b663a7f164323f01a9653
parent123b978c8278ca917cff9a6f85fdd65a1d58c414 (diff)
downloadpoky-1669f39e470fb3c66097b2e4a62e14d67c8b7e4d.tar.gz
bitbake: user-manual-fetching: Editing pass over the manual chapter
(Bitbake rev: b0fc79e6405b7070a42cfda035e87edc832f8334) Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
-rw-r--r--bitbake/doc/user-manual/user-manual-fetching.xml97
1 files changed, 53 insertions, 44 deletions
diff --git a/bitbake/doc/user-manual/user-manual-fetching.xml b/bitbake/doc/user-manual/user-manual-fetching.xml
index 1ff8acb4e0..cdca64c801 100644
--- a/bitbake/doc/user-manual/user-manual-fetching.xml
+++ b/bitbake/doc/user-manual/user-manual-fetching.xml
@@ -4,25 +4,25 @@
4<chapter> 4<chapter>
5<title>File download support</title> 5<title>File download support</title>
6 6
7 <section> 7 <section id='file-download-overview'>
8 <title>Overview</title> 8 <title>Overview</title>
9 9
10 <para> 10 <para>
11 BitBake provides support to download files 11 BitBake provides support to download files.
12 this procedure is called fetching and it handled by the 12 This procedure is called fetching and is handled by the
13 fetch and fetch2 modules. 13 fetch and fetch2 modules.
14 At this point the original fetch code is considered to 14 At this point, the original fetch code is considered to
15 be replaced by fetch2 and this manual only related 15 be replaced by fetch2 and this manual is only related
16 to the fetch2 codebase. 16 to the fetch2 codebase.
17 </para> 17 </para>
18 18
19 <para> 19 <para>
20 The <filename>SRC_URI</filename> is normally used to 20 The <filename>SRC_URI</filename> is normally used to
21 tell BitBake which files to fetch. 21 tell BitBake which files to fetch.
22 The next sections will describe the available fetchers and 22 The next sections describe the available fetchers and
23 their options. 23 their options.
24 Each fetcher honors a set of variables and per 24 Each fetcher honors a set of variables and per
25 URI parameters separated by a <quote>;</quote> consisting of a key and 25 URI parameters separated by a ; consisting of a key and
26 a value. 26 a value.
27 The semantics of the variables and parameters are 27 The semantics of the variables and parameters are
28 defined by the fetcher. 28 defined by the fetcher.
@@ -31,16 +31,16 @@
31 </para> 31 </para>
32 32
33 <para> 33 <para>
34 The overall fetch process is that first, fetches are attempted from 34 The overall fetch process first attempts to fetch from
35 <filename>PREMIRRORS</filename>. 35 <filename>PREMIRRORS</filename>.
36 If those don't work, the original <filename>SRC_URI</filename> 36 If these fail, the original <filename>SRC_URI</filename>
37 is attempted 37 is attempted.
38 and if that fails, BitBake will fall back to 38 If that fails, BitBake falls back to
39 <filename>MIRRORS</filename>. 39 <filename>MIRRORS</filename>.
40 Cross urls are supported, so its possible to mirror 40 Because cross-URLs are supported, it is possible to mirror
41 a git repository on an http server as a tarball for example. 41 a Git repository on an HTTP server as a tarball.
42 Some example commonly used mirror 42 Here are some examples that show commonly used mirror
43 definitions are: 43 definitions:
44 <literallayout class='monospaced'> 44 <literallayout class='monospaced'>
45PREMIRRORS ?= "\ 45PREMIRRORS ?= "\
46 bzr://.*/.* http://somemirror.org/sources/ \n \ 46 bzr://.*/.* http://somemirror.org/sources/ \n \
@@ -63,26 +63,33 @@ MIRRORS =+ "\
63 Non-local downloaded output is placed 63 Non-local downloaded output is placed
64 into the directory specified by the 64 into the directory specified by the
65 <filename>DL_DIR</filename> variable. 65 <filename>DL_DIR</filename> variable.
66 For non local archive downloads the code can verify 66 For non local archive downloads, the code can verify
67 sha256 and md5 checksums for the download to ensure 67 sha256 and md5 checksums for the download to ensure
68 the file has been downloaded correctly. 68 the file has been downloaded correctly.
69 These may be specified either in the form 69 These can be specified in the following forms
70 <filename>SRC_URI[md5sum]</filename> 70 for md5 and sha256 checksums, respectively:
71 for the md5 checksum and 71 <literallayout class='monospaced'>
72 <filename>SRC_URI[sha256sum]</filename> 72 SRC_URI[md5sum]
73 for the sha256 checksum or as parameters on the SRC_URI such as 73 SRC_URI[sha256sum]
74 SRC_URI="http://example.com/foobar.tar.bz2;md5sum=4a8e0f237e961fd7785d19d07fdb994d". 74 </literallayout>
75 You can also specify them as parameters on the
76 <filename>SRC_URI</filename>:
77 <literallayout class='monospaced'>
78 SRC_URI="http://example.com/foobar.tar.bz2;md5sum=4a8e0f237e961fd7785d19d07fdb994d"
79 </literallayout>
75 If <filename>BB_STRICT_CHECKSUM</filename> is set, any download 80 If <filename>BB_STRICT_CHECKSUM</filename> is set, any download
76 without a checksum will trigger an error message. 81 without a checksum will trigger an error message.
77 In cases where multiple files are listed in 82 In cases where multiple files are listed in
78 SRC_URI, the name parameter is used 83 <filename>SRC_URI</filename>, the name parameter is used
79 assign names to the urls and these are then specified 84 assign names to the URLs and these are then specified
80 in the checksums in the form 85 in the checksums using the following form:
81 SRC_URI[name.sha256sum]. 86 <literallayout class='monospaced'>
87 SRC_URI[name.sha256sum]
88 </literallayout>
82 </para> 89 </para>
83 </section> 90 </section>
84 91
85 <section> 92 <section id='local-file-fetcher'>
86 <title>Local file fetcher</title> 93 <title>Local file fetcher</title>
87 94
88 <para> 95 <para>
@@ -103,7 +110,7 @@ MIRRORS =+ "\
103 </para> 110 </para>
104 </section> 111 </section>
105 112
106 <section> 113 <section id='cvs-fetcher'>
107 <title>CVS fetcher</title> 114 <title>CVS fetcher</title>
108 115
109 <para> 116 <para>
@@ -145,16 +152,16 @@ MIRRORS =+ "\
145 </para> 152 </para>
146 </section> 153 </section>
147 154
148 <section> 155 <section id='http-ftp-fetcher'>
149 <title>HTTP/FTP fetcher</title> 156 <title>HTTP/FTP fetcher</title>
150 157
151 <para> 158 <para>
152 The URNs for the HTTP/FTP fetcher are http, https and ftp. 159 The URNs for the HTTP/FTP fetcher are http, https, and ftp.
153 This fetcher honors the variables 160 This fetcher honors the variables
154 <filename>FETCHCOMMAND_wget</filename>. 161 <filename>FETCHCOMMAND_wget</filename>.
155 <filename>FETCHCOMMAND</filename> contains the command used 162 <filename>FETCHCOMMAND</filename> contains the command used
156 for fetching. 163 for fetching.
157 <quote>${URI}</quote> and <quote>${FILES}</quote> will be replaced by the URI and 164 ${URI} and ${FILES} will be replaced by the URI and
158 basename of the file to be fetched. 165 basename of the file to be fetched.
159 <literallayout class='monospaced'> 166 <literallayout class='monospaced'>
160 SRC_URI = "http://oe.handhelds.org/not_there.aac" 167 SRC_URI = "http://oe.handhelds.org/not_there.aac"
@@ -164,8 +171,9 @@ MIRRORS =+ "\
164 </para> 171 </para>
165 </section> 172 </section>
166 173
167 <section> 174 <section id='svn-fetcher'>
168 <title>SVN fetcher</title> 175 <title>SVN Fetcher</title>
176
169 <para> 177 <para>
170 The URN for the SVN fetcher is svn. 178 The URN for the SVN fetcher is svn.
171 </para> 179 </para>
@@ -174,7 +182,7 @@ MIRRORS =+ "\
174 This fetcher honors the variables 182 This fetcher honors the variables
175 <filename>FETCHCOMMAND_svn</filename>, 183 <filename>FETCHCOMMAND_svn</filename>,
176 <filename>SVNDIR</filename>, 184 <filename>SVNDIR</filename>,
177 <filename>SRCREV</filename>. 185 and <filename>SRCREV</filename>.
178 <filename>FETCHCOMMAND</filename> contains the 186 <filename>FETCHCOMMAND</filename> contains the
179 subversion command. 187 subversion command.
180 <filename>SRCREV</filename> specifies which revision 188 <filename>SRCREV</filename> specifies which revision
@@ -185,8 +193,8 @@ MIRRORS =+ "\
185 The supported parameters are proto, rev and scmdata. 193 The supported parameters are proto, rev and scmdata.
186 proto is the Subversion protocol, rev is the 194 proto is the Subversion protocol, rev is the
187 Subversion revision. 195 Subversion revision.
188 If scmdata is set to <quote>keep</quote>, the <quote>.svn</quote> directories will 196 If scmdata is set to keep, the .svn directories will
189 be available during compile-time. 197 be available during compile-time.
190 <literallayout class='monospaced'> 198 <literallayout class='monospaced'>
191 SRC_URI = "svn://svn.oe.handhelds.org/svn;module=vip;proto=http;rev=667" 199 SRC_URI = "svn://svn.oe.handhelds.org/svn;module=vip;proto=http;rev=667"
192 SRC_URI = "svn://svn.oe.handhelds.org/svn/;module=opie;proto=svn+ssh;date=20060126" 200 SRC_URI = "svn://svn.oe.handhelds.org/svn/;module=opie;proto=svn+ssh;date=20060126"
@@ -194,23 +202,24 @@ MIRRORS =+ "\
194 </para> 202 </para>
195 </section> 203 </section>
196 204
197 <section> 205 <section id='git-fetcher'>
198 <title>GIT fetcher</title> 206 <title>GIT Fetcher</title>
207
199 <para> 208 <para>
200 The URN for the GIT Fetcher is git. 209 The URN for the GIT Fetcher is git.
201 </para> 210 </para>
202 211
203 <para> 212 <para>
204 The variable <filename>GITDIR</filename> will be used as the 213 The variable <filename>GITDIR</filename> will be used as the
205 base directory where the git tree is cloned to. 214 base directory where the Git tree is cloned to.
206 </para> 215 </para>
207 216
208 <para> 217 <para>
209 The parameters are tag, protocol and scmdata. 218 The parameters are tag, protocol, and scmdata.
210 tag is a Git tag, the default is <quote>master</quote>. 219 The tag parameter is a Git tag, the default is master.
211 protocol is the Git protocol to use and defaults to <quote>git</quote> 220 The protocol tag is the Git protocol to use and defaults to git
212 if a hostname is set, otherwise its <quote>file</quote>. 221 if a hostname is set, otherwise it is file.
213 If scmdata is set to <quote>keep</quote>, the <quote>.git</quote> directory will be available 222 If scmdata is set to keep, the .git directory will be available
214 during compile-time. 223 during compile-time.
215 <literallayout class='monospaced'> 224 <literallayout class='monospaced'>
216 SRC_URI = "git://git.oe.handhelds.org/git/vip.git;tag=version-1" 225 SRC_URI = "git://git.oe.handhelds.org/git/vip.git;tag=version-1"