summaryrefslogtreecommitdiffstats
path: root/documentation/getting-started/eclipse/html/getting-started/user-configuration.html
diff options
context:
space:
mode:
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.html232
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>
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-05-01 06:23:51 +0000