diff options
| -rw-r--r-- | documentation/dev-manual/dev-manual-start.xml | 212 |
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> |