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:16:34 +0100 |
| commit | d38c9ba94aada3d07eb9b6700a2a16b9e205252a (patch) | |
| tree | c9b6ff6382fa353ed714bd02941066a37a245707 /documentation/dev-manual/dev-manual-newbie.xml | |
| parent | 222824948893d10b1183b38b1593a9bb13de63c7 (diff) | |
| download | poky-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 (limited to 'documentation/dev-manual/dev-manual-newbie.xml')
| -rw-r--r-- | documentation/dev-manual/dev-manual-newbie.xml | 368 |
1 files changed, 0 insertions, 368 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 | ||