docs: import usermanual from org.openembedded.documentation.
[openembedded.git] / docs / usermanual / reference / var_src_uri.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <section id="src_uri_variable" xreflabel="SRC_URI variable">
3   <title>SRC_URI variable: Source code and patches</title>
4
5   <para>All recipies need to contain a definition of
6   <command>SRC_URI</command>. It determines what files and source code is
7   needed and where that source code should be obtained from. This includes
8   patches to be applied and basic files that are shipped as part of the
9   meta-data for the package.</para>
10
11   <para>A typical <command>SRC_URI</command> contains a list of URL's, patches
12   and files as shown in this example from quagga:<screen>SRC_URI = "http://www.quagga.net/download/quagga-${PV}.tar.gz \
13            file://ospfd-no-opaque-lsa-fix.patch;patch=1 \
14            file://fix-for-lib-inpath.patch;patch=1 \
15            file://quagga.init \
16            file://quagga.default \
17            file://watchquagga.init \
18            file://watchquagga.default"</screen>All source code and files will
19   be placed into the work directory, <command>${WORKDIR}</command>, for the
20   package. All patches will be placed into a <command>patches</command>
21   subdirectory of the package source directory, <command>${S}</command>, and
22   then automatically applied to the source.</para>
23
24   <para>Before downloading from a remote URI a check will be made to see if
25   what is to be retrieved is already present in the download source directory,
26   <command>${DL_DIR}</command>, along with an associated md5 sum. If the
27   source is present in the downloaded sources directory and the md5 sum
28   matches that listed in the associated md5 sum file, then that version will
29   be used in preference to retrieving a new version . Any source that is
30   retrieved from a remote URI will be stored in the download source directory
31   and an appropriate md5 sum generated and stored alongside it.</para>
32
33   <para>Each URI supports a set of additional options. These options are
34   tag/value pairs of the form <command>"a=b"</command> and are semi-colon
35   separated from each other and from the URI. The follow examples shows two
36   options being included, the patch and pnum options:<screen>file://ospfd-no-opaque-lsa-fix.patch;patch=1;pnum=2</screen>The
37   supported methods for fetching source and files are:</para>
38
39   <variablelist>
40     <varlistentry>
41       <term>http, https, ftps</term>
42
43       <listitem>
44         <para>Used to download files and source code via the specified URL.
45         These are fetched from the specified location using wget.</para>
46       </listitem>
47     </varlistentry>
48
49     <varlistentry>
50       <term>file</term>
51
52       <listitem>
53         <para>Used for files that are included locally in the meta-data. These
54         may be plain files, such as init scripts to be added to the final
55         package, or they may be patch files to be applied to other
56         source.</para>
57       </listitem>
58     </varlistentry>
59
60     <varlistentry>
61       <term>cvs</term>
62
63       <listitem>
64         <para>Used to download from a CVS repository.</para>
65       </listitem>
66     </varlistentry>
67
68     <varlistentry>
69       <term>svn</term>
70
71       <listitem>
72         <para>Used to download from a subversion repository.</para>
73       </listitem>
74     </varlistentry>
75
76     <varlistentry>
77       <term>git</term>
78
79       <listitem>
80         <para>Used to download from a git repository.</para>
81       </listitem>
82     </varlistentry>
83   </variablelist>
84
85   <para>When source code is specified as a part of <command>SRC_URI</command>
86   it is unpacked into the work directory, <command>${WORKDIR}</command>. The
87   unpacker recognises several archive and compression types and for these it
88   will decompress any compressed files and extract all of the files from
89   archives into the work directory. The supported types are:</para>
90
91   <variablelist>
92     <varlistentry>
93       <term>.tar</term>
94
95       <listitem>
96         <para>Tar archives which will be extracted with <command>"tar x
97         --no-same-owner -f &lt;srcfile&gt;"</command>.</para>
98       </listitem>
99     </varlistentry>
100
101     <varlistentry>
102       <term>.tgz, .tar.gz, tar.Z</term>
103
104       <listitem>
105         <para>Gzip compressed tar archives which will be extracted with
106         <command>"tar xz --no-same-owner -f &lt;srcfile&gt;"</command>.</para>
107       </listitem>
108     </varlistentry>
109
110     <varlistentry>
111       <term>.tbz, .tar.bz2</term>
112
113       <listitem>
114         <para>Bzip2 compressed tar archives which will be extracted with
115         <command>"bzip2 -dc &lt;srcfile&gt; | tar x --no-same-owner -f
116         -"</command>.</para>
117       </listitem>
118     </varlistentry>
119
120     <varlistentry>
121       <term>.gz, .Z, .z</term>
122
123       <listitem>
124         <para>Gzip compressed files which will be decompressed with
125         <command>"gzip -dc &lt;srcfile&gt; &gt;
126         &lt;dstfile&gt;"</command>.</para>
127       </listitem>
128     </varlistentry>
129
130     <varlistentry>
131       <term>.bz2</term>
132
133       <listitem>
134         <para>Bzip2 compressed files which will be decompressed with
135         <command>"bzip2 -dc &lt;srcfile&gt; &gt;
136         &lt;dstfile&gt;"</command>.</para>
137       </listitem>
138     </varlistentry>
139
140     <varlistentry>
141       <term>.zip</term>
142
143       <listitem>
144         <para>Zip archives which will be extracted with <command>"unzip -q
145         &lt;srcfile&gt;"</command>.</para>
146       </listitem>
147     </varlistentry>
148   </variablelist>
149
150   <para>The downloading of the source files occurs in the
151   <emphasis>fetch</emphasis> task, the unpacking and copying to the work
152   directory occurs in the <emphasis>unpack</emphasis> task and the applying of
153   patches occurs in the <emphasis>patch</emphasis> task.</para>
154
155   <section>
156     <title>http/https/ftp (wget)</title>
157
158     <para>The wget fetcher handles http, https and ftp URLs.<screen>http://www.quagga.net/download/quagga-${PV}.tar.gz</screen></para>
159
160     <para>Supported options:</para>
161
162     <variablelist>
163       <varlistentry>
164         <term>md5sum</term>
165
166         <listitem>
167           <para>If an md5sum is provided then the downloaded files will only
168           be considered valid if the md5sum of the downloaded file matches the
169           md5sum option provided.</para>
170         </listitem>
171       </varlistentry>
172     </variablelist>
173
174     <para>Related variables:</para>
175
176     <variablelist>
177       <varlistentry>
178         <term>MIRRORS</term>
179
180         <listitem>
181           <para>Mirrors define alternative locations to download source files
182           from. See the mirror section below for more information.</para>
183         </listitem>
184       </varlistentry>
185
186       <varlistentry>
187         <term>DL_DIR</term>
188
189         <listitem>
190           <para>The downloaded files will be placed in this directory with the
191           name exactly as supplied via the URI.</para>
192         </listitem>
193       </varlistentry>
194     </variablelist>
195   </section>
196
197   <section>
198     <title>file: for patches and additional files</title>
199
200     <para>The file URI's are used to copy files, included as part of the
201     package meta data, into the work directory to be used when building the
202     package. Typical use of the file URI's is to specify patches that be
203     applied to the source and to provide additional files, such as init
204     scripts, to be included in the final package.</para>
205
206     <para>The following example shows the specification of a patch
207     file:<screen>file://ospfd-no-opaque-lsa-fix.patch;patch=1</screen></para>
208
209     <para>Patch files are be copied to the patches subdirectory of the source
210     directory, <command>${S}/patches</command>, and then applied from the
211     source directory. The patches are searched for along the path specified
212     via the file path variable, <command>${FILESPATH},</command> and if not
213     found the directory specified by the file directory variable,
214     <command>${FILEDIR}</command>, is also checked.</para>
215
216     <para>The following example shows the specification of a non-patch file.
217     In this case it's an init script:<screen>file://quagga.init</screen>Non-patch
218     files are copied to the work directory, <command>${WORKDIR}</command>. You
219     can access these files from within a recipe by referring to them relative
220     to the work directory. The following example, from the quagga recipe,
221     shows the above init script being included in the package by copying it
222     during the <emphasis>install</emphasis> task:<screen>do_install () {
223     # Install init script and default settings
224     install -m 0755 -d ${D}${sysconfdir}/default ${D}${sysconfdir}/init.d ${D}${sysconfdir}/quagga
225     install -m 0644 <emphasis role="bold">${WORKDIR}/quagga.init</emphasis> ${D}${sysconfdir}/init.d/quagga
226 ...</screen></para>
227
228     <para>Supported options:</para>
229
230     <variablelist>
231       <varlistentry>
232         <term>patch</term>
233
234         <listitem>
235           <para>Used as <command>"patch=1"</command> to define this file as a
236           patch file. Patch files will be copied to
237           <command>${S}/patches</command> and then applied to source from
238           within the source directory, <command>${S}</command>.</para>
239         </listitem>
240       </varlistentry>
241
242       <varlistentry>
243         <term>pnum</term>
244
245         <listitem>
246           <para>By default patches are applied with the <command>"-p
247           1"</command> parameter, which strips off the first directory of the
248           pathname in the patches. This option is used to explicitly control
249           the value passed to <command>"-p"</command>. The most typical use is
250           when the patches are relative to the source directory already and
251           need to be applied using <command>"-p 0"</command>, in which case
252           the <command>"pnum=0"</command> option is supplied.</para>
253         </listitem>
254       </varlistentry>
255     </variablelist>
256   </section>
257
258   <section>
259     <title>cvs</title>
260
261     <para>The cvs fetcher is used to retrieve files from a CVS repository.
262     <screen>    cvs://anonymous@cvs.sourceforge.net/cvsroot/linuxsh;module=linux;date=20051111</screen>A
263     cvs URI will retrieve the source from a cvs repository. Note that use of
264     the <emphasis>date=</emphasis> to specify a checkout for specified date.
265     It is preferable to use either a <emphasis>date=</emphasis> or a
266     <emphasis>tag=</emphasis> option to select a specific date and/or tag from
267     cvs rather than leave the checkout floating at the head revision.</para>
268
269     <para>Supported options:</para>
270
271     <variablelist>
272       <varlistentry>
273         <term>module</term>
274
275         <listitem>
276           <para>The name of a module to retrieve. This is a required parameter
277           and there is no default value.</para>
278         </listitem>
279       </varlistentry>
280
281       <varlistentry>
282         <term>tag</term>
283
284         <listitem>
285           <para>The name of a cvs tag to retrieve. Releases are often tagged
286           with a specific name to allow easy access. Either a tag or a date
287           can be specified, but not both.</para>
288         </listitem>
289       </varlistentry>
290
291       <varlistentry>
292         <term>date</term>
293
294         <listitem>
295           <para>The date to retrieve. This requests that files as of the
296           specified date, rather then the current code or a tagged release. If
297           no date or tag options are specified, then the date is set to the
298           current date. The date is of any form accepted by cvs with the most
299           common format being <command>"YYYYMMDD"</command>.</para>
300         </listitem>
301       </varlistentry>
302
303       <varlistentry>
304         <term>method</term>
305
306         <listitem>
307           <para>The method used to access the repository. Common options are
308           <command>"pserver"</command> and <command>"ext"</command> (for cvs
309           over rsh or ssh). The default is
310           <command>"pserver"</command>.</para>
311         </listitem>
312       </varlistentry>
313
314       <varlistentry>
315         <term>rsh</term>
316
317         <listitem>
318           <para>The rsh command to use with the <command>"ext"</command>
319           method. Common options are <command>"rsh"</command> or
320           <command>"ssh"</command>. The default is
321           <command>"rsh"</command>.</para>
322         </listitem>
323       </varlistentry>
324     </variablelist>
325
326     <para>Related variables:<variablelist>
327         <varlistentry>
328           <term>CVS_TARBALL_STASH</term>
329
330           <listitem>
331             <para>Used to specifies a location to search for pre-generated tar
332             archives to use instead of accessing cvs directly.</para>
333           </listitem>
334         </varlistentry>
335
336         <varlistentry>
337           <term>CVSDIR</term>
338
339           <listitem>
340             <para>The directory in which the cvs checkouts will be performed.
341             The default is <command>${DL_DIR}/cvs</command>.</para>
342           </listitem>
343         </varlistentry>
344
345         <varlistentry>
346           <term>DL_DIR</term>
347
348           <listitem>
349             <para>A compressed tar archive of the retrieved files will be
350             placed in this directory. The archive name will be of the form:
351             <command>"&lt;module&gt;_&lt;host&gt;_&lt;tag&gt;_&lt;date&gt;.tar.gz"</command>.
352             Path separators in <command>module</command> will be replaced with
353             full stops.</para>
354           </listitem>
355         </varlistentry>
356       </variablelist></para>
357   </section>
358
359   <section>
360     <title>svn</title>
361
362     <para>The svn fetcher is used to retrieve files from a subversion
363     repository.</para>
364
365     <para><screen>    svn://svn.xiph.org/trunk;module=Tremor;rev=4573;proto=http</screen></para>
366
367     <para>Supported options:</para>
368
369     <variablelist>
370       <varlistentry>
371         <term>module</term>
372
373         <listitem>
374           <para>The name of a module to retrieve. This is a required parameter
375           and there is no default value.</para>
376         </listitem>
377       </varlistentry>
378
379       <varlistentry>
380         <term>rev</term>
381
382         <listitem>
383           <para>The revision to retrieve. Revisions in subversion are integer
384           values.</para>
385         </listitem>
386       </varlistentry>
387
388       <varlistentry>
389         <term>proto</term>
390
391         <listitem>
392           <para>The method to use to access the repository. Common options are
393           <command>"svn"</command>, <command>"svn+ssh"</command>,
394           <command>"http"</command> and <command>"https"</command>. The
395           default is <command>"svn"</command>.</para>
396         </listitem>
397       </varlistentry>
398
399       <varlistentry>
400         <term>rsh</term>
401
402         <listitem>
403           <para>The rsh command to use with using the
404           <command>"svn+ssh"</command> method. Common options are
405           <command>"rsh"</command> or <command>"ssh"</command>. The default is
406           <command>"ssh"</command>.</para>
407         </listitem>
408       </varlistentry>
409     </variablelist>
410
411     <para>Related variables:<variablelist>
412         <varlistentry>
413           <term>SVNDIR</term>
414
415           <listitem>
416             <para>The directory in which the svn checkouts will be performed..
417             The default is <command>${DL_DIR}/svn</command>.</para>
418           </listitem>
419         </varlistentry>
420
421         <varlistentry>
422           <term>DL_DIR</term>
423
424           <listitem>
425             <para>A compressed tar archive of the retrieved files will be
426             placed in this directory. The archive name will be of the form:
427             <command>"&lt;module&gt;_&lt;host&gt;_&lt;path&gt;_&lt;revn&gt;_&lt;date&gt;.tar.gz"</command>.
428             Path separators in <command>path</command> and
429             <command>module</command> will be replaced with full stops.</para>
430           </listitem>
431         </varlistentry>
432       </variablelist></para>
433   </section>
434
435   <section>
436     <title>git</title>
437
438     <para>The git fetcher is used to retrieve files from a git repository.
439     <screen>  SRC_URI = "git://www.denx.de/git/u-boot.git;protocol=git;tag=${TAG}"</screen></para>
440
441     <para>Supported options:</para>
442
443     <variablelist>
444       <varlistentry>
445         <term>tag</term>
446
447         <listitem>
448           <para>The tag to retrieve. The default is
449           <command>"master"</command>.</para>
450         </listitem>
451       </varlistentry>
452
453       <varlistentry>
454         <term>protocol</term>
455
456         <listitem>
457           <para>The method to use to access the repository. Common options are
458           <command>"git"</command> and <command>"rsync"</command>. The default
459           is <command>"rsync"</command>.</para>
460         </listitem>
461       </varlistentry>
462     </variablelist>
463
464     <para>Related variables</para>
465
466     <para><variablelist>
467         <varlistentry>
468           <term>GITDIR</term>
469
470           <listitem>
471             <para>The directory in which the git checkouts will be performed.
472             The default is <command>${DL_DIR}/git</command>.</para>
473           </listitem>
474         </varlistentry>
475
476         <varlistentry>
477           <term>DL_DIR</term>
478
479           <listitem>
480             <para>A compressed tar archive of the retrieved files will be
481             placed in this directory. The archive name will be of the form:
482             <command>"git_&lt;host&gt;&lt;mpath&gt;_&lt;tag&gt;.tar.gz"</command>.
483             Path separators in <command>host</command> will be replaced with
484             full stops.</para>
485           </listitem>
486         </varlistentry>
487       </variablelist></para>
488   </section>
489
490   <section>
491     <title>Mirrors</title>
492
493     <para>The support for mirror sites enables spreading the load over sites
494     and allows for downloads to occur even when one of the mirror sites are
495     unavailable.</para>
496
497     <para>Default mirrors, along with their primary URL, include:</para>
498
499     <variablelist>
500       <varlistentry>
501         <term>GNU_MIRROR</term>
502
503         <listitem>
504           <para>ftp://ftp.gnu.org/gnu</para>
505         </listitem>
506       </varlistentry>
507
508       <varlistentry>
509         <term>DEBIAN_MIRROR</term>
510
511         <listitem>
512           <para>ftp://ftp.debian.org/debian/pool</para>
513         </listitem>
514       </varlistentry>
515
516       <varlistentry>
517         <term>SOURCEFORGE_MIRROR</term>
518
519         <listitem>
520           <para>http://heanet.dl.sourceforge.net/sourceforge</para>
521         </listitem>
522       </varlistentry>
523
524       <varlistentry>
525         <term>GPE_MIRROR</term>
526
527         <listitem>
528           <para>http://handhelds.org/pub/projects/gpe/source</para>
529         </listitem>
530       </varlistentry>
531
532       <varlistentry>
533         <term>XLIBS_MIRROR</term>
534
535         <listitem>
536           <para>http://xlibs.freedesktop.org/release</para>
537         </listitem>
538       </varlistentry>
539
540       <varlistentry>
541         <term>XORG_MIRROR</term>
542
543         <listitem>
544           <para>http://xorg.freedesktop.org/releases</para>
545         </listitem>
546       </varlistentry>
547
548       <varlistentry>
549         <term>GNOME_MIRROR</term>
550
551         <listitem>
552           <para>http://ftp.gnome.org/pub/GNOME/sources</para>
553         </listitem>
554       </varlistentry>
555
556       <varlistentry>
557         <term>FREEBSD_MIRROR</term>
558
559         <listitem>
560           <para>ftp://ftp.freebsd.org/pub/FreeBSD</para>
561         </listitem>
562       </varlistentry>
563
564       <varlistentry>
565         <term>GENTOO_MIRROR</term>
566
567         <listitem>
568           <para>http://distro.ibiblio.org/pub/linux/distributions/gentoo/distfiles</para>
569         </listitem>
570       </varlistentry>
571
572       <varlistentry>
573         <term>APACHE_MIRROR</term>
574
575         <listitem>
576           <para>http://www.apache.org/dist</para>
577         </listitem>
578       </varlistentry>
579     </variablelist>
580
581     <para>When creating new recipes this mirrors should be used when you wish
582     to use one of the above sites by referring to the name of the mirror in
583     the URI, as show in this example from flex:<screen>SRC_URI = "${SOURCEFORGE_MIRROR}/lex/flex-2.5.31.tar.bz2</screen></para>
584
585     <para>You can manually define your mirrors if you wish to force the use of
586     a specific mirror by exporting the appropriate mirrors in
587     <command>local.conf</command> with them set to the local mirror:<screen>export GNU_MIRROR = "http://www.planetmirror.com/pub/gnu"
588 export DEBIAN_MIRROR = "http://mirror.optusnet.com.au/debian/pool"
589 export SOURCEFORGE_MIRROR = "http://optusnet.dl.sourceforge.net/sourceforge"</screen></para>
590
591     <para>Mirrors can be extended in individual recipes via the use of
592     <command>MIRRORS_prepend</command> or <command>MIRRORS_append</command>.
593     Each entry in the list contains the mirror name on the left-hand side and
594     the URI of the mirror on the right-hand side. The following example from
595     libffi shows the addition of two URI for the
596     <command>"${GNU_MIRROR}/gcc/"</command> URI:<screen>MIRRORS_prepend () {
597   ${GNU_MIRROR}/gcc/  http://gcc.get-software.com/releases/
598   ${GNU_MIRROR}/gcc/  http://mirrors.rcn.net/pub/sourceware/gcc/releases/
599 }</screen></para>
600   </section>
601
602   <section>
603     <title>Manipulating SRC_URI</title>
604
605     <para>Sometimes it is desirable to only include patches for a specific
606     architecture and/or to include different files based on the architecture.
607     This can be done via the <command>SRC_URI_append</command> and/or
608     <command>SRC_URI_prepend</command> methods for adding additional URI's
609     based on the architecture or machine name.</para>
610
611     <para>In this example from glibc, the patch creates a configuration file
612     for glibc, which should only be used or the sh4 architecture. Therefore
613     this patch is appended to the <command>SRC_URI</command>, but only for the
614     sh4 architecture. For other architectures it is ignored:<screen># Build fails on sh4 unless no-z-defs is defined
615 SRC_URI_append_sh4 = " file://no-z-defs.patch;patch=1"</screen></para>
616   </section>
617
618   <section>
619     <title>Source distribution (src_distribute_local)</title>
620
621     <para>In order to obtain a set of source files for a build you can use the
622     <emphasis>src_distribute_local</emphasis> class. This will result in all
623     the files that were actually used during a build being made available in a
624     seperate directory and therefore they can be distributed with the
625     binaries.</para>
626
627     <para>Enabling this option is as simple as activating the functionality by
628     including the required class in one of your configuration files:<screen>SRC_DIST_LOCAL = "copy"
629 INHERIT += "src_distribute_local"</screen></para>
630
631     <para>Now during a build each recipe which has a LICENSE that mandates
632     source availability, like the GPL, will be placed into the source
633     distribution directory, <command>${SRC_DISTRIBUTEDIR}</command>, after
634     building.</para>
635
636     <para>There are some options available to effect the option</para>
637
638     <variablelist>
639       <varlistentry>
640         <term>SRC_DIST_LOCAL</term>
641
642         <listitem>
643           <para>Specifies if the source files should be copied, symlinked or
644           moved and symlinked back. The default is
645           <command>"move+symlink"</command>.</para>
646         </listitem>
647       </varlistentry>
648
649       <varlistentry>
650         <term>SRC_DISTRIBUTEDIR</term>
651
652         <listitem>
653           <para>Specifies the source distribution directory - this is why the
654           source files that was used for the build are placed. The default is
655           <command>"${DEPLOY_DIR}/sources"</command>.</para>
656         </listitem>
657       </varlistentry>
658     </variablelist>
659
660     <para>The valid values for <command>SRC_DIST_LOCAL</command> are:</para>
661
662     <variablelist>
663       <varlistentry>
664         <term>copy</term>
665
666         <listitem>
667           <para>Copies the files to the downloaded sources directory into the
668           distribution directory.</para>
669         </listitem>
670       </varlistentry>
671
672       <varlistentry>
673         <term>symlink</term>
674
675         <listitem>
676           <para>Symlinks the files from the downloaded sources directory into
677           the distribution directory.</para>
678         </listitem>
679       </varlistentry>
680
681       <varlistentry>
682         <term>move+symlink</term>
683
684         <listitem>
685           <para>Moves the files from the downloaded sources directory into the
686           distribution directory. Then creates a symlink in the download
687           sources directory to the moved files.</para>
688         </listitem>
689       </varlistentry>
690     </variablelist>
691   </section>
692 </section>