summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2018-05-16 13:10:58 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2018-05-24 17:16:34 +0100
commitd38c9ba94aada3d07eb9b6700a2a16b9e205252a (patch)
treec9b6ff6382fa353ed714bd02941066a37a245707
parent222824948893d10b1183b38b1593a9bb13de63c7 (diff)
downloadpoky-d38c9ba94aada3d07eb9b6700a2a16b9e205252a.tar.gz
dev-manual: Moved section on setting up a team YP environment
This section was in the chapter on the open source development environment. It is better suited to be in a newly named chapter "Setting Up to Use the Yocto Project". I have moved it. (From yocto-docs rev: 028f8f7a1b93a023a99ffadb01b0da699b4081c2) Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat
-rw-r--r--documentation/dev-manual/dev-manual-newbie.xml368
-rw-r--r--documentation/dev-manual/dev-manual-start.xml378
2 files changed, 374 insertions, 372 deletions
diff --git a/documentation/dev-manual/dev-manual-newbie.xml b/documentation/dev-manual/dev-manual-newbie.xml
index 40328b1135..27e1d04761 100644
--- a/documentation/dev-manual/dev-manual-newbie.xml
+++ b/documentation/dev-manual/dev-manual-newbie.xml
@@ -6,374 +6,6 @@
6 6
7<title>The Yocto Project Open Source Development Environment</title> 7<title>The Yocto Project Open Source Development Environment</title>
8 8
9<section id="usingpoky-changes-collaborate">
10 <title>Setting Up a Team Yocto Project Development Environment</title>
11
12 <para>
13 It might not be immediately clear how you can use the Yocto
14 Project in a team development environment, or scale it for a large
15 team of developers.
16 One of the strengths of the Yocto Project is that it is extremely
17 flexible.
18 Thus, you can adapt it to many different use cases and scenarios.
19 However, these characteristics can cause a struggle if you are trying
20 to create a working setup that scales across a large team.
21 </para>
22
23 <para>
24 To help you understand how to set up this type of environment,
25 this section presents a procedure that gives you the information
26 to learn how to get the results you want.
27 The procedure is high-level and presents some of the project's most
28 successful experiences, practices, solutions, and available
29 technologies that work well.
30 Keep in mind, the procedure here is a starting point.
31 You can build off it and customize it to fit any
32 particular working environment and set of practices.
33 <orderedlist>
34 <listitem><para>
35 <emphasis>Determine Who is Going to be Developing:</emphasis>
36 You need to understand who is going to be doing anything
37 related to the Yocto Project and what their roles would be.
38 Making this determination is essential to completing the
39 steps two and three, which are to get your equipment together
40 and set up your development environment's hardware topology.
41 </para>
42
43 <para>The following roles exist:
44 <itemizedlist>
45 <listitem><para>
46 <emphasis>Application Development:</emphasis>
47 These types of developers do application level work
48 on top of an existing software stack.
49 </para></listitem>
50 <listitem><para>
51 <emphasis>Core System Development:</emphasis>
52 These types of developers work on the contents of the
53 operating system image itself.
54 </para></listitem>
55 <listitem><para>
56 <emphasis>Build Engineer:</emphasis>
57 This type of developer manages Autobuilders and
58 releases.
59 Not all environments need a Build Engineer.
60 </para></listitem>
61 <listitem><para>
62 <emphasis>Test Engineer:</emphasis>
63 This type of developer creates and manages automated
64 tests needed to ensure all application and core
65 system development meets desired quality standards.
66 </para></listitem>
67 </itemizedlist>
68 </para></listitem>
69 <listitem><para>
70 <emphasis>Gather the Hardware:</emphasis>
71 Based on the size and make-up of the team, get the hardware
72 together.
73 Any development, build, or test engineer should be using
74 a system that is running a supported Linux distribution.
75 Systems, in general, should be high performance (e.g. dual,
76 six-core Xeons with 24 Gbytes of RAM and plenty of disk space).
77 You can help ensure efficiency by having any machines used
78 for testing or that run Autobuilders be as high performance
79 as possible.
80 </para></listitem>
81 <listitem><para>
82 <emphasis>Understand the Hardware Topology of the Environment:</emphasis>
83 Once you understand the hardware involved and the make-up
84 of the team, you can understand the hardware topology of the
85 development environment.
86 You can get a visual idea of the machines and their roles
87 across the development environment.
88
89<!--
90 The following figure shows a moderately sized Yocto Project
91 development environment.
92
93 <para role="writernotes">
94 Need figure.</para>
95-->
96
97 </para></listitem>
98 <listitem><para>
99 <emphasis>Use Git as Your Source Control Manager (SCM):</emphasis>
100 Keeping your
101 <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink>
102 and any software you are developing under the
103 control of an SCM system that is compatible
104 with the OpenEmbedded build system is advisable.
105 Of the SCMs BitBake supports, the
106 Yocto Project team strongly recommends using
107 <ulink url='&YOCTO_DOCS_OM_URL;#git'>Git</ulink>.
108 Git is a distributed system that is easy to backup,
109 allows you to work remotely, and then connects back to the
110 infrastructure.
111 <note>
112 For information about BitBake, see the
113 <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>.
114 </note></para>
115
116 <para>It is relatively easy to set up Git services and create
117 infrastructure like
118 <ulink url='&YOCTO_GIT_URL;'>http://git.yoctoproject.org</ulink>,
119 which is based on server software called
120 <filename>gitolite</filename> with <filename>cgit</filename>
121 being used to generate the web interface that lets you view the
122 repositories.
123 The <filename>gitolite</filename> software identifies users
124 using SSH keys and allows branch-based
125 access controls to repositories that you can control as little
126 or as much as necessary.
127
128 <note>
129 The setup of these services is beyond the scope of this
130 manual.
131 However, sites such as these exist that describe how to
132 perform setup:
133 <itemizedlist>
134 <listitem><para>
135 <ulink url='http://git-scm.com/book/ch4-8.html'>Git documentation</ulink>:
136 Describes how to install <filename>gitolite</filename>
137 on the server.
138 </para></listitem>
139 <listitem><para>
140 <ulink url='http://gitolite.com'>Gitolite</ulink>:
141 Information for <filename>gitolite</filename>.
142 </para></listitem>
143 <listitem><para>
144 <ulink url='https://git.wiki.kernel.org/index.php/Interfaces,_frontends,_and_tools'>Interfaces, frontends, and tools</ulink>:
145 Documentation on how to create interfaces and frontends
146 for Git.
147 </para></listitem>
148 </itemizedlist>
149 </note>
150 </para></listitem>
151 <listitem><para>
152 <emphasis>Set up the Application Development Machines:</emphasis>
153 As mentioned earlier, application developers are creating
154 applications on top of existing software stacks.
155 Following are some best practices for setting up machines
156 that do application development:
157 <itemizedlist>
158 <listitem><para>
159 Use a pre-built toolchain that
160 contains the software stack itself.
161 Then, develop the application code on top of the
162 stack.
163 This method works well for small numbers of relatively
164 isolated applications.
165 </para></listitem>
166 <listitem><para>
167 When possible, use the Yocto Project
168 plug-in for the
169 <trademark class='trade'>Eclipse</trademark> IDE
170 and SDK development practices.
171 For more information, see the
172 "<ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink>"
173 manual.
174 </para></listitem>
175 <listitem><para>
176 Keep your cross-development toolchains updated.
177 You can do this through provisioning either as new
178 toolchain downloads or as updates through a package
179 update mechanism using <filename>opkg</filename>
180 to provide updates to an existing toolchain.
181 The exact mechanics of how and when to do this are a
182 question for local policy.
183 </para></listitem>
184 <listitem><para>
185 Use multiple toolchains installed locally
186 into different locations to allow development across
187 versions.
188 </para></listitem>
189 </itemizedlist>
190 </para></listitem>
191 <listitem><para>
192 <emphasis>Set up the Core Development Machines:</emphasis>
193 As mentioned earlier, these types of developers work on the
194 contents of the operating system itself.
195 Following are some best practices for setting up machines
196 used for developing images:
197 <itemizedlist>
198 <listitem><para>
199 Have the Yocto Project build system itself available on
200 the developer workstations so developers can run their own
201 builds and directly rebuild the software stack.
202 </para></listitem>
203 <listitem><para>
204 Keep the core system unchanged as much as
205 possible and do your work in layers on top of the
206 core system.
207 Doing so gives you a greater level of portability when
208 upgrading to new versions of the core system or Board
209 Support Packages (BSPs).
210 </para></listitem>
211 <listitem><para>
212 Share layers amongst the developers of a
213 particular project and contain the policy configuration
214 that defines the project.
215 </para></listitem>
216 </itemizedlist>
217 </para></listitem>
218 <listitem><para>
219 <emphasis>Set up an Autobuilder:</emphasis>
220 Autobuilders are often the core of the development
221 environment.
222 It is here that changes from individual developers are brought
223 together and centrally tested and subsequent decisions about
224 releases can be made.
225 Autobuilders also allow for "continuous integration" style
226 testing of software components and regression identification
227 and tracking.</para>
228
229 <para>See "<ulink url='http://autobuilder.yoctoproject.org'>Yocto Project Autobuilder</ulink>"
230 for more information and links to buildbot.
231 The Yocto Project team has found this implementation
232 works well in this role.
233 A public example of this is the Yocto Project
234 Autobuilders, which we use to test the overall health of the
235 project.</para>
236
237 <para>The features of this system are:
238 <itemizedlist>
239 <listitem><para>
240 Highlights when commits break the build.
241 </para></listitem>
242 <listitem><para>
243 Populates an sstate cache from which
244 developers can pull rather than requiring local
245 builds.
246 </para></listitem>
247 <listitem><para>
248 Allows commit hook triggers,
249 which trigger builds when commits are made.
250 </para></listitem>
251 <listitem><para>
252 Allows triggering of automated image booting
253 and testing under the QuickEMUlator (QEMU).
254 </para></listitem>
255 <listitem><para>
256 Supports incremental build testing and
257 from-scratch builds.
258 </para></listitem>
259 <listitem><para>
260 Shares output that allows developer
261 testing and historical regression investigation.
262 </para></listitem>
263 <listitem><para>
264 Creates output that can be used for releases.
265 </para></listitem>
266 <listitem><para>
267 Allows scheduling of builds so that resources
268 can be used efficiently.
269 </para></listitem>
270 </itemizedlist>
271 </para></listitem>
272 <listitem><para>
273 <emphasis>Set up Test Machines:</emphasis>
274 Use a small number of shared, high performance systems
275 for testing purposes.
276 Developers can use these systems for wider, more
277 extensive testing while they continue to develop
278 locally using their primary development system.
279 </para></listitem>
280 <listitem><para>
281 <emphasis>Document Policies and Change Flow:</emphasis>
282 The Yocto Project itself uses a hierarchical structure and a
283 pull model.
284 Scripts exist to create and send pull requests
285 (i.e. <filename>create-pull-request</filename> and
286 <filename>send-pull-request</filename>).
287 This model is in line with other open source projects where
288 maintainers are responsible for specific areas of the project
289 and a single maintainer handles the final "top-of-tree" merges.
290 <note>
291 You can also use a more collective push model.
292 The <filename>gitolite</filename> software supports both the
293 push and pull models quite easily.
294 </note></para>
295
296 <para>As with any development environment, it is important
297 to document the policy used as well as any main project
298 guidelines so they are understood by everyone.
299 It is also a good idea to have well structured
300 commit messages, which are usually a part of a project's
301 guidelines.
302 Good commit messages are essential when looking back in time and
303 trying to understand why changes were made.</para>
304
305 <para>If you discover that changes are needed to the core
306 layer of the project, it is worth sharing those with the
307 community as soon as possible.
308 Chances are if you have discovered the need for changes,
309 someone else in the community needs them also.
310 </para></listitem>
311 <listitem><para>
312 <emphasis>Development Environment Summary:</emphasis>
313 Aside from the previous steps, some best practices exist
314 within the Yocto Project development environment.
315 Consider the following:
316 <itemizedlist>
317 <listitem><para>
318 Use
319 <ulink url='&YOCTO_DOCS_OM_URL;#git'>Git</ulink>
320 as the source control system.
321 </para></listitem>
322 <listitem><para>
323 Maintain your Metadata in layers that make sense
324 for your situation.
325 See the "<link linkend='understanding-and-creating-layers'>Understanding
326 and Creating Layers</link>" section for more information on
327 layers.
328 </para></listitem>
329 <listitem><para>
330 Separate the project's Metadata and code by using
331 separate Git repositories.
332 See the
333 "<ulink url='&YOCTO_DOCS_OM_URL;#yocto-project-repositories'>Yocto Project Source Repositories</ulink>"
334 section for information on these repositories.
335 See the
336 "<link linkend='working-with-yocto-project-source-files'>Working With Yocto Project Source Files</link>"
337 section for information on how to set up local Git
338 repositories for related upstream Yocto Project
339 Git repositories.
340 </para></listitem>
341 <listitem><para>
342 Set up the directory for the shared state cache
343 (<ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_DIR'><filename>SSTATE_DIR</filename></ulink>)
344 where it makes sense.
345 For example, set up the sstate cache on a system used
346 by developers in the same organization and share the
347 same source directories on their machines.
348 </para></listitem>
349 <listitem><para>
350 Set up an Autobuilder and have it populate the
351 sstate cache and source directories.
352 </para></listitem>
353 <listitem><para>
354 The Yocto Project community encourages you
355 to send patches to the project to fix bugs or add features.
356 If you do submit patches, follow the project commit
357 guidelines for writing good commit messages.
358 See the "<link linkend='how-to-submit-a-change'>Submitting a Change to the Yocto Project</link>"
359 section.
360 </para></listitem>
361 <listitem><para>
362 Send changes to the core sooner than later
363 as others are likely to run into the same issues.
364 For some guidance on mailing lists to use, see the list in the
365 "<link linkend='how-to-submit-a-change'>Submitting a Change to the Yocto Project</link>"
366 section.
367 For a description of the available mailing lists, see the
368 "<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing Lists</ulink>"
369 section in the Yocto Project Reference Manual.
370 </para></listitem>
371 </itemizedlist>
372 </para></listitem>
373 </orderedlist>
374 </para>
375</section>
376
377<section id='submitting-a-defect-against-the-yocto-project'> 9<section id='submitting-a-defect-against-the-yocto-project'>
378 <title>Submitting a Defect Against the Yocto Project</title> 10 <title>Submitting a Defect Against the Yocto Project</title>
379 11
diff --git a/documentation/dev-manual/dev-manual-start.xml b/documentation/dev-manual/dev-manual-start.xml
index 773c89cb82..9a7df72ec1 100644
--- a/documentation/dev-manual/dev-manual-start.xml
+++ b/documentation/dev-manual/dev-manual-start.xml
@@ -4,14 +4,384 @@
4 4
5<chapter id='dev-manual-start'> 5<chapter id='dev-manual-start'>
6 6
7<title>Getting Started with the Yocto Project</title> 7<title>Setting Up to Use the Yocto Project</title>
8 8
9<para> 9<para>
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, working with Yocto Project source files, and building 11 Yocto Project.
12 an image. 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
14 source repositories, and how to create local Git repositories.
13</para> 15</para>
14 16
17<section id="usingpoky-changes-collaborate">
18 <title>Creating a Team Development Environment</title>
19
20 <para>
21 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
23 team of developers.
24 One of the strengths of the Yocto Project is that it is extremely
25 flexible.
26 Thus, you can adapt it to many different use cases and scenarios.
27 However, these characteristics can cause a struggle if you are trying
28 to create a working setup that scales across a large team.
29 </para>
30
31 <para>
32 To help you understand how to set up this type of environment,
33 this section presents a procedure that gives you the information
34 to learn how to get the results you want.
35 The procedure is high-level and presents some of the project's most
36 successful experiences, practices, solutions, and available
37 technologies that work well.
38 Keep in mind, the procedure here is a starting point.
39 You can build off it and customize it to fit any
40 particular working environment and set of practices.
41 <orderedlist>
42 <listitem><para>
43 <emphasis>Determine Who is Going to be Developing:</emphasis>
44 You need to understand who is going to be doing anything
45 related to the Yocto Project and what their roles would be.
46 Making this determination is essential to completing the
47 steps two and three, which are to get your equipment together
48 and set up your development environment's hardware topology.
49 </para>
50
51 <para>The following roles exist:
52 <itemizedlist>
53 <listitem><para>
54 <emphasis>Application Development:</emphasis>
55 These types of developers do application level work
56 on top of an existing software stack.
57 </para></listitem>
58 <listitem><para>
59 <emphasis>Core System Development:</emphasis>
60 These types of developers work on the contents of the
61 operating system image itself.
62 </para></listitem>
63 <listitem><para>
64 <emphasis>Build Engineer:</emphasis>
65 This type of developer manages Autobuilders and
66 releases.
67 Not all environments need a Build Engineer.
68 </para></listitem>
69 <listitem><para>
70 <emphasis>Test Engineer:</emphasis>
71 This type of developer creates and manages automated
72 tests needed to ensure all application and core
73 system development meets desired quality standards.
74 </para></listitem>
75 </itemizedlist>
76 </para></listitem>
77 <listitem><para>
78 <emphasis>Gather the Hardware:</emphasis>
79 Based on the size and make-up of the team, get the hardware
80 together.
81 Any development, build, or test engineer should be using
82 a system that is running a supported Linux distribution.
83 Systems, in general, should be high performance (e.g. dual,
84 six-core Xeons with 24 Gbytes of RAM and plenty of disk space).
85 You can help ensure efficiency by having any machines used
86 for testing or that run Autobuilders be as high performance
87 as possible.
88 </para></listitem>
89 <listitem><para>
90 <emphasis>Understand the Hardware Topology of the Environment:</emphasis>
91 Once you understand the hardware involved and the make-up
92 of the team, you can understand the hardware topology of the
93 development environment.
94 You can get a visual idea of the machines and their roles
95 across the development environment.
96
97<!--
98 The following figure shows a moderately sized Yocto Project
99 development environment.
100
101 <para role="writernotes">
102 Need figure.</para>
103-->
104
105 </para></listitem>
106 <listitem><para>
107 <emphasis>Use Git as Your Source Control Manager (SCM):</emphasis>
108 Keeping your
109 <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink>
110 and any software you are developing under the
111 control of an SCM system that is compatible
112 with the OpenEmbedded build system is advisable.
113 Of the SCMs BitBake supports, the
114 Yocto Project team strongly recommends using
115 <ulink url='&YOCTO_DOCS_OM_URL;#git'>Git</ulink>.
116 Git is a distributed system that is easy to backup,
117 allows you to work remotely, and then connects back to the
118 infrastructure.
119 <note>
120 For information about BitBake, see the
121 <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>.
122 </note></para>
123
124 <para>It is relatively easy to set up Git services and create
125 infrastructure like
126 <ulink url='&YOCTO_GIT_URL;'>http://git.yoctoproject.org</ulink>,
127 which is based on server software called
128 <filename>gitolite</filename> with <filename>cgit</filename>
129 being used to generate the web interface that lets you view the
130 repositories.
131 The <filename>gitolite</filename> software identifies users
132 using SSH keys and allows branch-based
133 access controls to repositories that you can control as little
134 or as much as necessary.
135
136 <note>
137 The setup of these services is beyond the scope of this
138 manual.
139 However, sites such as these exist that describe how to
140 perform setup:
141 <itemizedlist>
142 <listitem><para>
143 <ulink url='http://git-scm.com/book/ch4-8.html'>Git documentation</ulink>:
144 Describes how to install <filename>gitolite</filename>
145 on the server.
146 </para></listitem>
147 <listitem><para>
148 <ulink url='http://gitolite.com'>Gitolite</ulink>:
149 Information for <filename>gitolite</filename>.
150 </para></listitem>
151 <listitem><para>
152 <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
154 for Git.
155 </para></listitem>
156 </itemizedlist>
157 </note>
158 </para></listitem>
159 <listitem><para>
160 <emphasis>Set up the Application Development Machines:</emphasis>
161 As mentioned earlier, application developers are creating
162 applications on top of existing software stacks.
163 Following are some best practices for setting up machines
164 that do application development:
165 <itemizedlist>
166 <listitem><para>
167 Use a pre-built toolchain that
168 contains the software stack itself.
169 Then, develop the application code on top of the
170 stack.
171 This method works well for small numbers of relatively
172 isolated applications.
173 </para></listitem>
174 <listitem><para>
175 When possible, use the Yocto Project
176 plug-in for the
177 <trademark class='trade'>Eclipse</trademark> IDE
178 and SDK development practices.
179 For more information, see the
180 "<ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink>"
181 manual.
182 </para></listitem>
183 <listitem><para>
184 Keep your cross-development toolchains updated.
185 You can do this through provisioning either as new
186 toolchain downloads or as updates through a package
187 update mechanism using <filename>opkg</filename>
188 to provide updates to an existing toolchain.
189 The exact mechanics of how and when to do this are a
190 question for local policy.
191 </para></listitem>
192 <listitem><para>
193 Use multiple toolchains installed locally
194 into different locations to allow development across
195 versions.
196 </para></listitem>
197 </itemizedlist>
198 </para></listitem>
199 <listitem><para>
200 <emphasis>Set up the Core Development Machines:</emphasis>
201 As mentioned earlier, these types of developers work on the
202 contents of the operating system itself.
203 Following are some best practices for setting up machines
204 used for developing images:
205 <itemizedlist>
206 <listitem><para>
207 Have the Yocto Project build system itself available on
208 the developer workstations so developers can run their own
209 builds and directly rebuild the software stack.
210 </para></listitem>
211 <listitem><para>
212 Keep the core system unchanged as much as
213 possible and do your work in layers on top of the
214 core system.
215 Doing so gives you a greater level of portability when
216 upgrading to new versions of the core system or Board
217 Support Packages (BSPs).
218 </para></listitem>
219 <listitem><para>
220 Share layers amongst the developers of a
221 particular project and contain the policy configuration
222 that defines the project.
223 </para></listitem>
224 </itemizedlist>
225 </para></listitem>
226 <listitem><para>
227 <emphasis>Set up an Autobuilder:</emphasis>
228 Autobuilders are often the core of the development
229 environment.
230 It is here that changes from individual developers are brought
231 together and centrally tested and subsequent decisions about
232 releases can be made.
233 Autobuilders also allow for "continuous integration" style
234 testing of software components and regression identification
235 and tracking.</para>
236
237 <para>See "<ulink url='http://autobuilder.yoctoproject.org'>Yocto Project Autobuilder</ulink>"
238 for more information and links to buildbot.
239 The Yocto Project team has found this implementation
240 works well in this role.
241 A public example of this is the Yocto Project
242 Autobuilders, which we use to test the overall health of the
243 project.</para>
244
245 <para>The features of this system are:
246 <itemizedlist>
247 <listitem><para>
248 Highlights when commits break the build.
249 </para></listitem>
250 <listitem><para>
251 Populates an sstate cache from which
252 developers can pull rather than requiring local
253 builds.
254 </para></listitem>
255 <listitem><para>
256 Allows commit hook triggers,
257 which trigger builds when commits are made.
258 </para></listitem>
259 <listitem><para>
260 Allows triggering of automated image booting
261 and testing under the QuickEMUlator (QEMU).
262 </para></listitem>
263 <listitem><para>
264 Supports incremental build testing and
265 from-scratch builds.
266 </para></listitem>
267 <listitem><para>
268 Shares output that allows developer
269 testing and historical regression investigation.
270 </para></listitem>
271 <listitem><para>
272 Creates output that can be used for releases.
273 </para></listitem>
274 <listitem><para>
275 Allows scheduling of builds so that resources
276 can be used efficiently.
277 </para></listitem>
278 </itemizedlist>
279 </para></listitem>
280 <listitem><para>
281 <emphasis>Set up Test Machines:</emphasis>
282 Use a small number of shared, high performance systems
283 for testing purposes.
284 Developers can use these systems for wider, more
285 extensive testing while they continue to develop
286 locally using their primary development system.
287 </para></listitem>
288 <listitem><para>
289 <emphasis>Document Policies and Change Flow:</emphasis>
290 The Yocto Project itself uses a hierarchical structure and a
291 pull model.
292 Scripts exist to create and send pull requests
293 (i.e. <filename>create-pull-request</filename> and
294 <filename>send-pull-request</filename>).
295 This model is in line with other open source projects where
296 maintainers are responsible for specific areas of the project
297 and a single maintainer handles the final "top-of-tree" merges.
298 <note>
299 You can also use a more collective push model.
300 The <filename>gitolite</filename> software supports both the
301 push and pull models quite easily.
302 </note></para>
303
304 <para>As with any development environment, it is important
305 to document the policy used as well as any main project
306 guidelines so they are understood by everyone.
307 It is also a good idea to have well structured
308 commit messages, which are usually a part of a project's
309 guidelines.
310 Good commit messages are essential when looking back in time and
311 trying to understand why changes were made.</para>
312
313 <para>If you discover that changes are needed to the core
314 layer of the project, it is worth sharing those with the
315 community as soon as possible.
316 Chances are if you have discovered the need for changes,
317 someone else in the community needs them also.
318 </para></listitem>
319 <listitem><para>
320 <emphasis>Development Environment Summary:</emphasis>
321 Aside from the previous steps, some best practices exist
322 within the Yocto Project development environment.
323 Consider the following:
324 <itemizedlist>
325 <listitem><para>
326 Use
327 <ulink url='&YOCTO_DOCS_OM_URL;#git'>Git</ulink>
328 as the source control system.
329 </para></listitem>
330 <listitem><para>
331 Maintain your Metadata in layers that make sense
332 for your situation.
333 See the "<link linkend='understanding-and-creating-layers'>Understanding
334 and Creating Layers</link>" section for more information on
335 layers.
336 </para></listitem>
337 <listitem><para>
338 Separate the project's Metadata and code by using
339 separate Git repositories.
340 See the
341 "<ulink url='&YOCTO_DOCS_OM_URL;#yocto-project-repositories'>Yocto Project Source Repositories</ulink>"
342 section for information on these repositories.
343 See the
344 "<link linkend='working-with-yocto-project-source-files'>Working With Yocto Project Source Files</link>"
345 section for information on how to set up local Git
346 repositories for related upstream Yocto Project
347 Git repositories.
348 </para></listitem>
349 <listitem><para>
350 Set up the directory for the shared state cache
351 (<ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_DIR'><filename>SSTATE_DIR</filename></ulink>)
352 where it makes sense.
353 For example, set up the sstate cache on a system used
354 by developers in the same organization and share the
355 same source directories on their machines.
356 </para></listitem>
357 <listitem><para>
358 Set up an Autobuilder and have it populate the
359 sstate cache and source directories.
360 </para></listitem>
361 <listitem><para>
362 The Yocto Project community encourages you
363 to send patches to the project to fix bugs or add features.
364 If you do submit patches, follow the project commit
365 guidelines for writing good commit messages.
366 See the "<link linkend='how-to-submit-a-change'>Submitting a Change to the Yocto Project</link>"
367 section.
368 </para></listitem>
369 <listitem><para>
370 Send changes to the core sooner than later
371 as others are likely to run into the same issues.
372 For some guidance on mailing lists to use, see the list in the
373 "<link linkend='how-to-submit-a-change'>Submitting a Change to the Yocto Project</link>"
374 section.
375 For a description of the available mailing lists, see the
376 "<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing Lists</ulink>"
377 section in the Yocto Project Reference Manual.
378 </para></listitem>
379 </itemizedlist>
380 </para></listitem>
381 </orderedlist>
382 </para>
383</section>
384
15<section id='setting-up-the-development-host-to-use-the-yocto-project'> 385<section id='setting-up-the-development-host-to-use-the-yocto-project'>
16 <title>Setting Up the Development Host to Use the Yocto Project</title> 386 <title>Setting Up the Development Host to Use the Yocto Project</title>
17 387
@@ -760,7 +1130,7 @@
760 <emphasis>Set up Your Host Development System to Support 1130 <emphasis>Set up Your Host Development System to Support
761 Development Using the Yocto Project</emphasis>: 1131 Development Using the Yocto Project</emphasis>:
762 See the 1132 See the
763 "<link linkend='dev-manual-start'>Getting Started With the Yocto Project</link>" 1133 "<link linkend='dev-manual-start'>Setting Up to Use the Yocto Project</link>"
764 section for options on how to get a build host ready to use 1134 section for options on how to get a build host ready to use
765 the Yocto Project. 1135 the Yocto Project.
766 </para></listitem> 1136 </para></listitem>
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2025-12-04 08:56:21 +0000