diff options
Diffstat (limited to 'documentation/dev-manual/dev-manual-newbie.xml')
| -rw-r--r-- | documentation/dev-manual/dev-manual-newbie.xml | 129 |
1 files changed, 56 insertions, 73 deletions
diff --git a/documentation/dev-manual/dev-manual-newbie.xml b/documentation/dev-manual/dev-manual-newbie.xml index cf6f700..1da05e2 100644 --- a/documentation/dev-manual/dev-manual-newbie.xml +++ b/documentation/dev-manual/dev-manual-newbie.xml @@ -1,5 +1,6 @@ <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" -"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" +[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > <chapter id='dev-manual-newbie'> @@ -122,7 +123,7 @@ <para> The Yocto Project team maintains complete source repositories for all Yocto Project files - at <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi'></ulink>. + at <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi'></ulink>. This web-based source code browser is organized into categories by function such as IDE Plugins, Matchbox, Poky, Yocto Linux Kernel, and so forth. From the interface, you can click on any particular item in the "Name" column and @@ -143,7 +144,7 @@ <para> For any supported release of Yocto Project, you can go to the Yocto Project website’s - <ulink url='http://www.yoctoproject.org/download'>download page</ulink> and get a + <ulink url='&YOCTO_HOME_URL;/download'>download page</ulink> and get a tarball of the release. You can also go to this site to download any supported BSP tarballs. Unpacking the tarball gives you a hierarchical directory structure of Yocto Project @@ -158,14 +159,14 @@ <para> In summary, here is where you can get the Yocto Project files needed for development: <itemizedlist> - <listitem><para id='source-repositories'><emphasis><ulink url='http://git.yoctoproject.org/cgit/cgit.cgi'>Source Repositories:</ulink></emphasis> + <listitem><para id='source-repositories'><emphasis><ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi'>Source Repositories:</ulink></emphasis> This area contains IDE Plugins, Matchbox, Poky, Poky Support, Tools, Yocto Linux Kernel, and Yocto Metadata Layers. You can create Git repositories for each of these areas.</para> <para> <imagedata fileref="figures/source-repos.png" align="center" width="6in" depth="4in" /> </para></listitem> - <listitem><para><anchor id='index-downloads' /><emphasis><ulink url='http://downloads.yoctoproject.org/releases/'>Index of /releases:</ulink></emphasis> + <listitem><para><anchor id='index-downloads' /><emphasis><ulink url='&YOCTO_DL_URL;/releases/'>Index of /releases:</ulink></emphasis> This area contains index releases such as the <trademark class='trade'>Eclipse</trademark> Yocto Plug-in, miscellaneous support, Poky, pseudo, cross-development toolchains, @@ -175,11 +176,11 @@ <para> <imagedata fileref="figures/index-downloads.png" align="center" width="6in" depth="4in" /> </para></listitem> - <listitem><para><emphasis><ulink url='http://www.yoctoproject.org/download'>Yocto Project Download Page</ulink></emphasis> + <listitem><para><emphasis><ulink url='&YOCTO_HOME_URL;/download'>Yocto Project Download Page</ulink></emphasis> This page on the Yocto Project website allows you to download any Yocto Project release or Board Support Package (BSP) in tarball form. The tarballs are similar to those found in the - <ulink url='http://downloads.yoctoproject.org/releases/'>Index of /releases:</ulink> area.</para> + <ulink url='&YOCTO_DL_URL;/releases/'>Index of /releases:</ulink> area.</para> <para> <imagedata fileref="figures/yp-download.png" align="center" width="6in" depth="4in" /> </para></listitem> @@ -239,12 +240,12 @@ Images are the binary output that runs on specific hardware and for specific use cases. For a list of the supported image types that the Yocto Project provides, see the - "<ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#ref-images'>Reference: Images</ulink>" + "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Reference: Images</ulink>" appendix in The Yocto Project Reference Manual.</para></listitem> <listitem><para id='layer'><emphasis>Layer:</emphasis> A collection of recipes representing the core, a BSP, or an application stack. For a discussion on BSP Layers, see the - "<ulink url='http://www.yoctoproject.org/docs/latest/bsp-guide/bsp-guide.html#bsp-layers'>BSP Layers</ulink>" + "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>" section in the Yocto Project Board Support Packages (BSP) Developer's Guide.</para></listitem> <listitem><para id='metadata'><emphasis>Metadata:</emphasis> The files that BitBake parses when building an image. @@ -283,44 +284,42 @@ by cloning <filename>git://git.yoctoproject.org/poky</filename>. Sometimes the term "the Yocto Project Files structure" is used as well.</para> - <para>The Yocto Project files contain BitBake, Documentation, metadata and + <para>The Yocto Project Files contain BitBake, Documentation, metadata and other files that all support the development environment. - Consequently, you must have the Yocto Project files in place on your development + Consequently, you must have the Yocto Project Files in place on your development system in order to do any development using the Yocto Project.</para> - <para>The name of the top-level directory of the Yocto Project file structure + <para>The name of the top-level directory of the Yocto Project Files structure is derived from the Yocto Project release tarball. - For example, downloading and unpacking <filename>poky-edison-6.0.tar.bz2</filename> + For example, downloading and unpacking <filename>&YOCTO_POKY_TARBALL;</filename> results in a Yocto Project file structure whose Yocto Project source directory is named - <filename>poky-edison-6.0</filename>. + <filename>&YOCTO_POKY;</filename>. If you create a Git repository, then you can name the repository anything you like. - By default, your local Git repository is named <filename>poky</filename>.</para> + Throughout much of the documentation, the name of the Git repository is used as the + name for the local folder. + So, for example, cloning the <filename>poky</filename> Git repository results in a + local Git repository also named <filename>poky</filename>.</para> <para>It is important to understand the differences between Yocto Project Files created by unpacking a release tarball as compared to cloning <filename>git://git.yoctoproject.org/poky</filename>. When you unpack a tarball, you have an exact copy of the files based on the time of release - a fixed release point. - Any changes you make to your local Yocto Project files are on top of the release. + Any changes you make to your local Yocto Project Files are on top of the release. On the other hand, when you clone the Yocto Project Git repository, you have an active development repository. - creates a build directory named <filename>YP-6.0</filename> - in your home directory within the directory <filename>mybuilds</filename>. - If <filename>mybuilds</filename> does not exist it is created for you. In this case, any local changes you make to the Yocto Project can be later applied to active - development branches of the upstream Yocto Project Git repository. - If you want to track a set of local changes while starting from the same point + In this case, any local changes you make to the Yocto Project can be later applied + to active development branches of the upstream Yocto Project Git repository.</para> + + <para>Finally, if you want to track a set of local changes while starting from the same point as a release tarball, you can create a local Git branch that reflects the exact copy of the files at the time of their release. - You do this using Git tags that are part of the repository. - For more information on concepts, see the section - "<link linkend='repositories-tags-and-branches'>Repositories, Tags, and Branches</link>". - </para> - - <para>You can find instruction on how to set up the Yocto Project files on your - host development system by reading - the - "<ulink url='http://www.yoctoproject.org/docs/latest/dev-manual/dev-manual.html#getting-setup'>Getting - Setup</ulink>" section.</para></listitem> + You do this using Git tags that are part of the repository.</para> + + <para>For more information on concepts around Git repositories, branches, and tags, + see the + "<link linkend='repositories-tags-and-branches'>Repositories, Tags, and Branches</link>" + section.</para></listitem> <listitem> <para id='yocto-project-build-directory'><emphasis>Yocto Project Build Directory:</emphasis> This term refers to the area used by the Yocto Project for builds. @@ -341,17 +340,17 @@ </literallayout></para></listitem> <listitem><para>Provide a directory path and specifically name the build directory. - This next example creates a build directory named <filename>YP-6.0</filename> + This next example creates a build directory named <filename>YP-&POKYVERSION;</filename> in your home directory within the directory <filename>mybuilds</filename>. If <filename>mybuilds</filename> does not exist, the directory is created for you: <literallayout class='monospaced'> - $ source poky-edison-6.0/oe-init-build-env $HOME/mybuilds/YP-6.0 + $ source &OE_INIT_PATH; $HOME/mybuilds/YP-&POKYVERSION; </literallayout></para></listitem> <listitem><para>Provide an existing directory to use as the build directory. This example uses the existing <filename>mybuilds</filename> directory as the build directory. <literallayout class='monospaced'> - $ source poky-edison-6.0/oe-init-build-env $HOME/mybuilds/ + $ source &OE_INIT_PATH; $HOME/mybuilds/ </literallayout></para></listitem> </itemizedlist> </para></listitem> @@ -419,7 +418,7 @@ <para> You can find a list of the combined SPDX and OSI licenses that the Yocto Project uses - <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/meta/files/common-licenses'>here</ulink>. + <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta/files/common-licenses'>here</ulink>. This wiki page discusses the license infrastructure used by the Yocto Project. </para> </section> @@ -449,7 +448,7 @@ As mentioned earlier in section "<link linkend='yocto-project-repositories'>Yocto Project Source Repositories</link>", the Yocto Project maintains source repositories at - <ulink url='http://git.yoctoproject.org/cgit.cgi'></ulink>. + <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>. If you look at this web-interface of the repositories, each item is a separate Git repository. </para> @@ -489,9 +488,9 @@ <filename>edison</filename>, and <filename>master</filename> branches among others. You can see all the branches by going to - <ulink url='http://git.yoctoproject.org/cgit.cgi/poky/'></ulink> and + <ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/'></ulink> and clicking on the - <filename><ulink url='http://git.yoctoproject.org/cgit.cgi/poky/refs/heads'>[...]</ulink></filename> + <filename><ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/refs/heads'>[...]</ulink></filename> link beneath the "Branch" heading. </para> @@ -512,19 +511,19 @@ branch in the repository. To help illustrate, here is a set of commands that creates a local copy of the <filename>poky</filename> Git repository and then creates and checks out a local - Git branch that tracks the Yocto Project 1.1 Release (edison) development: + Git branch that tracks the Yocto Project &DISTRO; Release (&DISTRO_NAME;) development: <literallayout class='monospaced'> $ cd ~ $ git clone git://git.yoctoproject.org/poky $ cd poky - $ git checkout edison -b edison + $ git checkout &DISTRO_NAME; -b &DISTRO_NAME; </literallayout> In this example, the name of the top-level directory of your local Yocto Project Files Git repository is <filename>poky</filename>. And, the name of the local working area (or local branch) you have created and checked - out is named <filename>edison</filename>. + out is named <filename>&DISTRO_NAME;</filename>. The files in your repository now reflect the same files that are in the - <filename>edison</filename> development branch of the Yocto Project's + <filename>&DISTRO_NAME;</filename> development branch of the Yocto Project's <filename>poky</filename> repository. It is important to understand that when you create and checkout a local working branch based on a branch name, @@ -532,8 +531,8 @@ at the time you created your local branch, which could be different than the files at the time of a similarly named release. In other words, creating and checking out a local branch based on the - <filename>edison</filename> branch name is not the same as creating and - checking out a local branch based on the <filename>edison-6.0</filename> + <filename>&DISTRO_NAME;</filename> branch name is not the same as creating and + checking out a local branch based on the <filename>&DISTRO_NAME;-&DISTRO;</filename> release. Keep reading to see how you create a local snapshot of a Yocto Project Release. </para> @@ -543,15 +542,15 @@ Typically, a tag is used to mark a special point such as the final change before a project is released. You can see the tags used with the <filename>poky</filename> Git repository - by going to <ulink url='http://git.yoctoproject.org/cgit.cgi/poky/'></ulink> and + by going to <ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/'></ulink> and clicking on the - <filename><ulink url='http://git.yoctoproject.org/cgit.cgi/poky/refs/tags'>[...]</ulink></filename> + <filename><ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/refs/tags'>[...]</ulink></filename> link beneath the "Tag" heading. </para> <para> Some key tags are <filename>laverne-4.0</filename>, <filename>bernard-5.0</filename>, - and <filename>edison-6.0</filename>. + and <filename>&DISTRO_NAME;-&POKYVERSION;</filename>. These tags represent Yocto Project releases. </para> @@ -569,14 +568,14 @@ $ cd ~ $ git clone git://git.yoctoproject.org/poky $ cd poky - $ git checkout edison-6.0 -b edison-6.0 + $ git checkout &DISTRO_NAME;-&POKYVERSION; -b &DISTRO_NAME;-&POKYVERSION; </literallayout> In this example, the name of the top-level directory of your local Yocto Project Files Git repository is <filename>poky</filename>. And, the name of the local branch you have created and checked out is - <filename>edison-6.0</filename>. - The files in your repository now exactly match the Yocto Project 1.1 - Release tag (edison). + <filename>&DISTRO_NAME;-&POKYVERSION;</filename>. + The files in your repository now exactly match the Yocto Project &DISTRO; + Release tag (&DISTRO_NAME;). It is important to understand that when you create and checkout a local working branch based on a tag, your environment matches a specific point in time and not a development branch. @@ -807,7 +806,7 @@ changes, can be used to communicate changes and problems with developers, can be used to submit and review patches, and can be used to manage quality assurance. The home page for the Yocto Project implementation of Bugzilla is - <ulink url='http://bugzilla.yoctoproject.org'>http://bugzilla.yoctoproject.org</ulink>. + <ulink url='&YOCTO_BUGZILLA_URL;'>&YOCTO_BUGZILLA_URL;</ulink>. </para> <para> @@ -818,7 +817,7 @@ Bugzilla. You can find more information on defect management, bug tracking, and feature request processes all accomplished through the Yocto Project Bugzilla on the wiki page - <ulink url='https://wiki.yoctoproject.org/wiki/Bugzilla_Configuration_and_Bug_Tracking'>here</ulink>. + <ulink url='&YOCTO_WIKI_URL;/wiki/Bugzilla_Configuration_and_Bug_Tracking'>here</ulink>. <orderedlist> <listitem><para>Always use the Yocto Project implementation of Bugzilla to submit a bug.</para></listitem> @@ -866,7 +865,7 @@ You should send patches to the appropriate Yocto Project mailing list to get them in front of the Yocto Project Maintainer. For a list of the Yocto Project mailing lists, see the - "<ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#resources-mailinglist'>Mailing lists</ulink>" section in + "<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing lists</ulink>" section in The Yocto Project Reference Manual. </para> @@ -875,14 +874,14 @@ <itemizedlist> <listitem><para>For defects against the Yocto Project build system Poky, send your patch to the - <ulink url='http://lists.yoctoproject.org/listinfo/poky'></ulink> mailing list. + <ulink url='&YOCTO_LISTS_URL;/listinfo/poky'></ulink> mailing list. This mailing list corresponds to issues that are not specific to the Yocto Project but are part of the OE-core. For example, a defect against anything in the <filename>meta</filename> layer or the BitBake Manual could be sent to this mailing list.</para></listitem> <listitem><para>For defects against Yocto-specific layers, tools, and Yocto Project documentation use the - <ulink url='http://lists.yoctoproject.org/listinfo/yocto'></ulink> mailing list. + <ulink url='&YOCTO_LISTS_URL;/listinfo/yocto'></ulink> mailing list. This mailing list corresponds to Yocto-specific areas such as <filename>meta-yocto</filename>, <filename>meta-intel</filename>, <filename>linux-yocto</filename>, and <filename>documentation</filename>.</para></listitem> @@ -973,7 +972,7 @@ <para> You can find more guidance on creating well-formed commit messages at this OpenEmbedded wiki page: - <ulink url='http://www.openembedded.org/wiki/Commit_Patch_Message_Guidelines'></ulink>. + <ulink url='&OE_HOME_URL;/wiki/Commit_Patch_Message_Guidelines'></ulink>. </para> <para> @@ -1089,22 +1088,6 @@ </para> </section> </section> - - - - - - - - - - - - - - - - </chapter> <!-- vim: expandtab tw=80 ts=4 |
