summaryrefslogtreecommitdiffstats
path: root/documentation
diff options
context:
space:
mode:
Diffstat (limited to 'documentation')
-rw-r--r--documentation/getting-started/getting-started-development-environment.xml375
1 files changed, 254 insertions, 121 deletions
diff --git a/documentation/getting-started/getting-started-development-environment.xml b/documentation/getting-started/getting-started-development-environment.xml
index 54a607f6ab..f7d646c2b7 100644
--- a/documentation/getting-started/getting-started-development-environment.xml
+++ b/documentation/getting-started/getting-started-development-environment.xml
@@ -15,9 +15,8 @@
15</para> 15</para>
16 16
17<para> 17<para>
18 Specifically, this chapter addresses open source philosophy, workflows, 18 Specifically, this chapter addresses open source philosophy, source
19 Git, source repositories, licensing, and development 19 repositories, workflows, Git, and licensing.
20 syntax.
21</para> 20</para>
22 21
23<section id='open-source-philosophy'> 22<section id='open-source-philosophy'>
@@ -66,8 +65,256 @@
66 </para> 65 </para>
67</section> 66</section>
68 67
69<section id='workflows'> 68<section id='gs-the-development-host'>
70 <title>Workflows</title> 69 <title>The Development Host</title>
70
71 <para>
72 A development host or build host is key to using the Yocto Project.
73 Because the goal of the Yocto Project is to develop images or
74 applications that run on embedded hardware, development of those
75 images and applications generally takes place on a system not
76 intended to run the software - the development host.
77 </para>
78
79 <para>
80 You need to set up a development host in order to use it with the
81 Yocto Project.
82 Most find that it is best to have a native Linux machine function as
83 the development host.
84 However, it is possible to use a system that does not run Linux
85 as its operating system as your development host.
86 When you have a Mac or Windows-based system, you can set it up
87 as the development host by using
88 <ulink url='https://git.yoctoproject.org/cgit/cgit.cgi/crops/about/'>CROPS</ulink>,
89 which leverages
90 <ulink url='https://www.docker.com/'>Docker Containers</ulink>.
91 Once you take the steps to set up a CROPS machine, you effectively
92 have access to a shell environment that is similar to what you see
93 when using a Linux-based development host.
94 For the steps needed to set up a system using CROPS, see the
95 "<ulink url='&YOCTO_DOCS_DEV_URL;#setting-up-to-use-crops'>Setting Up to Use CROss PlatformS (CROPS)</ulink>"
96 section in the Yocto Project Development Tasks Manual.
97 </para>
98
99 <para>
100 If your development host is going to be a system that runs a Linux
101 distribution, steps still exist that you must take to prepare the
102 system for use with the Yocto Project.
103 You need to be sure that the Linux distribution on the system is
104 one that supports the Yocto Project.
105 You also need to be sure that the correct set of host packages are
106 installed that allow development using the Yocto Project.
107 For the steps needed to set up a development host that runs Linux,
108 see the
109 "<ulink url='&YOCTO_DOCS_DEV_URL;#setting-up-a-native-linux-host'>Setting Up a Native Linux Host</ulink>"
110 section in the Yocto Project Development Tasks Manual.
111 </para>
112
113 <para>
114 Once your development host is set up to use the Yocto Project,
115 several methods exist for you to do work in the Yocto Project
116 environment:
117 <itemizedlist>
118 <listitem><para>
119 <emphasis>Command Lines, BitBake, and Shells:</emphasis>
120 Traditional development in the Yocto Project involves using
121 OpenEmbedded build system, which uses BitBake, in a
122 command-line environment from a shell on your development
123 host.
124 You can accomplish this from a host that is a native Linux
125 machine or from a host that has been set up with CROPS.
126 Either way, you create, modify, and build images and
127 applications all within a shell-based environment using
128 components and tools available through your Linux distribution
129 and the Yocto Project.</para>
130
131 <para>For a general flow of the build procedures, see the
132 "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-building-an-image'>Building an Image</ulink>"
133 section in the Yocto Project Development Tasks Manual.
134 </para></listitem>
135 <listitem><para>
136 <emphasis>Board Support Package (BSP) Development:</emphasis>
137 Development of BSPs involves using the Yocto Project to
138 create and test layers that allow easy development of
139 images and applications targeted for specific hardware.
140 To development BSPs, you need to take some additional steps
141 beyond what was described in setting up a development host.
142 </para>
143
144 <para>The
145 <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide'</ulink>
146 provides BSP-related development information.
147 For specifics on development host preparation, see the
148 "<ulink url='&YOCTO_DOCS_BSP_URL;#preparing-your-build-host-to-work-with-bsp-layers'>Preparing Your Build Host to Work With BSP Layers</ulink>"
149 section in the Yocto Project Board Support Package (BSP)
150 Developer's Guide.
151 </para></listitem>
152 <listitem><para>
153 <emphasis>Kernel Development:</emphasis>
154 If you are going to be developing kernels using the Yocto
155 Project you likely will be using <filename>devtool</filename>.
156 A workflow using <filename>devtool</filename> makes kernel
157 development quicker by reducing iteration cycle times.</para>
158
159 <para>The
160 <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;'>Yocto Project Linux Kernel Development Manual</ulink>
161 provides kernel-related development information.
162 For specifics on development host preparation, see the
163 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#preparing-the-build-host-to-work-on-the-kernel'>Preparing the Build Host to Work on the Kernel</ulink>"
164 section in the Yocto Project Linux Kernel Development Manual.
165 </para></listitem>
166 <listitem><para>
167 <emphasis>Using the <trademark class='trade'>Eclipse</trademark> IDE:</emphasis>
168 One of two Yocto Project development methods that involves an
169 interface that effectively puts the Yocto Project into the
170 background is the popular Eclipse IDE.
171 This method of development is advantageous if you are already
172 familiar with working within Eclipse.
173 Development is supported through a plugin that you install
174 onto your development host.</para>
175
176 <para>For steps that show you how to set up your development
177 host to use the Eclipse Yocto Project plugin, see the
178 "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-eclipse-project'>Developing Applications Using <trademark class='trade'>Eclipse</trademark></ulink>"
179 Chapter in the Yocto Project Application Development and the
180 Extensible Software Development Kit (eSDK) manual.
181 </para></listitem>
182 <listitem><para>
183 <emphasis>Using the Toaster:</emphasis>
184 The other Yocto Project development method that involves an
185 interface that effectively puts the Yocto Project into the
186 background is Toaster.
187 Toaster provides an interface to the OpenEmbedded build system.
188 The interface enables you to configure and run your builds.
189 Information about builds is collected and stored in a database.
190 You can use Toaster to configure and start builds on multiple
191 remote build servers.</para>
192
193 <para>For steps that show you how to set up your development
194 host to use Toaster and on how to use Toaster in general,
195 see the
196 <ulink url='&YOCTO_DOCS_TOAST_URL;'>Toaster User Manual</ulink>.
197 </para></listitem>
198 </itemizedlist>
199 </para>
200</section>
201
202<section id='yocto-project-repositories'>
203 <title>Yocto Project Source Repositories</title>
204
205 <para>
206 The Yocto Project team maintains complete source repositories for all
207 Yocto Project files at
208 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi'></ulink>.
209 This web-based source code browser is organized into categories by
210 function such as IDE Plugins, Matchbox, Poky, Yocto Linux Kernel, and
211 so forth.
212 From the interface, you can click on any particular item in the "Name"
213 column and see the URL at the bottom of the page that you need to clone
214 a Git repository for that particular item.
215 Having a local Git repository of the
216 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>,
217 which is usually named "poky", allows
218 you to make changes, contribute to the history, and ultimately enhance
219 the Yocto Project's tools, Board Support Packages, and so forth.
220 </para>
221
222 <para>
223 For any supported release of Yocto Project, you can also go to the
224 <ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink> and
225 select the "Downloads" tab and get a released tarball of the
226 <filename>poky</filename> repository or any supported BSP tarballs.
227 Unpacking these tarballs gives you a snapshot of the released
228 files.
229 <note><title>Notes</title>
230 <itemizedlist>
231 <listitem><para>
232 The recommended method for setting up the Yocto Project
233 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
234 and the files for supported BSPs
235 (e.g., <filename>meta-intel</filename>) is to use
236 <link linkend='git'>Git</link> to create a local copy of
237 the upstream repositories.
238 </para></listitem>
239 <listitem><para>
240 Be sure to always work in matching branches for both
241 the selected BSP repository and the
242 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
243 (i.e. <filename>poky</filename>) repository.
244 For example, if you have checked out the "master" branch
245 of <filename>poky</filename> and you are going to use
246 <filename>meta-intel</filename>, be sure to checkout the
247 "master" branch of <filename>meta-intel</filename>.
248 </para></listitem>
249 </itemizedlist>
250 </note>
251 </para>
252
253 <para>
254 In summary, here is where you can get the project files needed for
255 development:
256 <itemizedlist>
257 <listitem><para id='source-repositories'>
258 <emphasis>
259 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi'>Source Repositories:</ulink>
260 </emphasis>
261 This area contains IDE Plugins, Matchbox, Poky, Poky Support,
262 Tools, Yocto Linux Kernel, and Yocto Metadata Layers.
263 You can create local copies of Git repositories for each of
264 these areas.</para>
265
266 <para>
267 <imagedata fileref="figures/source-repos.png" align="center" width="6in" depth="4in" />
268 For steps on how to view and access these upstream Git
269 repositories, see the
270 "<ulink url='&YOCTO_DOCS_DEV_URL;#accessing-source-repositories'>Accessing Source Repositories</ulink>"
271 Section in the Yocto Project Development Tasks Manual.
272 </para></listitem>
273 <listitem><para><anchor id='index-downloads' />
274 <emphasis>
275 <ulink url='&YOCTO_DL_URL;/releases/'>Index of /releases:</ulink>
276 </emphasis>
277 This is an index of releases such as
278 the <trademark class='trade'>Eclipse</trademark>
279 Yocto Plug-in, miscellaneous support, Poky, Pseudo, installers
280 for cross-development toolchains, and all released versions of
281 Yocto Project in the form of images or tarballs.
282 Downloading and extracting these files does not produce a local
283 copy of the Git repository but rather a snapshot of a
284 particular release or image.</para>
285
286 <para>
287 <imagedata fileref="figures/index-downloads.png" align="center" width="6in" depth="3.5in" />
288 For steps on how to view and access these files, see the
289 "<ulink url='&YOCTO_DOCS_DEV_URL;#accessing-index-of-releases'>Accessing Index of Releases</ulink>"
290 section in the Yocto Project Development Tasks Manual.
291 </para></listitem>
292 <listitem><para id='downloads-page'>
293 <emphasis>"Downloads" page for the
294 <ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink>:
295 </emphasis></para>
296
297 <para role="writernotes">This section will change due to
298 reworking of the YP Website.</para>
299
300 <para>The Yocto Project website includes a "Downloads" tab
301 that allows you to download any Yocto Project
302 release and Board Support Package (BSP) in tarball form.
303 The tarballs are similar to those found in the
304 <ulink url='&YOCTO_DL_URL;/releases/'>Index of /releases:</ulink> area.</para>
305
306 <para>
307 <imagedata fileref="figures/yp-download.png" align="center" width="6in" depth="4in" />
308 For steps on how to use the "Downloads" page, see the
309 "<ulink url='&YOCTO_DOCS_DEV_URL;#using-the-downloads-page'>Using the Downloads Page</ulink>"
310 section in the Yocto Project Development Tasks Manual.
311 </para></listitem>
312 </itemizedlist>
313 </para>
314</section>
315
316<section id='gs-git-workflows-and-the-yocto-project'>
317 <title>Git Workflows and the Yocto Project</title>
71 318
72 <para> 319 <para>
73 This section provides workflow concepts using the Yocto Project and 320 This section provides workflow concepts using the Yocto Project and
@@ -298,8 +545,8 @@
298 545
299 <para> 546 <para>
300 As mentioned briefly in the previous section and also in the 547 As mentioned briefly in the previous section and also in the
301 "<link linkend='workflows'>Workflows</link>" section, 548 "<link linkend='gs-git-workflows-and-the-yocto-project'>Git Workflows and the Yocto Project</link>"
302 the Yocto Project maintains source repositories at 549 section, the Yocto Project maintains source repositories at
303 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>. 550 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>.
304 If you look at this web-interface of the repositories, each item 551 If you look at this web-interface of the repositories, each item
305 is a separate Git repository. 552 is a separate Git repository.
@@ -622,120 +869,6 @@
622 </section> 869 </section>
623</section> 870</section>
624 871
625<section id='yocto-project-repositories'>
626 <title>Yocto Project Source Repositories</title>
627
628 <para>
629 The Yocto Project team maintains complete source repositories for all
630 Yocto Project files at
631 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi'></ulink>.
632 This web-based source code browser is organized into categories by
633 function such as IDE Plugins, Matchbox, Poky, Yocto Linux Kernel, and
634 so forth.
635 From the interface, you can click on any particular item in the "Name"
636 column and see the URL at the bottom of the page that you need to clone
637 a Git repository for that particular item.
638 Having a local Git repository of the
639 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>,
640 which is usually named "poky", allows
641 you to make changes, contribute to the history, and ultimately enhance
642 the Yocto Project's tools, Board Support Packages, and so forth.
643 </para>
644
645 <para>
646 For any supported release of Yocto Project, you can also go to the
647 <ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink> and
648 select the "Downloads" tab and get a released tarball of the
649 <filename>poky</filename> repository or any supported BSP tarballs.
650 Unpacking these tarballs gives you a snapshot of the released
651 files.
652 <note><title>Notes</title>
653 <itemizedlist>
654 <listitem><para>
655 The recommended method for setting up the Yocto Project
656 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
657 and the files for supported BSPs
658 (e.g., <filename>meta-intel</filename>) is to use
659 <link linkend='git'>Git</link> to create a local copy of
660 the upstream repositories.
661 </para></listitem>
662 <listitem><para>
663 Be sure to always work in matching branches for both
664 the selected BSP repository and the
665 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
666 (i.e. <filename>poky</filename>) repository.
667 For example, if you have checked out the "master" branch
668 of <filename>poky</filename> and you are going to use
669 <filename>meta-intel</filename>, be sure to checkout the
670 "master" branch of <filename>meta-intel</filename>.
671 </para></listitem>
672 </itemizedlist>
673 </note>
674 </para>
675
676 <para>
677 In summary, here is where you can get the project files needed for
678 development:
679 <itemizedlist>
680 <listitem><para id='source-repositories'>
681 <emphasis>
682 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi'>Source Repositories:</ulink>
683 </emphasis>
684 This area contains IDE Plugins, Matchbox, Poky, Poky Support,
685 Tools, Yocto Linux Kernel, and Yocto Metadata Layers.
686 You can create local copies of Git repositories for each of
687 these areas.</para>
688
689 <para>
690 <imagedata fileref="figures/source-repos.png" align="center" width="6in" depth="4in" />
691 For steps on how to view and access these upstream Git
692 repositories, see the
693 "<ulink url='&YOCTO_DOCS_DEV_URL;#accessing-source-repositories'>Accessing Source Repositories</ulink>"
694 Section in the Yocto Project Development Tasks Manual.
695 </para></listitem>
696 <listitem><para><anchor id='index-downloads' />
697 <emphasis>
698 <ulink url='&YOCTO_DL_URL;/releases/'>Index of /releases:</ulink>
699 </emphasis>
700 This is an index of releases such as
701 the <trademark class='trade'>Eclipse</trademark>
702 Yocto Plug-in, miscellaneous support, Poky, Pseudo, installers
703 for cross-development toolchains, and all released versions of
704 Yocto Project in the form of images or tarballs.
705 Downloading and extracting these files does not produce a local
706 copy of the Git repository but rather a snapshot of a
707 particular release or image.</para>
708
709 <para>
710 <imagedata fileref="figures/index-downloads.png" align="center" width="6in" depth="3.5in" />
711 For steps on how to view and access these files, see the
712 "<ulink url='&YOCTO_DOCS_DEV_URL;#accessing-index-of-releases'>Accessing Index of Releases</ulink>"
713 section in the Yocto Project Development Tasks Manual.
714 </para></listitem>
715 <listitem><para id='downloads-page'>
716 <emphasis>"Downloads" page for the
717 <ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink>:
718 </emphasis></para>
719
720 <para role="writernotes">This section will change due to
721 reworking of the YP Website.</para>
722
723 <para>The Yocto Project website includes a "Downloads" tab
724 that allows you to download any Yocto Project
725 release and Board Support Package (BSP) in tarball form.
726 The tarballs are similar to those found in the
727 <ulink url='&YOCTO_DL_URL;/releases/'>Index of /releases:</ulink> area.</para>
728
729 <para>
730 <imagedata fileref="figures/yp-download.png" align="center" width="6in" depth="4in" />
731 For steps on how to use the "Downloads" page, see the
732 "<ulink url='&YOCTO_DOCS_DEV_URL;#using-the-downloads-page'>Using the Downloads Page</ulink>"
733 section in the Yocto Project Development Tasks Manual.
734 </para></listitem>
735 </itemizedlist>
736 </para>
737</section>
738
739<section id='licensing'> 872<section id='licensing'>
740 <title>Licensing</title> 873 <title>Licensing</title>
741 874