summaryrefslogtreecommitdiffstats
path: root/bitbake/doc/user-manual/user-manual-fetching.xml
blob: 23ff3482dcd2629f612753735c5152d44bf718d3 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<chapter>
<title>File download support</title>

    <section>
        <title>Overview</title>

        <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>

        <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.
        </para>

        <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>

        <para>
            <screen><varname>PREMIRRORS</varname> ?= "\
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"

<varname>MIRRORS</varname> =+ "\
ftp://.*/.*      http://somemirror.org/sources/ \n \
http://.*/.*     http://somemirror.org/sources/ \n \
https://.*/.*    http://somemirror.org/sources/ \n"</screen>
        </para>

        <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>
    </section>

    <section>
        <title>Local file fetcher</title>

        <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.
<screen><varname>SRC_URI</varname>= "file://relativefile.patch"
<varname>SRC_URI</varname>= "file://relativefile.patch;this=ignored"
<varname>SRC_URI</varname>= "file:///Users/ich/very_important_software"
</screen>
        </para>
    </section>

    <section>
        <title>CVS fetcher</title>

        <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.
        </para>

        <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>.
<screen><varname>SRC_URI</varname> = "cvs://CVSROOT;module=mymodule;tag=some-version;method=ext"
<varname>SRC_URI</varname> = "cvs://CVSROOT;module=mymodule;date=20060126;localdir=usethat"
</screen>
        </para>
    </section>

    <section>
        <title>HTTP/FTP fetcher</title>

        <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.
        </para>
        <para>
            <screen><varname>SRC_URI</varname> = "http://oe.handhelds.org/not_there.aac"
<varname>SRC_URI</varname> = "ftp://oe.handhelds.org/not_there_as_well.aac"
<varname>SRC_URI</varname> = "ftp://you@oe.handheld.sorg/home/you/secret.plan"
</screen>
        </para>
    </section>

    <section>
        <title>SVN fetcher</title>
        <para>
            The URN for the SVN fetcher is <emphasis>svn</emphasis>.
        </para>

        <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.
        </para>

        <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.
        </para>
        <para>
            <screen><varname>SRC_URI</varname> = "svn://svn.oe.handhelds.org/svn;module=vip;proto=http;rev=667"
<varname>SRC_URI</varname> = "svn://svn.oe.handhelds.org/svn/;module=opie;proto=svn+ssh;date=20060126"
</screen>
        </para>
    </section>

    <section>
        <title>GIT fetcher</title>
        <para>
            The URN for the GIT Fetcher is <emphasis>git</emphasis>.
        </para>

        <para>
            The variable <varname>GITDIR</varname> will be used as the
            base directory where the git tree is cloned to.
        </para>

        <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.
        </para>
        <para>
            <screen><varname>SRC_URI</varname> = "git://git.oe.handhelds.org/git/vip.git;tag=version-1"
<varname>SRC_URI</varname> = "git://git.oe.handhelds.org/git/vip.git;protocol=http"
            </screen>
        </para>
    </section>
</chapter>