diff options
author | Scott Rifenbark <srifenbark@gmail.com> | 2018-05-16 13:10:58 -0700 |
---|---|---|
committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2018-05-24 17:18:04 +0100 |
commit | 1fae7f57cc701ffa1cf9e7e43feb518169180238 (patch) | |
tree | d8737487106f31cad45c679f857c751848a24e59 /documentation/dev-manual/dev-manual-start.xml | |
parent | ef3b230abf31ccbc9114957b2c15f9a49c01ae81 (diff) | |
download | poky-1fae7f57cc701ffa1cf9e7e43feb518169180238.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 (limited to 'documentation/dev-manual/dev-manual-start.xml')
-rw-r--r-- | documentation/dev-manual/dev-manual-start.xml | 378 |
1 files changed, 374 insertions, 4 deletions
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> |