class_siteinfo.xml: Replace packages/ with recipes/.
[openembedded.git] / docs / usermanual / reference / class_siteinfo.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <section id="siteinfo_class" xreflabel="siteinfo class">
3   <title>siteinfo class</title>
4
5   <para>The siteinfo class provides information for a target with a particular
6   emphasis on determining the names of the site files to be passed to
7   autoconf, as described in the <xref linkend="autotools_class" />. Full site
8   information for your target can be determined by looking at the table in the
9   class implementation found in the
10   <command>classes/siteinfo.bbclass</command> file. A typical entry contains
11   the name of the target and a list of site information for the
12   target:<screen>    "sh4-linux":               "endian-little bit-32 common-glibc sh-common",</screen>In
13   the above example for sh4-linux target (that's a build for an sh4 processor
14   using glibc) we see that the endianess and bit-size of target are defined
15   and an additional set of site files that should be used are listed. These
16   include a common site file for glibc and a common site file for sh
17   processors (so sh3 and sh4 can share defines). A <command>"common"</command>
18   entry is automatically added to the end of each of the definitions during
19   processing.</para>
20
21   <para>The class makes available three variables based on the information
22   provided for a target:</para>
23
24   <variablelist>
25     <varlistentry>
26       <term>SITEINFO_ENDIANESS</term>
27
28       <listitem>
29         <para>Defines the endianess of the target as either
30         <command>"le"</command> (little endian) or <command>"be"</command>
31         (big endian). The target must list either
32         <command>endian-little</command> or <command>endian-big</command> in
33         it's site information.</para>
34       </listitem>
35     </varlistentry>
36
37     <varlistentry>
38       <term>SITEINFO_BITS</term>
39
40       <listitem>
41         <para>Defines the bitsize of the target as either
42         <command>"32"</command> or <command>"64"</command>. The target must
43         list either <command>bit-32</command> or <command>bit-64</command> in
44         it's site information.</para>
45       </listitem>
46     </varlistentry>
47
48     <varlistentry>
49       <term>CONFIG_SITE</term>
50
51       <listitem>
52         <para>Defines the site files to be used by autoconf. This is a space
53         separated list of one or more site files for the target.</para>
54       </listitem>
55     </varlistentry>
56   </variablelist>
57
58   <para>A typical use for the <command>SITEINFO_ENDIANESS</command> and
59   <command>SITEINFO_BITS</command> variables is to provide configuration
60   within a recipe based on their values. The following example from the
61   <emphasis>openssl</emphasis> recipe showw the correct define for the
62   endiness of the target being passed to openssl via the compiler flags. The
63   define to add to the flags is set based on the value of the
64   <command>SITEINFO_ENDIANESS</command> variable. Note that use of the
65   <emphasis>base_conditional</emphasis> method (see the <xref
66   linkend="recipes_advanced_python" /> section) to select a value conditional
67   on the endianess setting:</para>
68
69   <para><screen>  # Additional flag based on target endiness (see siteinfo.bbclass)
70     CFLAG="${CFLAG} ${@base_conditional('SITEINFO_ENDIANESS', 'le', '-DL_ENDIAN', '-DB_ENDIAN', d)}"</screen></para>
71
72   <section>
73     <title>CONFIG_SITE: The autoconf site files</title>
74
75     <para>The autotools configuration method has support for caching the
76     results of tests. In the cross-compilation case it is sometimes necessary
77     to prime the cache with per-calculated results (since tests designed to
78     run on the target cannot be run when cross-compiling). These are defined
79     via the site file(s) for the architecture you are using and may be
80     specific to the package you are building.</para>
81
82     <para>Which site files are used is determined via the
83     <command>CONFIG_SITE</command> definition which is calculated via the
84     siteinfo class. Typically the following site files will be checked for,
85     and used in the order found:</para>
86
87     <variablelist>
88       <varlistentry>
89         <term>endian-(big|little)</term>
90
91         <listitem>
92           <para>Either <command>endian-big</command> or
93           <command>endian-little</command> depending on the endianess of the
94           target. This site file would contain defines that only change based
95           on if the target is little endian or big endian.</para>
96         </listitem>
97       </varlistentry>
98
99       <varlistentry>
100         <term>bit-(32|64)</term>
101
102         <listitem>
103           <para>Either <command>bit-32</command> or <command>bit-64</command>
104           depending on the bitsize of the target. This site file would contain
105           defines that only change based on if the target is a 32-bit or
106           64-bit cpu.</para>
107         </listitem>
108       </varlistentry>
109
110       <varlistentry>
111         <term>common-(libc|uclibc)</term>
112
113         <listitem>
114           <para>Either <command>common-libc</command> or
115           <command>common-uclibc</command> based on the C library being used
116           for the target. This site file would contain defines the are
117           specific to the C library being used.</para>
118         </listitem>
119       </varlistentry>
120
121       <varlistentry>
122         <term>&lt;arch&gt;-common</term>
123
124         <listitem>
125           <para>A common site file for the target architecture. For i386,
126           i485, i586 and i686 this would be <command>x86-common</command>, for
127           sh3 and sh4 this would be <command>sh-common</command> and for
128           various arm targets this would be
129           <command>arm-common</command>.</para>
130         </listitem>
131       </varlistentry>
132
133       <varlistentry>
134         <term>common</term>
135
136         <listitem>
137           <para>This is a site file which is common for all targets and
138           contains definitions which remain the same no matter what target is
139           being built.</para>
140         </listitem>
141       </varlistentry>
142     </variablelist>
143
144     <para>Each of the supported site files for a target is will be checked for
145     in several different directories. Each time a file is found it as added to
146     the list of files in the <command>CONFIG_SITE</command> variable. The
147     following directories are checked:</para>
148
149     <variablelist>
150       <varlistentry>
151         <term>org.openembedded.dev/recipes/&lt;packagename&gt;/site-&lt;version&gt;/</term>
152
153         <listitem>
154           <para>This directory is for site files which are specific to a
155           particular version (where version is the PV of the package) of a
156           package.</para>
157         </listitem>
158       </varlistentry>
159
160       <varlistentry>
161         <term>org.openembedded.dev/recipes/&lt;packagename&gt;/site/</term>
162
163         <listitem>
164           <para>This directory is for site files which are specific to a
165           particular package, but apply to all versions of the package.</para>
166         </listitem>
167       </varlistentry>
168
169       <varlistentry>
170         <term>org.openembedded.dev/site/</term>
171
172         <listitem>
173           <para>This directory is for site files that are common to all
174           packages. Originally this was the only site file directory that was
175           supported.</para>
176         </listitem>
177       </varlistentry>
178     </variablelist>
179   </section>
180 </section>