summaryrefslogtreecommitdiffstats
path: root/documentation
diff options
context:
space:
mode:
Diffstat (limited to 'documentation')
-rw-r--r--documentation/dev-manual/dev-manual-start.xml212
1 files changed, 113 insertions, 99 deletions
diff --git a/documentation/dev-manual/dev-manual-start.xml b/documentation/dev-manual/dev-manual-start.xml
index d8726b4857..f72606553a 100644
--- a/documentation/dev-manual/dev-manual-start.xml
+++ b/documentation/dev-manual/dev-manual-start.xml
@@ -10,8 +10,10 @@
10 This chapter provides procedures related to getting set up to use the 10 This chapter provides procedures related to getting set up to use the
11 Yocto Project. 11 Yocto Project.
12 You can learn about creating a team environment that develops using the 12 You can learn about creating a team environment that develops using the
13 Yocto Project, how to set up a build host, how to locate Yocto Project 13 Yocto Project, how to set up a
14 source repositories, and how to create local Git repositories. 14 <ulink url='&YOCTO_DOCS_REF_URL;#hardware-build-system-term'>build host</ulink>,
15 how to locate Yocto Project source repositories, and how to create local
16 Git repositories.
15</para> 17</para>
16 18
17<section id="usingpoky-changes-collaborate"> 19<section id="usingpoky-changes-collaborate">
@@ -19,69 +21,71 @@
19 21
20 <para> 22 <para>
21 It might not be immediately clear how you can use the Yocto 23 It might not be immediately clear how you can use the Yocto
22 Project in a team development environment, or scale it for a large 24 Project in a team development environment, or how to scale it for a
23 team of developers. 25 large team of developers.
24 One of the strengths of the Yocto Project is that it is extremely 26 One of the strengths of the Yocto Project is that it is extremely
25 flexible. 27 flexible.
26 Thus, you can adapt it to many different use cases and scenarios. 28 Thus, you can adapt it to many different use cases and scenarios.
27 However, these characteristics can cause a struggle if you are trying 29 However, this flexibility could cause difficulties if you are trying
28 to create a working setup that scales across a large team. 30 to create a working setup that scales across a large team.
29 </para> 31 </para>
30 32
31 <para> 33 <para>
32 To help you understand how to set up this type of environment, 34 To help you understand how to set up this type of environment,
33 this section presents a procedure that gives you the information 35 this section presents a procedure that gives you information
34 to learn how to get the results you want. 36 that can help you get the results you want.
35 The procedure is high-level and presents some of the project's most 37 The procedure is high-level and presents some of the project's most
36 successful experiences, practices, solutions, and available 38 successful experiences, practices, solutions, and available
37 technologies that work well. 39 technologies that have proved to work well in the past.
38 Keep in mind, the procedure here is a starting point. 40 Keep in mind, the procedure here is a starting point.
39 You can build off it and customize it to fit any 41 You can build off these steps and customize the procedure to fit any
40 particular working environment and set of practices. 42 particular working environment and set of practices.
41 <orderedlist> 43 <orderedlist>
42 <listitem><para> 44 <listitem><para>
43 <emphasis>Determine Who is Going to be Developing:</emphasis> 45 <emphasis>Determine Who is Going to be Developing:</emphasis>
44 You need to understand who is going to be doing anything 46 You need to understand who is going to be doing anything
45 related to the Yocto Project and what their roles would be. 47 related to the Yocto Project and what their roles would be.
46 Making this determination is essential to completing the 48 Making this determination is essential to completing
47 steps two and three, which are to get your equipment together 49 steps two and three, which are to get your equipment together
48 and set up your development environment's hardware topology. 50 and set up your development environment's hardware topology.
49 </para> 51 </para>
50 52
51 <para>The following roles exist: 53 <para>The following roles exist:
52 <itemizedlist> 54 <itemizedlist>
53 <listitem><para> 55 <listitem><para>
54 <emphasis>Application Development:</emphasis> 56 <emphasis>Application Developer:</emphasis>
55 These types of developers do application level work 57 This type of developer does application level work
56 on top of an existing software stack. 58 on top of an existing software stack.
57 </para></listitem> 59 </para></listitem>
58 <listitem><para> 60 <listitem><para>
59 <emphasis>Core System Development:</emphasis> 61 <emphasis>Core System Developer:</emphasis>
60 These types of developers work on the contents of the 62 This type of developer works on the contents of the
61 operating system image itself. 63 operating system image itself.
62 </para></listitem> 64 </para></listitem>
63 <listitem><para> 65 <listitem><para>
64 <emphasis>Build Engineer:</emphasis> 66 <emphasis>Build Engineer:</emphasis>
65 This type of developer manages Autobuilders and 67 This type of developer manages Autobuilders and
66 releases. 68 releases.
67 Not all environments need a Build Engineer. 69 Not all environments need a Build Engineer.
68 </para></listitem> 70 </para></listitem>
69 <listitem><para> 71 <listitem><para>
70 <emphasis>Test Engineer:</emphasis> 72 <emphasis>Test Engineer:</emphasis>
71 This type of developer creates and manages automated 73 This type of developer creates and manages automated
72 tests needed to ensure all application and core 74 tests that are used to ensure all application and
73 system development meets desired quality standards. 75 core system development meets desired quality
74 </para></listitem> 76 standards.
75 </itemizedlist> 77 </para></listitem>
78 </itemizedlist>
76 </para></listitem> 79 </para></listitem>
77 <listitem><para> 80 <listitem><para>
78 <emphasis>Gather the Hardware:</emphasis> 81 <emphasis>Gather the Hardware:</emphasis>
79 Based on the size and make-up of the team, get the hardware 82 Based on the size and make-up of the team, get the hardware
80 together. 83 together.
81 Any development, build, or test engineer should be using 84 Ideally, any development, build, or test engineer uses
82 a system that is running a supported Linux distribution. 85 a system that runs a supported Linux distribution.
83 Systems, in general, should be high performance (e.g. dual, 86 These systems, in general, should be high performance
84 six-core Xeons with 24 Gbytes of RAM and plenty of disk space). 87 (e.g. dual, six-core Xeons with 24 Gbytes of RAM and plenty
88 of disk space).
85 You can help ensure efficiency by having any machines used 89 You can help ensure efficiency by having any machines used
86 for testing or that run Autobuilders be as high performance 90 for testing or that run Autobuilders be as high performance
87 as possible. 91 as possible.
@@ -107,11 +111,12 @@
107 <emphasis>Use Git as Your Source Control Manager (SCM):</emphasis> 111 <emphasis>Use Git as Your Source Control Manager (SCM):</emphasis>
108 Keeping your 112 Keeping your
109 <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink> 113 <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink>
110 and any software you are developing under the 114 (i.e. recipes, configuration files, classes, and so forth)
111 control of an SCM system that is compatible 115 and any software you are developing under the control of an SCM
112 with the OpenEmbedded build system is advisable. 116 system that is compatible with the OpenEmbedded build system
113 Of the SCMs BitBake supports, the 117 is advisable.
114 Yocto Project team strongly recommends using 118 Of the SCMs BitBake supports, the Yocto Project team strongly
119 recommends using
115 <ulink url='&YOCTO_DOCS_OM_URL;#git'>Git</ulink>. 120 <ulink url='&YOCTO_DOCS_OM_URL;#git'>Git</ulink>.
116 Git is a distributed system that is easy to backup, 121 Git is a distributed system that is easy to backup,
117 allows you to work remotely, and then connects back to the 122 allows you to work remotely, and then connects back to the
@@ -129,20 +134,19 @@
129 being used to generate the web interface that lets you view the 134 being used to generate the web interface that lets you view the
130 repositories. 135 repositories.
131 The <filename>gitolite</filename> software identifies users 136 The <filename>gitolite</filename> software identifies users
132 using SSH keys and allows branch-based 137 using SSH keys and allows branch-based access controls to
133 access controls to repositories that you can control as little 138 repositories that you can control as little or as much as
134 or as much as necessary. 139 necessary.
135
136 <note> 140 <note>
137 The setup of these services is beyond the scope of this 141 The setup of these services is beyond the scope of this
138 manual. 142 manual.
139 However, sites such as these exist that describe how to 143 However, sites such as the following exist that describe
140 perform setup: 144 how to perform setup:
141 <itemizedlist> 145 <itemizedlist>
142 <listitem><para> 146 <listitem><para>
143 <ulink url='http://git-scm.com/book/ch4-8.html'>Git documentation</ulink>: 147 <ulink url='http://git-scm.com/book/ch4-8.html'>Git documentation</ulink>:
144 Describes how to install <filename>gitolite</filename> 148 Describes how to install
145 on the server. 149 <filename>gitolite</filename> on the server.
146 </para></listitem> 150 </para></listitem>
147 <listitem><para> 151 <listitem><para>
148 <ulink url='http://gitolite.com'>Gitolite</ulink>: 152 <ulink url='http://gitolite.com'>Gitolite</ulink>:
@@ -150,8 +154,8 @@
150 </para></listitem> 154 </para></listitem>
151 <listitem><para> 155 <listitem><para>
152 <ulink url='https://git.wiki.kernel.org/index.php/Interfaces,_frontends,_and_tools'>Interfaces, frontends, and tools</ulink>: 156 <ulink url='https://git.wiki.kernel.org/index.php/Interfaces,_frontends,_and_tools'>Interfaces, frontends, and tools</ulink>:
153 Documentation on how to create interfaces and frontends 157 Documentation on how to create interfaces and
154 for Git. 158 frontends for Git.
155 </para></listitem> 159 </para></listitem>
156 </itemizedlist> 160 </itemizedlist>
157 </note> 161 </note>
@@ -161,23 +165,22 @@
161 As mentioned earlier, application developers are creating 165 As mentioned earlier, application developers are creating
162 applications on top of existing software stacks. 166 applications on top of existing software stacks.
163 Following are some best practices for setting up machines 167 Following are some best practices for setting up machines
164 that do application development: 168 used for application development:
165 <itemizedlist> 169 <itemizedlist>
166 <listitem><para> 170 <listitem><para>
167 Use a pre-built toolchain that 171 Use a pre-built toolchain that contains the software
168 contains the software stack itself. 172 stack itself.
169 Then, develop the application code on top of the 173 Then, develop the application code on top of the
170 stack. 174 stack.
171 This method works well for small numbers of relatively 175 This method works well for small numbers of relatively
172 isolated applications. 176 isolated applications.
173 </para></listitem> 177 </para></listitem>
174 <listitem><para> 178 <listitem><para>
175 When possible, use the Yocto Project 179 When possible, use the Yocto Project plug-in for the
176 plug-in for the
177 <trademark class='trade'>Eclipse</trademark> IDE 180 <trademark class='trade'>Eclipse</trademark> IDE
178 and SDK development practices. 181 and SDK development practices.
179 For more information, see the 182 For more information, see the
180 "<ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink>" 183 <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink>
181 manual. 184 manual.
182 </para></listitem> 185 </para></listitem>
183 <listitem><para> 186 <listitem><para>
@@ -186,27 +189,29 @@
186 toolchain downloads or as updates through a package 189 toolchain downloads or as updates through a package
187 update mechanism using <filename>opkg</filename> 190 update mechanism using <filename>opkg</filename>
188 to provide updates to an existing toolchain. 191 to provide updates to an existing toolchain.
189 The exact mechanics of how and when to do this are a 192 The exact mechanics of how and when to do this depend
190 question for local policy. 193 on local policy.
191 </para></listitem> 194 </para></listitem>
192 <listitem><para> 195 <listitem><para>
193 Use multiple toolchains installed locally 196 Use multiple toolchains installed locally into
194 into different locations to allow development across 197 different locations to allow development across
195 versions. 198 versions.
196 </para></listitem> 199 </para></listitem>
197 </itemizedlist> 200 </itemizedlist>
198 </para></listitem> 201 </para></listitem>
199 <listitem><para> 202 <listitem><para>
200 <emphasis>Set up the Core Development Machines:</emphasis> 203 <emphasis>Set up the Core Development Machines:</emphasis>
201 As mentioned earlier, these types of developers work on the 204 As mentioned earlier, core developers work on the contents of
202 contents of the operating system itself. 205 the operating system itself.
203 Following are some best practices for setting up machines 206 Following are some best practices for setting up machines
204 used for developing images: 207 used for developing images:
205 <itemizedlist> 208 <itemizedlist>
206 <listitem><para> 209 <listitem><para>
207 Have the Yocto Project build system itself available on 210 Have the
208 the developer workstations so developers can run their own 211 <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink>
209 builds and directly rebuild the software stack. 212 available on the developer workstations so developers
213 can run their own builds and directly rebuild the
214 software stack.
210 </para></listitem> 215 </para></listitem>
211 <listitem><para> 216 <listitem><para>
212 Keep the core system unchanged as much as 217 Keep the core system unchanged as much as
@@ -228,8 +233,9 @@
228 Autobuilders are often the core of the development 233 Autobuilders are often the core of the development
229 environment. 234 environment.
230 It is here that changes from individual developers are brought 235 It is here that changes from individual developers are brought
231 together and centrally tested and subsequent decisions about 236 together and centrally tested.
232 releases can be made. 237 Based on this automated build and test environment, subsequent
238 decisions about releases can be made.
233 Autobuilders also allow for "continuous integration" style 239 Autobuilders also allow for "continuous integration" style
234 testing of software components and regression identification 240 testing of software components and regression identification
235 and tracking.</para> 241 and tracking.</para>
@@ -239,22 +245,23 @@
239 The Yocto Project team has found this implementation 245 The Yocto Project team has found this implementation
240 works well in this role. 246 works well in this role.
241 A public example of this is the Yocto Project 247 A public example of this is the Yocto Project
242 Autobuilders, which we use to test the overall health of the 248 Autobuilders, which the Yocto Project team uses to test the
243 project.</para> 249 overall health of the project.</para>
244 250
245 <para>The features of this system are: 251 <para>The features of this system are:
246 <itemizedlist> 252 <itemizedlist>
247 <listitem><para> 253 <listitem><para>
248 Highlights when commits break the build. 254 Highlights when commits break the build.
249 </para></listitem> 255 </para></listitem>
250 <listitem><para> 256 <listitem><para>
251 Populates an sstate cache from which 257 Populates an
252 developers can pull rather than requiring local 258 <ulink url='&YOCTO_DOCS_OM_URL;#shared-state-cache'>sstate cache</ulink>
253 builds. 259 from which developers can pull rather than requiring
260 local builds.
254 </para></listitem> 261 </para></listitem>
255 <listitem><para> 262 <listitem><para>
256 Allows commit hook triggers, 263 Allows commit hook triggers, which trigger builds when
257 which trigger builds when commits are made. 264 commits are made.
258 </para></listitem> 265 </para></listitem>
259 <listitem><para> 266 <listitem><para>
260 Allows triggering of automated image booting 267 Allows triggering of automated image booting
@@ -275,19 +282,19 @@
275 Allows scheduling of builds so that resources 282 Allows scheduling of builds so that resources
276 can be used efficiently. 283 can be used efficiently.
277 </para></listitem> 284 </para></listitem>
278 </itemizedlist> 285 </itemizedlist>
279 </para></listitem> 286 </para></listitem>
280 <listitem><para> 287 <listitem><para>
281 <emphasis>Set up Test Machines:</emphasis> 288 <emphasis>Set up Test Machines:</emphasis>
282 Use a small number of shared, high performance systems 289 Use a small number of shared, high performance systems
283 for testing purposes. 290 for testing purposes.
284 Developers can use these systems for wider, more 291 Developers can use these systems for wider, more
285 extensive testing while they continue to develop 292 extensive testing while they continue to develop
286 locally using their primary development system. 293 locally using their primary development system.
287 </para></listitem> 294 </para></listitem>
288 <listitem><para> 295 <listitem><para>
289 <emphasis>Document Policies and Change Flow:</emphasis> 296 <emphasis>Document Policies and Change Flow:</emphasis>
290 The Yocto Project itself uses a hierarchical structure and a 297 The Yocto Project uses a hierarchical structure and a
291 pull model. 298 pull model.
292 Scripts exist to create and send pull requests 299 Scripts exist to create and send pull requests
293 (i.e. <filename>create-pull-request</filename> and 300 (i.e. <filename>create-pull-request</filename> and
@@ -330,16 +337,20 @@
330 <listitem><para> 337 <listitem><para>
331 Maintain your Metadata in layers that make sense 338 Maintain your Metadata in layers that make sense
332 for your situation. 339 for your situation.
333 See the "<link linkend='understanding-and-creating-layers'>Understanding 340 See the
334 and Creating Layers</link>" section for more information on 341 "<ulink url='&YOCTO_DOCS_OM_URL;#the-yocto-project-layer-model'>The Yocto Project Layer Model</ulink>"
335 layers. 342 section in the Yocto Project Overview and Concepts
343 Manual and the
344 "<link linkend='understanding-and-creating-layers'>Understanding and Creating Layers</link>"
345 section for more information on layers.
336 </para></listitem> 346 </para></listitem>
337 <listitem><para> 347 <listitem><para>
338 Separate the project's Metadata and code by using 348 Separate the project's Metadata and code by using
339 separate Git repositories. 349 separate Git repositories.
340 See the 350 See the
341 "<ulink url='&YOCTO_DOCS_OM_URL;#yocto-project-repositories'>Yocto Project Source Repositories</ulink>" 351 "<ulink url='&YOCTO_DOCS_OM_URL;#yocto-project-repositories'>Yocto Project Source Repositories</ulink>"
342 section for information on these repositories. 352 section in the Yocto Project Overview and Concepts
353 Manual for information on these repositories.
343 See the 354 See the
344 "<link linkend='locating-yocto-project-source-files'>Locating Yocto Project Source Files</link>" 355 "<link linkend='locating-yocto-project-source-files'>Locating Yocto Project Source Files</link>"
345 section for information on how to set up local Git 356 section for information on how to set up local Git
@@ -360,7 +371,8 @@
360 </para></listitem> 371 </para></listitem>
361 <listitem><para> 372 <listitem><para>
362 The Yocto Project community encourages you 373 The Yocto Project community encourages you
363 to send patches to the project to fix bugs or add features. 374 to send patches to the project to fix bugs or add
375 features.
364 If you do submit patches, follow the project commit 376 If you do submit patches, follow the project commit
365 guidelines for writing good commit messages. 377 guidelines for writing good commit messages.
366 See the "<link linkend='how-to-submit-a-change'>Submitting a Change to the Yocto Project</link>" 378 See the "<link linkend='how-to-submit-a-change'>Submitting a Change to the Yocto Project</link>"
@@ -369,10 +381,12 @@
369 <listitem><para> 381 <listitem><para>
370 Send changes to the core sooner than later 382 Send changes to the core sooner than later
371 as others are likely to run into the same issues. 383 as others are likely to run into the same issues.
372 For some guidance on mailing lists to use, see the list in the 384 For some guidance on mailing lists to use, see the list
385 in the
373 "<link linkend='how-to-submit-a-change'>Submitting a Change to the Yocto Project</link>" 386 "<link linkend='how-to-submit-a-change'>Submitting a Change to the Yocto Project</link>"
374 section. 387 section.
375 For a description of the available mailing lists, see the 388 For a description of the available mailing lists, see
389 the
376 "<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing Lists</ulink>" 390 "<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing Lists</ulink>"
377 section in the Yocto Project Reference Manual. 391 section in the Yocto Project Reference Manual.
378 </para></listitem> 392 </para></listitem>