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 @@ This chapter provides procedures related to getting set up to use the Yocto Project. You can learn about creating a team environment that develops using the - Yocto Project, how to set up a build host, how to locate Yocto Project - source repositories, and how to create local Git repositories. + Yocto Project, how to set up a + build host, + how to locate Yocto Project source repositories, and how to create local + Git repositories.
@@ -19,69 +21,71 @@ It might not be immediately clear how you can use the Yocto - Project in a team development environment, or scale it for a large - team of developers. + Project in a team development environment, or how to scale it for a + large team of developers. One of the strengths of the Yocto Project is that it is extremely flexible. Thus, you can adapt it to many different use cases and scenarios. - However, these characteristics can cause a struggle if you are trying + However, this flexibility could cause difficulties if you are trying to create a working setup that scales across a large team. To help you understand how to set up this type of environment, - this section presents a procedure that gives you the information - to learn how to get the results you want. + this section presents a procedure that gives you information + that can help you get the results you want. The procedure is high-level and presents some of the project's most successful experiences, practices, solutions, and available - technologies that work well. + technologies that have proved to work well in the past. Keep in mind, the procedure here is a starting point. - You can build off it and customize it to fit any + You can build off these steps and customize the procedure to fit any particular working environment and set of practices. Determine Who is Going to be Developing: You need to understand who is going to be doing anything related to the Yocto Project and what their roles would be. - Making this determination is essential to completing the + Making this determination is essential to completing steps two and three, which are to get your equipment together and set up your development environment's hardware topology. The following roles exist: - - - Application Development: - These types of developers do application level work - on top of an existing software stack. - - - Core System Development: - These types of developers work on the contents of the - operating system image itself. - - - Build Engineer: - This type of developer manages Autobuilders and - releases. - Not all environments need a Build Engineer. - - - Test Engineer: - This type of developer creates and manages automated - tests needed to ensure all application and core - system development meets desired quality standards. - - + + + Application Developer: + This type of developer does application level work + on top of an existing software stack. + + + Core System Developer: + This type of developer works on the contents of the + operating system image itself. + + + Build Engineer: + This type of developer manages Autobuilders and + releases. + Not all environments need a Build Engineer. + + + Test Engineer: + This type of developer creates and manages automated + tests that are used to ensure all application and + core system development meets desired quality + standards. + + Gather the Hardware: Based on the size and make-up of the team, get the hardware together. - Any development, build, or test engineer should be using - a system that is running a supported Linux distribution. - Systems, in general, should be high performance (e.g. dual, - six-core Xeons with 24 Gbytes of RAM and plenty of disk space). + Ideally, any development, build, or test engineer uses + a system that runs a supported Linux distribution. + These systems, in general, should be high performance + (e.g. dual, six-core Xeons with 24 Gbytes of RAM and plenty + of disk space). You can help ensure efficiency by having any machines used for testing or that run Autobuilders be as high performance as possible. @@ -107,11 +111,12 @@ Use Git as Your Source Control Manager (SCM): Keeping your Metadata - and any software you are developing under the - control of an SCM system that is compatible - with the OpenEmbedded build system is advisable. - Of the SCMs BitBake supports, the - Yocto Project team strongly recommends using + (i.e. recipes, configuration files, classes, and so forth) + and any software you are developing under the control of an SCM + system that is compatible with the OpenEmbedded build system + is advisable. + Of the SCMs BitBake supports, the Yocto Project team strongly + recommends using Git. Git is a distributed system that is easy to backup, allows you to work remotely, and then connects back to the @@ -129,20 +134,19 @@ being used to generate the web interface that lets you view the repositories. The gitolite software identifies users - using SSH keys and allows branch-based - access controls to repositories that you can control as little - or as much as necessary. - + using SSH keys and allows branch-based access controls to + repositories that you can control as little or as much as + necessary. The setup of these services is beyond the scope of this manual. - However, sites such as these exist that describe how to - perform setup: + However, sites such as the following exist that describe + how to perform setup: Git documentation: - Describes how to install gitolite - on the server. + Describes how to install + gitolite on the server. Gitolite: @@ -150,8 +154,8 @@ Interfaces, frontends, and tools: - Documentation on how to create interfaces and frontends - for Git. + Documentation on how to create interfaces and + frontends for Git. @@ -161,23 +165,22 @@ As mentioned earlier, application developers are creating applications on top of existing software stacks. Following are some best practices for setting up machines - that do application development: + used for application development: - Use a pre-built toolchain that - contains the software stack itself. + Use a pre-built toolchain that contains the software + stack itself. Then, develop the application code on top of the stack. This method works well for small numbers of relatively isolated applications. - When possible, use the Yocto Project - plug-in for the + When possible, use the Yocto Project plug-in for the Eclipse IDE and SDK development practices. For more information, see the - "Yocto Project Application Development and the Extensible Software Development Kit (eSDK)" + Yocto Project Application Development and the Extensible Software Development Kit (eSDK) manual. @@ -186,27 +189,29 @@ toolchain downloads or as updates through a package update mechanism using opkg to provide updates to an existing toolchain. - The exact mechanics of how and when to do this are a - question for local policy. + The exact mechanics of how and when to do this depend + on local policy. - Use multiple toolchains installed locally - into different locations to allow development across + Use multiple toolchains installed locally into + different locations to allow development across versions. Set up the Core Development Machines: - As mentioned earlier, these types of developers work on the - contents of the operating system itself. + As mentioned earlier, core developers work on the contents of + the operating system itself. Following are some best practices for setting up machines used for developing images: - Have the Yocto Project build system itself available on - the developer workstations so developers can run their own - builds and directly rebuild the software stack. + Have the + OpenEmbedded build system + available on the developer workstations so developers + can run their own builds and directly rebuild the + software stack. Keep the core system unchanged as much as @@ -228,8 +233,9 @@ Autobuilders are often the core of the development environment. It is here that changes from individual developers are brought - together and centrally tested and subsequent decisions about - releases can be made. + together and centrally tested. + Based on this automated build and test environment, subsequent + decisions about releases can be made. Autobuilders also allow for "continuous integration" style testing of software components and regression identification and tracking. @@ -239,22 +245,23 @@ The Yocto Project team has found this implementation works well in this role. A public example of this is the Yocto Project - Autobuilders, which we use to test the overall health of the - project. + Autobuilders, which the Yocto Project team uses to test the + overall health of the project. The features of this system are: - Highlights when commits break the build. - - - Populates an sstate cache from which - developers can pull rather than requiring local - builds. + Highlights when commits break the build. - Allows commit hook triggers, - which trigger builds when commits are made. + Populates an + sstate cache + from which developers can pull rather than requiring + local builds. + + + Allows commit hook triggers, which trigger builds when + commits are made. Allows triggering of automated image booting @@ -275,19 +282,19 @@ Allows scheduling of builds so that resources can be used efficiently. - - - - Set up Test Machines: - Use a small number of shared, high performance systems - for testing purposes. - Developers can use these systems for wider, more - extensive testing while they continue to develop - locally using their primary development system. - - - Document Policies and Change Flow: - The Yocto Project itself uses a hierarchical structure and a + + + + Set up Test Machines: + Use a small number of shared, high performance systems + for testing purposes. + Developers can use these systems for wider, more + extensive testing while they continue to develop + locally using their primary development system. + + + Document Policies and Change Flow: + The Yocto Project uses a hierarchical structure and a pull model. Scripts exist to create and send pull requests (i.e. create-pull-request and @@ -330,16 +337,20 @@ Maintain your Metadata in layers that make sense for your situation. - See the "Understanding - and Creating Layers" section for more information on - layers. + See the + "The Yocto Project Layer Model" + section in the Yocto Project Overview and Concepts + Manual and the + "Understanding and Creating Layers" + section for more information on layers. Separate the project's Metadata and code by using separate Git repositories. See the "Yocto Project Source Repositories" - section for information on these repositories. + section in the Yocto Project Overview and Concepts + Manual for information on these repositories. See the "Locating Yocto Project Source Files" section for information on how to set up local Git @@ -360,7 +371,8 @@ The Yocto Project community encourages you - to send patches to the project to fix bugs or add features. + to send patches to the project to fix bugs or add + features. If you do submit patches, follow the project commit guidelines for writing good commit messages. See the "Submitting a Change to the Yocto Project" @@ -369,10 +381,12 @@ Send changes to the core sooner than later as others are likely to run into the same issues. - For some guidance on mailing lists to use, see the list in the + For some guidance on mailing lists to use, see the list + in the "Submitting a Change to the Yocto Project" section. - For a description of the available mailing lists, see the + For a description of the available mailing lists, see + the "Mailing Lists" section in the Yocto Project Reference Manual.