From d38c9ba94aada3d07eb9b6700a2a16b9e205252a Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Wed, 16 May 2018 13:10:58 -0700 Subject: 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 Signed-off-by: Richard Purdie --- documentation/dev-manual/dev-manual-start.xml | 378 +++++++++++++++++++++++++- 1 file changed, 374 insertions(+), 4 deletions(-) (limited to 'documentation/dev-manual/dev-manual-start.xml') 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 @@ -Getting Started with the Yocto Project +Setting Up to Use the Yocto Project This chapter provides procedures related to getting set up to use the - Yocto Project, working with Yocto Project source files, and building - an image. + 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. +
+ Creating a Team Development Environment + + + 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. + 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 + 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. + The procedure is high-level and presents some of the project's most + successful experiences, practices, solutions, and available + technologies that work well. + Keep in mind, the procedure here is a starting point. + You can build off it and customize it 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 + 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. + + + + + 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). + You can help ensure efficiency by having any machines used + for testing or that run Autobuilders be as high performance + as possible. + + + Understand the Hardware Topology of the Environment: + Once you understand the hardware involved and the make-up + of the team, you can understand the hardware topology of the + development environment. + You can get a visual idea of the machines and their roles + across the development environment. + + + + + + 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 + Git. + Git is a distributed system that is easy to backup, + allows you to work remotely, and then connects back to the + infrastructure. + + For information about BitBake, see the + BitBake User Manual. + + + It is relatively easy to set up Git services and create + infrastructure like + http://git.yoctoproject.org, + which is based on server software called + gitolite with cgit + 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. + + + The setup of these services is beyond the scope of this + manual. + However, sites such as these exist that describe how to + perform setup: + + + Git documentation: + Describes how to install gitolite + on the server. + + + Gitolite: + Information for gitolite. + + + Interfaces, frontends, and tools: + Documentation on how to create interfaces and frontends + for Git. + + + + + + Set up the Application Development Machines: + 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: + + + 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 + Eclipse IDE + and SDK development practices. + For more information, see the + "Yocto Project Application Development and the Extensible Software Development Kit (eSDK)" + manual. + + + Keep your cross-development toolchains updated. + You can do this through provisioning either as new + 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. + + + 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. + 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. + + + Keep the core system unchanged as much as + possible and do your work in layers on top of the + core system. + Doing so gives you a greater level of portability when + upgrading to new versions of the core system or Board + Support Packages (BSPs). + + + Share layers amongst the developers of a + particular project and contain the policy configuration + that defines the project. + + + + + Set up an Autobuilder: + 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. + Autobuilders also allow for "continuous integration" style + testing of software components and regression identification + and tracking. + + See "Yocto Project Autobuilder" + for more information and links to buildbot. + 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. + + 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. + + + Allows commit hook triggers, + which trigger builds when commits are made. + + + Allows triggering of automated image booting + and testing under the QuickEMUlator (QEMU). + + + Supports incremental build testing and + from-scratch builds. + + + Shares output that allows developer + testing and historical regression investigation. + + + Creates output that can be used for releases. + + + 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 + pull model. + Scripts exist to create and send pull requests + (i.e. create-pull-request and + send-pull-request). + This model is in line with other open source projects where + maintainers are responsible for specific areas of the project + and a single maintainer handles the final "top-of-tree" merges. + + You can also use a more collective push model. + The gitolite software supports both the + push and pull models quite easily. + + + As with any development environment, it is important + to document the policy used as well as any main project + guidelines so they are understood by everyone. + It is also a good idea to have well structured + commit messages, which are usually a part of a project's + guidelines. + Good commit messages are essential when looking back in time and + trying to understand why changes were made. + + If you discover that changes are needed to the core + layer of the project, it is worth sharing those with the + community as soon as possible. + Chances are if you have discovered the need for changes, + someone else in the community needs them also. + + + Development Environment Summary: + Aside from the previous steps, some best practices exist + within the Yocto Project development environment. + Consider the following: + + + Use + Git + as the source control system. + + + Maintain your Metadata in layers that make sense + for your situation. + See 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. + See the + "Working With Yocto Project Source Files" + section for information on how to set up local Git + repositories for related upstream Yocto Project + Git repositories. + + + Set up the directory for the shared state cache + (SSTATE_DIR) + where it makes sense. + For example, set up the sstate cache on a system used + by developers in the same organization and share the + same source directories on their machines. + + + Set up an Autobuilder and have it populate the + sstate cache and source directories. + + + The Yocto Project community encourages you + 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" + section. + + + 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 + "Submitting a Change to the Yocto Project" + section. + For a description of the available mailing lists, see the + "Mailing Lists" + section in the Yocto Project Reference Manual. + + + + + +
+
Setting Up the Development Host to Use the Yocto Project @@ -760,7 +1130,7 @@ Set up Your Host Development System to Support Development Using the Yocto Project: See the - "Getting Started With the Yocto Project" + "Setting Up to Use the Yocto Project" section for options on how to get a build host ready to use the Yocto Project. -- cgit v1.2.3-54-g00ecf