diff options
| author | Scott Rifenbark <srifenbark@gmail.com> | 2017-06-20 06:37:18 -0700 |
|---|---|---|
| committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2017-06-22 09:16:44 +0100 |
| commit | cd9279ab5cb572d804806283c13857346dc54de8 (patch) | |
| tree | 814aa7fa9e03d31e3f2d7be71a10af4e3bf3fdd4 /documentation/dev-manual/dev-manual-newbie.xml | |
| parent | e928b5251cdc7baba8a78380041b8156c106f9fc (diff) | |
| download | poky-cd9279ab5cb572d804806283c13857346dc54de8.tar.gz | |
dev-manual: Updated the section on the YP development environment
Fixes [YOCTO #11630]
Extensively updated the development environment section by
creating a task-oriented section.
(From yocto-docs rev: d440f0b5ceb1aca57a73d8bced515ae0bd3188f7)
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 | 631 |
1 files changed, 322 insertions, 309 deletions
diff --git a/documentation/dev-manual/dev-manual-newbie.xml b/documentation/dev-manual/dev-manual-newbie.xml index 1bb82b711d..1d9926c6cd 100644 --- a/documentation/dev-manual/dev-manual-newbie.xml +++ b/documentation/dev-manual/dev-manual-newbie.xml | |||
| @@ -7,12 +7,12 @@ | |||
| 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"> | 9 | <section id="usingpoky-changes-collaborate"> |
| 10 | <title>Using the Yocto Project in a Team Environment</title> | 10 | <title>Setting Up a Team Yocto Project Development Environment</title> |
| 11 | 11 | ||
| 12 | <para> | 12 | <para> |
| 13 | It might not be immediately clear how you can use the Yocto | 13 | It might not be immediately clear how you can use the Yocto |
| 14 | Project in a team environment, or scale it for a large team of | 14 | Project in a team development environment, or scale it for a large |
| 15 | developers. | 15 | team of developers. |
| 16 | One of the strengths of the Yocto Project is that it is extremely | 16 | One of the strengths of the Yocto Project is that it is extremely |
| 17 | flexible. | 17 | flexible. |
| 18 | Thus, you can adapt it to many different use cases and scenarios. | 18 | Thus, you can adapt it to many different use cases and scenarios. |
| @@ -21,337 +21,350 @@ | |||
| 21 | </para> | 21 | </para> |
| 22 | 22 | ||
| 23 | <para> | 23 | <para> |
| 24 | To help with these types of situations, this section presents | 24 | To help you understand how to set up this type of environment, |
| 25 | some of the project's most successful experiences, | 25 | this section presents a procedure that gives you the information |
| 26 | practices, solutions, and available technologies that work well. | 26 | to learn how to get the results you want. |
| 27 | Keep in mind, the information here is a starting point. | 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. | ||
| 28 | You can build off it and customize it to fit any | 31 | You can build off it and customize it to fit any |
| 29 | particular working environment and set of practices. | 32 | particular working environment and set of practices. |
| 30 | </para> | 33 | <orderedlist> |
| 31 | 34 | <listitem><para> | |
| 32 | <section id='best-practices-system-configurations'> | 35 | <emphasis>Determine Who is Going to be Developing:</emphasis> |
| 33 | <title>System Configurations</title> | 36 | You need to understand who is going to be doing anything |
| 34 | 37 | related to the Yocto Project and what their roles would be. | |
| 35 | <para> | 38 | Making this determination is essential to completing the |
| 36 | Systems across a large team should meet the needs of | 39 | steps two and three, which are to get your equipment together |
| 37 | two types of developers: those working on the contents of the | 40 | and set up your development environment's hardware topology. |
| 38 | operating system image itself and those developing applications. | 41 | </para> |
| 39 | Regardless of the type of developer, their workstations must | 42 | |
| 40 | be both reasonably powerful and run Linux. | 43 | <para>The following roles exist: |
| 41 | </para> | 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 | Now that you know how many developers and support engineers | ||
| 84 | are required, you can understand the topology of the | ||
| 85 | hardware environment. | ||
| 86 | The following figure shows a moderately sized Yocto Project | ||
| 87 | development environment. | ||
| 42 | 88 | ||
| 43 | <section id='best-practices-application-development'> | 89 | <para role="writernotes"> |
| 44 | <title>Application Development</title> | 90 | Need figure.</para> |
| 45 | 91 | ||
| 46 | <para> | 92 | </para></listitem> |
| 47 | For developers who mainly do application level work | 93 | <listitem><para> |
| 48 | on top of an existing software stack, | 94 | <emphasis>Use Git as Your Source Control Manager (SCM):</emphasis> |
| 49 | the following list shows practices that work best. | 95 | Keeping your |
| 50 | For information on using a Software Development Kit (SDK), see | 96 | <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink> |
| 51 | the | 97 | and any software you are developing under the |
| 52 | <ulink url='&YOCTO_DOCS_SDK_URL;#sdk-intro'>Yocto Project Software Development Kit (SDK) Developer's Guide</ulink>: | 98 | control of an SCM system that is compatible |
| 99 | with the OpenEmbedded build system is advisable. | ||
| 100 | Of the SCMs BitBake supports, the | ||
| 101 | Yocto Project team strongly recommends using | ||
| 102 | <ulink url='&YOCTO_DOCS_REF_URL;#git'>Git</ulink>. | ||
| 103 | Git is a distributed system that is easy to backup, | ||
| 104 | allows you to work remotely, and then connects back to the | ||
| 105 | infrastructure. | ||
| 106 | <note> | ||
| 107 | For information about BitBake, see the | ||
| 108 | <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>. | ||
| 109 | </note></para> | ||
| 110 | |||
| 111 | <para>It is relatively easy to set up Git services and create | ||
| 112 | infrastructure like | ||
| 113 | <ulink url='&YOCTO_GIT_URL;'>http://git.yoctoproject.org</ulink>, | ||
| 114 | which is based on server software called | ||
| 115 | <filename>gitolite</filename> with <filename>cgit</filename> | ||
| 116 | being used to generate the web interface that lets you view the | ||
| 117 | repositories. | ||
| 118 | The <filename>gitolite</filename> software identifies users | ||
| 119 | using SSH keys and allows branch-based | ||
| 120 | access controls to repositories that you can control as little | ||
| 121 | or as much as necessary. | ||
| 122 | |||
| 123 | <note> | ||
| 124 | The setup of these services is beyond the scope of this | ||
| 125 | manual. | ||
| 126 | However, sites such as these exist that describe how to | ||
| 127 | perform setup: | ||
| 128 | <itemizedlist> | ||
| 129 | <listitem><para> | ||
| 130 | <ulink url='http://git-scm.com/book/ch4-8.html'>Git documentation</ulink>: | ||
| 131 | Describes how to install <filename>gitolite</filename> | ||
| 132 | on the server. | ||
| 133 | </para></listitem> | ||
| 134 | <listitem><para> | ||
| 135 | <ulink url='http://sitaramc.github.com/gitolite/master-toc.html'>The <filename>gitolite</filename> master index</ulink>: | ||
| 136 | All topics for <filename>gitolite</filename>. | ||
| 137 | </para></listitem> | ||
| 138 | <listitem><para> | ||
| 139 | <ulink url='https://git.wiki.kernel.org/index.php/Interfaces,_frontends,_and_tools'>Interfaces, frontends, and tools</ulink>: | ||
| 140 | Documentation on how to create interfaces and frontends | ||
| 141 | for Git. | ||
| 142 | </para></listitem> | ||
| 143 | </itemizedlist> | ||
| 144 | </note> | ||
| 145 | </para></listitem> | ||
| 146 | <listitem><para> | ||
| 147 | <emphasis>Set up the Application Development Machines:</emphasis> | ||
| 148 | As mentioned earlier, application developers are creating | ||
| 149 | applications on top of existing software stacks. | ||
| 150 | Following are some best practices for setting up machines | ||
| 151 | that do application development: | ||
| 53 | <itemizedlist> | 152 | <itemizedlist> |
| 54 | <listitem><para>Use a pre-built toolchain that | 153 | <listitem><para> |
| 154 | Use a pre-built toolchain that | ||
| 55 | contains the software stack itself. | 155 | contains the software stack itself. |
| 56 | Then, develop the application code on top of the | 156 | Then, develop the application code on top of the |
| 57 | stack. | 157 | stack. |
| 58 | This method works well for small numbers of relatively | 158 | This method works well for small numbers of relatively |
| 59 | isolated applications.</para></listitem> | 159 | isolated applications. |
| 60 | <listitem><para>When possible, use the Yocto Project | 160 | </para></listitem> |
| 61 | plug-in for the <trademark class='trade'>Eclipse</trademark> IDE | 161 | <listitem><para> |
| 162 | When possible, use the Yocto Project | ||
| 163 | plug-in for the | ||
| 164 | <trademark class='trade'>Eclipse</trademark> IDE | ||
| 62 | and SDK development practices. | 165 | and SDK development practices. |
| 63 | For more information, see the | 166 | For more information, see the |
| 64 | "<ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Software Development Kit (SDK) Developer's Guide</ulink>". | 167 | "<ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Software Development Kit (SDK) Developer's Guide</ulink>". |
| 65 | </para></listitem> | 168 | </para></listitem> |
| 66 | <listitem><para>Keep your cross-development toolchains | 169 | <listitem><para> |
| 67 | updated. | 170 | Keep your cross-development toolchains updated. |
| 68 | You can do this through provisioning either as new | 171 | You can do this through provisioning either as new |
| 69 | toolchain downloads or as updates through a package | 172 | toolchain downloads or as updates through a package |
| 70 | update mechanism using <filename>opkg</filename> | 173 | update mechanism using <filename>opkg</filename> |
| 71 | to provide updates to an existing toolchain. | 174 | to provide updates to an existing toolchain. |
| 72 | The exact mechanics of how and when to do this are a | 175 | The exact mechanics of how and when to do this are a |
| 73 | question for local policy.</para></listitem> | 176 | question for local policy. |
| 74 | <listitem><para>Use multiple toolchains installed locally | 177 | </para></listitem> |
| 178 | <listitem><para> | ||
| 179 | Use multiple toolchains installed locally | ||
| 75 | into different locations to allow development across | 180 | into different locations to allow development across |
| 76 | versions.</para></listitem> | 181 | versions. |
| 182 | </para></listitem> | ||
| 77 | </itemizedlist> | 183 | </itemizedlist> |
| 78 | </para> | 184 | </para></listitem> |
| 79 | </section> | 185 | <listitem><para> |
| 80 | 186 | <emphasis>Set up the Core Development Machines:</emphasis> | |
| 81 | <section id='best-practices-core-system-development'> | 187 | As mentioned earlier, these types of developers work on the |
| 82 | <title>Core System Development</title> | 188 | contents of the operating system itself. |
| 83 | 189 | Following are some best practices for setting up machines | |
| 84 | <para> | 190 | used for developing images: |
| 85 | For core system development, it is often best to have the | ||
| 86 | build system itself available on the developer workstations | ||
| 87 | so developers can run their own builds and directly | ||
| 88 | rebuild the software stack. | ||
| 89 | You should keep the core system unchanged as much as | ||
| 90 | possible and do your work in layers on top of the core system. | ||
| 91 | Doing so gives you a greater level of portability when | ||
| 92 | upgrading to new versions of the core system or Board | ||
| 93 | Support Packages (BSPs). | ||
| 94 | You can share layers amongst the developers of a particular | ||
| 95 | project and contain the policy configuration that defines | ||
| 96 | the project. | ||
| 97 | </para> | ||
| 98 | |||
| 99 | <para> | ||
| 100 | Aside from the previous best practices, there exists a number | ||
| 101 | of tips and tricks that can help speed up core development | ||
| 102 | projects: | ||
| 103 | <itemizedlist> | 191 | <itemizedlist> |
| 104 | <listitem><para>Use a | 192 | <listitem><para> |
| 105 | <ulink url='&YOCTO_DOCS_REF_URL;#shared-state-cache'>Shared State Cache</ulink> | 193 | Have the Yocto Project build system itself available on |
| 106 | (sstate) among groups of developers who are on a | 194 | the developer workstations so developers can run their own |
| 107 | fast network. | 195 | builds and directly rebuild the software stack. |
| 108 | The best way to share sstate is through a | ||
| 109 | Network File System (NFS) share. | ||
| 110 | The first user to build a given component for the | ||
| 111 | first time contributes that object to the sstate, | ||
| 112 | while subsequent builds from other developers then | ||
| 113 | reuse the object rather than rebuild it themselves. | ||
| 114 | </para> | ||
| 115 | <para>Although it is possible to use other protocols for the | ||
| 116 | sstate such as HTTP and FTP, you should avoid these. | ||
| 117 | Using HTTP limits the sstate to read-only and | ||
| 118 | FTP provides poor performance. | ||
| 119 | </para></listitem> | 196 | </para></listitem> |
| 120 | <listitem><para>Have autobuilders contribute to the sstate | 197 | <listitem><para> |
| 121 | pool similarly to how the developer workstations | 198 | Keep the core system unchanged as much as |
| 122 | contribute. | 199 | possible and do your work in layers on top of the |
| 123 | For information, see the | 200 | core system. |
| 124 | "<link linkend='best-practices-autobuilders'>Autobuilders</link>" | 201 | Doing so gives you a greater level of portability when |
| 125 | section.</para></listitem> | 202 | upgrading to new versions of the core system or Board |
| 126 | <listitem><para>Build stand-alone tarballs that contain | 203 | Support Packages (BSPs). |
| 127 | "missing" system requirements if for some reason | ||
| 128 | developer workstations do not meet minimum system | ||
| 129 | requirements such as latest Python versions, | ||
| 130 | <filename>chrpath</filename>, or other tools. | ||
| 131 | You can install and relocate the tarball exactly as you | ||
| 132 | would the usual cross-development toolchain so that | ||
| 133 | all developers can meet minimum version requirements | ||
| 134 | on most distributions.</para></listitem> | ||
| 135 | <listitem><para>Use a small number of shared, | ||
| 136 | high performance systems for testing purposes | ||
| 137 | (e.g. dual, six-core Xeons with 24 Gbytes of RAM | ||
| 138 | and plenty of disk space). | ||
| 139 | Developers can use these systems for wider, more | ||
| 140 | extensive testing while they continue to develop | ||
| 141 | locally using their primary development system. | ||
| 142 | </para></listitem> | 204 | </para></listitem> |
| 143 | <listitem><para>Enable the PR Service when package feeds | 205 | <listitem><para> |
| 144 | need to be incremental with continually increasing | 206 | Share layers amongst the developers of a |
| 145 | <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'>PR</ulink> | 207 | particular project and contain the policy configuration |
| 146 | values. | 208 | that defines the project. |
| 147 | Typically, this situation occurs when you use or | ||
| 148 | publish package feeds and use a shared state. | ||
| 149 | You should enable the PR Service for all users who | ||
| 150 | use the shared state pool. | ||
| 151 | For more information on the PR Service, see the | ||
| 152 | "<link linkend='working-with-a-pr-service'>Working With a PR Service</link>". | ||
| 153 | </para></listitem> | 209 | </para></listitem> |
| 154 | </itemizedlist> | 210 | </itemizedlist> |
| 155 | </para> | 211 | </para></listitem> |
| 156 | </section> | 212 | <listitem><para> |
| 157 | </section> | 213 | <emphasis>Set up an Autobuilder:</emphasis> |
| 158 | 214 | Autobuilders are often the core of the development | |
| 159 | <section id='best-practices-source-control-management'> | 215 | environment. |
| 160 | <title>Source Control Management (SCM)</title> | 216 | It is here that changes from individual developers are brought |
| 161 | 217 | together and centrally tested and subsequent decisions about | |
| 162 | <para> | 218 | releases can be made. |
| 163 | Keeping your | 219 | Autobuilders also allow for "continuous integration" style |
| 164 | <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink> | 220 | testing of software components and regression identification |
| 165 | and any software you are developing under the | 221 | and tracking.</para> |
| 166 | control of an SCM system that is compatible | 222 | |
| 167 | with the OpenEmbedded build system is advisable. | 223 | <para>See "<ulink url='http://autobuilder.yoctoproject.org'>Yocto Project Autobuilder</ulink>" |
| 168 | Of the SCMs BitBake supports, the | 224 | for more information and links to buildbot. |
| 169 | Yocto Project team strongly recommends using | 225 | The Yocto Project team has found this implementation |
| 170 | <ulink url='&YOCTO_DOCS_REF_URL;#git'>Git</ulink>. | 226 | works well in this role. |
| 171 | Git is a distributed system that is easy to backup, | 227 | A public example of this is the Yocto Project |
| 172 | allows you to work remotely, and then connects back to the | 228 | Autobuilders, which we use to test the overall health of the |
| 173 | infrastructure. | 229 | project.</para> |
| 174 | <note> | 230 | |
| 175 | For information about BitBake, see the | 231 | <para>The features of this system are: |
| 176 | <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>. | 232 | <itemizedlist> |
| 177 | </note> | 233 | <listitem><para> |
| 178 | </para> | 234 | Highlights when commits break the build. |
| 179 | 235 | </para></listitem> | |
| 180 | <para> | 236 | <listitem><para> |
| 181 | It is relatively easy to set up Git services and create | 237 | Populates an sstate cache from which |
| 182 | infrastructure like | 238 | developers can pull rather than requiring local |
| 183 | <ulink url='&YOCTO_GIT_URL;'>http://git.yoctoproject.org</ulink>, | 239 | builds. |
| 184 | which is based on server software called | 240 | </para></listitem> |
| 185 | <filename>gitolite</filename> with <filename>cgit</filename> | 241 | <listitem><para> |
| 186 | being used to generate the web interface that lets you view the | 242 | Allows commit hook triggers, |
| 187 | repositories. | 243 | which trigger builds when commits are made. |
| 188 | The <filename>gitolite</filename> software identifies users | 244 | </para></listitem> |
| 189 | using SSH keys and allows branch-based | 245 | <listitem><para> |
| 190 | access controls to repositories that you can control as little | 246 | Allows triggering of automated image booting |
| 191 | or as much as necessary. | 247 | and testing under the QuickEMUlator (QEMU). |
| 192 | </para> | 248 | </para></listitem> |
| 193 | 249 | <listitem><para> | |
| 194 | <note> | 250 | Supports incremental build testing and |
| 195 | The setup of these services is beyond the scope of this manual. | 251 | from-scratch builds. |
| 196 | However, sites such as these exist that describe how to perform | 252 | </para></listitem> |
| 197 | setup: | 253 | <listitem><para> |
| 198 | <itemizedlist> | 254 | Shares output that allows developer |
| 199 | <listitem><para><ulink url='http://git-scm.com/book/ch4-8.html'>Git documentation</ulink>: | 255 | testing and historical regression investigation. |
| 200 | Describes how to install <filename>gitolite</filename> | 256 | </para></listitem> |
| 201 | on the server.</para></listitem> | 257 | <listitem><para> |
| 202 | <listitem><para><ulink url='http://sitaramc.github.com/gitolite/master-toc.html'>The <filename>gitolite</filename> master index</ulink>: | 258 | Creates output that can be used for releases. |
| 203 | All topics for <filename>gitolite</filename>. | 259 | </para></listitem> |
| 204 | </para></listitem> | 260 | <listitem><para> |
| 205 | <listitem><para><ulink url='https://git.wiki.kernel.org/index.php/Interfaces,_frontends,_and_tools'>Interfaces, frontends, and tools</ulink>: | 261 | Allows scheduling of builds so that resources |
| 206 | Documentation on how to create interfaces and frontends | 262 | can be used efficiently. |
| 207 | for Git.</para></listitem> | 263 | </para></listitem> |
| 208 | </itemizedlist> | 264 | </itemizedlist> |
| 209 | </note> | 265 | </para></listitem> |
| 210 | </section> | 266 | <listitem><para> |
| 211 | 267 | <emphasis>Set up Test Machines:</emphasis> | |
| 212 | <section id='best-practices-autobuilders'> | 268 | Use a small number of shared, high performance systems |
| 213 | <title>Autobuilders</title> | 269 | for testing purposes. |
| 214 | 270 | Developers can use these systems for wider, more | |
| 215 | <para> | 271 | extensive testing while they continue to develop |
| 216 | Autobuilders are often the core of a development project. | 272 | locally using their primary development system. |
| 217 | It is here that changes from individual developers are brought | 273 | </para></listitem> |
| 218 | together and centrally tested and subsequent decisions about | 274 | <listitem><para> |
| 219 | releases can be made. | 275 | <emphasis>Document Policies and Change Flow:</emphasis> |
| 220 | Autobuilders also allow for "continuous integration" style | 276 | The Yocto Project itself uses a hierarchical structure and a |
| 221 | testing of software components and regression identification | 277 | pull model. |
| 222 | and tracking. | 278 | Scripts exist to create and send pull requests |
| 223 | </para> | 279 | (i.e. <filename>create-pull-request</filename> and |
| 224 | 280 | <filename>send-pull-request</filename>). | |
| 225 | <para> | 281 | This model is in line with other open source projects where |
| 226 | See "<ulink url='http://autobuilder.yoctoproject.org'>Yocto Project Autobuilder</ulink>" | 282 | maintainers are responsible for specific areas of the project |
| 227 | for more information and links to buildbot. | 283 | and a single maintainer handles the final "top-of-tree" merges. |
| 228 | The Yocto Project team has found this implementation | 284 | <note> |
| 229 | works well in this role. | 285 | You can also use a more collective push model. |
| 230 | A public example of this is the Yocto Project | 286 | The <filename>gitolite</filename> software supports both the |
| 231 | Autobuilders, which we use to test the overall health of the | 287 | push and pull models quite easily. |
| 232 | project. | 288 | </note></para> |
| 233 | </para> | 289 | |
| 234 | 290 | <para>As with any development environment, it is important | |
| 235 | <para> | 291 | to document the policy used as well as any main project |
| 236 | The features of this system are: | 292 | guidelines so they are understood by everyone. |
| 237 | <itemizedlist> | 293 | It is also a good idea to have well structured |
| 238 | <listitem><para>Highlights when commits break the build. | 294 | commit messages, which are usually a part of a project's |
| 239 | </para></listitem> | 295 | guidelines. |
| 240 | <listitem><para>Populates an sstate cache from which | 296 | Good commit messages are essential when looking back in time and |
| 241 | developers can pull rather than requiring local | 297 | trying to understand why changes were made.</para> |
| 242 | builds.</para></listitem> | 298 | |
| 243 | <listitem><para>Allows commit hook triggers, | 299 | <para>If you discover that changes are needed to the core |
| 244 | which trigger builds when commits are made. | 300 | layer of the project, it is worth sharing those with the |
| 245 | </para></listitem> | 301 | community as soon as possible. |
| 246 | <listitem><para>Allows triggering of automated image booting | 302 | Chances are if you have discovered the need for changes, |
| 247 | and testing under the QuickEMUlator (QEMU). | 303 | someone else in the community needs them also. |
| 248 | </para></listitem> | 304 | </para></listitem> |
| 249 | <listitem><para>Supports incremental build testing and | 305 | <listitem><para> |
| 250 | from-scratch builds.</para></listitem> | 306 | <emphasis>Development Environment Summary:</emphasis> |
| 251 | <listitem><para>Shares output that allows developer | 307 | Aside from the previous steps, some best practices exist |
| 252 | testing and historical regression investigation. | 308 | within the Yocto Project development environment. |
| 253 | </para></listitem> | 309 | Consider the following: |
| 254 | <listitem><para>Creates output that can be used for releases. | 310 | <itemizedlist> |
| 255 | </para></listitem> | 311 | <listitem><para> |
| 256 | <listitem><para>Allows scheduling of builds so that resources | 312 | Use <ulink url='&YOCTO_DOCS_REF_URL;#git'>Git</ulink> |
| 257 | can be used efficiently.</para></listitem> | 313 | as the source control system. |
| 258 | </itemizedlist> | 314 | </para></listitem> |
| 259 | </para> | 315 | <listitem><para> |
| 260 | </section> | 316 | Maintain your Metadata in layers that make sense |
| 261 | 317 | for your situation. | |
| 262 | <section id='best-practices-policies-and-change-flow'> | 318 | See the "<link linkend='understanding-and-creating-layers'>Understanding |
| 263 | <title>Policies and Change Flow</title> | 319 | and Creating Layers</link>" section for more information on |
| 264 | 320 | layers. | |
| 265 | <para> | 321 | </para></listitem> |
| 266 | The Yocto Project itself uses a hierarchical structure and a | 322 | <listitem><para> |
| 267 | pull model. | 323 | Separate the project's Metadata and code by using |
| 268 | Scripts exist to create and send pull requests | 324 | separate Git repositories. |
| 269 | (i.e. <filename>create-pull-request</filename> and | 325 | See the |
| 270 | <filename>send-pull-request</filename>). | 326 | "<ulink url='&YOCTO_DOCS_REF_URL;#yocto-project-repositories'>Yocto Project Source Repositories</ulink>" |
| 271 | This model is in line with other open source projects where | 327 | section for information on these repositories. |
| 272 | maintainers are responsible for specific areas of the project | 328 | See the |
| 273 | and a single maintainer handles the final "top-of-tree" merges. | 329 | "<link linkend='getting-setup'>Getting Set Up</link>" |
| 274 | </para> | 330 | section for information on how to set up local Git |
| 275 | 331 | repositories for related upstream Yocto Project | |
| 276 | <note> | 332 | Git repositories. |
| 277 | You can also use a more collective push model. | 333 | </para></listitem> |
| 278 | The <filename>gitolite</filename> software supports both the | 334 | <listitem><para> |
| 279 | push and pull models quite easily. | 335 | Set up the directory for the shared state cache |
| 280 | </note> | 336 | (<ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_DIR'><filename>SSTATE_DIR</filename></ulink>) |
| 281 | 337 | where it makes sense. | |
| 282 | <para> | 338 | For example, set up the sstate cache on a system used |
| 283 | As with any development environment, it is important | 339 | by developers in the same organization and share the |
| 284 | to document the policy used as well as any main project | 340 | same source directories on their machines. |
| 285 | guidelines so they are understood by everyone. | 341 | </para></listitem> |
| 286 | It is also a good idea to have well structured | 342 | <listitem><para> |
| 287 | commit messages, which are usually a part of a project's | 343 | Set up an Autobuilder and have it populate the |
| 288 | guidelines. | 344 | sstate cache and source directories. |
| 289 | Good commit messages are essential when looking back in time and | 345 | </para></listitem> |
| 290 | trying to understand why changes were made. | 346 | <listitem><para> |
| 291 | </para> | 347 | The Yocto Project community encourages you |
| 292 | 348 | to send patches to the project to fix bugs or add features. | |
| 293 | <para> | 349 | If you do submit patches, follow the project commit |
| 294 | If you discover that changes are needed to the core layer of the | 350 | guidelines for writing good commit messages. |
| 295 | project, it is worth sharing those with the community as soon | 351 | See the "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>" |
| 296 | as possible. | 352 | section. |
| 297 | Chances are if you have discovered the need for changes, someone | 353 | </para></listitem> |
| 298 | else in the community needs them also. | 354 | <listitem><para> |
| 299 | </para> | 355 | Send changes to the core sooner than later |
| 300 | </section> | 356 | as others are likely to run into the same issues. |
| 301 | 357 | For some guidance on mailing lists to use, see the list in the | |
| 302 | <section id='best-practices-summary'> | 358 | "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>" |
| 303 | <title>Summary</title> | 359 | section. |
| 304 | 360 | For a description of the available mailing lists, see the | |
| 305 | <para> | 361 | "<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing Lists</ulink>" |
| 306 | This section summarizes the key recommendations described in the | 362 | section in the Yocto Project Reference Manual. |
| 307 | previous sections: | 363 | </para></listitem> |
| 308 | <itemizedlist> | 364 | </itemizedlist> |
| 309 | <listitem><para>Use <ulink url='&YOCTO_DOCS_REF_URL;#git'>Git</ulink> | 365 | </para></listitem> |
| 310 | as the source control system.</para></listitem> | 366 | </orderedlist> |
| 311 | <listitem><para>Maintain your Metadata in layers that make sense | 367 | </para> |
| 312 | for your situation. | ||
| 313 | See the "<link linkend='understanding-and-creating-layers'>Understanding | ||
| 314 | and Creating Layers</link>" section for more information on | ||
| 315 | layers.</para></listitem> | ||
| 316 | <listitem><para> | ||
| 317 | Separate the project's Metadata and code by using | ||
| 318 | separate Git repositories. | ||
| 319 | See the | ||
| 320 | "<ulink url='&YOCTO_DOCS_REF_URL;#yocto-project-repositories'>Yocto Project Source Repositories</ulink>" | ||
| 321 | section for information on these repositories. | ||
| 322 | See the | ||
| 323 | "<link linkend='getting-setup'>Getting Set Up</link>" | ||
| 324 | section for information on how to set up local Git | ||
| 325 | repositories for related upstream Yocto Project | ||
| 326 | Git repositories. | ||
| 327 | </para></listitem> | ||
| 328 | <listitem><para>Set up the directory for the shared state cache | ||
| 329 | (<ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_DIR'><filename>SSTATE_DIR</filename></ulink>) | ||
| 330 | where it makes sense. | ||
| 331 | For example, set up the sstate cache on a system used | ||
| 332 | by developers in the same organization and share the | ||
| 333 | same source directories on their machines. | ||
| 334 | </para></listitem> | ||
| 335 | <listitem><para>Set up an Autobuilder and have it populate the | ||
| 336 | sstate cache and source directories.</para></listitem> | ||
| 337 | <listitem><para>The Yocto Project community encourages you | ||
| 338 | to send patches to the project to fix bugs or add features. | ||
| 339 | If you do submit patches, follow the project commit | ||
| 340 | guidelines for writing good commit messages. | ||
| 341 | See the "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>" | ||
| 342 | section.</para></listitem> | ||
| 343 | <listitem><para>Send changes to the core sooner than later | ||
| 344 | as others are likely to run into the same issues. | ||
| 345 | For some guidance on mailing lists to use, see the list in the | ||
| 346 | "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>" | ||
| 347 | section. | ||
| 348 | For a description of the available mailing lists, see the | ||
| 349 | "<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing Lists</ulink>" | ||
| 350 | section in the Yocto Project Reference Manual. | ||
| 351 | </para></listitem> | ||
| 352 | </itemizedlist> | ||
| 353 | </para> | ||
| 354 | </section> | ||
| 355 | </section> | 368 | </section> |
| 356 | 369 | ||
| 357 | <section id='submitting-a-defect-against-the-yocto-project'> | 370 | <section id='submitting-a-defect-against-the-yocto-project'> |