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 @@ The Yocto Project Open Source Development Environment -
- Setting Up a Team Yocto Project 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. - - - - - -
-
Submitting a Defect Against the Yocto Project 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.