summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual/dev-manual-newbie.xml
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/dev-manual/dev-manual-newbie.xml')
-rw-r--r--documentation/dev-manual/dev-manual-newbie.xml108
1 files changed, 54 insertions, 54 deletions
diff --git a/documentation/dev-manual/dev-manual-newbie.xml b/documentation/dev-manual/dev-manual-newbie.xml
index 46b680e6be..779d06d57e 100644
--- a/documentation/dev-manual/dev-manual-newbie.xml
+++ b/documentation/dev-manual/dev-manual-newbie.xml
@@ -12,9 +12,9 @@
12 closed, proprietary environment. 12 closed, proprietary environment.
13 Additionally, the Yocto Project uses specific tools and constructs as part of its development 13 Additionally, the Yocto Project uses specific tools and constructs as part of its development
14 environment. 14 environment.
15 This chapter specifically addresses open source philosophy, using the 15 This chapter specifically addresses open source philosophy, using the
16 Yocto Project in a team environment, source repositories, Yocto Project 16 Yocto Project in a team environment, source repositories, Yocto Project
17 terms, licensing, the open source distributed version control system Git, 17 terms, licensing, the open source distributed version control system Git,
18 workflows, bug tracking, and how to submit changes. 18 workflows, bug tracking, and how to submit changes.
19</para> 19</para>
20 20
@@ -190,15 +190,15 @@
190 extensive testing while they continue to develop 190 extensive testing while they continue to develop
191 locally using their primary development system. 191 locally using their primary development system.
192 </para></listitem> 192 </para></listitem>
193 <listitem><para>Enable the PR Service when package feeds 193 <listitem><para>Enable the PR Service when package feeds
194 need to be incremental with continually increasing 194 need to be incremental with continually increasing
195 <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'>PR</ulink> 195 <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'>PR</ulink>
196 values. 196 values.
197 Typically, this situation occurs when you use or 197 Typically, this situation occurs when you use or
198 publish package feeds and use a shared state. 198 publish package feeds and use a shared state.
199 You should enable the PR Service for all users who 199 You should enable the PR Service for all users who
200 use the shared state pool. 200 use the shared state pool.
201 For more information on the PR Service, see the 201 For more information on the PR Service, see the
202 "<link linkend='working-with-a-pr-service'>Working With a PR Service</link>". 202 "<link linkend='working-with-a-pr-service'>Working With a PR Service</link>".
203 </para></listitem> 203 </para></listitem>
204 </itemizedlist> 204 </itemizedlist>
@@ -218,9 +218,9 @@
218 Of the SCMs BitBake supports, the 218 Of the SCMs BitBake supports, the
219 Yocto Project team strongly recommends using 219 Yocto Project team strongly recommends using
220 <link linkend='git'>Git</link>. 220 <link linkend='git'>Git</link>.
221 Git is a distributed system that is easy to backup 221 Git is a distributed system that is easy to backup,
222 (each checkout is a backup in itself), allows you to work 222 allows you to work remotely, and then connects back to the
223 remotely, and then connects back to the infrastructure. 223 infrastructure.
224 <note> 224 <note>
225 For information about BitBake and SCMs, see the 225 For information about BitBake and SCMs, see the
226 BitBake manual located in the 226 BitBake manual located in the
@@ -428,8 +428,8 @@
428 </para> 428 </para>
429 429
430 <para> 430 <para>
431 For any supported release of Yocto Project, you can go to the 431 For any supported release of Yocto Project, you can go to the
432 <ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink> and 432 <ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink> and
433 select the "Downloads" tab and get a tarball of the release. 433 select the "Downloads" tab and get a tarball of the release.
434 You can also go to this site to download any supported BSP tarballs. 434 You can also go to this site to download any supported BSP tarballs.
435 Unpacking the tarball gives you a hierarchical Source Directory that lets you develop 435 Unpacking the tarball gives you a hierarchical Source Directory that lets you develop
@@ -461,7 +461,7 @@
461 <para> 461 <para>
462 <imagedata fileref="figures/index-downloads.png" align="center" width="6in" depth="3.5in" /> 462 <imagedata fileref="figures/index-downloads.png" align="center" width="6in" depth="3.5in" />
463 </para></listitem> 463 </para></listitem>
464 <listitem><para><emphasis>"Downloads" page for the 464 <listitem><para><emphasis>"Downloads" page for the
465 <ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink>:</emphasis> 465 <ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink>:</emphasis>
466 Access this page by going to the website and then selecting 466 Access this page by going to the website and then selecting
467 the "Downloads" tab. 467 the "Downloads" tab.
@@ -489,7 +489,7 @@
489 Append files are known as BitBake append files and <filename>.bbappend</filename> files. 489 Append files are known as BitBake append files and <filename>.bbappend</filename> files.
490 The OpenEmbedded build system expects every append file to have a corresponding 490 The OpenEmbedded build system expects every append file to have a corresponding
491 recipe (<filename>.bb</filename>) file. 491 recipe (<filename>.bb</filename>) file.
492 Furthermore, the append file and corresponding recipe file 492 Furthermore, the append file and corresponding recipe file
493 must use the same root filename. 493 must use the same root filename.
494 The filenames can differ only in the file type suffix used (e.g. 494 The filenames can differ only in the file type suffix used (e.g.
495 <filename>formfactor_0.0.bb</filename> and <filename>formfactor_0.0.bbappend</filename>). 495 <filename>formfactor_0.0.bb</filename> and <filename>formfactor_0.0.bbappend</filename>).
@@ -641,7 +641,7 @@
641 </para></listitem> 641 </para></listitem>
642 <listitem><para id='oe-core'><emphasis>OE-Core:</emphasis> A core set of Metadata originating 642 <listitem><para id='oe-core'><emphasis>OE-Core:</emphasis> A core set of Metadata originating
643 with OpenEmbedded (OE) that is shared between OE and the Yocto Project. 643 with OpenEmbedded (OE) that is shared between OE and the Yocto Project.
644 This Metadata is found in the <filename>meta</filename> directory of the 644 This Metadata is found in the <filename>meta</filename> directory of the
645 <link linkend='source-directory'>Source Directory</link>.</para></listitem> 645 <link linkend='source-directory'>Source Directory</link>.</para></listitem>
646 <listitem><para><emphasis>Package:</emphasis> In the context of the Yocto Project, 646 <listitem><para><emphasis>Package:</emphasis> In the context of the Yocto Project,
647 this term refers to the packaged output from a baked recipe. 647 this term refers to the packaged output from a baked recipe.
@@ -776,7 +776,7 @@
776 <para> 776 <para>
777 When you build an image using the Yocto Project, the build process uses a 777 When you build an image using the Yocto Project, the build process uses a
778 known list of licenses to ensure compliance. 778 known list of licenses to ensure compliance.
779 You can find this list in the 779 You can find this list in the
780 <link linkend='source-directory'>Source Directory</link> at 780 <link linkend='source-directory'>Source Directory</link> at
781 <filename>meta/files/common-licenses</filename>. 781 <filename>meta/files/common-licenses</filename>.
782 Once the build completes, the list of all licenses found and used during that build are 782 Once the build completes, the list of all licenses found and used during that build are
@@ -869,7 +869,7 @@
869 When you clone a Git repository, you end up with an identical copy of the 869 When you clone a Git repository, you end up with an identical copy of the
870 repository on your development system. 870 repository on your development system.
871 Once you have a local copy of a repository, you can take steps to develop locally. 871 Once you have a local copy of a repository, you can take steps to develop locally.
872 For examples on how to clone Git repositories, see the 872 For examples on how to clone Git repositories, see the
873 "<link linkend='getting-setup'>Getting Set Up</link>" section. 873 "<link linkend='getting-setup'>Getting Set Up</link>" section.
874 </para> 874 </para>
875 875
@@ -911,14 +911,14 @@
911 $ cd poky 911 $ cd poky
912 $ git checkout -b &DISTRO_NAME; origin/&DISTRO_NAME; 912 $ git checkout -b &DISTRO_NAME; origin/&DISTRO_NAME;
913 </literallayout> 913 </literallayout>
914 In this example, the name of the top-level directory of your local 914 In this example, the name of the top-level directory of your local
915 <link linkend='source-directory'>Source Directory</link> 915 <link linkend='source-directory'>Source Directory</link>
916 is <filename>poky</filename>, 916 is <filename>poky</filename>,
917 and the name of that local working area (local branch) you just 917 and the name of that local working area (local branch) you just
918 created and checked out is <filename>&DISTRO_NAME;</filename>. 918 created and checked out is <filename>&DISTRO_NAME;</filename>.
919 The files in your local repository now reflect the same files that 919 The files in your local repository now reflect the same files that
920 are in the <filename>&DISTRO_NAME;</filename> development 920 are in the <filename>&DISTRO_NAME;</filename> development
921 branch of the Yocto Project's <filename>poky</filename> 921 branch of the Yocto Project's <filename>poky</filename>
922 upstream repository. 922 upstream repository.
923 It is important to understand that when you create and checkout a 923 It is important to understand that when you create and checkout a
924 local working branch based on a branch name, 924 local working branch based on a branch name,
@@ -1037,10 +1037,10 @@
1037 repository and places it in your local Git repository. 1037 repository and places it in your local Git repository.
1038 You use this command to make sure you are synchronized with the repository 1038 You use this command to make sure you are synchronized with the repository
1039 from which you are basing changes (.e.g. the master branch).</para></listitem> 1039 from which you are basing changes (.e.g. the master branch).</para></listitem>
1040 <listitem><para><emphasis><filename>git push</filename>:</emphasis> 1040 <listitem><para><emphasis><filename>git push</filename>:</emphasis>
1041 Sends all your committed local changes to an upstream Git 1041 Sends all your committed local changes to an upstream Git
1042 repository (e.g. a contribution repository). 1042 repository (e.g. a contribution repository).
1043 The maintainer of the project draws from these repositories 1043 The maintainer of the project draws from these repositories
1044 when adding changes to the project’s master repository or 1044 when adding changes to the project’s master repository or
1045 other development branch. 1045 other development branch.
1046 </para></listitem> 1046 </para></listitem>
@@ -1088,8 +1088,8 @@
1088 The "master" branch is the “upstream” repository where the final builds of the project occur. 1088 The "master" branch is the “upstream” repository where the final builds of the project occur.
1089 The maintainer is responsible for allowing changes in from other developers and for 1089 The maintainer is responsible for allowing changes in from other developers and for
1090 organizing the underlying branch structure to reflect release strategies and so forth. 1090 organizing the underlying branch structure to reflect release strategies and so forth.
1091 <note>For information on finding out who is responsible (maintains) 1091 <note>For information on finding out who is responsible (maintains)
1092 for a particular area of code, see the 1092 for a particular area of code, see the
1093 "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>" 1093 "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>"
1094 section. 1094 section.
1095 </note> 1095 </note>
@@ -1160,8 +1160,8 @@
1160 You can name these branches anything you like. 1160 You can name these branches anything you like.
1161 It is helpful to give them names associated with the particular feature or change 1161 It is helpful to give them names associated with the particular feature or change
1162 on which you are working. 1162 on which you are working.
1163 Once you are done with a feature or change and have merged it 1163 Once you are done with a feature or change and have merged it
1164 into your local master branch, simply discard the temporary 1164 into your local master branch, simply discard the temporary
1165 branch.</para></listitem> 1165 branch.</para></listitem>
1166 <listitem><para><emphasis>Merge Changes:</emphasis> The <filename>git merge</filename> 1166 <listitem><para><emphasis>Merge Changes:</emphasis> The <filename>git merge</filename>
1167 command allows you to take the 1167 command allows you to take the
@@ -1189,9 +1189,9 @@
1189 <filename>send-pull-request</filename> that ship with the release to facilitate this 1189 <filename>send-pull-request</filename> that ship with the release to facilitate this
1190 workflow. 1190 workflow.
1191 You can find these scripts in the <filename>scripts</filename> 1191 You can find these scripts in the <filename>scripts</filename>
1192 folder of the 1192 folder of the
1193 <link linkend='source-directory'>Source Directory</link>. 1193 <link linkend='source-directory'>Source Directory</link>.
1194 For information on how to use these scripts, see the 1194 For information on how to use these scripts, see the
1195 "<link linkend='pushing-a-change-upstream'>Using Scripts to Push a Change Upstream and Request a Pull</link>" section. 1195 "<link linkend='pushing-a-change-upstream'>Using Scripts to Push a Change Upstream and Request a Pull</link>" section.
1196 </para></listitem> 1196 </para></listitem>
1197 <listitem><para><emphasis>Patch Workflow:</emphasis> This workflow allows you to notify the 1197 <listitem><para><emphasis>Patch Workflow:</emphasis> This workflow allows you to notify the
@@ -1199,7 +1199,7 @@
1199 for the "master" branch of the Git repository. 1199 for the "master" branch of the Git repository.
1200 To send this type of change, you format the patch and then send the email using the Git commands 1200 To send this type of change, you format the patch and then send the email using the Git commands
1201 <filename>git format-patch</filename> and <filename>git send-email</filename>. 1201 <filename>git format-patch</filename> and <filename>git send-email</filename>.
1202 For information on how to use these scripts, see the 1202 For information on how to use these scripts, see the
1203 "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>" 1203 "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>"
1204 section. 1204 section.
1205 </para></listitem> 1205 </para></listitem>
@@ -1251,10 +1251,10 @@
1251 <listitem><para>Provide a detailed description of the issue. 1251 <listitem><para>Provide a detailed description of the issue.
1252 You should provide as much detail as you can about the context, behavior, output, 1252 You should provide as much detail as you can about the context, behavior, output,
1253 and so forth that surrounds the issue. 1253 and so forth that surrounds the issue.
1254 You can even attach supporting files for output from logs by 1254 You can even attach supporting files for output from logs by
1255 using the "Add an attachment" button.</para></listitem> 1255 using the "Add an attachment" button.</para></listitem>
1256 <listitem><para>Be sure to copy the appropriate people in the 1256 <listitem><para>Be sure to copy the appropriate people in the
1257 "CC List" for the bug. 1257 "CC List" for the bug.
1258 See the "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>" 1258 See the "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>"
1259 section for information about finding out who is responsible 1259 section for information about finding out who is responsible
1260 for code.</para></listitem> 1260 for code.</para></listitem>
@@ -1281,37 +1281,37 @@
1281 or notifying: 1281 or notifying:
1282 <itemizedlist> 1282 <itemizedlist>
1283 <listitem><para><emphasis>Maintenance File:</emphasis> 1283 <listitem><para><emphasis>Maintenance File:</emphasis>
1284 Examine the <filename>maintainers.inc</filename> file, which is 1284 Examine the <filename>maintainers.inc</filename> file, which is
1285 located in the 1285 located in the
1286 <link linkend='source-directory'>Source Directory</link> 1286 <link linkend='source-directory'>Source Directory</link>
1287 at <filename>meta-yocto/conf/distro/include</filename>, to 1287 at <filename>meta-yocto/conf/distro/include</filename>, to
1288 see who is responsible for code. 1288 see who is responsible for code.
1289 </para></listitem> 1289 </para></listitem>
1290 <listitem><para><emphasis>Board Support Package (BSP) README Files:</emphasis> 1290 <listitem><para><emphasis>Board Support Package (BSP) README Files:</emphasis>
1291 For BSP maintainers of supported BSPs, you can examine 1291 For BSP maintainers of supported BSPs, you can examine
1292 individual BSP <filename>README</filename> files. 1292 individual BSP <filename>README</filename> files.
1293 Alternatively, you can examine the 1293 Alternatively, you can examine the
1294 <filename>MAINTAINERS</filename> file, which is found in the 1294 <filename>MAINTAINERS</filename> file, which is found in the
1295 <filename>meta-intel</filename>, for a list of all supported 1295 <filename>meta-intel</filename>, for a list of all supported
1296 BSP maintainers. 1296 BSP maintainers.
1297 </para></listitem> 1297 </para></listitem>
1298 <listitem><para><emphasis>Search by File:</emphasis> 1298 <listitem><para><emphasis>Search by File:</emphasis>
1299 Using <link linkend='git'>Git</link>, you can enter the 1299 Using <link linkend='git'>Git</link>, you can enter the
1300 following command to bring up a short list of all commits 1300 following command to bring up a short list of all commits
1301 against a specific file: 1301 against a specific file:
1302 <literallayout class='monospaced'> 1302 <literallayout class='monospaced'>
1303 git shortlog -- &lt;filename&gt; 1303 git shortlog -- &lt;filename&gt;
1304 </literallayout> 1304 </literallayout>
1305 Just provide the name of the file for which you are interested. 1305 Just provide the name of the file for which you are interested.
1306 The information returned is not ordered by history but does 1306 The information returned is not ordered by history but does
1307 include a list of all committers grouped by name. 1307 include a list of all committers grouped by name.
1308 From the list, you can see who is responsible for the bulk of 1308 From the list, you can see who is responsible for the bulk of
1309 the changes against the file. 1309 the changes against the file.
1310 </para></listitem> 1310 </para></listitem>
1311 </itemizedlist> 1311 </itemizedlist>
1312 </para> 1312 </para>
1313 1313
1314 <para> 1314 <para>
1315 For a list of the Yocto Project and related mailing lists, see the 1315 For a list of the Yocto Project and related mailing lists, see the
1316 "<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing lists</ulink>" section in 1316 "<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing lists</ulink>" section in
1317 the Yocto Project Reference Manual. 1317 the Yocto Project Reference Manual.
@@ -1320,7 +1320,7 @@
1320 <para> 1320 <para>
1321 Here is some guidance on which mailing list to use for what type of change: 1321 Here is some guidance on which mailing list to use for what type of change:
1322 <itemizedlist> 1322 <itemizedlist>
1323 <listitem><para>For changes to the core 1323 <listitem><para>For changes to the core
1324 <link linkend='metadata'>Metadata</link>, send your patch to the 1324 <link linkend='metadata'>Metadata</link>, send your patch to the
1325 <ulink url='&OE_LISTS_URL;/listinfo/openembedded-core'>openembedded-core</ulink> mailing list. 1325 <ulink url='&OE_LISTS_URL;/listinfo/openembedded-core'>openembedded-core</ulink> mailing list.
1326 For example, a change to anything under the <filename>meta</filename> or 1326 For example, a change to anything under the <filename>meta</filename> or
@@ -1435,7 +1435,7 @@
1435 </para> 1435 </para>
1436 1436
1437 <para> 1437 <para>
1438 The next two sections describe general instructions for both pushing 1438 The next two sections describe general instructions for both pushing
1439 changes upstream and for submitting changes as patches. 1439 changes upstream and for submitting changes as patches.
1440 </para> 1440 </para>
1441 1441
@@ -1493,7 +1493,7 @@
1493 Depending on the components changed, you need to submit the email to a specific 1493 Depending on the components changed, you need to submit the email to a specific
1494 mailing list. 1494 mailing list.
1495 For some guidance on which mailing list to use, see the list in the 1495 For some guidance on which mailing list to use, see the list in the
1496 "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>" 1496 "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>"
1497 section. 1497 section.
1498 For a description of the available mailing lists, see the 1498 For a description of the available mailing lists, see the
1499 "<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing Lists</ulink>" 1499 "<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing Lists</ulink>"
@@ -1521,8 +1521,8 @@
1521 To format commits, use the <filename>git format-patch</filename> command. 1521 To format commits, use the <filename>git format-patch</filename> command.
1522 When you provide the command, you must include a revision list or a number of patches 1522 When you provide the command, you must include a revision list or a number of patches
1523 as part of the command. 1523 as part of the command.
1524 For example, either of these two commands takes your most 1524 For example, either of these two commands takes your most
1525 recent single commit and formats it as an email message in 1525 recent single commit and formats it as an email message in
1526 the current directory: 1526 the current directory:
1527 <literallayout class='monospaced'> 1527 <literallayout class='monospaced'>
1528 $ git format-patch -1 1528 $ git format-patch -1
@@ -1534,7 +1534,7 @@
1534 <para>After the command is run, the current directory contains a 1534 <para>After the command is run, the current directory contains a
1535 numbered <filename>.patch</filename> file for the commit.</para> 1535 numbered <filename>.patch</filename> file for the commit.</para>
1536 <para>If you provide several commits as part of the command, 1536 <para>If you provide several commits as part of the command,
1537 the <filename>git format-patch</filename> command produces a 1537 the <filename>git format-patch</filename> command produces a
1538 series of numbered files in the current directory – one for each commit. 1538 series of numbered files in the current directory – one for each commit.
1539 If you have more than one patch, you should also use the 1539 If you have more than one patch, you should also use the
1540 <filename>--cover</filename> option with the command, which generates a 1540 <filename>--cover</filename> option with the command, which generates a
@@ -1571,7 +1571,7 @@
1571 The command also has several options that let you 1571 The command also has several options that let you
1572 specify recipients and perform further editing of the email message. 1572 specify recipients and perform further editing of the email message.
1573 For information on how to use the <filename>git send-email</filename> command, 1573 For information on how to use the <filename>git send-email</filename> command,
1574 see <filename>GIT-SEND-EMAIL(1)</filename> displayed using 1574 see <filename>GIT-SEND-EMAIL(1)</filename> displayed using
1575 the <filename>man git-send-email</filename> command. 1575 the <filename>man git-send-email</filename> command.
1576 </para></listitem> 1576 </para></listitem>
1577 </itemizedlist> 1577 </itemizedlist>