diff options
Diffstat (limited to 'documentation/getting-started/eclipse/html/getting-started/user-configuration.html')
-rw-r--r-- | documentation/getting-started/eclipse/html/getting-started/user-configuration.html | 232 |
1 files changed, 232 insertions, 0 deletions
diff --git a/documentation/getting-started/eclipse/html/getting-started/user-configuration.html b/documentation/getting-started/eclipse/html/getting-started/user-configuration.html new file mode 100644 index 0000000000..6f10791e7a --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/user-configuration.html | |||
@@ -0,0 +1,232 @@ | |||
1 | <html> | ||
2 | <head> | ||
3 | <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> | ||
4 | <title>2.8.1. User Configuration</title> | ||
5 | <link rel="stylesheet" type="text/css" href="../book.css"> | ||
6 | <meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> | ||
7 | <link rel="home" href="index.html" title="Getting Started With Yocto Project"> | ||
8 | <link rel="up" href="development-concepts.html" title="2.8. Development Concepts"> | ||
9 | <link rel="prev" href="development-concepts.html" title="2.8. Development Concepts"> | ||
10 | <link rel="next" href="metadata-machine-configuration-and-policy-configuration.html" title="2.8.2. Metadata, Machine Configuration, and Policy Configuration"> | ||
11 | </head> | ||
12 | <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="2.8.1. User Configuration"> | ||
13 | <div class="titlepage"><div><div><h3 class="title"> | ||
14 | <a name="user-configuration"></a>2.8.1. User Configuration</h3></div></div></div> | ||
15 | <p> | ||
16 | User configuration helps define the build. | ||
17 | Through user configuration, you can tell BitBake the | ||
18 | target architecture for which you are building the image, | ||
19 | where to store downloaded source, and other build properties. | ||
20 | </p> | ||
21 | <p> | ||
22 | The following figure shows an expanded representation of the | ||
23 | "User Configuration" box of the | ||
24 | <a class="link" href="development-concepts.html#general-yocto-environment-figure">general Yocto Project Development Environment figure</a>: | ||
25 | </p> | ||
26 | <p> | ||
27 | </p> | ||
28 | <table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="720"><tr style="height: 405px"><td align="center"><img src="figures/user-configuration.png" align="middle" height="405"></td></tr></table> | ||
29 | <p> | ||
30 | </p> | ||
31 | <p> | ||
32 | BitBake needs some basic configuration files in order to complete | ||
33 | a build. | ||
34 | These files are <code class="filename">*.conf</code> files. | ||
35 | The minimally necessary ones reside as example files in the | ||
36 | <a class="link" href="../ref-manual/source-directory.html" target="_self">Source Directory</a>. | ||
37 | For simplicity, this section refers to the Source Directory as | ||
38 | the "Poky Directory." | ||
39 | </p> | ||
40 | <p> | ||
41 | When you clone the <code class="filename">poky</code> Git repository or you | ||
42 | download and unpack a Yocto Project release, you can set up the | ||
43 | Source Directory to be named anything you want. | ||
44 | For this discussion, the cloned repository uses the default | ||
45 | name <code class="filename">poky</code>. | ||
46 | </p> | ||
47 | <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"> | ||
48 | <h3 class="title">Note</h3> | ||
49 | The Poky repository is primarily an aggregation of existing | ||
50 | repositories. | ||
51 | It is not a canonical upstream source. | ||
52 | </div> | ||
53 | <p> | ||
54 | </p> | ||
55 | <p> | ||
56 | The <code class="filename">meta-poky</code> layer inside Poky contains | ||
57 | a <code class="filename">conf</code> directory that has example | ||
58 | configuration files. | ||
59 | These example files are used as a basis for creating actual | ||
60 | configuration files when you source the build environment | ||
61 | script | ||
62 | (i.e. | ||
63 | <a class="link" href="../ref-manual/structure-core-script.html" target="_self"><code class="filename">oe-init-build-env</code></a>). | ||
64 | </p> | ||
65 | <p> | ||
66 | Sourcing the build environment script creates a | ||
67 | <a class="link" href="../ref-manual/build-directory.html" target="_self">Build Directory</a> | ||
68 | if one does not already exist. | ||
69 | BitBake uses the Build Directory for all its work during builds. | ||
70 | The Build Directory has a <code class="filename">conf</code> directory that | ||
71 | contains default versions of your <code class="filename">local.conf</code> | ||
72 | and <code class="filename">bblayers.conf</code> configuration files. | ||
73 | These default configuration files are created only if versions | ||
74 | do not already exist in the Build Directory at the time you | ||
75 | source the build environment setup script. | ||
76 | </p> | ||
77 | <p> | ||
78 | Because the Poky repository is fundamentally an aggregation of | ||
79 | existing repositories, some users might be familiar with running | ||
80 | the <code class="filename">oe-init-build-env</code> script in the context | ||
81 | of separate OpenEmbedded-Core and BitBake repositories rather than a | ||
82 | single Poky repository. | ||
83 | This discussion assumes the script is executed from within a cloned | ||
84 | or unpacked version of Poky. | ||
85 | </p> | ||
86 | <p> | ||
87 | Depending on where the script is sourced, different sub-scripts | ||
88 | are called to set up the Build Directory (Yocto or OpenEmbedded). | ||
89 | Specifically, the script | ||
90 | <code class="filename">scripts/oe-setup-builddir</code> inside the | ||
91 | poky directory sets up the Build Directory and seeds the directory | ||
92 | (if necessary) with configuration files appropriate for the | ||
93 | Yocto Project development environment. | ||
94 | </p> | ||
95 | <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"> | ||
96 | <h3 class="title">Note</h3> | ||
97 | The <code class="filename">scripts/oe-setup-builddir</code> script | ||
98 | uses the <code class="filename">$TEMPLATECONF</code> variable to | ||
99 | determine which sample configuration files to locate. | ||
100 | </div> | ||
101 | <p> | ||
102 | </p> | ||
103 | <p> | ||
104 | The <code class="filename">local.conf</code> file provides many | ||
105 | basic variables that define a build environment. | ||
106 | Here is a list of a few. | ||
107 | To see the default configurations in a <code class="filename">local.conf</code> | ||
108 | file created by the build environment script, see the | ||
109 | <code class="filename">local.conf.sample</code> in the | ||
110 | <code class="filename">meta-poky</code> layer: | ||
111 | </p> | ||
112 | <div class="itemizedlist"><ul class="itemizedlist" type="disc"> | ||
113 | <li class="listitem"><p><span class="emphasis"><em>Parallelism Options:</em></span> | ||
114 | Controlled by the | ||
115 | <a class="link" href="../ref-manual/var-BB_NUMBER_THREADS.html" target="_self"><code class="filename">BB_NUMBER_THREADS</code></a>, | ||
116 | <a class="link" href="../ref-manual/var-PARALLEL_MAKE.html" target="_self"><code class="filename">PARALLEL_MAKE</code></a>, | ||
117 | and | ||
118 | <a class="link" href="../bitbake-user-manual/var-BB_NUMBER_PARSE_THREADS.html" target="_self"><code class="filename">BB_NUMBER_PARSE_THREADS</code></a> | ||
119 | variables.</p></li> | ||
120 | <li class="listitem"><p><span class="emphasis"><em>Target Machine Selection:</em></span> | ||
121 | Controlled by the | ||
122 | <a class="link" href="../ref-manual/var-MACHINE.html" target="_self"><code class="filename">MACHINE</code></a> | ||
123 | variable.</p></li> | ||
124 | <li class="listitem"><p><span class="emphasis"><em>Download Directory:</em></span> | ||
125 | Controlled by the | ||
126 | <a class="link" href="../ref-manual/var-DL_DIR.html" target="_self"><code class="filename">DL_DIR</code></a> | ||
127 | variable.</p></li> | ||
128 | <li class="listitem"><p><span class="emphasis"><em>Shared State Directory:</em></span> | ||
129 | Controlled by the | ||
130 | <a class="link" href="../ref-manual/var-SSTATE_DIR.html" target="_self"><code class="filename">SSTATE_DIR</code></a> | ||
131 | variable.</p></li> | ||
132 | <li class="listitem"><p><span class="emphasis"><em>Build Output:</em></span> | ||
133 | Controlled by the | ||
134 | <a class="link" href="../ref-manual/var-TMPDIR.html" target="_self"><code class="filename">TMPDIR</code></a> | ||
135 | variable.</p></li> | ||
136 | </ul></div> | ||
137 | <p> | ||
138 | </p> | ||
139 | <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"> | ||
140 | <h3 class="title">Note</h3> | ||
141 | Configurations set in the <code class="filename">conf/local.conf</code> | ||
142 | file can also be set in the | ||
143 | <code class="filename">conf/site.conf</code> and | ||
144 | <code class="filename">conf/auto.conf</code> configuration files. | ||
145 | </div> | ||
146 | <p> | ||
147 | </p> | ||
148 | <p> | ||
149 | The <code class="filename">bblayers.conf</code> file tells BitBake what | ||
150 | layers you want considered during the build. | ||
151 | By default, the layers listed in this file include layers | ||
152 | minimally needed by the build system. | ||
153 | However, you must manually add any custom layers you have created. | ||
154 | You can find more information on working with the | ||
155 | <code class="filename">bblayers.conf</code> file in the | ||
156 | "<a class="link" href="../dev-manual/enabling-your-layer.html" target="_self">Enabling Your Layer</a>" | ||
157 | section in the Yocto Project Development Tasks Manual. | ||
158 | </p> | ||
159 | <p> | ||
160 | The files <code class="filename">site.conf</code> and | ||
161 | <code class="filename">auto.conf</code> are not created by the environment | ||
162 | initialization script. | ||
163 | If you want the <code class="filename">site.conf</code> file, you need to | ||
164 | create that yourself. | ||
165 | The <code class="filename">auto.conf</code> file is typically created by | ||
166 | an autobuilder: | ||
167 | </p> | ||
168 | <div class="itemizedlist"><ul class="itemizedlist" type="disc"> | ||
169 | <li class="listitem"> | ||
170 | <p><span class="emphasis"><em><code class="filename">site.conf</code>:</em></span> | ||
171 | You can use the <code class="filename">conf/site.conf</code> | ||
172 | configuration file to configure multiple build directories. | ||
173 | For example, suppose you had several build environments and | ||
174 | they shared some common features. | ||
175 | You can set these default build properties here. | ||
176 | A good example is perhaps the packaging format to use | ||
177 | through the | ||
178 | <a class="link" href="../ref-manual/var-PACKAGE_CLASSES.html" target="_self"><code class="filename">PACKAGE_CLASSES</code></a> | ||
179 | variable.</p> | ||
180 | <p>One useful scenario for using the | ||
181 | <code class="filename">conf/site.conf</code> file is to extend your | ||
182 | <a class="link" href="../ref-manual/var-BBPATH.html" target="_self"><code class="filename">BBPATH</code></a> | ||
183 | variable to include the path to a | ||
184 | <code class="filename">conf/site.conf</code>. | ||
185 | Then, when BitBake looks for Metadata using | ||
186 | <code class="filename">BBPATH</code>, it finds the | ||
187 | <code class="filename">conf/site.conf</code> file and applies your | ||
188 | common configurations found in the file. | ||
189 | To override configurations in a particular build directory, | ||
190 | alter the similar configurations within that build | ||
191 | directory's <code class="filename">conf/local.conf</code> file. | ||
192 | </p> | ||
193 | </li> | ||
194 | <li class="listitem"><p><span class="emphasis"><em><code class="filename">auto.conf</code>:</em></span> | ||
195 | The file is usually created and written to by | ||
196 | an autobuilder. | ||
197 | The settings put into the file are typically the same as | ||
198 | you would find in the <code class="filename">conf/local.conf</code> | ||
199 | or the <code class="filename">conf/site.conf</code> files. | ||
200 | </p></li> | ||
201 | </ul></div> | ||
202 | <p> | ||
203 | </p> | ||
204 | <p> | ||
205 | You can edit all configuration files to further define | ||
206 | any particular build environment. | ||
207 | This process is represented by the "User Configuration Edits" | ||
208 | box in the figure. | ||
209 | </p> | ||
210 | <p> | ||
211 | When you launch your build with the | ||
212 | <code class="filename">bitbake <em class="replaceable"><code>target</code></em></code> | ||
213 | command, BitBake sorts out the configurations to ultimately | ||
214 | define your build environment. | ||
215 | It is important to understand that the OpenEmbedded build system | ||
216 | reads the configuration files in a specific order: | ||
217 | <code class="filename">site.conf</code>, <code class="filename">auto.conf</code>, | ||
218 | and <code class="filename">local.conf</code>. | ||
219 | And, the build system applies the normal assignment statement | ||
220 | rules. | ||
221 | Because the files are parsed in a specific order, variable | ||
222 | assignments for the same variable could be affected. | ||
223 | For example, if the <code class="filename">auto.conf</code> file and | ||
224 | the <code class="filename">local.conf</code> set | ||
225 | <em class="replaceable"><code>variable1</code></em> to different values, because | ||
226 | the build system parses <code class="filename">local.conf</code> after | ||
227 | <code class="filename">auto.conf</code>, | ||
228 | <em class="replaceable"><code>variable1</code></em> is assigned the value from | ||
229 | the <code class="filename">local.conf</code> file. | ||
230 | </p> | ||
231 | </div></body> | ||
232 | </html> | ||