diff options
author | Scott Rifenbark <srifenbark@gmail.com> | 2018-01-29 15:18:03 -0800 |
---|---|---|
committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2018-02-14 15:25:29 +0000 |
commit | ae06e04cd225d2c2147ca355e2dd39b4f6cf6775 (patch) | |
tree | c920e85262a91e7626279e7dcbbd56a299919f49 /documentation/getting-started/eclipse/html/getting-started/user-configuration.html | |
parent | ebc7de094881dd8f2450aa4fdf548f2e9c835df1 (diff) | |
download | poky-ae06e04cd225d2c2147ca355e2dd39b4f6cf6775.tar.gz |
documentation: Created new "Getting Started" manual.
Creation involved removing the overview-manual and replacing it
with the getting-started manual. All links to the string
"&YOCTO_DOCS_OVERVIEW_URL" had to be replaced with
"&YOCTO_DOCS_GS_URL" across the entire YP manual set. I renamed
files used to create the manual with prefixes suited for the
new manual name, which is "Getting Started With Yocto Project".
The style sheet for the new manual needed updating to display the
new .PNG image for the title page. The mega-manual file had to
be updated to include the files. The mega-manual.sed file had
to be updated to include the new manual and not use the overview
manual.
(From yocto-docs rev: 6c7abf9192390121000f577d6c98f259d290d15d)
Signed-off-by: Scott Rifenbark <srifenbark@gmail.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
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> | ||