summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2017-06-28 09:20:48 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2017-07-12 00:28:13 +0100
commitba6887404aa400bbed125dce3614399e42438f26 (patch)
tree2b7c61c2ae8e21f8a3df38f139bbe2f8d5020612 /documentation/dev-manual
parented25d7df9cc755cfcbf24e3a83f129ad8e1575e9 (diff)
downloadpoky-ba6887404aa400bbed125dce3614399e42438f26.tar.gz
documentation: Re-write of dev-manual setup chapter
Fixes [YOCTO #11630] The chapter on setting up YP has been completely re-written to move towards a "how-to" manual. This involved touching every aspect of the chapter. All subsections now have procedures surrounding set up stuff. There are some development sections that still need fleshed out. Many, many links and references in other chapters were affected. These have been fixed. A couple style-sheet (*.css) files were also updated to support the "writernotes" style, which renders paragraph text in red. (From yocto-docs rev: c4c2a6cf575ce5c783b1cc84d9f7e961aebef49c) Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/dev-manual')
-rw-r--r--documentation/dev-manual/dev-manual-model.xml12
-rw-r--r--documentation/dev-manual/dev-manual-newbie.xml2
-rw-r--r--documentation/dev-manual/dev-manual-start.xml576
3 files changed, 369 insertions, 221 deletions
diff --git a/documentation/dev-manual/dev-manual-model.xml b/documentation/dev-manual/dev-manual-model.xml
index 5c0f5cd851..d2c84eae03 100644
--- a/documentation/dev-manual/dev-manual-model.xml
+++ b/documentation/dev-manual/dev-manual-model.xml
@@ -130,14 +130,17 @@
130 process and to the tools you need. 130 process and to the tools you need.
131 For information on how to set up the Source Directory, 131 For information on how to set up the Source Directory,
132 see the 132 see the
133 "<link linkend='getting-setup'>Getting Set Up</link>" section.</para></listitem> 133 "<link linkend='working-with-yocto-project-source-files'>Working With Yocto Project Source Files</link>"
134 section.
135 </para></listitem>
134 <listitem><para><emphasis>Establish the <filename>meta-intel</filename> 136 <listitem><para><emphasis>Establish the <filename>meta-intel</filename>
135 repository on your system</emphasis>: Having local copies 137 repository on your system</emphasis>: Having local copies
136 of these supported BSP layers on your system gives you 138 of these supported BSP layers on your system gives you
137 access to layers you might be able to build on or modify 139 access to layers you might be able to build on or modify
138 to create your BSP. 140 to create your BSP.
139 For information on how to get these files, see the 141 For information on how to get these files, see the
140 "<link linkend='getting-setup'>Getting Set Up</link>" section.</para></listitem> 142 "<link linkend='setting-up-bsp-layers'>Setting Up BSP Layers</link>" section.
143 </para></listitem>
141 <listitem><para><emphasis>Create your own BSP layer using the 144 <listitem><para><emphasis>Create your own BSP layer using the
142 <ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'><filename>yocto-bsp</filename></ulink> script</emphasis>: 145 <ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'><filename>yocto-bsp</filename></ulink> script</emphasis>:
143 Layers are ideal for 146 Layers are ideal for
@@ -475,8 +478,9 @@
475 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink> 478 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
476 on your system gives you access to the build process and tools 479 on your system gives you access to the build process and tools
477 you need. 480 you need.
478 For information on how to get these files, see the bulleted item 481 For information on how to get these files, see the
479 "<link linkend='local-yp-release'>Yocto Project Release</link>" earlier in this manual. 482 "<link linkend='cloning-the-poky-repository'>Cloning the <filename>poky</filename> Repository</link>"
483 section.
480 </para></listitem> 484 </para></listitem>
481 <listitem><para><emphasis>Establish the temporary kernel source files</emphasis>: 485 <listitem><para><emphasis>Establish the temporary kernel source files</emphasis>:
482 Temporary kernel source files are kept in the 486 Temporary kernel source files are kept in the
diff --git a/documentation/dev-manual/dev-manual-newbie.xml b/documentation/dev-manual/dev-manual-newbie.xml
index 6dfec666be..86561271ba 100644
--- a/documentation/dev-manual/dev-manual-newbie.xml
+++ b/documentation/dev-manual/dev-manual-newbie.xml
@@ -326,7 +326,7 @@
326 "<ulink url='&YOCTO_DOCS_REF_URL;#yocto-project-repositories'>Yocto Project Source Repositories</ulink>" 326 "<ulink url='&YOCTO_DOCS_REF_URL;#yocto-project-repositories'>Yocto Project Source Repositories</ulink>"
327 section for information on these repositories. 327 section for information on these repositories.
328 See the 328 See the
329 "<link linkend='getting-setup'>Getting Set Up</link>" 329 "<link linkend='working-with-yocto-project-source-files'>Working With Yocto Project Source Files</link>"
330 section for information on how to set up local Git 330 section for information on how to set up local Git
331 repositories for related upstream Yocto Project 331 repositories for related upstream Yocto Project
332 Git repositories. 332 Git repositories.
diff --git a/documentation/dev-manual/dev-manual-start.xml b/documentation/dev-manual/dev-manual-start.xml
index cdb349be3a..e1b2e5d4c7 100644
--- a/documentation/dev-manual/dev-manual-start.xml
+++ b/documentation/dev-manual/dev-manual-start.xml
@@ -14,236 +14,354 @@
14 <ulink url='&YOCTO_DOCS_QS_URL;'>Yocto Project Quick Start</ulink>. 14 <ulink url='&YOCTO_DOCS_QS_URL;'>Yocto Project Quick Start</ulink>.
15</para> 15</para>
16 16
17<section id='getting-setup'> 17<section id='setting-up-the-development-host-to-use-the-yocto-project'>
18 <title>Getting Set Up</title> 18 <title>Setting Up the Development Host to Use the Yocto Project</title>
19 19
20 <para> 20 <para>
21 Here is what you need to use the Yocto Project: 21 This section provides procedures to set up your development host to
22 <itemizedlist> 22 use the Yocto Project.
23 <listitem><para><emphasis>Host System:</emphasis> You should have a reasonably current 23 For a Linux system to use the Yocto Project, you need to be sure
24 Linux-based host system. 24 you are running a supported Linux distribution and have the proper
25 You will have the best results with a recent release of Fedora, 25 host packages installed.
26 openSUSE, Debian, Ubuntu, or CentOS as these releases are frequently tested against the Yocto Project 26 If you are using
27 and officially supported. 27 <ulink url='https://git.yoctoproject.org/cgit/cgit.cgi/crops/about/'>CROPS</ulink>
28 For a list of the distributions under validation and their status, see the 28 that leverages
29 "<ulink url='&YOCTO_DOCS_REF_URL;#detailed-supported-distros'>Supported Linux Distributions</ulink>" section 29 <ulink url='https://www.docker.com/'>Docker Containers</ulink>,
30 in the Yocto Project Reference Manual and the wiki page at 30 host setup differs from that of a native Linux machine.
31 <ulink url='&YOCTO_WIKI_URL;/wiki/Distribution_Support'>Distribution Support</ulink>.</para> 31 </para>
32 <para> 32
33 You should also have about 50 Gbytes of free disk space for building images. 33 <section id='setting-up-a-native-linux-host'>
34 </para></listitem> 34 <title>Setting Up a Native Linux Host</title>
35 <listitem><para><emphasis>Packages:</emphasis> The OpenEmbedded build system 35
36 requires that certain packages exist on your development system (e.g. Python 2.7). 36 <para role='writernotes'>
37 See "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Build Host Packages</ulink>" 37 Need text - Following is some basics for a Linux host system.
38 section in the Yocto Project Quick Start and the 38 This information needs to be worked in.
39 "<ulink url='&YOCTO_DOCS_REF_URL;#required-packages-for-the-host-development-system'>Required Packages for the Host Development System</ulink>" 39 </para>
40 section in the Yocto Project Reference Manual for the exact 40
41 package requirements and the installation commands to install 41 <para>
42 them for the supported distributions. 42 Setup consists of making sure you have a supported operating system,
43 </para></listitem> 43 installing host packages, and Here is what you need to use the Yocto Project:
44 <listitem id='local-yp-release'><para><emphasis>Yocto Project Release:</emphasis> 44 <itemizedlist>
45 You need a release of the Yocto Project locally installed on 45 <listitem><para>
46 your development system. 46 <emphasis>Host System:</emphasis>
47 The documentation refers to this set of locally installed files 47 You should have a reasonably current Linux-based host
48 as the <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>. 48 system.
49 You create your Source Directory by using 49 You will have the best results with a recent release of
50 <ulink url='&YOCTO_DOCS_REF_URL;#git'>Git</ulink> to clone a local copy 50 Fedora, openSUSE, Debian, Ubuntu, or CentOS as these
51 of the upstream <filename>poky</filename> repository, 51 releases are frequently tested against the Yocto Project
52 or by downloading and unpacking a tarball of an official 52 and officially supported.
53 Yocto Project release. 53 For a list of the distributions under validation and their
54 The preferred method is to create a clone of the repository. 54 status, see the
55 </para> 55 "<ulink url='&YOCTO_DOCS_REF_URL;#detailed-supported-distros'>Supported Linux Distributions</ulink>" section
56 <para>Working from a copy of the upstream repository allows you 56 in the Yocto Project Reference Manual and the wiki page at
57 to contribute back into the Yocto Project or simply work with 57 <ulink url='&YOCTO_WIKI_URL;/wiki/Distribution_Support'>Distribution Support</ulink>.</para>
58 the latest software on a development branch. 58 <para>
59 Because Git maintains and creates an upstream repository with 59 You should also have about 50 Gbytes of free disk space
60 a complete history of changes and you are working with a local 60 for building images.
61 clone of that repository, you have access to all the Yocto 61 </para></listitem>
62 Project development branches and tag names used in the upstream 62 <listitem><para>
63 repository.</para> 63 <emphasis>Packages:</emphasis>
64 <note>You can view the Yocto Project Source Repositories at 64 The OpenEmbedded build system requires that certain
65 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink> 65 packages exist on your development system
66 (e.g. Python 2.7).
67 See the
68 "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>Build Host Packages</ulink>"
69 section in the Yocto Project Quick Start and the
70 "<ulink url='&YOCTO_DOCS_REF_URL;#required-packages-for-the-host-development-system'>Required Packages for the Host Development System</ulink>"
71 section in the Yocto Project Reference Manual for the
72 exact package requirements and the installation commands
73 to install them for the supported distributions.
74 </para></listitem>
75 </itemizedlist>
76 </para>
77 </section>
78
79 <section id='setting-up-to-use-crops'>
80 <title>Setting Up to Use CROPS</title>
81
82 <para role='writernotes'>
83 Need text.
84 With CROPS, not sure what the basic package requirements are.
85 Need to find this out.
86 </para>
87 </section>
88
89 <section id='setting-up-bsp-layers'>
90 <title>Setting Up BSP Layers</title>
91
92 <para>
93 This section describes how to set up a layer for a Board Support
94 Package (BSP).
95 For structural information on BSPs, see the
96 <ulink url='&YOCTO_DOCS_BSP_URL;#bsp-guide'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>.
97 <orderedlist>
98 <listitem><para>
99 <emphasis>Determine the BSP Layer You Want:</emphasis>
100 The Yocto Project supports many BSPs, which are maintained in
101 their own layers or in layers designed to contain several
102 BSPs.
103 To get an idea of machine support through BSP layers, you can
104 look at the
105 <ulink url='&YOCTO_RELEASE_DL_URL;/machines'>index of machines</ulink>
106 for the release.
107 <note>
108 The Yocto Project uses the following BSP layer naming
109 scheme:
110 <literallayout class='monospaced'>
111 meta-<replaceable>bsp_name</replaceable>
112 </literallayout>
113 where <replaceable>bsp_name</replaceable> is the recognized
114 BSP name.
115 Here is an example:
116 <literallayout class='monospaced'>
117 meta-raspberrypi
118 </literallayout>
119 See the
120 "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>"
121 section in the Yocto Project Board Support Package (BSP)
122 Developer's Guide for more information on BSP Layers.
123 </note>
124 </para></listitem>
125 <listitem><para>
126 <emphasis>Optionally Set Up the <filename>meta-intel</filename> BSP Layer:</emphasis>
127 If your hardware is based on current Intel CPUs and devices,
128 you can leverage this BSP layer.
129 For details on the <filename>meta-intel</filename> BSP layer,
130 see the layer's
131 <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/meta-intel/tree/README'><filename>README</filename></ulink>
132 file.
133 <orderedlist>
134 <listitem><para>
135 <emphasis>Navigate to Your Source Directory:</emphasis>
136 Typically, you set up the
137 <filename>meta-intel</filename> Git repository
138 inside the
139 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
140 (e.g. <filename>poky</filename>).
141 </para></listitem>
142 <listitem><para>
143 <emphasis>Clone the Layer:</emphasis>
144 <literallayout class='monospaced'>
145 $ git clone git://git.yoctoproject.org/meta-intel.git
146 Cloning into 'meta-intel'...
147 remote: Counting objects: 14224, done.
148 remote: Compressing objects: 100% (4591/4591), done.
149 remote: Total 14224 (delta 8245), reused 13985 (delta 8006)
150 Receiving objects: 100% (14224/14224), 4.29 MiB | 2.90 MiB/s, done.
151 Resolving deltas: 100% (8245/8245), done.
152 Checking connectivity... done.
153 </literallayout>
154 </para></listitem>
155 <listitem><para>
156 <emphasis>Check Out the Proper Branch:</emphasis>
157 The branch you check out for
158 <filename>meta-intel</filename> must match the same
159 branch you are using for the Yocto Project release
160 (e.g. &DISTRO_NAME_NO_CAP;):
161 <literallayout class='monospaced'>
162 $ git checkout <replaceable>branch_name</replaceable>
163 </literallayout>
164 For an example on how to discover branch names and
165 checkout on a branch, see the
166 "<link linkend='checking-out-by-branch-in-poky'>Checking Out By Branch in Poky</link>"
167 section.
168 </para></listitem>
169 </orderedlist>
170 </para></listitem>
171 <listitem><para>
172 <emphasis>Optionally Set Up an Alternative BSP Layer:</emphasis>
173 If your hardware can be more closely leveraged to an
174 existing BSP not within the <filename>meta-intel</filename>
175 BSP layer, you can clone that BSP layer.</para>
176
177 <para>The process is identical to the process used for the
178 <filename>meta-intel</filename> layer except for the layer's
179 name.
180 For example, if you determine that your hardware most
181 closely matches the <filename>meta-minnow</filename>,
182 clone that layer:
183 <literallayout class='monospaced'>
184 $ git clone git://git.yoctoproject.org/meta-minnow
185 Cloning into 'meta-minnow'...
186 remote: Counting objects: 456, done.
187 remote: Compressing objects: 100% (283/283), done.
188 remote: Total 456 (delta 163), reused 384 (delta 91)
189 Receiving objects: 100% (456/456), 96.74 KiB | 0 bytes/s, done.
190 Resolving deltas: 100% (163/163), done.
191 Checking connectivity... done.
192 </literallayout>
193 </para></listitem>
194 </orderedlist>
195 </para>
196 </section>
197
198 <section id='local-kernel-files'>
199 <title>Setting Up to Work on a Kernel</title>
200
201 <para>
202 Kernel development is best accomplished using the
203 <filename>devtool</filename> tool and not through traditional
204 kernel workflow methods.
205 This section provides procedures for both.
206 </para>
207
208 <section id='getting-ready-to-develop-using-devtool'>
209 <title>Getting Ready to Develop using <filename>devtool</filename></title>
210
211 <para role='writernotes'>
212 Need the updated wiki stuff here
213 </para>
214 </section>
215
216 <section id='getting-ready-for-traditional-kernel-development'>
217 <title>Getting Ready for Traditional Kernel Development</title>
218
219 <para>
220 For traditional kernel development using the Yocto
221 Project, you need to establish local copies of the
222 kernel source.
223 You can find Git repositories of supported Yocto Project
224 kernels organized under "Yocto Linux Kernel" in the Yocto
225 Project Source Repositories at
226 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>.
227 </para>
228
229 <para>
230 This setup can involve creating a bare clone of the
231 Yocto Project kernel and then copying that cloned
232 repository.
233 You can create the bare clone and the copy of the bare
234 clone anywhere you like.
235 For simplicity, it is recommended that you create these
236 structures outside of the
237 <ulink url='&YOCTO_DOCS_REF_URL;source-directory'>Source Directory</ulink>,
238 which is usually named <filename>poky</filename>.
239 </para>
240
241 <para>
242 The following steps show how to create a bare clone of the
243 <filename>linux-yocto-4.4</filename> kernel and then
244 create a copy of that clone:
245 <note>
246 When you have a local Yocto Project kernel Git
247 repository, you can reference that repository rather than
248 the upstream Git repository as part of the
249 <filename>clone</filename> command.
250 Doing so can speed up the process.
66 </note> 251 </note>
67 <para>The following transcript shows how to clone the 252 <orderedlist>
68 <filename>poky</filename> Git repository into the current 253 <listitem><para>
69 working directory. 254 <emphasis>Create the Bare Clone:</emphasis>
70 The command creates the local repository in a directory 255 In the following example, the bare clone is named
71 named <filename>poky</filename>. 256 <filename>linux-yocto-4.4.git</filename>:
72 For information on Git used within the Yocto Project, see 257 <literallayout class='monospaced'>
73 the "<ulink url='&YOCTO_DOCS_REF_URL;#git'>Git</ulink>" section. 258 $ git clone &dash;&dash;bare git://git.yoctoproject.org/linux-yocto-4.4 linux-yocto-4.4.git
74 <literallayout class='monospaced'> 259 Cloning into bare repository 'linux-yocto-4.4.git'...
75 $ git clone git://git.yoctoproject.org/poky 260 remote: Counting objects: 4543903, done.
76 Cloning into 'poky'... 261 remote: Compressing objects: 100% (695618/695618), done.
77 remote: Counting objects: 226790, done. 262 remote: Total 4543903 (delta 3818435), reused 4541724 (delta 3816256)
78 remote: Compressing objects: 100% (57465/57465), done. 263 Receiving objects: 100% (4543903/4543903), 801.08 MiB | 6.55 MiB/s, done.
79 remote: Total 226790 (delta 165212), reused 225887 (delta 164327) 264 Resolving deltas: 100% (3818435/3818435), done.
80 Receiving objects: 100% (226790/226790), 100.98 MiB | 263 KiB/s, done.
81 Resolving deltas: 100% (165212/165212), done.
82 </literallayout></para>
83 <para>For another example of how to set up your own local Git
84 repositories, see this
85 <ulink url='&YOCTO_WIKI_URL;/wiki/Transcript:_from_git_checkout_to_meta-intel_BSP'>
86 wiki page</ulink>, which describes how to create local
87 Git repositories for both
88 <filename>poky</filename> and <filename>meta-intel</filename>.
89 </para>
90 <para>
91 You can also get the Yocto Project Files by downloading
92 Yocto Project releases from the
93 <ulink url="&YOCTO_HOME_URL;">Yocto Project website</ulink>.
94 From the website, you just click "Downloads" in the navigation
95 pane to the left to display all Yocto Project downloads.
96 Current and archived releases are available for download.
97 Nightly and developmental builds are also maintained at
98 <ulink url="&YOCTO_AB_NIGHTLY_URL;"></ulink>.
99 One final site you can visit for information on Yocto Project
100 releases is the
101 <ulink url='&YOCTO_WIKI_URL;/wiki/Releases'>Releases</ulink>
102 wiki.
103 </para></listitem>
104 <listitem id='local-kernel-files'><para><emphasis>Yocto Project Kernel:</emphasis>
105 If you are going to be making modifications to a supported Yocto Project kernel, you
106 need to establish local copies of the source.
107 You can find Git repositories of supported Yocto Project kernels organized under
108 "Yocto Linux Kernel" in the Yocto Project Source Repositories at
109 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>.</para>
110 <para>This setup can involve creating a bare clone of the Yocto Project kernel and then
111 copying that cloned repository.
112 You can create the bare clone and the copy of the bare clone anywhere you like.
113 For simplicity, it is recommended that you create these structures outside of the
114 Source Directory, which is usually named <filename>poky</filename>.</para>
115 <para>As an example, the following transcript shows how to create the bare clone
116 of the <filename>linux-yocto-3.19</filename> kernel and then create a copy of
117 that clone.
118 <note>When you have a local Yocto Project kernel Git repository, you can
119 reference that repository rather than the upstream Git repository as
120 part of the <filename>clone</filename> command.
121 Doing so can speed up the process.</note></para>
122 <para>In the following example, the bare clone is named
123 <filename>linux-yocto-3.19.git</filename>, while the
124 copy is named <filename>my-linux-yocto-3.19-work</filename>:
125 <literallayout class='monospaced'>
126 $ git clone --bare git://git.yoctoproject.org/linux-yocto-3.19 linux-yocto-3.19.git
127 Cloning into bare repository 'linux-yocto-3.19.git'...
128 remote: Counting objects: 3983256, done.
129 remote: Compressing objects: 100% (605006/605006), done.
130 remote: Total 3983256 (delta 3352832), reused 3974503 (delta 3344079)
131 Receiving objects: 100% (3983256/3983256), 843.66 MiB | 1.07 MiB/s, done.
132 Resolving deltas: 100% (3352832/3352832), done.
133 Checking connectivity... done. 265 Checking connectivity... done.
134 </literallayout></para> 266 </literallayout>
135 <para>Now create a clone of the bare clone just created: 267 </para></listitem>
136 <literallayout class='monospaced'> 268 <listitem><para>
137 $ git clone linux-yocto-3.19.git my-linux-yocto-3.19-work 269 <emphasis>Create the Copy of the Bare Clone:</emphasis>
138 Cloning into 'my-linux-yocto-3.19-work'... 270 In the following command, the copy of the bare clone
271 is named <filename>my-linux-yocto-4.4-work</filename>:
272 <literallayout class='monospaced'>
273 $ git clone linux-yocto-4.4.git my-linux-yocto-4.4-work
274 Cloning into 'my-linux-yocto-4.4-work'...
139 done. 275 done.
140 Checking out files: 100% (48440/48440), done. 276 Checking out files: 100% (52221/52221), done.
141 </literallayout></para></listitem> 277 </literallayout>
142 <listitem id='meta-yocto-kernel-extras-repo'><para><emphasis> 278 </para></listitem>
143 The <filename>meta-yocto-kernel-extras</filename> Git Repository</emphasis>: 279 <listitem><para>
144 The <filename>meta-yocto-kernel-extras</filename> Git repository contains Metadata needed 280 <emphasis>Cloning the <filename>meta-yocto-kernel-extras</filename> Repository:</emphasis>
145 only if you are modifying and building the kernel image. 281 The <filename>meta-yocto-kernel-extras</filename> Git
146 In particular, it contains the kernel BitBake append (<filename>.bbappend</filename>) 282 repository contains Metadata needed only if you are
147 files that you 283 modifying and building the kernel image.
148 edit to point to your locally modified kernel source files and to build the kernel 284 In particular, it contains the kernel BitBake append
149 image. 285 (<filename>.bbappend</filename>) files that you edit to
150 Pointing to these local files is much more efficient than requiring a download of the 286 point to your locally modified kernel source files and to
151 kernel's source files from upstream each time you make changes to the kernel.</para> 287 build the kernel image.
152 <para>You can find the <filename>meta-yocto-kernel-extras</filename> Git Repository in the 288 Pointing to these local files is much more efficient than
153 "Yocto Metadata Layers" area of the Yocto Project Source Repositories at 289 requiring a download of the kernel's source files from
154 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>. 290 upstream each time you make changes to the kernel.</para>
155 It is good practice to create this Git repository inside the Source Directory.</para> 291
156 <para>Following is an example that creates the <filename>meta-yocto-kernel-extras</filename> Git 292 <para>You can find the
157 repository inside the Source Directory, which is named <filename>poky</filename> 293 <filename>meta-yocto-kernel-extras</filename> Git
158 in this case: 294 Repository in the "Yocto Metadata Layers" area of the
159 <literallayout class='monospaced'> 295 Yocto Project Source Repositories at
296 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>.
297 It is good practice to create this Git repository
298 inside the Source Directory.</para>
299
300 <para>Following is an example that creates the
301 <filename>meta-yocto-kernel-extras</filename> Git
302 repository inside the Source Directory, which is named
303 <filename>poky</filename>, in this case:
304 <literallayout class='monospaced'>
160 $ cd ~/poky 305 $ cd ~/poky
161 $ git clone git://git.yoctoproject.org/meta-yocto-kernel-extras meta-yocto-kernel-extras 306 $ git clone git://git.yoctoproject.org/meta-yocto-kernel-extras meta-yocto-kernel-extras
162 Cloning into 'meta-yocto-kernel-extras'... 307 Cloning into 'meta-yocto-kernel-extras'...
163 remote: Counting objects: 727, done. 308 remote: Counting objects: 727, done.
164 remote: Compressing objects: 100% (452/452), done. 309 remote: Compressing objects: 100% (452/452), done.
165 remote: Total 727 (delta 260), reused 719 (delta 252) 310 remote: Total 727 (delta 260), reused 719 (delta 252)
166 Receiving objects: 100% (727/727), 536.36 KiB | 240 KiB/s, done. 311 Receiving objects: 100% (727/727), 536.36 KiB | 0 bytes/s, done.
167 Resolving deltas: 100% (260/260), done. 312 Resolving deltas: 100% (260/260), done.
168 </literallayout></para></listitem>
169 <listitem><para id='supported-board-support-packages-(bsps)'><emphasis>Supported Board Support Packages (BSPs):</emphasis>
170 The Yocto Project supports many BSPs, which are maintained in
171 their own layers or in layers designed to contain several
172 BSPs.
173 To get an idea of machine support through BSP layers, you can
174 look at the
175 <ulink url='&YOCTO_RELEASE_DL_URL;/machines'>index of machines</ulink>
176 for the release.</para>
177
178 <para>The Yocto Project uses the following BSP layer naming
179 scheme:
180 <literallayout class='monospaced'>
181 meta-<replaceable>bsp_name</replaceable>
182 </literallayout>
183 where <replaceable>bsp_name</replaceable> is the recognized
184 BSP name.
185 Here is an example:
186 <literallayout class='monospaced'>
187 meta-raspberrypi
188 </literallayout>
189 See the
190 "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>"
191 section in the Yocto Project Board Support Package (BSP)
192 Developer's Guide for more information on BSP Layers.</para>
193
194 <para>A useful Git repository released with the Yocto
195 Project is <filename>meta-intel</filename>, which is a
196 parent layer that contains many supported
197 <ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>.
198 You can locate the <filename>meta-intel</filename> Git
199 repository in the "Yocto Metadata Layers" area of the Yocto
200 Project Source Repositories at
201 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>.</para>
202
203 <para>Using
204 <ulink url='&YOCTO_DOCS_REF_URL;#git'>Git</ulink> to create a local clone of the
205 upstream repository can be helpful if you are working with
206 BSPs.
207 Typically, you set up the <filename>meta-intel</filename>
208 Git repository inside the Source Directory.
209 For example, the following transcript shows the steps to clone
210 <filename>meta-intel</filename>.
211 <note>
212 Be sure to work in the <filename>meta-intel</filename>
213 branch that matches your
214 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
215 (i.e. <filename>poky</filename>) branch.
216 For example, if you have checked out the "master" branch
217 of <filename>poky</filename> and you are going to use
218 <filename>meta-intel</filename>, be sure to checkout the
219 "master" branch of <filename>meta-intel</filename>.
220 </note>
221 <literallayout class='monospaced'>
222 $ cd ~/poky
223 $ git clone git://git.yoctoproject.org/meta-intel.git
224 Cloning into 'meta-intel'...
225 remote: Counting objects: 11917, done.
226 remote: Compressing objects: 100% (3842/3842), done.
227 remote: Total 11917 (delta 6840), reused 11699 (delta 6622)
228 Receiving objects: 100% (11917/11917), 2.92 MiB | 2.88 MiB/s, done.
229 Resolving deltas: 100% (6840/6840), done.
230 Checking connectivity... done. 313 Checking connectivity... done.
231 </literallayout></para> 314 </literallayout>
315 </para></listitem>
316 </orderedlist>
317 </para>
318 </section>
319 </section>
232 320
233 <para>The same 321 <section id='setting-up-to-use-eclipse'>
234 <ulink url='&YOCTO_WIKI_URL;/wiki/Transcript:_from_git_checkout_to_meta-intel_BSP'>wiki page</ulink> 322 <title>Setting Up to Use Eclipse</title>
235 referenced earlier covers how to set up the 323
236 <filename>meta-intel</filename> Git repository. 324 <para>
237 </para></listitem> 325 This section presents the steps needed to set up your host if you
238 <listitem><para><emphasis>Eclipse Yocto Plug-in:</emphasis> If you are developing 326 are going to be using the popular
239 applications using the Eclipse Integrated Development Environment (IDE), 327 <trademark class='trade'>Eclipse</trademark> IDE.
240 you will need this plug-in. 328 The steps in this procedure are links to sections in the
241 See the 329 Yocto Project Software Development Kit (SDK) Developer's Guide
242 "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-appendix-latest-yp-eclipse-plug-in'>Using Eclipse</ulink>" 330 that provide detailed procedures given the Neon version of
243 section in the Yocto Project Software Development Kit (SDK) 331 Eclipse.
244 Developer's Guide for more information.</para></listitem> 332 For procedures on the entire development process using
245 </itemizedlist> 333 Eclipse, see the
246 </para> 334 "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-developing-applications-using-eclipse'>Developing Applications Using Eclipse</ulink>"
335 section in the Yocto Project Software Development Kit (SDK)
336 Developer's Guide.
337 <orderedlist>
338 <listitem><para>
339 <emphasis>Install Eclipse:</emphasis>
340 See the
341 "<ulink url='&YOCTO_DOCS_SDK_URL;#neon-installing-eclipse-ide'>Installing the Neon Eclipse IDE</ulink>"
342 section.
343 </para></listitem>
344 <listitem><para>
345 <emphasis>Configure Eclipse:</emphasis>
346 See the
347 "<ulink url='&YOCTO_DOCS_SDK_URL;#neon-configuring-the-mars-eclipse-ide'>Configuring the Neon Eclipse IDE</ulink>"
348 section.
349 </para></listitem>
350 <listitem><para>
351 <emphasis>Configure Eclipse:</emphasis>
352 See the
353 "<ulink url='&YOCTO_DOCS_SDK_URL;#neon-installing-the-eclipse-yocto-plug-in'>Installing or Accessing the Neon Eclipse Yocto Plug-in</ulink>"
354 section.
355 </para></listitem>
356 <listitem><para>
357 <emphasis>Configure Eclipse:</emphasis>
358 See the
359 "<ulink url='&YOCTO_DOCS_SDK_URL;#neon-configuring-the-eclipse-yocto-plug-in'>Configuring the Neon Eclipse Yocto Plug-in</ulink>"
360 section.
361 </para></listitem>
362 </orderedlist>
363 </para>
364 </section>
247</section> 365</section>
248 366
249<section id='working-with-yocto-project-source-files'> 367<section id='working-with-yocto-project-source-files'>
@@ -400,6 +518,32 @@
400 <title>Cloning the <filename>poky</filename> Repository</title> 518 <title>Cloning the <filename>poky</filename> Repository</title>
401 519
402 <para> 520 <para>
521 To use the Yocto Project, you need a release of the Yocto Project
522 locally installed on your development system.
523 The locally installed set of files is referred to as the
524 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
525 in the Yocto Project documentation.
526 </para>
527
528 <para>
529 You create your Source Directory by using
530 <ulink url='&YOCTO_DOCS_REF_URL;#git'>Git</ulink> to clone a local
531 copy of the upstream <filename>poky</filename> repository.
532 <note><title>Tip</title>
533 The preferred method of getting the Yocto Project Source
534 Directory set up is to clone the repository.
535 </note>
536 Working from a copy of the upstream repository allows you
537 to contribute back into the Yocto Project or simply work with
538 the latest software on a development branch.
539 Because Git maintains and creates an upstream repository with
540 a complete history of changes and you are working with a local
541 clone of that repository, you have access to all the Yocto
542 Project development branches and tag names used in the upstream
543 repository.
544 </para>
545
546 <para>
403 Follow these steps to create a local version of the 547 Follow these steps to create a local version of the
404 upstream 548 upstream
405 <ulink url='&YOCTO_DOCS_REF_URL;#poky'><filename>poky</filename></ulink> 549 <ulink url='&YOCTO_DOCS_REF_URL;#poky'><filename>poky</filename></ulink>