diff options
Diffstat (limited to 'documentation/getting-started')
119 files changed, 16087 insertions, 0 deletions
diff --git a/documentation/getting-started/eclipse/getting-started-toc.xml b/documentation/getting-started/eclipse/getting-started-toc.xml new file mode 100644 index 0000000000..6f1c29af30 --- /dev/null +++ b/documentation/getting-started/eclipse/getting-started-toc.xml | |||
| @@ -0,0 +1,86 @@ | |||
| 1 | <?xml version="1.0" encoding="utf-8" standalone="no"?> | ||
| 2 | <toc label="Getting Started With Yocto Project" topic="html/getting-started/index.html"> | ||
| 3 | <topic label="The Yocto Project Overview Manual" href="html/getting-started/overview-manual-intro.html"> | ||
| 4 | <topic label="Welcome" href="html/getting-started/overview-welcome.html"/> | ||
| 5 | <topic label="Other Information" href="html/getting-started/overview-other-information.html"/> | ||
| 6 | </topic> | ||
| 7 | <topic label="The Yocto Project Development Environment" href="html/getting-started/overview-development-environment.html"> | ||
| 8 | <topic label="Introduction" href="html/getting-started/yp-intro.html"/> | ||
| 9 | <topic label="Open Source Philosophy" href="html/getting-started/open-source-philosophy.html"/> | ||
| 10 | <topic label="Workflows" href="html/getting-started/workflows.html"/> | ||
| 11 | <topic label="Git" href="html/getting-started/git.html"> | ||
| 12 | <topic label="Repositories, Tags, and Branches" href="html/getting-started/repositories-tags-and-branches.html"/> | ||
| 13 | <topic label="Basic Commands" href="html/getting-started/basic-commands.html"/> | ||
| 14 | </topic> | ||
| 15 | <topic label="Yocto Project Source Repositories" href="html/getting-started/yocto-project-repositories.html"/> | ||
| 16 | <topic label="Licensing" href="html/getting-started/licensing.html"/> | ||
| 17 | <topic label="Recipe Syntax" href="html/getting-started/recipe-syntax.html"/> | ||
| 18 | <topic label="Development Concepts" href="html/getting-started/development-concepts.html"> | ||
| 19 | <topic label="User Configuration" href="html/getting-started/user-configuration.html"/> | ||
| 20 | <topic label="Metadata, Machine Configuration, and Policy Configuration" href="html/getting-started/metadata-machine-configuration-and-policy-configuration.html"> | ||
| 21 | <topic label="Distro Layer" href="html/getting-started/distro-layer.html"/> | ||
| 22 | <topic label="BSP Layer" href="html/getting-started/bsp-layer.html"/> | ||
| 23 | <topic label="Software Layer" href="html/getting-started/software-layer.html"/> | ||
| 24 | </topic> | ||
| 25 | <topic label="Sources" href="html/getting-started/sources-dev-environment.html"> | ||
| 26 | <topic label="Upstream Project Releases" href="html/getting-started/upstream-project-releases.html"/> | ||
| 27 | <topic label="Local Projects" href="html/getting-started/local-projects.html"/> | ||
| 28 | <topic label="Source Control Managers (Optional)" href="html/getting-started/scms.html"/> | ||
| 29 | <topic label="Source Mirror(s)" href="html/getting-started/source-mirrors.html"/> | ||
| 30 | </topic> | ||
| 31 | <topic label="Package Feeds" href="html/getting-started/package-feeds-dev-environment.html"/> | ||
| 32 | <topic label="BitBake" href="html/getting-started/bitbake-dev-environment.html"> | ||
| 33 | <topic label="Source Fetching" href="html/getting-started/source-fetching-dev-environment.html"/> | ||
| 34 | <topic label="Patching" href="html/getting-started/patching-dev-environment.html"/> | ||
| 35 | <topic label="Configuration and Compilation" href="html/getting-started/configuration-and-compilation-dev-environment.html"/> | ||
| 36 | <topic label="Package Splitting" href="html/getting-started/package-splitting-dev-environment.html"/> | ||
| 37 | <topic label="Image Generation" href="html/getting-started/image-generation-dev-environment.html"/> | ||
| 38 | <topic label="SDK Generation" href="html/getting-started/sdk-generation-dev-environment.html"/> | ||
| 39 | <topic label="Stamp Files and the Rerunning of Tasks" href="html/getting-started/stamp-files-and-the-rerunning-of-tasks.html"/> | ||
| 40 | <topic label="Setscene Tasks and Shared State" href="html/getting-started/setscene-tasks-and-shared-state.html"/> | ||
| 41 | </topic> | ||
| 42 | <topic label="Images" href="html/getting-started/images-dev-environment.html"/> | ||
| 43 | <topic label="Application Development SDK" href="html/getting-started/sdk-dev-environment.html"/> | ||
| 44 | </topic> | ||
| 45 | </topic> | ||
| 46 | <topic label="Yocto Project Concepts" href="html/getting-started/overview-concepts.html"> | ||
| 47 | <topic label="Yocto Project Components" href="html/getting-started/yocto-project-components.html"> | ||
| 48 | <topic label="BitBake" href="html/getting-started/usingpoky-components-bitbake.html"/> | ||
| 49 | <topic label="Metadata (Recipes)" href="html/getting-started/usingpoky-components-metadata.html"/> | ||
| 50 | <topic label="Metadata (Virtual Providers)" href="html/getting-started/metadata-virtual-providers.html"/> | ||
| 51 | <topic label="Classes" href="html/getting-started/usingpoky-components-classes.html"/> | ||
| 52 | <topic label="Configuration" href="html/getting-started/usingpoky-components-configuration.html"/> | ||
| 53 | </topic> | ||
| 54 | <topic label="Cross-Development Toolchain Generation" href="html/getting-started/cross-development-toolchain-generation.html"/> | ||
| 55 | <topic label="Shared State Cache" href="html/getting-started/shared-state-cache.html"> | ||
| 56 | <topic label="Overall Architecture" href="html/getting-started/overall-architecture.html"/> | ||
| 57 | <topic label="Checksums (Signatures)" href="html/getting-started/overview-checksums.html"/> | ||
| 58 | <topic label="Shared State" href="html/getting-started/shared-state.html"/> | ||
| 59 | <topic label="Tips and Tricks" href="html/getting-started/tips-and-tricks.html"> | ||
| 60 | <topic label="Debugging" href="html/getting-started/overview-debugging.html"/> | ||
| 61 | <topic label="Invalidating Shared State" href="html/getting-started/invalidating-shared-state.html"/> | ||
| 62 | </topic> | ||
| 63 | </topic> | ||
| 64 | <topic label="Automatically Added Runtime Dependencies" href="html/getting-started/automatically-added-runtime-dependencies.html"/> | ||
| 65 | <topic label="Fakeroot and Pseudo" href="html/getting-started/fakeroot-and-pseudo.html"/> | ||
| 66 | <topic label="Wayland" href="html/getting-started/wayland.html"> | ||
| 67 | <topic label="Support" href="html/getting-started/wayland-support.html"/> | ||
| 68 | <topic label="Enabling Wayland in an Image" href="html/getting-started/enabling-wayland-in-an-image.html"> | ||
| 69 | <topic label="Building" href="html/getting-started/enable-building.html"/> | ||
| 70 | <topic label="Installing" href="html/getting-started/enable-installation-in-an-image.html"/> | ||
| 71 | </topic> | ||
| 72 | <topic label="Running Weston" href="html/getting-started/running-weston.html"/> | ||
| 73 | </topic> | ||
| 74 | <topic label="Licenses" href="html/getting-started/overview-licenses.html"> | ||
| 75 | <topic label="Tracking License Changes" href="html/getting-started/usingpoky-configuring-LIC_FILES_CHKSUM.html"> | ||
| 76 | <topic label="Specifying the LIC_FILES_CHKSUM Variable" href="html/getting-started/usingpoky-specifying-LIC_FILES_CHKSUM.html"/> | ||
| 77 | <topic label="Explanation of Syntax" href="html/getting-started/usingpoky-LIC_FILES_CHKSUM-explanation-of-syntax.html"/> | ||
| 78 | </topic> | ||
| 79 | <topic label="Enabling Commercially Licensed Recipes" href="html/getting-started/enabling-commercially-licensed-recipes.html"> | ||
| 80 | <topic label="License Flag Matching" href="html/getting-started/license-flag-matching.html"/> | ||
| 81 | <topic label="Other Variables Related to Commercial Licenses" href="html/getting-started/other-variables-related-to-commercial-licenses.html"/> | ||
| 82 | </topic> | ||
| 83 | </topic> | ||
| 84 | <topic label="x32 psABI" href="html/getting-started/x32.html"/> | ||
| 85 | </topic> | ||
| 86 | </toc> | ||
diff --git a/documentation/getting-started/eclipse/html/getting-started/automatically-added-runtime-dependencies.html b/documentation/getting-started/eclipse/html/getting-started/automatically-added-runtime-dependencies.html new file mode 100644 index 0000000000..885ee089e1 --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/automatically-added-runtime-dependencies.html | |||
| @@ -0,0 +1,164 @@ | |||
| 1 | <html> | ||
| 2 | <head> | ||
| 3 | <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> | ||
| 4 | <title>3.4.Automatically Added Runtime Dependencies</title> | ||
| 5 | <link rel="stylesheet" type="text/css" href="../book.css"> | ||
| 6 | <meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> | ||
| 7 | <link rel="home" href="index.html" title="Getting Started With Yocto Project"> | ||
| 8 | <link rel="up" href="overview-concepts.html" title="Chapter3.Yocto Project Concepts"> | ||
| 9 | <link rel="prev" href="invalidating-shared-state.html" title="3.3.4.2.Invalidating Shared State"> | ||
| 10 | <link rel="next" href="fakeroot-and-pseudo.html" title="3.5.Fakeroot and Pseudo"> | ||
| 11 | </head> | ||
| 12 | <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="3.4.Automatically Added Runtime Dependencies"> | ||
| 13 | <div class="titlepage"><div><div><h2 class="title" style="clear: both"> | ||
| 14 | <a name="automatically-added-runtime-dependencies"></a>3.4.Automatically Added Runtime Dependencies</h2></div></div></div> | ||
| 15 | <p> | ||
| 16 | The OpenEmbedded build system automatically adds common types of | ||
| 17 | runtime dependencies between packages, which means that you do not | ||
| 18 | need to explicitly declare the packages using | ||
| 19 | <a class="link" href="../ref-manual/var-RDEPENDS.html" target="_self"><code class="filename">RDEPENDS</code></a>. | ||
| 20 | Three automatic mechanisms exist (<code class="filename">shlibdeps</code>, | ||
| 21 | <code class="filename">pcdeps</code>, and <code class="filename">depchains</code>) | ||
| 22 | that handle shared libraries, package configuration (pkg-config) | ||
| 23 | modules, and <code class="filename">-dev</code> and | ||
| 24 | <code class="filename">-dbg</code> packages, respectively. | ||
| 25 | For other types of runtime dependencies, you must manually declare | ||
| 26 | the dependencies. | ||
| 27 | </p> | ||
| 28 | <div class="itemizedlist"><ul class="itemizedlist" type="disc"> | ||
| 29 | <li class="listitem"> | ||
| 30 | <p> | ||
| 31 | <code class="filename">shlibdeps</code>: | ||
| 32 | During the | ||
| 33 | <a class="link" href="../ref-manual/ref-tasks-package.html" target="_self"><code class="filename">do_package</code></a> | ||
| 34 | task of each recipe, all shared libraries installed by the | ||
| 35 | recipe are located. | ||
| 36 | For each shared library, the package that contains the | ||
| 37 | shared library is registered as providing the shared | ||
| 38 | library. | ||
| 39 | More specifically, the package is registered as providing | ||
| 40 | the | ||
| 41 | <a class="ulink" href="https://en.wikipedia.org/wiki/Soname" target="_self">soname</a> | ||
| 42 | of the library. | ||
| 43 | The resulting shared-library-to-package mapping | ||
| 44 | is saved globally in | ||
| 45 | <a class="link" href="../ref-manual/var-PKGDATA_DIR.html" target="_self"><code class="filename">PKGDATA_DIR</code></a> | ||
| 46 | by the | ||
| 47 | <a class="link" href="../ref-manual/ref-tasks-packagedata.html" target="_self"><code class="filename">do_packagedata</code></a> | ||
| 48 | task.</p> | ||
| 49 | <p>Simultaneously, all executables and shared libraries | ||
| 50 | installed by the recipe are inspected to see what shared | ||
| 51 | libraries they link against. | ||
| 52 | For each shared library dependency that is found, | ||
| 53 | <code class="filename">PKGDATA_DIR</code> is queried to | ||
| 54 | see if some package (likely from a different recipe) | ||
| 55 | contains the shared library. | ||
| 56 | If such a package is found, a runtime dependency is added | ||
| 57 | from the package that depends on the shared library to the | ||
| 58 | package that contains the library.</p> | ||
| 59 | <p>The automatically added runtime dependency also | ||
| 60 | includes a version restriction. | ||
| 61 | This version restriction specifies that at least the | ||
| 62 | current version of the package that provides the shared | ||
| 63 | library must be used, as if | ||
| 64 | "<em class="replaceable"><code>package</code></em> (>= <em class="replaceable"><code>version</code></em>)" | ||
| 65 | had been added to | ||
| 66 | <a class="link" href="../ref-manual/var-RDEPENDS.html" target="_self"><code class="filename">RDEPENDS</code></a>. | ||
| 67 | This forces an upgrade of the package containing the shared | ||
| 68 | library when installing the package that depends on the | ||
| 69 | library, if needed.</p> | ||
| 70 | <p>If you want to avoid a package being registered as | ||
| 71 | providing a particular shared library (e.g. because the library | ||
| 72 | is for internal use only), then add the library to | ||
| 73 | <a class="link" href="../ref-manual/var-PRIVATE_LIBS.html" target="_self"><code class="filename">PRIVATE_LIBS</code></a> | ||
| 74 | inside the package's recipe. | ||
| 75 | </p> | ||
| 76 | </li> | ||
| 77 | <li class="listitem"> | ||
| 78 | <p> | ||
| 79 | <code class="filename">pcdeps</code>: | ||
| 80 | During the | ||
| 81 | <a class="link" href="../ref-manual/ref-tasks-package.html" target="_self"><code class="filename">do_package</code></a> | ||
| 82 | task of each recipe, all pkg-config modules | ||
| 83 | (<code class="filename">*.pc</code> files) installed by the recipe | ||
| 84 | are located. | ||
| 85 | For each module, the package that contains the module is | ||
| 86 | registered as providing the module. | ||
| 87 | The resulting module-to-package mapping is saved globally in | ||
| 88 | <a class="link" href="../ref-manual/var-PKGDATA_DIR.html" target="_self"><code class="filename">PKGDATA_DIR</code></a> | ||
| 89 | by the | ||
| 90 | <a class="link" href="../ref-manual/ref-tasks-packagedata.html" target="_self"><code class="filename">do_packagedata</code></a> | ||
| 91 | task.</p> | ||
| 92 | <p>Simultaneously, all pkg-config modules installed by | ||
| 93 | the recipe are inspected to see what other pkg-config | ||
| 94 | modules they depend on. | ||
| 95 | A module is seen as depending on another module if it | ||
| 96 | contains a "Requires:" line that specifies the other module. | ||
| 97 | For each module dependency, | ||
| 98 | <code class="filename">PKGDATA_DIR</code> is queried to see if some | ||
| 99 | package contains the module. | ||
| 100 | If such a package is found, a runtime dependency is added | ||
| 101 | from the package that depends on the module to the package | ||
| 102 | that contains the module. | ||
| 103 | </p> | ||
| 104 | <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"> | ||
| 105 | <h3 class="title">Note</h3> | ||
| 106 | The <code class="filename">pcdeps</code> mechanism most often | ||
| 107 | infers dependencies between <code class="filename">-dev</code> | ||
| 108 | packages. | ||
| 109 | </div> | ||
| 110 | <p> | ||
| 111 | </p> | ||
| 112 | </li> | ||
| 113 | <li class="listitem"> | ||
| 114 | <p> | ||
| 115 | <code class="filename">depchains</code>: | ||
| 116 | If a package <code class="filename">foo</code> depends on a package | ||
| 117 | <code class="filename">bar</code>, then <code class="filename">foo-dev</code> | ||
| 118 | and <code class="filename">foo-dbg</code> are also made to depend on | ||
| 119 | <code class="filename">bar-dev</code> and | ||
| 120 | <code class="filename">bar-dbg</code>, respectively. | ||
| 121 | Taking the <code class="filename">-dev</code> packages as an | ||
| 122 | example, the <code class="filename">bar-dev</code> package might | ||
| 123 | provide headers and shared library symlinks needed by | ||
| 124 | <code class="filename">foo-dev</code>, which shows the need | ||
| 125 | for a dependency between the packages.</p> | ||
| 126 | <p>The dependencies added by | ||
| 127 | <code class="filename">depchains</code> are in the form of | ||
| 128 | <a class="link" href="../ref-manual/var-RRECOMMENDS.html" target="_self"><code class="filename">RRECOMMENDS</code></a>. | ||
| 129 | </p> | ||
| 130 | <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"> | ||
| 131 | <h3 class="title">Note</h3> | ||
| 132 | By default, <code class="filename">foo-dev</code> also has an | ||
| 133 | <code class="filename">RDEPENDS</code>-style dependency on | ||
| 134 | <code class="filename">foo</code>, because the default value of | ||
| 135 | <code class="filename">RDEPENDS_${PN}-dev</code> (set in | ||
| 136 | <code class="filename">bitbake.conf</code>) includes | ||
| 137 | "${PN}". | ||
| 138 | </div> | ||
| 139 | <p>To ensure that the dependency chain is never broken, | ||
| 140 | <code class="filename">-dev</code> and <code class="filename">-dbg</code> | ||
| 141 | packages are always generated by default, even if the | ||
| 142 | packages turn out to be empty. | ||
| 143 | See the | ||
| 144 | <a class="link" href="../ref-manual/var-ALLOW_EMPTY.html" target="_self"><code class="filename">ALLOW_EMPTY</code></a> | ||
| 145 | variable for more information. | ||
| 146 | </p> | ||
| 147 | </li> | ||
| 148 | </ul></div> | ||
| 149 | <p> | ||
| 150 | </p> | ||
| 151 | <p> | ||
| 152 | The <code class="filename">do_package</code> task depends on the | ||
| 153 | <a class="link" href="../ref-manual/ref-tasks-packagedata.html" target="_self"><code class="filename">do_packagedata</code></a> | ||
| 154 | task of each recipe in | ||
| 155 | <a class="link" href="../ref-manual/var-DEPENDS.html" target="_self"><code class="filename">DEPENDS</code></a> | ||
| 156 | through use of a | ||
| 157 | <code class="filename">[</code><a class="link" href="../bitbake-user-manual/variable-flags.html" target="_self"><code class="filename">deptask</code></a><code class="filename">]</code> | ||
| 158 | declaration, which guarantees that the required | ||
| 159 | shared-library/module-to-package mapping information will be available | ||
| 160 | when needed as long as <code class="filename">DEPENDS</code> has been | ||
| 161 | correctly set. | ||
| 162 | </p> | ||
| 163 | </div></body> | ||
| 164 | </html> | ||
diff --git a/documentation/getting-started/eclipse/html/getting-started/basic-commands.html b/documentation/getting-started/eclipse/html/getting-started/basic-commands.html new file mode 100644 index 0000000000..b145086974 --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/basic-commands.html | |||
| @@ -0,0 +1,176 @@ | |||
| 1 | <html> | ||
| 2 | <head> | ||
| 3 | <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> | ||
| 4 | <title>2.4.2.Basic Commands</title> | ||
| 5 | <link rel="stylesheet" type="text/css" href="../book.css"> | ||
| 6 | <meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> | ||
| 7 | <link rel="home" href="index.html" title="Getting Started With Yocto Project"> | ||
| 8 | <link rel="up" href="git.html" title="2.4.Git"> | ||
| 9 | <link rel="prev" href="repositories-tags-and-branches.html" title="2.4.1.Repositories, Tags, and Branches"> | ||
| 10 | <link rel="next" href="yocto-project-repositories.html" title="2.5.Yocto Project Source Repositories"> | ||
| 11 | </head> | ||
| 12 | <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="2.4.2.Basic Commands"> | ||
| 13 | <div class="titlepage"><div><div><h3 class="title"> | ||
| 14 | <a name="basic-commands"></a>2.4.2.Basic Commands</h3></div></div></div> | ||
| 15 | <p> | ||
| 16 | Git has an extensive set of commands that lets you manage changes | ||
| 17 | and perform collaboration over the life of a project. | ||
| 18 | Conveniently though, you can manage with a small set of basic | ||
| 19 | operations and workflows once you understand the basic | ||
| 20 | philosophy behind Git. | ||
| 21 | You do not have to be an expert in Git to be functional. | ||
| 22 | A good place to look for instruction on a minimal set of Git | ||
| 23 | commands is | ||
| 24 | <a class="ulink" href="http://git-scm.com/documentation" target="_self">here</a>. | ||
| 25 | </p> | ||
| 26 | <p> | ||
| 27 | If you do not know much about Git, you should educate | ||
| 28 | yourself by visiting the links previously mentioned. | ||
| 29 | </p> | ||
| 30 | <p> | ||
| 31 | The following list of Git commands briefly describes some basic | ||
| 32 | Git operations as a way to get started. | ||
| 33 | As with any set of commands, this list (in most cases) simply shows | ||
| 34 | the base command and omits the many arguments they support. | ||
| 35 | See the Git documentation for complete descriptions and strategies | ||
| 36 | on how to use these commands: | ||
| 37 | </p> | ||
| 38 | <div class="itemizedlist"><ul class="itemizedlist" type="disc"> | ||
| 39 | <li class="listitem"><p> | ||
| 40 | <span class="emphasis"><em><code class="filename">git init</code>:</em></span> | ||
| 41 | Initializes an empty Git repository. | ||
| 42 | You cannot use Git commands unless you have a | ||
| 43 | <code class="filename">.git</code> repository. | ||
| 44 | </p></li> | ||
| 45 | <li class="listitem"><p><a name="git-commands-clone"></a> | ||
| 46 | <span class="emphasis"><em><code class="filename">git clone</code>:</em></span> | ||
| 47 | Creates a local clone of a Git repository that is on | ||
| 48 | equal footing with a fellow developer’s Git repository | ||
| 49 | or an upstream repository. | ||
| 50 | </p></li> | ||
| 51 | <li class="listitem"><p> | ||
| 52 | <span class="emphasis"><em><code class="filename">git add</code>:</em></span> | ||
| 53 | Locally stages updated file contents to the index that | ||
| 54 | Git uses to track changes. | ||
| 55 | You must stage all files that have changed before you | ||
| 56 | can commit them. | ||
| 57 | </p></li> | ||
| 58 | <li class="listitem"><p> | ||
| 59 | <span class="emphasis"><em><code class="filename">git commit</code>:</em></span> | ||
| 60 | Creates a local "commit" that documents the changes you | ||
| 61 | made. | ||
| 62 | Only changes that have been staged can be committed. | ||
| 63 | Commits are used for historical purposes, for determining | ||
| 64 | if a maintainer of a project will allow the change, | ||
| 65 | and for ultimately pushing the change from your local | ||
| 66 | Git repository into the project’s upstream repository. | ||
| 67 | </p></li> | ||
| 68 | <li class="listitem"><p> | ||
| 69 | <span class="emphasis"><em><code class="filename">git status</code>:</em></span> | ||
| 70 | Reports any modified files that possibly need to be | ||
| 71 | staged and gives you a status of where you stand regarding | ||
| 72 | local commits as compared to the upstream repository. | ||
| 73 | </p></li> | ||
| 74 | <li class="listitem"><p> | ||
| 75 | <span class="emphasis"><em><code class="filename">git checkout</code> <em class="replaceable"><code>branch-name</code></em>:</em></span> | ||
| 76 | Changes your working branch. | ||
| 77 | This command is analogous to "cd". | ||
| 78 | </p></li> | ||
| 79 | <li class="listitem"><p><span class="emphasis"><em><code class="filename">git checkout –b</code> <em class="replaceable"><code>working-branch</code></em>:</em></span> | ||
| 80 | Creates and checks out a working branch on your local | ||
| 81 | machine that you can use to isolate your work. | ||
| 82 | It is a good idea to use local branches when adding | ||
| 83 | specific features or changes. | ||
| 84 | Using isolated branches facilitates easy removal of | ||
| 85 | changes if they do not work out. | ||
| 86 | </p></li> | ||
| 87 | <li class="listitem"><p><span class="emphasis"><em><code class="filename">git branch</code>:</em></span> | ||
| 88 | Displays the existing local branches associated with your | ||
| 89 | local repository. | ||
| 90 | The branch that you have currently checked out is noted | ||
| 91 | with an asterisk character. | ||
| 92 | </p></li> | ||
| 93 | <li class="listitem"><p> | ||
| 94 | <span class="emphasis"><em><code class="filename">git branch -D</code> <em class="replaceable"><code>branch-name</code></em>:</em></span> | ||
| 95 | Deletes an existing local branch. | ||
| 96 | You need to be in a local branch other than the one you | ||
| 97 | are deleting in order to delete | ||
| 98 | <em class="replaceable"><code>branch-name</code></em>. | ||
| 99 | </p></li> | ||
| 100 | <li class="listitem"><p> | ||
| 101 | <span class="emphasis"><em><code class="filename">git pull</code>:</em></span> | ||
| 102 | Retrieves information from an upstream Git repository | ||
| 103 | and places it in your local Git repository. | ||
| 104 | You use this command to make sure you are synchronized with | ||
| 105 | the repository from which you are basing changes | ||
| 106 | (.e.g. the "master" branch). | ||
| 107 | </p></li> | ||
| 108 | <li class="listitem"><p> | ||
| 109 | <span class="emphasis"><em><code class="filename">git push</code>:</em></span> | ||
| 110 | Sends all your committed local changes to the upstream Git | ||
| 111 | repository that your local repository is tracking | ||
| 112 | (e.g. a contribution repository). | ||
| 113 | The maintainer of the project draws from these repositories | ||
| 114 | to merge changes (commits) into the appropriate branch | ||
| 115 | of project's upstream repository. | ||
| 116 | </p></li> | ||
| 117 | <li class="listitem"><p> | ||
| 118 | <span class="emphasis"><em><code class="filename">git merge</code>:</em></span> | ||
| 119 | Combines or adds changes from one | ||
| 120 | local branch of your repository with another branch. | ||
| 121 | When you create a local Git repository, the default branch | ||
| 122 | is named "master". | ||
| 123 | A typical workflow is to create a temporary branch that is | ||
| 124 | based off "master" that you would use for isolated work. | ||
| 125 | You would make your changes in that isolated branch, | ||
| 126 | stage and commit them locally, switch to the "master" | ||
| 127 | branch, and then use the <code class="filename">git merge</code> | ||
| 128 | command to apply the changes from your isolated branch | ||
| 129 | into the currently checked out branch (e.g. "master"). | ||
| 130 | After the merge is complete and if you are done with | ||
| 131 | working in that isolated branch, you can safely delete | ||
| 132 | the isolated branch. | ||
| 133 | </p></li> | ||
| 134 | <li class="listitem"><p> | ||
| 135 | <span class="emphasis"><em><code class="filename">git cherry-pick</code>:</em></span> | ||
| 136 | Choose and apply specific commits from one branch | ||
| 137 | into another branch. | ||
| 138 | There are times when you might not be able to merge | ||
| 139 | all the changes in one branch with | ||
| 140 | another but need to pick out certain ones. | ||
| 141 | </p></li> | ||
| 142 | <li class="listitem"> | ||
| 143 | <p> | ||
| 144 | <span class="emphasis"><em><code class="filename">gitk</code>:</em></span> | ||
| 145 | Provides a GUI view of the branches and changes in your | ||
| 146 | local Git repository. | ||
| 147 | This command is a good way to graphically see where things | ||
| 148 | have diverged in your local repository. | ||
| 149 | </p> | ||
| 150 | <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"> | ||
| 151 | <h3 class="title">Note</h3> | ||
| 152 | You need to install the <code class="filename">gitk</code> | ||
| 153 | package on your development system to use this | ||
| 154 | command. | ||
| 155 | </div> | ||
| 156 | <p> | ||
| 157 | </p> | ||
| 158 | </li> | ||
| 159 | <li class="listitem"><p> | ||
| 160 | <span class="emphasis"><em><code class="filename">git log</code>:</em></span> | ||
| 161 | Reports a history of your commits to the repository. | ||
| 162 | This report lists all commits regardless of whether you | ||
| 163 | have pushed them upstream or not. | ||
| 164 | </p></li> | ||
| 165 | <li class="listitem"><p> | ||
| 166 | <span class="emphasis"><em><code class="filename">git diff</code>:</em></span> | ||
| 167 | Displays line-by-line differences between a local | ||
| 168 | working file and the same file as understood by Git. | ||
| 169 | This command is useful to see what you have changed | ||
| 170 | in any given file. | ||
| 171 | </p></li> | ||
| 172 | </ul></div> | ||
| 173 | <p> | ||
| 174 | </p> | ||
| 175 | </div></body> | ||
| 176 | </html> | ||
diff --git a/documentation/getting-started/eclipse/html/getting-started/bitbake-dev-environment.html b/documentation/getting-started/eclipse/html/getting-started/bitbake-dev-environment.html new file mode 100644 index 0000000000..eda2c3370f --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/bitbake-dev-environment.html | |||
| @@ -0,0 +1,31 @@ | |||
| 1 | <html> | ||
| 2 | <head> | ||
| 3 | <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> | ||
| 4 | <title>2.8.5.BitBake</title> | ||
| 5 | <link rel="stylesheet" type="text/css" href="../book.css"> | ||
| 6 | <meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> | ||
| 7 | <link rel="home" href="index.html" title="Getting Started With Yocto Project"> | ||
| 8 | <link rel="up" href="development-concepts.html" title="2.8.Development Concepts"> | ||
| 9 | <link rel="prev" href="package-feeds-dev-environment.html" title="2.8.4.Package Feeds"> | ||
| 10 | <link rel="next" href="source-fetching-dev-environment.html" title="2.8.5.1.Source Fetching"> | ||
| 11 | </head> | ||
| 12 | <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="2.8.5.BitBake"> | ||
| 13 | <div class="titlepage"><div><div><h3 class="title"> | ||
| 14 | <a name="bitbake-dev-environment"></a>2.8.5.BitBake</h3></div></div></div> | ||
| 15 | <p> | ||
| 16 | The OpenEmbedded build system uses | ||
| 17 | <a class="link" href="../ref-manual/bitbake-term.html" target="_self">BitBake</a> | ||
| 18 | to produce images. | ||
| 19 | You can see from the | ||
| 20 | <a class="link" href="development-concepts.html#general-yocto-environment-figure">general Yocto Project Development Environment figure</a>, | ||
| 21 | the BitBake area consists of several functional areas. | ||
| 22 | This section takes a closer look at each of those areas. | ||
| 23 | </p> | ||
| 24 | <p> | ||
| 25 | Separate documentation exists for the BitBake tool. | ||
| 26 | See the | ||
| 27 | <a class="link" href="../bitbake-user-manual/bitbake-user-manual.html" target="_self">BitBake User Manual</a> | ||
| 28 | for reference material on BitBake. | ||
| 29 | </p> | ||
| 30 | </div></body> | ||
| 31 | </html> | ||
diff --git a/documentation/getting-started/eclipse/html/getting-started/bsp-layer.html b/documentation/getting-started/eclipse/html/getting-started/bsp-layer.html new file mode 100644 index 0000000000..2d009d5720 --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/bsp-layer.html | |||
| @@ -0,0 +1,54 @@ | |||
| 1 | <html> | ||
| 2 | <head> | ||
| 3 | <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> | ||
| 4 | <title>2.8.2.2.BSP Layer</title> | ||
| 5 | <link rel="stylesheet" type="text/css" href="../book.css"> | ||
| 6 | <meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> | ||
| 7 | <link rel="home" href="index.html" title="Getting Started With Yocto Project"> | ||
| 8 | <link rel="up" href="metadata-machine-configuration-and-policy-configuration.html" title="2.8.2.Metadata, Machine Configuration, and Policy Configuration"> | ||
| 9 | <link rel="prev" href="distro-layer.html" title="2.8.2.1.Distro Layer"> | ||
| 10 | <link rel="next" href="software-layer.html" title="2.8.2.3.Software Layer"> | ||
| 11 | </head> | ||
| 12 | <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="2.8.2.2.BSP Layer"> | ||
| 13 | <div class="titlepage"><div><div><h4 class="title"> | ||
| 14 | <a name="bsp-layer"></a>2.8.2.2.BSP Layer</h4></div></div></div> | ||
| 15 | <p> | ||
| 16 | The BSP Layer provides machine configurations. | ||
| 17 | Everything in this layer is specific to the machine for which | ||
| 18 | you are building the image or the SDK. | ||
| 19 | A common structure or form is defined for BSP layers. | ||
| 20 | You can learn more about this structure in the | ||
| 21 | <a class="link" href="../bsp-guide/index.html" target="_self">Yocto Project Board Support Package (BSP) Developer's Guide</a>. | ||
| 22 | </p> | ||
| 23 | <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"> | ||
| 24 | <h3 class="title">Note</h3> | ||
| 25 | In order for a BSP layer to be considered compliant with the | ||
| 26 | Yocto Project, it must meet some structural requirements. | ||
| 27 | </div> | ||
| 28 | <p> | ||
| 29 | </p> | ||
| 30 | <p> | ||
| 31 | The BSP Layer's configuration directory contains | ||
| 32 | configuration files for the machine | ||
| 33 | (<code class="filename">conf/machine/<em class="replaceable"><code>machine</code></em>.conf</code>) and, | ||
| 34 | of course, the layer (<code class="filename">conf/layer.conf</code>). | ||
| 35 | </p> | ||
| 36 | <p> | ||
| 37 | The remainder of the layer is dedicated to specific recipes | ||
| 38 | by function: <code class="filename">recipes-bsp</code>, | ||
| 39 | <code class="filename">recipes-core</code>, | ||
| 40 | <code class="filename">recipes-graphics</code>, and | ||
| 41 | <code class="filename">recipes-kernel</code>. | ||
| 42 | Metadata can exist for multiple formfactors, graphics | ||
| 43 | support systems, and so forth. | ||
| 44 | </p> | ||
| 45 | <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"> | ||
| 46 | <h3 class="title">Note</h3> | ||
| 47 | While the figure shows several <code class="filename">recipes-*</code> | ||
| 48 | directories, not all these directories appear in all | ||
| 49 | BSP layers. | ||
| 50 | </div> | ||
| 51 | <p> | ||
| 52 | </p> | ||
| 53 | </div></body> | ||
| 54 | </html> | ||
diff --git a/documentation/getting-started/eclipse/html/getting-started/configuration-and-compilation-dev-environment.html b/documentation/getting-started/eclipse/html/getting-started/configuration-and-compilation-dev-environment.html new file mode 100644 index 0000000000..9a94cc47da --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/configuration-and-compilation-dev-environment.html | |||
| @@ -0,0 +1,93 @@ | |||
| 1 | <html> | ||
| 2 | <head> | ||
| 3 | <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> | ||
| 4 | <title>2.8.5.3.Configuration and Compilation</title> | ||
| 5 | <link rel="stylesheet" type="text/css" href="../book.css"> | ||
| 6 | <meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> | ||
| 7 | <link rel="home" href="index.html" title="Getting Started With Yocto Project"> | ||
| 8 | <link rel="up" href="bitbake-dev-environment.html" title="2.8.5.BitBake"> | ||
| 9 | <link rel="prev" href="patching-dev-environment.html" title="2.8.5.2.Patching"> | ||
| 10 | <link rel="next" href="package-splitting-dev-environment.html" title="2.8.5.4.Package Splitting"> | ||
| 11 | </head> | ||
| 12 | <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="2.8.5.3.Configuration and Compilation"> | ||
| 13 | <div class="titlepage"><div><div><h4 class="title"> | ||
| 14 | <a name="configuration-and-compilation-dev-environment"></a>2.8.5.3.Configuration and Compilation</h4></div></div></div> | ||
| 15 | <p> | ||
| 16 | After source code is patched, BitBake executes tasks that | ||
| 17 | configure and compile the source code: | ||
| 18 | </p> | ||
| 19 | <table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="630"><tr style="height: 450px"><td align="center"><img src="figures/configuration-compile-autoreconf.png" align="middle" width="630"></td></tr></table> | ||
| 20 | <p> | ||
| 21 | </p> | ||
| 22 | <p> | ||
| 23 | This step in the build process consists of three tasks: | ||
| 24 | </p> | ||
| 25 | <div class="itemizedlist"><ul class="itemizedlist" type="disc"> | ||
| 26 | <li class="listitem"><p> | ||
| 27 | <span class="emphasis"><em><a class="link" href="../ref-manual/ref-tasks-prepare_recipe_sysroot.html" target="_self"><code class="filename">do_prepare_recipe_sysroot</code></a>:</em></span> | ||
| 28 | This task sets up the two sysroots in | ||
| 29 | <code class="filename">${</code><a class="link" href="../ref-manual/var-WORKDIR.html" target="_self"><code class="filename">WORKDIR</code></a><code class="filename">}</code> | ||
| 30 | (i.e. <code class="filename">recipe-sysroot</code> and | ||
| 31 | <code class="filename">recipe-sysroot-native</code>) so that | ||
| 32 | the sysroots contain the contents of the | ||
| 33 | <a class="link" href="../ref-manual/ref-tasks-populate_sysroot.html" target="_self"><code class="filename">do_populate_sysroot</code></a> | ||
| 34 | tasks of the recipes on which the recipe | ||
| 35 | containing the tasks depends. | ||
| 36 | A sysroot exists for both the target and for the native | ||
| 37 | binaries, which run on the host system. | ||
| 38 | </p></li> | ||
| 39 | <li class="listitem"> | ||
| 40 | <p><span class="emphasis"><em><code class="filename">do_configure</code>:</em></span> | ||
| 41 | This task configures the source by enabling and | ||
| 42 | disabling any build-time and configuration options for | ||
| 43 | the software being built. | ||
| 44 | Configurations can come from the recipe itself as well | ||
| 45 | as from an inherited class. | ||
| 46 | Additionally, the software itself might configure itself | ||
| 47 | depending on the target for which it is being built. | ||
| 48 | </p> | ||
| 49 | <p>The configurations handled by the | ||
| 50 | <a class="link" href="../ref-manual/ref-tasks-configure.html" target="_self"><code class="filename">do_configure</code></a> | ||
| 51 | task are specific | ||
| 52 | to source code configuration for the source code | ||
| 53 | being built by the recipe.</p> | ||
| 54 | <p>If you are using the | ||
| 55 | <a class="link" href="../ref-manual/ref-classes-autotools.html" target="_self"><code class="filename">autotools</code></a> | ||
| 56 | class, | ||
| 57 | you can add additional configuration options by using | ||
| 58 | the | ||
| 59 | <a class="link" href="../ref-manual/var-EXTRA_OECONF.html" target="_self"><code class="filename">EXTRA_OECONF</code></a> | ||
| 60 | or | ||
| 61 | <a class="link" href="../ref-manual/var-PACKAGECONFIG_CONFARGS.html" target="_self"><code class="filename">PACKAGECONFIG_CONFARGS</code></a> | ||
| 62 | variables. | ||
| 63 | For information on how this variable works within | ||
| 64 | that class, see the | ||
| 65 | <code class="filename">meta/classes/autotools.bbclass</code> file. | ||
| 66 | </p> | ||
| 67 | </li> | ||
| 68 | <li class="listitem"><p><span class="emphasis"><em><code class="filename">do_compile</code>:</em></span> | ||
| 69 | Once a configuration task has been satisfied, BitBake | ||
| 70 | compiles the source using the | ||
| 71 | <a class="link" href="../ref-manual/ref-tasks-compile.html" target="_self"><code class="filename">do_compile</code></a> | ||
| 72 | task. | ||
| 73 | Compilation occurs in the directory pointed to by the | ||
| 74 | <a class="link" href="../ref-manual/var-B.html" target="_self"><code class="filename">B</code></a> | ||
| 75 | variable. | ||
| 76 | Realize that the <code class="filename">B</code> directory is, by | ||
| 77 | default, the same as the | ||
| 78 | <a class="link" href="../ref-manual/var-S.html" target="_self"><code class="filename">S</code></a> | ||
| 79 | directory.</p></li> | ||
| 80 | <li class="listitem"><p><span class="emphasis"><em><code class="filename">do_install</code>:</em></span> | ||
| 81 | Once compilation is done, BitBake executes the | ||
| 82 | <a class="link" href="../ref-manual/ref-tasks-install.html" target="_self"><code class="filename">do_install</code></a> | ||
| 83 | task. | ||
| 84 | This task copies files from the <code class="filename">B</code> | ||
| 85 | directory and places them in a holding area pointed to | ||
| 86 | by the | ||
| 87 | <a class="link" href="../ref-manual/var-D.html" target="_self"><code class="filename">D</code></a> | ||
| 88 | variable.</p></li> | ||
| 89 | </ul></div> | ||
| 90 | <p> | ||
| 91 | </p> | ||
| 92 | </div></body> | ||
| 93 | </html> | ||
diff --git a/documentation/getting-started/eclipse/html/getting-started/cross-development-toolchain-generation.html b/documentation/getting-started/eclipse/html/getting-started/cross-development-toolchain-generation.html new file mode 100644 index 0000000000..a1aef9119d --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/cross-development-toolchain-generation.html | |||
| @@ -0,0 +1,241 @@ | |||
| 1 | <html> | ||
| 2 | <head> | ||
| 3 | <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> | ||
| 4 | <title>3.2.Cross-Development Toolchain Generation</title> | ||
| 5 | <link rel="stylesheet" type="text/css" href="../book.css"> | ||
| 6 | <meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> | ||
| 7 | <link rel="home" href="index.html" title="Getting Started With Yocto Project"> | ||
| 8 | <link rel="up" href="overview-concepts.html" title="Chapter3.Yocto Project Concepts"> | ||
| 9 | <link rel="prev" href="usingpoky-components-configuration.html" title="3.1.5.Configuration"> | ||
| 10 | <link rel="next" href="shared-state-cache.html" title="3.3.Shared State Cache"> | ||
| 11 | </head> | ||
| 12 | <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="3.2.Cross-Development Toolchain Generation"> | ||
| 13 | <div class="titlepage"><div><div><h2 class="title" style="clear: both"> | ||
| 14 | <a name="cross-development-toolchain-generation"></a>3.2.Cross-Development Toolchain Generation</h2></div></div></div> | ||
| 15 | <p> | ||
| 16 | The Yocto Project does most of the work for you when it comes to | ||
| 17 | creating | ||
| 18 | <a class="link" href="../ref-manual/cross-development-toolchain.html" target="_self">cross-development toolchains</a>. | ||
| 19 | This section provides some technical background on how | ||
| 20 | cross-development toolchains are created and used. | ||
| 21 | For more information on toolchains, you can also see the | ||
| 22 | <a class="link" href="../sdk-manual/index.html" target="_self">Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</a> | ||
| 23 | manual. | ||
| 24 | </p> | ||
| 25 | <p> | ||
| 26 | In the Yocto Project development environment, cross-development | ||
| 27 | toolchains are used to build the image and applications that run | ||
| 28 | on the target hardware. | ||
| 29 | With just a few commands, the OpenEmbedded build system creates | ||
| 30 | these necessary toolchains for you. | ||
| 31 | </p> | ||
| 32 | <p> | ||
| 33 | The following figure shows a high-level build environment regarding | ||
| 34 | toolchain construction and use. | ||
| 35 | </p> | ||
| 36 | <p> | ||
| 37 | </p> | ||
| 38 | <table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="720"><tr style="height: 540px"><td align="center"><img src="figures/cross-development-toolchains.png" align="middle" width="720"></td></tr></table> | ||
| 39 | <p> | ||
| 40 | </p> | ||
| 41 | <p> | ||
| 42 | Most of the work occurs on the Build Host. | ||
| 43 | This is the machine used to build images and generally work within the | ||
| 44 | the Yocto Project environment. | ||
| 45 | When you run BitBake to create an image, the OpenEmbedded build system | ||
| 46 | uses the host <code class="filename">gcc</code> compiler to bootstrap a | ||
| 47 | cross-compiler named <code class="filename">gcc-cross</code>. | ||
| 48 | The <code class="filename">gcc-cross</code> compiler is what BitBake uses to | ||
| 49 | compile source files when creating the target image. | ||
| 50 | You can think of <code class="filename">gcc-cross</code> simply as an | ||
| 51 | automatically generated cross-compiler that is used internally within | ||
| 52 | BitBake only. | ||
| 53 | </p> | ||
| 54 | <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"> | ||
| 55 | <h3 class="title">Note</h3> | ||
| 56 | The extensible SDK does not use | ||
| 57 | <code class="filename">gcc-cross-canadian</code> since this SDK | ||
| 58 | ships a copy of the OpenEmbedded build system and the sysroot | ||
| 59 | within it contains <code class="filename">gcc-cross</code>. | ||
| 60 | </div> | ||
| 61 | <p> | ||
| 62 | </p> | ||
| 63 | <p> | ||
| 64 | The chain of events that occurs when <code class="filename">gcc-cross</code> is | ||
| 65 | bootstrapped is as follows: | ||
| 66 | </p> | ||
| 67 | <pre class="literallayout"> | ||
| 68 | gcc -> binutils-cross -> gcc-cross-initial -> linux-libc-headers -> glibc-initial -> glibc -> gcc-cross -> gcc-runtime | ||
| 69 | </pre> | ||
| 70 | <p> | ||
| 71 | </p> | ||
| 72 | <div class="itemizedlist"><ul class="itemizedlist" type="disc"> | ||
| 73 | <li class="listitem"><p> | ||
| 74 | <code class="filename">gcc</code>: | ||
| 75 | The build host's GNU Compiler Collection (GCC). | ||
| 76 | </p></li> | ||
| 77 | <li class="listitem"><p> | ||
| 78 | <code class="filename">binutils-cross</code>: | ||
| 79 | The bare minimum binary utilities needed in order to run | ||
| 80 | the <code class="filename">gcc-cross-initial</code> phase of the | ||
| 81 | bootstrap operation. | ||
| 82 | </p></li> | ||
| 83 | <li class="listitem"><p> | ||
| 84 | <code class="filename">gcc-cross-initial</code>: | ||
| 85 | An early stage of the bootstrap process for creating | ||
| 86 | the cross-compiler. | ||
| 87 | This stage builds enough of the <code class="filename">gcc-cross</code>, | ||
| 88 | the C library, and other pieces needed to finish building the | ||
| 89 | final cross-compiler in later stages. | ||
| 90 | This tool is a "native" package (i.e. it is designed to run on | ||
| 91 | the build host). | ||
| 92 | </p></li> | ||
| 93 | <li class="listitem"><p> | ||
| 94 | <code class="filename">linux-libc-headers</code>: | ||
| 95 | Headers needed for the cross-compiler. | ||
| 96 | </p></li> | ||
| 97 | <li class="listitem"><p> | ||
| 98 | <code class="filename">glibc-initial</code>: | ||
| 99 | An initial version of the Embedded GLIBC needed to bootstrap | ||
| 100 | <code class="filename">glibc</code>. | ||
| 101 | </p></li> | ||
| 102 | <li class="listitem"> | ||
| 103 | <p> | ||
| 104 | <code class="filename">gcc-cross</code>: | ||
| 105 | The final stage of the bootstrap process for the | ||
| 106 | cross-compiler. | ||
| 107 | This stage results in the actual cross-compiler that | ||
| 108 | BitBake uses when it builds an image for a targeted | ||
| 109 | device. | ||
| 110 | </p> | ||
| 111 | <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"> | ||
| 112 | <h3 class="title">Note</h3> | ||
| 113 | If you are replacing this cross compiler toolchain | ||
| 114 | with a custom version, you must replace | ||
| 115 | <code class="filename">gcc-cross</code>. | ||
| 116 | </div> | ||
| 117 | <p> | ||
| 118 | This tool is also a "native" package (i.e. it is | ||
| 119 | designed to run on the build host). | ||
| 120 | </p> | ||
| 121 | </li> | ||
| 122 | <li class="listitem"><p> | ||
| 123 | <code class="filename">gcc-runtime</code>: | ||
| 124 | Runtime libraries resulting from the toolchain bootstrapping | ||
| 125 | process. | ||
| 126 | This tool produces a binary that consists of the | ||
| 127 | runtime libraries need for the targeted device. | ||
| 128 | </p></li> | ||
| 129 | </ul></div> | ||
| 130 | <p> | ||
| 131 | </p> | ||
| 132 | <p> | ||
| 133 | You can use the OpenEmbedded build system to build an installer for | ||
| 134 | the relocatable SDK used to develop applications. | ||
| 135 | When you run the installer, it installs the toolchain, which contains | ||
| 136 | the development tools (e.g., the | ||
| 137 | <code class="filename">gcc-cross-canadian</code>), | ||
| 138 | <code class="filename">binutils-cross-canadian</code>, and other | ||
| 139 | <code class="filename">nativesdk-*</code> tools, | ||
| 140 | which are tools native to the SDK (i.e. native to | ||
| 141 | <a class="link" href="../ref-manual/var-SDK_ARCH.html" target="_self"><code class="filename">SDK_ARCH</code></a>), | ||
| 142 | you need to cross-compile and test your software. | ||
| 143 | The figure shows the commands you use to easily build out this | ||
| 144 | toolchain. | ||
| 145 | This cross-development toolchain is built to execute on the | ||
| 146 | <a class="link" href="../ref-manual/var-SDKMACHINE.html" target="_self"><code class="filename">SDKMACHINE</code></a>, | ||
| 147 | which might or might not be the same | ||
| 148 | machine as the Build Host. | ||
| 149 | </p> | ||
| 150 | <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"> | ||
| 151 | <h3 class="title">Note</h3> | ||
| 152 | If your target architecture is supported by the Yocto Project, | ||
| 153 | you can take advantage of pre-built images that ship with the | ||
| 154 | Yocto Project and already contain cross-development toolchain | ||
| 155 | installers. | ||
| 156 | </div> | ||
| 157 | <p> | ||
| 158 | </p> | ||
| 159 | <p> | ||
| 160 | Here is the bootstrap process for the relocatable toolchain: | ||
| 161 | </p> | ||
| 162 | <pre class="literallayout"> | ||
| 163 | gcc -> binutils-crosssdk -> gcc-crosssdk-initial -> linux-libc-headers -> | ||
| 164 | glibc-initial -> nativesdk-glibc -> gcc-crosssdk -> gcc-cross-canadian | ||
| 165 | </pre> | ||
| 166 | <p> | ||
| 167 | </p> | ||
| 168 | <div class="itemizedlist"><ul class="itemizedlist" type="disc"> | ||
| 169 | <li class="listitem"><p> | ||
| 170 | <code class="filename">gcc</code>: | ||
| 171 | The build host's GNU Compiler Collection (GCC). | ||
| 172 | </p></li> | ||
| 173 | <li class="listitem"><p> | ||
| 174 | <code class="filename">binutils-crosssdk</code>: | ||
| 175 | The bare minimum binary utilities needed in order to run | ||
| 176 | the <code class="filename">gcc-crosssdk-initial</code> phase of the | ||
| 177 | bootstrap operation. | ||
| 178 | </p></li> | ||
| 179 | <li class="listitem"><p> | ||
| 180 | <code class="filename">gcc-crosssdk-initial</code>: | ||
| 181 | An early stage of the bootstrap process for creating | ||
| 182 | the cross-compiler. | ||
| 183 | This stage builds enough of the | ||
| 184 | <code class="filename">gcc-crosssdk</code> and supporting pieces so that | ||
| 185 | the final stage of the bootstrap process can produce the | ||
| 186 | finished cross-compiler. | ||
| 187 | This tool is a "native" binary that runs on the build host. | ||
| 188 | </p></li> | ||
| 189 | <li class="listitem"><p> | ||
| 190 | <code class="filename">linux-libc-headers</code>: | ||
| 191 | Headers needed for the cross-compiler. | ||
| 192 | </p></li> | ||
| 193 | <li class="listitem"><p> | ||
| 194 | <code class="filename">glibc-initial</code>: | ||
| 195 | An initial version of the Embedded GLIBC needed to bootstrap | ||
| 196 | <code class="filename">nativesdk-glibc</code>. | ||
| 197 | </p></li> | ||
| 198 | <li class="listitem"><p> | ||
| 199 | <code class="filename">nativesdk-glibc</code>: | ||
| 200 | The Embedded GLIBC needed to bootstrap the | ||
| 201 | <code class="filename">gcc-crosssdk</code>. | ||
| 202 | </p></li> | ||
| 203 | <li class="listitem"><p> | ||
| 204 | <code class="filename">gcc-crosssdk</code>: | ||
| 205 | The final stage of the bootstrap process for the | ||
| 206 | relocatable cross-compiler. | ||
| 207 | The <code class="filename">gcc-crosssdk</code> is a transitory compiler | ||
| 208 | and never leaves the build host. | ||
| 209 | Its purpose is to help in the bootstrap process to create the | ||
| 210 | eventual relocatable <code class="filename">gcc-cross-canadian</code> | ||
| 211 | compiler, which is relocatable. | ||
| 212 | This tool is also a "native" package (i.e. it is | ||
| 213 | designed to run on the build host). | ||
| 214 | </p></li> | ||
| 215 | <li class="listitem"><p> | ||
| 216 | <code class="filename">gcc-cross-canadian</code>: | ||
| 217 | The final relocatable cross-compiler. | ||
| 218 | When run on the | ||
| 219 | <a class="link" href="../ref-manual/var-SDKMACHINE.html" target="_self"><code class="filename">SDKMACHINE</code></a>, | ||
| 220 | this tool | ||
| 221 | produces executable code that runs on the target device. | ||
| 222 | Only one cross-canadian compiler is produced per architecture | ||
| 223 | since they can be targeted at different processor optimizations | ||
| 224 | using configurations passed to the compiler through the | ||
| 225 | compile commands. | ||
| 226 | This circumvents the need for multiple compilers and thus | ||
| 227 | reduces the size of the toolchains. | ||
| 228 | </p></li> | ||
| 229 | </ul></div> | ||
| 230 | <p> | ||
| 231 | </p> | ||
| 232 | <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"> | ||
| 233 | <h3 class="title">Note</h3> | ||
| 234 | For information on advantages gained when building a | ||
| 235 | cross-development toolchain installer, see the | ||
| 236 | "<a class="link" href="../sdk-manual/sdk-building-an-sdk-installer.html" target="_self">Building an SDK Installer</a>" | ||
| 237 | section in the Yocto Project Application Development and the | ||
| 238 | Extensible Software Development Kit (eSDK) manual. | ||
| 239 | </div> | ||
| 240 | </div></body> | ||
| 241 | </html> | ||
diff --git a/documentation/getting-started/eclipse/html/getting-started/development-concepts.html b/documentation/getting-started/eclipse/html/getting-started/development-concepts.html new file mode 100644 index 0000000000..ccfb73189a --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/development-concepts.html | |||
| @@ -0,0 +1,66 @@ | |||
| 1 | <html> | ||
| 2 | <head> | ||
| 3 | <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> | ||
| 4 | <title>2.8.Development Concepts</title> | ||
| 5 | <link rel="stylesheet" type="text/css" href="../book.css"> | ||
| 6 | <meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> | ||
| 7 | <link rel="home" href="index.html" title="Getting Started With Yocto Project"> | ||
| 8 | <link rel="up" href="overview-development-environment.html" title="Chapter2.The Yocto Project Development Environment"> | ||
| 9 | <link rel="prev" href="recipe-syntax.html" title="2.7.Recipe Syntax"> | ||
| 10 | <link rel="next" href="user-configuration.html" title="2.8.1.User Configuration"> | ||
| 11 | </head> | ||
| 12 | <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="2.8.Development Concepts"> | ||
| 13 | <div class="titlepage"><div><div><h2 class="title" style="clear: both"> | ||
| 14 | <a name="development-concepts"></a>2.8.Development Concepts</h2></div></div></div> | ||
| 15 | <p> | ||
| 16 | This section takes a more detailed look inside the development | ||
| 17 | process. | ||
| 18 | The following diagram represents development at a high level. | ||
| 19 | The remainder of this chapter expands on the fundamental input, output, | ||
| 20 | process, and | ||
| 21 | <a class="link" href="../ref-manual/metadata.html" target="_self">Metadata</a>) blocks | ||
| 22 | that make up development in the Yocto Project environment. | ||
| 23 | </p> | ||
| 24 | <p><a name="general-yocto-environment-figure"></a> | ||
| 25 | </p> | ||
| 26 | <table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="720"><tr style="height: 383px"><td align="center"><img src="figures/yocto-environment-ref.png" align="middle" height="383"></td></tr></table> | ||
| 27 | <p> | ||
| 28 | </p> | ||
| 29 | <p> | ||
| 30 | In general, development consists of several functional areas: | ||
| 31 | </p> | ||
| 32 | <div class="itemizedlist"><ul class="itemizedlist" type="disc"> | ||
| 33 | <li class="listitem"><p><span class="emphasis"><em>User Configuration:</em></span> | ||
| 34 | Metadata you can use to control the build process. | ||
| 35 | </p></li> | ||
| 36 | <li class="listitem"><p><span class="emphasis"><em>Metadata Layers:</em></span> | ||
| 37 | Various layers that provide software, machine, and | ||
| 38 | distro Metadata.</p></li> | ||
| 39 | <li class="listitem"><p><span class="emphasis"><em>Source Files:</em></span> | ||
| 40 | Upstream releases, local projects, and SCMs.</p></li> | ||
| 41 | <li class="listitem"><p><span class="emphasis"><em>Build System:</em></span> | ||
| 42 | Processes under the control of | ||
| 43 | <a class="link" href="../ref-manual/bitbake-term.html" target="_self">BitBake</a>. | ||
| 44 | This block expands on how BitBake fetches source, applies | ||
| 45 | patches, completes compilation, analyzes output for package | ||
| 46 | generation, creates and tests packages, generates images, and | ||
| 47 | generates cross-development tools.</p></li> | ||
| 48 | <li class="listitem"><p><span class="emphasis"><em>Package Feeds:</em></span> | ||
| 49 | Directories containing output packages (RPM, DEB or IPK), | ||
| 50 | which are subsequently used in the construction of an image or | ||
| 51 | SDK, produced by the build system. | ||
| 52 | These feeds can also be copied and shared using a web server or | ||
| 53 | other means to facilitate extending or updating existing | ||
| 54 | images on devices at runtime if runtime package management is | ||
| 55 | enabled.</p></li> | ||
| 56 | <li class="listitem"><p><span class="emphasis"><em>Images:</em></span> | ||
| 57 | Images produced by the development process. | ||
| 58 | </p></li> | ||
| 59 | <li class="listitem"><p><span class="emphasis"><em>Application Development SDK:</em></span> | ||
| 60 | Cross-development tools that are produced along with an image | ||
| 61 | or separately with BitBake.</p></li> | ||
| 62 | </ul></div> | ||
| 63 | <p> | ||
| 64 | </p> | ||
| 65 | </div></body> | ||
| 66 | </html> | ||
diff --git a/documentation/getting-started/eclipse/html/getting-started/distro-layer.html b/documentation/getting-started/eclipse/html/getting-started/distro-layer.html new file mode 100644 index 0000000000..da6da55986 --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/distro-layer.html | |||
| @@ -0,0 +1,60 @@ | |||
| 1 | <html> | ||
| 2 | <head> | ||
| 3 | <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> | ||
| 4 | <title>2.8.2.1.Distro Layer</title> | ||
| 5 | <link rel="stylesheet" type="text/css" href="../book.css"> | ||
| 6 | <meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> | ||
| 7 | <link rel="home" href="index.html" title="Getting Started With Yocto Project"> | ||
| 8 | <link rel="up" href="metadata-machine-configuration-and-policy-configuration.html" title="2.8.2.Metadata, Machine Configuration, and Policy Configuration"> | ||
| 9 | <link rel="prev" href="metadata-machine-configuration-and-policy-configuration.html" title="2.8.2.Metadata, Machine Configuration, and Policy Configuration"> | ||
| 10 | <link rel="next" href="bsp-layer.html" title="2.8.2.2.BSP Layer"> | ||
| 11 | </head> | ||
| 12 | <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="2.8.2.1.Distro Layer"> | ||
| 13 | <div class="titlepage"><div><div><h4 class="title"> | ||
| 14 | <a name="distro-layer"></a>2.8.2.1.Distro Layer</h4></div></div></div> | ||
| 15 | <p> | ||
| 16 | The distribution layer provides policy configurations for your | ||
| 17 | distribution. | ||
| 18 | Best practices dictate that you isolate these types of | ||
| 19 | configurations into their own layer. | ||
| 20 | Settings you provide in | ||
| 21 | <code class="filename">conf/distro/<em class="replaceable"><code>distro</code></em>.conf</code> override | ||
| 22 | similar | ||
| 23 | settings that BitBake finds in your | ||
| 24 | <code class="filename">conf/local.conf</code> file in the Build | ||
| 25 | Directory. | ||
| 26 | </p> | ||
| 27 | <p> | ||
| 28 | The following list provides some explanation and references | ||
| 29 | for what you typically find in the distribution layer: | ||
| 30 | </p> | ||
| 31 | <div class="itemizedlist"><ul class="itemizedlist" type="disc"> | ||
| 32 | <li class="listitem"><p><span class="emphasis"><em>classes:</em></span> | ||
| 33 | Class files (<code class="filename">.bbclass</code>) hold | ||
| 34 | common functionality that can be shared among | ||
| 35 | recipes in the distribution. | ||
| 36 | When your recipes inherit a class, they take on the | ||
| 37 | settings and functions for that class. | ||
| 38 | You can read more about class files in the | ||
| 39 | "<a class="link" href="../ref-manual/ref-classes.html" target="_self">Classes</a>" | ||
| 40 | section of the Yocto Reference Manual. | ||
| 41 | </p></li> | ||
| 42 | <li class="listitem"><p><span class="emphasis"><em>conf:</em></span> | ||
| 43 | This area holds configuration files for the | ||
| 44 | layer (<code class="filename">conf/layer.conf</code>), | ||
| 45 | the distribution | ||
| 46 | (<code class="filename">conf/distro/<em class="replaceable"><code>distro</code></em>.conf</code>), | ||
| 47 | and any distribution-wide include files. | ||
| 48 | </p></li> | ||
| 49 | <li class="listitem"><p><span class="emphasis"><em>recipes-*:</em></span> | ||
| 50 | Recipes and append files that affect common | ||
| 51 | functionality across the distribution. | ||
| 52 | This area could include recipes and append files | ||
| 53 | to add distribution-specific configuration, | ||
| 54 | initialization scripts, custom image recipes, | ||
| 55 | and so forth.</p></li> | ||
| 56 | </ul></div> | ||
| 57 | <p> | ||
| 58 | </p> | ||
| 59 | </div></body> | ||
| 60 | </html> | ||
diff --git a/documentation/getting-started/eclipse/html/getting-started/enable-building.html b/documentation/getting-started/eclipse/html/getting-started/enable-building.html new file mode 100644 index 0000000000..af70491f97 --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/enable-building.html | |||
| @@ -0,0 +1,37 @@ | |||
| 1 | <html> | ||
| 2 | <head> | ||
| 3 | <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> | ||
| 4 | <title>3.6.2.1.Building</title> | ||
| 5 | <link rel="stylesheet" type="text/css" href="../book.css"> | ||
| 6 | <meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> | ||
| 7 | <link rel="home" href="index.html" title="Getting Started With Yocto Project"> | ||
| 8 | <link rel="up" href="enabling-wayland-in-an-image.html" title="3.6.2.Enabling Wayland in an Image"> | ||
| 9 | <link rel="prev" href="enabling-wayland-in-an-image.html" title="3.6.2.Enabling Wayland in an Image"> | ||
| 10 | <link rel="next" href="enable-installation-in-an-image.html" title="3.6.2.2.Installing"> | ||
| 11 | </head> | ||
| 12 | <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="3.6.2.1.Building"> | ||
| 13 | <div class="titlepage"><div><div><h4 class="title"> | ||
| 14 | <a name="enable-building"></a>3.6.2.1.Building</h4></div></div></div> | ||
| 15 | <p> | ||
| 16 | To cause Mesa to build the <code class="filename">wayland-egl</code> | ||
| 17 | platform and Weston to build Wayland with Kernel Mode | ||
| 18 | Setting | ||
| 19 | (<a class="ulink" href="https://wiki.archlinux.org/index.php/Kernel_Mode_Setting" target="_self">KMS</a>) | ||
| 20 | support, include the "wayland" flag in the | ||
| 21 | <a class="link" href="../ref-manual/var-DISTRO_FEATURES.html" target="_self"><code class="filename">DISTRO_FEATURES</code></a> | ||
| 22 | statement in your <code class="filename">local.conf</code> file: | ||
| 23 | </p> | ||
| 24 | <pre class="literallayout"> | ||
| 25 | DISTRO_FEATURES_append = " wayland" | ||
| 26 | </pre> | ||
| 27 | <p> | ||
| 28 | </p> | ||
| 29 | <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"> | ||
| 30 | <h3 class="title">Note</h3> | ||
| 31 | If X11 has been enabled elsewhere, Weston will build | ||
| 32 | Wayland with X11 support | ||
| 33 | </div> | ||
| 34 | <p> | ||
| 35 | </p> | ||
| 36 | </div></body> | ||
| 37 | </html> | ||
diff --git a/documentation/getting-started/eclipse/html/getting-started/enable-installation-in-an-image.html b/documentation/getting-started/eclipse/html/getting-started/enable-installation-in-an-image.html new file mode 100644 index 0000000000..490f1d1036 --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/enable-installation-in-an-image.html | |||
| @@ -0,0 +1,27 @@ | |||
| 1 | <html> | ||
| 2 | <head> | ||
| 3 | <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> | ||
| 4 | <title>3.6.2.2.Installing</title> | ||
| 5 | <link rel="stylesheet" type="text/css" href="../book.css"> | ||
| 6 | <meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> | ||
| 7 | <link rel="home" href="index.html" title="Getting Started With Yocto Project"> | ||
| 8 | <link rel="up" href="enabling-wayland-in-an-image.html" title="3.6.2.Enabling Wayland in an Image"> | ||
| 9 | <link rel="prev" href="enable-building.html" title="3.6.2.1.Building"> | ||
| 10 | <link rel="next" href="running-weston.html" title="3.6.3.Running Weston"> | ||
| 11 | </head> | ||
| 12 | <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="3.6.2.2.Installing"> | ||
| 13 | <div class="titlepage"><div><div><h4 class="title"> | ||
| 14 | <a name="enable-installation-in-an-image"></a>3.6.2.2.Installing</h4></div></div></div> | ||
| 15 | <p> | ||
| 16 | To install the Wayland feature into an image, you must | ||
| 17 | include the following | ||
| 18 | <a class="link" href="../ref-manual/var-CORE_IMAGE_EXTRA_INSTALL.html" target="_self"><code class="filename">CORE_IMAGE_EXTRA_INSTALL</code></a> | ||
| 19 | statement in your <code class="filename">local.conf</code> file: | ||
| 20 | </p> | ||
| 21 | <pre class="literallayout"> | ||
| 22 | CORE_IMAGE_EXTRA_INSTALL += "wayland weston" | ||
| 23 | </pre> | ||
| 24 | <p> | ||
| 25 | </p> | ||
| 26 | </div></body> | ||
| 27 | </html> | ||
diff --git a/documentation/getting-started/eclipse/html/getting-started/enabling-commercially-licensed-recipes.html b/documentation/getting-started/eclipse/html/getting-started/enabling-commercially-licensed-recipes.html new file mode 100644 index 0000000000..1a31d0e6b1 --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/enabling-commercially-licensed-recipes.html | |||
| @@ -0,0 +1,91 @@ | |||
| 1 | <html> | ||
| 2 | <head> | ||
| 3 | <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> | ||
| 4 | <title>3.7.2.Enabling Commercially Licensed Recipes</title> | ||
| 5 | <link rel="stylesheet" type="text/css" href="../book.css"> | ||
| 6 | <meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> | ||
| 7 | <link rel="home" href="index.html" title="Getting Started With Yocto Project"> | ||
| 8 | <link rel="up" href="overview-licenses.html" title="3.7.Licenses"> | ||
| 9 | <link rel="prev" href="usingpoky-LIC_FILES_CHKSUM-explanation-of-syntax.html" title="3.7.1.2.Explanation of Syntax"> | ||
| 10 | <link rel="next" href="license-flag-matching.html" title="3.7.2.1.License Flag Matching"> | ||
| 11 | </head> | ||
| 12 | <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="3.7.2.Enabling Commercially Licensed Recipes"> | ||
| 13 | <div class="titlepage"><div><div><h3 class="title"> | ||
| 14 | <a name="enabling-commercially-licensed-recipes"></a>3.7.2.Enabling Commercially Licensed Recipes</h3></div></div></div> | ||
| 15 | <p> | ||
| 16 | By default, the OpenEmbedded build system disables | ||
| 17 | components that have commercial or other special licensing | ||
| 18 | requirements. | ||
| 19 | Such requirements are defined on a | ||
| 20 | recipe-by-recipe basis through the | ||
| 21 | <a class="link" href="../ref-manual/var-LICENSE_FLAGS.html" target="_self"><code class="filename">LICENSE_FLAGS</code></a> | ||
| 22 | variable definition in the affected recipe. | ||
| 23 | For instance, the | ||
| 24 | <code class="filename">poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly</code> | ||
| 25 | recipe contains the following statement: | ||
| 26 | </p> | ||
| 27 | <pre class="literallayout"> | ||
| 28 | LICENSE_FLAGS = "commercial" | ||
| 29 | </pre> | ||
| 30 | <p> | ||
| 31 | Here is a slightly more complicated example that contains both | ||
| 32 | an explicit recipe name and version (after variable expansion): | ||
| 33 | </p> | ||
| 34 | <pre class="literallayout"> | ||
| 35 | LICENSE_FLAGS = "license_${PN}_${PV}" | ||
| 36 | </pre> | ||
| 37 | <p> | ||
| 38 | In order for a component restricted by a | ||
| 39 | <code class="filename">LICENSE_FLAGS</code> definition to be enabled and | ||
| 40 | included in an image, it needs to have a matching entry in the | ||
| 41 | global | ||
| 42 | <a class="link" href="../ref-manual/var-LICENSE_FLAGS_WHITELIST.html" target="_self"><code class="filename">LICENSE_FLAGS_WHITELIST</code></a> | ||
| 43 | variable, which is a variable typically defined in your | ||
| 44 | <code class="filename">local.conf</code> file. | ||
| 45 | For example, to enable the | ||
| 46 | <code class="filename">poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly</code> | ||
| 47 | package, you could add either the string | ||
| 48 | "commercial_gst-plugins-ugly" or the more general string | ||
| 49 | "commercial" to <code class="filename">LICENSE_FLAGS_WHITELIST</code>. | ||
| 50 | See the | ||
| 51 | "<a class="link" href="license-flag-matching.html" title="3.7.2.1.License Flag Matching">License Flag Matching</a>" | ||
| 52 | section for a full | ||
| 53 | explanation of how <code class="filename">LICENSE_FLAGS</code> matching | ||
| 54 | works. | ||
| 55 | Here is the example: | ||
| 56 | </p> | ||
| 57 | <pre class="literallayout"> | ||
| 58 | LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly" | ||
| 59 | </pre> | ||
| 60 | <p> | ||
| 61 | Likewise, to additionally enable the package built from the | ||
| 62 | recipe containing | ||
| 63 | <code class="filename">LICENSE_FLAGS = "license_${PN}_${PV}"</code>, | ||
| 64 | and assuming that the actual recipe name was | ||
| 65 | <code class="filename">emgd_1.10.bb</code>, the following string would | ||
| 66 | enable that package as well as the original | ||
| 67 | <code class="filename">gst-plugins-ugly</code> package: | ||
| 68 | </p> | ||
| 69 | <pre class="literallayout"> | ||
| 70 | LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly license_emgd_1.10" | ||
| 71 | </pre> | ||
| 72 | <p> | ||
| 73 | As a convenience, you do not need to specify the complete | ||
| 74 | license string in the whitelist for every package. | ||
| 75 | You can use an abbreviated form, which consists | ||
| 76 | of just the first portion or portions of the license | ||
| 77 | string before the initial underscore character or characters. | ||
| 78 | A partial string will match any license that contains the | ||
| 79 | given string as the first portion of its license. | ||
| 80 | For example, the following whitelist string will also match | ||
| 81 | both of the packages previously mentioned as well as any other | ||
| 82 | packages that have licenses starting with "commercial" or | ||
| 83 | "license". | ||
| 84 | </p> | ||
| 85 | <pre class="literallayout"> | ||
| 86 | LICENSE_FLAGS_WHITELIST = "commercial license" | ||
| 87 | </pre> | ||
| 88 | <p> | ||
| 89 | </p> | ||
| 90 | </div></body> | ||
| 91 | </html> | ||
diff --git a/documentation/getting-started/eclipse/html/getting-started/enabling-wayland-in-an-image.html b/documentation/getting-started/eclipse/html/getting-started/enabling-wayland-in-an-image.html new file mode 100644 index 0000000000..6a325dbfd2 --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/enabling-wayland-in-an-image.html | |||
| @@ -0,0 +1,20 @@ | |||
| 1 | <html> | ||
| 2 | <head> | ||
| 3 | <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> | ||
| 4 | <title>3.6.2.Enabling Wayland in an Image</title> | ||
| 5 | <link rel="stylesheet" type="text/css" href="../book.css"> | ||
| 6 | <meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> | ||
| 7 | <link rel="home" href="index.html" title="Getting Started With Yocto Project"> | ||
| 8 | <link rel="up" href="wayland.html" title="3.6.Wayland"> | ||
| 9 | <link rel="prev" href="wayland-support.html" title="3.6.1.Support"> | ||
| 10 | <link rel="next" href="enable-building.html" title="3.6.2.1.Building"> | ||
| 11 | </head> | ||
| 12 | <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="3.6.2.Enabling Wayland in an Image"> | ||
| 13 | <div class="titlepage"><div><div><h3 class="title"> | ||
| 14 | <a name="enabling-wayland-in-an-image"></a>3.6.2.Enabling Wayland in an Image</h3></div></div></div> | ||
| 15 | <p> | ||
| 16 | To enable Wayland, you need to enable it to be built and enable | ||
| 17 | it to be included in the image. | ||
| 18 | </p> | ||
| 19 | </div></body> | ||
| 20 | </html> | ||
diff --git a/documentation/getting-started/eclipse/html/getting-started/fakeroot-and-pseudo.html b/documentation/getting-started/eclipse/html/getting-started/fakeroot-and-pseudo.html new file mode 100644 index 0000000000..8354ad6730 --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/fakeroot-and-pseudo.html | |||
| @@ -0,0 +1,91 @@ | |||
| 1 | <html> | ||
| 2 | <head> | ||
| 3 | <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> | ||
| 4 | <title>3.5.Fakeroot and Pseudo</title> | ||
| 5 | <link rel="stylesheet" type="text/css" href="../book.css"> | ||
| 6 | <meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> | ||
| 7 | <link rel="home" href="index.html" title="Getting Started With Yocto Project"> | ||
| 8 | <link rel="up" href="overview-concepts.html" title="Chapter3.Yocto Project Concepts"> | ||
| 9 | <link rel="prev" href="automatically-added-runtime-dependencies.html" title="3.4.Automatically Added Runtime Dependencies"> | ||
| 10 | <link rel="next" href="wayland.html" title="3.6.Wayland"> | ||
| 11 | </head> | ||
| 12 | <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="3.5.Fakeroot and Pseudo"> | ||
| 13 | <div class="titlepage"><div><div><h2 class="title" style="clear: both"> | ||
| 14 | <a name="fakeroot-and-pseudo"></a>3.5.Fakeroot and Pseudo</h2></div></div></div> | ||
| 15 | <p> | ||
| 16 | Some tasks are easier to implement when allowed to perform certain | ||
| 17 | operations that are normally reserved for the root user (e.g. | ||
| 18 | <a class="link" href="../ref-manual/ref-tasks-install.html" target="_self"><code class="filename">do_install</code></a>, | ||
| 19 | <a class="link" href="../ref-manual/ref-tasks-package_write_deb.html" target="_self"><code class="filename">do_package_write*</code></a>, | ||
| 20 | <a class="link" href="../ref-manual/ref-tasks-rootfs.html" target="_self"><code class="filename">do_rootfs</code></a>, | ||
| 21 | and | ||
| 22 | <a class="link" href="../ref-manual/ref-tasks-image.html" target="_self"><code class="filename">do_image*</code></a>). | ||
| 23 | For example, the <code class="filename">do_install</code> task benefits | ||
| 24 | from being able to set the UID and GID of installed files to | ||
| 25 | arbitrary values. | ||
| 26 | </p> | ||
| 27 | <p> | ||
| 28 | One approach to allowing tasks to perform root-only operations | ||
| 29 | would be to require BitBake to run as root. | ||
| 30 | However, this method is cumbersome and has security issues. | ||
| 31 | The approach that is actually used is to run tasks that benefit | ||
| 32 | from root privileges in a "fake" root environment. | ||
| 33 | Within this environment, the task and its child processes believe | ||
| 34 | that they are running as the root user, and see an internally | ||
| 35 | consistent view of the filesystem. | ||
| 36 | As long as generating the final output (e.g. a package or an image) | ||
| 37 | does not require root privileges, the fact that some earlier | ||
| 38 | steps ran in a fake root environment does not cause problems. | ||
| 39 | </p> | ||
| 40 | <p> | ||
| 41 | The capability to run tasks in a fake root environment is known as | ||
| 42 | "<a class="ulink" href="http://man.he.net/man1/fakeroot" target="_self">fakeroot</a>", | ||
| 43 | which is derived from the BitBake keyword/variable | ||
| 44 | flag that requests a fake root environment for a task. | ||
| 45 | </p> | ||
| 46 | <p> | ||
| 47 | In the OpenEmbedded build system, the program that implements | ||
| 48 | fakeroot is known as Pseudo. | ||
| 49 | Pseudo overrides system calls by using the environment variable | ||
| 50 | <code class="filename">LD_PRELOAD</code>, which results in the illusion | ||
| 51 | of running as root. | ||
| 52 | To keep track of "fake" file ownership and permissions resulting | ||
| 53 | from operations that require root permissions, Pseudo uses | ||
| 54 | an SQLite 3 database. | ||
| 55 | This database is stored in | ||
| 56 | <code class="filename">${</code><a class="link" href="../ref-manual/var-WORKDIR.html" target="_self"><code class="filename">WORKDIR</code></a><code class="filename">}/pseudo/files.db</code> | ||
| 57 | for individual recipes. | ||
| 58 | Storing the database in a file as opposed to in memory | ||
| 59 | gives persistence between tasks and builds, which is not | ||
| 60 | accomplished using fakeroot. | ||
| 61 | </p> | ||
| 62 | <div class="note" title="Caution" style="margin-left: 0.5in; margin-right: 0.5in;"> | ||
| 63 | <h3 class="title">Caution</h3> | ||
| 64 | If you add your own task that manipulates the same files or | ||
| 65 | directories as a fakeroot task, then that task also needs to | ||
| 66 | run under fakeroot. | ||
| 67 | Otherwise, the task cannot run root-only operations, and | ||
| 68 | cannot see the fake file ownership and permissions set by the | ||
| 69 | other task. | ||
| 70 | You need to also add a dependency on | ||
| 71 | <code class="filename">virtual/fakeroot-native:do_populate_sysroot</code>, | ||
| 72 | giving the following: | ||
| 73 | <pre class="literallayout"> | ||
| 74 | fakeroot do_mytask () { | ||
| 75 | ... | ||
| 76 | } | ||
| 77 | do_mytask[depends] += "virtual/fakeroot-native:do_populate_sysroot" | ||
| 78 | </pre> | ||
| 79 | </div> | ||
| 80 | <p> | ||
| 81 | For more information, see the | ||
| 82 | <a class="link" href="../bitbake-user-manual/var-FAKEROOT.html" target="_self"><code class="filename">FAKEROOT*</code></a> | ||
| 83 | variables in the BitBake User Manual. | ||
| 84 | You can also reference the | ||
| 85 | "<a class="ulink" href="http://www.ibm.com/developerworks/opensource/library/os-aapseudo1/index.html" target="_self">Pseudo</a>" | ||
| 86 | and | ||
| 87 | "<a class="ulink" href="https://github.com/wrpseudo/pseudo/wiki/WhyNotFakeroot" target="_self">Why Not Fakeroot?</a>" | ||
| 88 | articles for background information on Pseudo. | ||
| 89 | </p> | ||
| 90 | </div></body> | ||
| 91 | </html> | ||
diff --git a/documentation/getting-started/eclipse/html/getting-started/figures/YP-flow-diagram.png b/documentation/getting-started/eclipse/html/getting-started/figures/YP-flow-diagram.png new file mode 100644 index 0000000000..8264410504 --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/figures/YP-flow-diagram.png | |||
| Binary files differ | |||
diff --git a/documentation/getting-started/eclipse/html/getting-started/figures/analysis-for-package-splitting.png b/documentation/getting-started/eclipse/html/getting-started/figures/analysis-for-package-splitting.png new file mode 100644 index 0000000000..04f2794ea9 --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/figures/analysis-for-package-splitting.png | |||
| Binary files differ | |||
diff --git a/documentation/getting-started/eclipse/html/getting-started/figures/configuration-compile-autoreconf.png b/documentation/getting-started/eclipse/html/getting-started/figures/configuration-compile-autoreconf.png new file mode 100644 index 0000000000..a07464f04c --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/figures/configuration-compile-autoreconf.png | |||
| Binary files differ | |||
diff --git a/documentation/getting-started/eclipse/html/getting-started/figures/cross-development-toolchains.png b/documentation/getting-started/eclipse/html/getting-started/figures/cross-development-toolchains.png new file mode 100644 index 0000000000..d36670a198 --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/figures/cross-development-toolchains.png | |||
| Binary files differ | |||
diff --git a/documentation/getting-started/eclipse/html/getting-started/figures/getting-started-title.png b/documentation/getting-started/eclipse/html/getting-started/figures/getting-started-title.png new file mode 100644 index 0000000000..f38b078ab7 --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/figures/getting-started-title.png | |||
| Binary files differ | |||
diff --git a/documentation/getting-started/eclipse/html/getting-started/figures/git-workflow.png b/documentation/getting-started/eclipse/html/getting-started/figures/git-workflow.png new file mode 100644 index 0000000000..e401330a12 --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/figures/git-workflow.png | |||
| Binary files differ | |||
diff --git a/documentation/getting-started/eclipse/html/getting-started/figures/image-generation.png b/documentation/getting-started/eclipse/html/getting-started/figures/image-generation.png new file mode 100644 index 0000000000..71a48dc6f4 --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/figures/image-generation.png | |||
| Binary files differ | |||
diff --git a/documentation/getting-started/eclipse/html/getting-started/figures/images.png b/documentation/getting-started/eclipse/html/getting-started/figures/images.png new file mode 100644 index 0000000000..d99eac1fbf --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/figures/images.png | |||
| Binary files differ | |||
diff --git a/documentation/getting-started/eclipse/html/getting-started/figures/index-downloads.png b/documentation/getting-started/eclipse/html/getting-started/figures/index-downloads.png new file mode 100644 index 0000000000..96303b8781 --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/figures/index-downloads.png | |||
| Binary files differ | |||
diff --git a/documentation/getting-started/eclipse/html/getting-started/figures/layer-input.png b/documentation/getting-started/eclipse/html/getting-started/figures/layer-input.png new file mode 100644 index 0000000000..0a4f2e74f3 --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/figures/layer-input.png | |||
| Binary files differ | |||
diff --git a/documentation/getting-started/eclipse/html/getting-started/figures/package-feeds.png b/documentation/getting-started/eclipse/html/getting-started/figures/package-feeds.png new file mode 100644 index 0000000000..37c9c32506 --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/figures/package-feeds.png | |||
| Binary files differ | |||
diff --git a/documentation/getting-started/eclipse/html/getting-started/figures/patching.png b/documentation/getting-started/eclipse/html/getting-started/figures/patching.png new file mode 100644 index 0000000000..8ecd018502 --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/figures/patching.png | |||
| Binary files differ | |||
diff --git a/documentation/getting-started/eclipse/html/getting-started/figures/sdk-generation.png b/documentation/getting-started/eclipse/html/getting-started/figures/sdk-generation.png new file mode 100755 index 0000000000..adbe1f4acf --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/figures/sdk-generation.png | |||
| Binary files differ | |||
diff --git a/documentation/getting-started/eclipse/html/getting-started/figures/sdk.png b/documentation/getting-started/eclipse/html/getting-started/figures/sdk.png new file mode 100644 index 0000000000..5c36b7548b --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/figures/sdk.png | |||
| Binary files differ | |||
diff --git a/documentation/getting-started/eclipse/html/getting-started/figures/source-fetching.png b/documentation/getting-started/eclipse/html/getting-started/figures/source-fetching.png new file mode 100644 index 0000000000..26aefb50c2 --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/figures/source-fetching.png | |||
| Binary files differ | |||
diff --git a/documentation/getting-started/eclipse/html/getting-started/figures/source-input.png b/documentation/getting-started/eclipse/html/getting-started/figures/source-input.png new file mode 100644 index 0000000000..f7515058ef --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/figures/source-input.png | |||
| Binary files differ | |||
diff --git a/documentation/getting-started/eclipse/html/getting-started/figures/source-repos.png b/documentation/getting-started/eclipse/html/getting-started/figures/source-repos.png new file mode 100644 index 0000000000..603300b6d2 --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/figures/source-repos.png | |||
| Binary files differ | |||
diff --git a/documentation/getting-started/eclipse/html/getting-started/figures/user-configuration.png b/documentation/getting-started/eclipse/html/getting-started/figures/user-configuration.png new file mode 100644 index 0000000000..c298401fc3 --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/figures/user-configuration.png | |||
| Binary files differ | |||
diff --git a/documentation/getting-started/eclipse/html/getting-started/figures/yocto-environment-ref.png b/documentation/getting-started/eclipse/html/getting-started/figures/yocto-environment-ref.png new file mode 100644 index 0000000000..650c6c8030 --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/figures/yocto-environment-ref.png | |||
| Binary files differ | |||
diff --git a/documentation/getting-started/eclipse/html/getting-started/figures/yp-download.png b/documentation/getting-started/eclipse/html/getting-started/figures/yp-download.png new file mode 100644 index 0000000000..5770be6883 --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/figures/yp-download.png | |||
| Binary files differ | |||
diff --git a/documentation/getting-started/eclipse/html/getting-started/git.html b/documentation/getting-started/eclipse/html/getting-started/git.html new file mode 100644 index 0000000000..7e652a4efa --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/git.html | |||
| @@ -0,0 +1,51 @@ | |||
| 1 | <html> | ||
| 2 | <head> | ||
| 3 | <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> | ||
| 4 | <title>2.4.Git</title> | ||
| 5 | <link rel="stylesheet" type="text/css" href="../book.css"> | ||
| 6 | <meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> | ||
| 7 | <link rel="home" href="index.html" title="Getting Started With Yocto Project"> | ||
| 8 | <link rel="up" href="overview-development-environment.html" title="Chapter2.The Yocto Project Development Environment"> | ||
| 9 | <link rel="prev" href="workflows.html" title="2.3.Workflows"> | ||
| 10 | <link rel="next" href="repositories-tags-and-branches.html" title="2.4.1.Repositories, Tags, and Branches"> | ||
| 11 | </head> | ||
| 12 | <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="2.4.Git"> | ||
| 13 | <div class="titlepage"><div><div><h2 class="title" style="clear: both"> | ||
| 14 | <a name="git"></a>2.4.Git</h2></div></div></div> | ||
| 15 | <p> | ||
| 16 | The Yocto Project makes extensive use of Git, which is a | ||
| 17 | free, open source distributed version control system. | ||
| 18 | Git supports distributed development, non-linear development, | ||
| 19 | and can handle large projects. | ||
| 20 | It is best that you have some fundamental understanding | ||
| 21 | of how Git tracks projects and how to work with Git if | ||
| 22 | you are going to use the Yocto Project for development. | ||
| 23 | This section provides a quick overview of how Git works and | ||
| 24 | provides you with a summary of some essential Git commands. | ||
| 25 | </p> | ||
| 26 | <div class="note" title="Notes" style="margin-left: 0.5in; margin-right: 0.5in;"> | ||
| 27 | <h3 class="title">Notes</h3> | ||
| 28 | <div class="itemizedlist"><ul class="itemizedlist" type="disc"> | ||
| 29 | <li class="listitem"><p> | ||
| 30 | For more information on Git, see | ||
| 31 | <a class="ulink" href="http://git-scm.com/documentation" target="_self">http://git-scm.com/documentation</a>. | ||
| 32 | </p></li> | ||
| 33 | <li class="listitem"><p> | ||
| 34 | If you need to download Git, it is recommended that you add | ||
| 35 | Git to your system through your distribution's "software | ||
| 36 | store" (e.g. for Ubuntu, use the Ubuntu Software feature). | ||
| 37 | For the Git download page, see | ||
| 38 | <a class="ulink" href="http://git-scm.com/download" target="_self">http://git-scm.com/download</a>. | ||
| 39 | </p></li> | ||
| 40 | <li class="listitem"><p> | ||
| 41 | For examples beyond the limited few in this section on how | ||
| 42 | to use Git with the Yocto Project, see the | ||
| 43 | "<a class="link" href="../dev-manual/working-with-yocto-project-source-files.html" target="_self">Working With Yocto Project Source Files</a>" | ||
| 44 | section in the Yocto Project Development Tasks Manual. | ||
| 45 | </p></li> | ||
| 46 | </ul></div> | ||
| 47 | </div> | ||
| 48 | <p> | ||
| 49 | </p> | ||
| 50 | </div></body> | ||
| 51 | </html> | ||
diff --git a/documentation/getting-started/eclipse/html/getting-started/image-generation-dev-environment.html b/documentation/getting-started/eclipse/html/getting-started/image-generation-dev-environment.html new file mode 100644 index 0000000000..9f682d082c --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/image-generation-dev-environment.html | |||
| @@ -0,0 +1,178 @@ | |||
| 1 | <html> | ||
| 2 | <head> | ||
| 3 | <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> | ||
| 4 | <title>2.8.5.5.Image Generation</title> | ||
| 5 | <link rel="stylesheet" type="text/css" href="../book.css"> | ||
| 6 | <meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> | ||
| 7 | <link rel="home" href="index.html" title="Getting Started With Yocto Project"> | ||
| 8 | <link rel="up" href="bitbake-dev-environment.html" title="2.8.5.BitBake"> | ||
| 9 | <link rel="prev" href="package-splitting-dev-environment.html" title="2.8.5.4.Package Splitting"> | ||
| 10 | <link rel="next" href="sdk-generation-dev-environment.html" title="2.8.5.6.SDK Generation"> | ||
| 11 | </head> | ||
| 12 | <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="2.8.5.5.Image Generation"> | ||
| 13 | <div class="titlepage"><div><div><h4 class="title"> | ||
| 14 | <a name="image-generation-dev-environment"></a>2.8.5.5.Image Generation</h4></div></div></div> | ||
| 15 | <p> | ||
| 16 | Once packages are split and stored in the Package Feeds area, | ||
| 17 | the OpenEmbedded build system uses BitBake to generate the | ||
| 18 | root filesystem image: | ||
| 19 | </p> | ||
| 20 | <table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="540"><tr style="height: 630px"><td align="center"><img src="figures/image-generation.png" align="middle" width="540"></td></tr></table> | ||
| 21 | <p> | ||
| 22 | </p> | ||
| 23 | <p> | ||
| 24 | The image generation process consists of several stages and | ||
| 25 | depends on several tasks and variables. | ||
| 26 | The | ||
| 27 | <a class="link" href="../ref-manual/ref-tasks-rootfs.html" target="_self"><code class="filename">do_rootfs</code></a> | ||
| 28 | task creates the root filesystem (file and directory structure) | ||
| 29 | for an image. | ||
| 30 | This task uses several key variables to help create the list | ||
| 31 | of packages to actually install: | ||
| 32 | </p> | ||
| 33 | <div class="itemizedlist"><ul class="itemizedlist" type="disc"> | ||
| 34 | <li class="listitem"><p><a class="link" href="../ref-manual/var-IMAGE_INSTALL.html" target="_self"><code class="filename">IMAGE_INSTALL</code></a>: | ||
| 35 | Lists out the base set of packages to install from | ||
| 36 | the Package Feeds area.</p></li> | ||
| 37 | <li class="listitem"><p><a class="link" href="../ref-manual/var-PACKAGE_EXCLUDE.html" target="_self"><code class="filename">PACKAGE_EXCLUDE</code></a>: | ||
| 38 | Specifies packages that should not be installed. | ||
| 39 | </p></li> | ||
| 40 | <li class="listitem"><p><a class="link" href="../ref-manual/var-IMAGE_FEATURES.html" target="_self"><code class="filename">IMAGE_FEATURES</code></a>: | ||
| 41 | Specifies features to include in the image. | ||
| 42 | Most of these features map to additional packages for | ||
| 43 | installation.</p></li> | ||
| 44 | <li class="listitem"><p><a class="link" href="../ref-manual/var-PACKAGE_CLASSES.html" target="_self"><code class="filename">PACKAGE_CLASSES</code></a>: | ||
| 45 | Specifies the package backend to use and consequently | ||
| 46 | helps determine where to locate packages within the | ||
| 47 | Package Feeds area.</p></li> | ||
| 48 | <li class="listitem"><p><a class="link" href="../ref-manual/var-IMAGE_LINGUAS.html" target="_self"><code class="filename">IMAGE_LINGUAS</code></a>: | ||
| 49 | Determines the language(s) for which additional | ||
| 50 | language support packages are installed. | ||
| 51 | </p></li> | ||
| 52 | <li class="listitem"><p><a class="link" href="../ref-manual/var-PACKAGE_INSTALL.html" target="_self"><code class="filename">PACKAGE_INSTALL</code></a>: | ||
| 53 | The final list of packages passed to the package manager | ||
| 54 | for installation into the image. | ||
| 55 | </p></li> | ||
| 56 | </ul></div> | ||
| 57 | <p> | ||
| 58 | </p> | ||
| 59 | <p> | ||
| 60 | With | ||
| 61 | <a class="link" href="../ref-manual/var-IMAGE_ROOTFS.html" target="_self"><code class="filename">IMAGE_ROOTFS</code></a> | ||
| 62 | pointing to the location of the filesystem under construction and | ||
| 63 | the <code class="filename">PACKAGE_INSTALL</code> variable providing the | ||
| 64 | final list of packages to install, the root file system is | ||
| 65 | created. | ||
| 66 | </p> | ||
| 67 | <p> | ||
| 68 | Package installation is under control of the package manager | ||
| 69 | (e.g. dnf/rpm, opkg, or apt/dpkg) regardless of whether or | ||
| 70 | not package management is enabled for the target. | ||
| 71 | At the end of the process, if package management is not | ||
| 72 | enabled for the target, the package manager's data files | ||
| 73 | are deleted from the root filesystem. | ||
| 74 | As part of the final stage of package installation, postinstall | ||
| 75 | scripts that are part of the packages are run. | ||
| 76 | Any scripts that fail to run | ||
| 77 | on the build host are run on the target when the target system | ||
| 78 | is first booted. | ||
| 79 | If you are using a | ||
| 80 | <a class="link" href="../dev-manual/creating-a-read-only-root-filesystem.html" target="_self">read-only root filesystem</a>, | ||
| 81 | all the post installation scripts must succeed during the | ||
| 82 | package installation phase since the root filesystem is | ||
| 83 | read-only. | ||
| 84 | </p> | ||
| 85 | <p> | ||
| 86 | The final stages of the <code class="filename">do_rootfs</code> task | ||
| 87 | handle post processing. | ||
| 88 | Post processing includes creation of a manifest file and | ||
| 89 | optimizations. | ||
| 90 | </p> | ||
| 91 | <p> | ||
| 92 | The manifest file (<code class="filename">.manifest</code>) resides | ||
| 93 | in the same directory as the root filesystem image. | ||
| 94 | This file lists out, line-by-line, the installed packages. | ||
| 95 | The manifest file is useful for the | ||
| 96 | <a class="link" href="../ref-manual/ref-classes-testimage*.html" target="_self"><code class="filename">testimage</code></a> | ||
| 97 | class, for example, to determine whether or not to run | ||
| 98 | specific tests. | ||
| 99 | See the | ||
| 100 | <a class="link" href="../ref-manual/var-IMAGE_MANIFEST.html" target="_self"><code class="filename">IMAGE_MANIFEST</code></a> | ||
| 101 | variable for additional information. | ||
| 102 | </p> | ||
| 103 | <p> | ||
| 104 | Optimizing processes run across the image include | ||
| 105 | <code class="filename">mklibs</code>, <code class="filename">prelink</code>, | ||
| 106 | and any other post-processing commands as defined by the | ||
| 107 | <a class="link" href="../ref-manual/var-ROOTFS_POSTPROCESS_COMMAND.html" target="_self"><code class="filename">ROOTFS_POSTPROCESS_COMMAND</code></a> | ||
| 108 | variable. | ||
| 109 | The <code class="filename">mklibs</code> process optimizes the size | ||
| 110 | of the libraries, while the | ||
| 111 | <code class="filename">prelink</code> process optimizes the dynamic | ||
| 112 | linking of shared libraries to reduce start up time of | ||
| 113 | executables. | ||
| 114 | </p> | ||
| 115 | <p> | ||
| 116 | After the root filesystem is built, processing begins on | ||
| 117 | the image through the | ||
| 118 | <a class="link" href="../ref-manual/ref-tasks-image.html" target="_self"><code class="filename">do_image</code></a> | ||
| 119 | task. | ||
| 120 | The build system runs any pre-processing commands as defined | ||
| 121 | by the | ||
| 122 | <a class="link" href="../ref-manual/var-IMAGE_PREPROCESS_COMMAND.html" target="_self"><code class="filename">IMAGE_PREPROCESS_COMMAND</code></a> | ||
| 123 | variable. | ||
| 124 | This variable specifies a list of functions to call before | ||
| 125 | the OpenEmbedded build system creates the final image output | ||
| 126 | files. | ||
| 127 | </p> | ||
| 128 | <p> | ||
| 129 | The OpenEmbedded build system dynamically creates | ||
| 130 | <code class="filename">do_image_*</code> tasks as needed, based | ||
| 131 | on the image types specified in the | ||
| 132 | <a class="link" href="../ref-manual/var-IMAGE_FSTYPES.html" target="_self"><code class="filename">IMAGE_FSTYPES</code></a> | ||
| 133 | variable. | ||
| 134 | The process turns everything into an image file or a set of | ||
| 135 | image files and compresses the root filesystem image to reduce | ||
| 136 | the overall size of the image. | ||
| 137 | The formats used for the root filesystem depend on the | ||
| 138 | <code class="filename">IMAGE_FSTYPES</code> variable. | ||
| 139 | </p> | ||
| 140 | <p> | ||
| 141 | As an example, a dynamically created task when creating a | ||
| 142 | particular image <em class="replaceable"><code>type</code></em> would take the | ||
| 143 | following form: | ||
| 144 | </p> | ||
| 145 | <pre class="literallayout"> | ||
| 146 | do_image_<em class="replaceable"><code>type</code></em>[depends] | ||
| 147 | </pre> | ||
| 148 | <p> | ||
| 149 | So, if the <em class="replaceable"><code>type</code></em> as specified by the | ||
| 150 | <code class="filename">IMAGE_FSTYPES</code> were | ||
| 151 | <code class="filename">ext4</code>, the dynamically generated task | ||
| 152 | would be as follows: | ||
| 153 | </p> | ||
| 154 | <pre class="literallayout"> | ||
| 155 | do_image_ext4[depends] | ||
| 156 | </pre> | ||
| 157 | <p> | ||
| 158 | </p> | ||
| 159 | <p> | ||
| 160 | The final task involved in image creation is the | ||
| 161 | <a class="link" href="../ref-manual/ref-tasks-image-complete.html" target="_self"><code class="filename">do_image_complete</code></a> | ||
| 162 | task. | ||
| 163 | This task completes the image by applying any image | ||
| 164 | post processing as defined through the | ||
| 165 | <a class="link" href="../ref-manual/var-IMAGE_POSTPROCESS_COMMAND.html" target="_self"><code class="filename">IMAGE_POSTPROCESS_COMMAND</code></a> | ||
| 166 | variable. | ||
| 167 | The variable specifies a list of functions to call once the | ||
| 168 | OpenEmbedded build system has created the final image output | ||
| 169 | files. | ||
| 170 | </p> | ||
| 171 | <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"> | ||
| 172 | <h3 class="title">Note</h3> | ||
| 173 | The entire image generation process is run under Pseudo. | ||
| 174 | Running under Pseudo ensures that the files in the root | ||
| 175 | filesystem have correct ownership. | ||
| 176 | </div> | ||
| 177 | </div></body> | ||
| 178 | </html> | ||
diff --git a/documentation/getting-started/eclipse/html/getting-started/images-dev-environment.html b/documentation/getting-started/eclipse/html/getting-started/images-dev-environment.html new file mode 100644 index 0000000000..2561f1f4a6 --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/images-dev-environment.html | |||
| @@ -0,0 +1,99 @@ | |||
| 1 | <html> | ||
| 2 | <head> | ||
| 3 | <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> | ||
| 4 | <title>2.8.6.Images</title> | ||
| 5 | <link rel="stylesheet" type="text/css" href="../book.css"> | ||
| 6 | <meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> | ||
| 7 | <link rel="home" href="index.html" title="Getting Started With Yocto Project"> | ||
| 8 | <link rel="up" href="development-concepts.html" title="2.8.Development Concepts"> | ||
| 9 | <link rel="prev" href="setscene-tasks-and-shared-state.html" title="2.8.5.8.Setscene Tasks and Shared State"> | ||
| 10 | <link rel="next" href="sdk-dev-environment.html" title="2.8.7.Application Development SDK"> | ||
| 11 | </head> | ||
| 12 | <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="2.8.6.Images"> | ||
| 13 | <div class="titlepage"><div><div><h3 class="title"> | ||
| 14 | <a name="images-dev-environment"></a>2.8.6.Images</h3></div></div></div> | ||
| 15 | <p> | ||
| 16 | The images produced by the OpenEmbedded build system | ||
| 17 | are compressed forms of the | ||
| 18 | root filesystem that are ready to boot on a target device. | ||
| 19 | You can see from the | ||
| 20 | <a class="link" href="development-concepts.html#general-yocto-environment-figure">general Yocto Project Development Environment figure</a> | ||
| 21 | that BitBake output, in part, consists of images. | ||
| 22 | This section is going to look more closely at this output: | ||
| 23 | </p> | ||
| 24 | <table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="495"><tr style="height: 495px"><td align="center"><img src="figures/images.png" align="middle" width="495"></td></tr></table> | ||
| 25 | <p> | ||
| 26 | </p> | ||
| 27 | <p> | ||
| 28 | For a list of example images that the Yocto Project provides, | ||
| 29 | see the | ||
| 30 | "<a class="link" href="../ref-manual/ref-images.html" target="_self">Images</a>" | ||
| 31 | chapter in the Yocto Project Reference Manual. | ||
| 32 | </p> | ||
| 33 | <p> | ||
| 34 | Images are written out to the | ||
| 35 | <a class="link" href="../ref-manual/build-directory.html" target="_self">Build Directory</a> | ||
| 36 | inside the | ||
| 37 | <code class="filename">tmp/deploy/images/<em class="replaceable"><code>machine</code></em>/</code> | ||
| 38 | folder as shown in the figure. | ||
| 39 | This folder contains any files expected to be loaded on the | ||
| 40 | target device. | ||
| 41 | The | ||
| 42 | <a class="link" href="../ref-manual/var-DEPLOY_DIR.html" target="_self"><code class="filename">DEPLOY_DIR</code></a> | ||
| 43 | variable points to the <code class="filename">deploy</code> directory, | ||
| 44 | while the | ||
| 45 | <a class="link" href="../ref-manual/var-DEPLOY_DIR_IMAGE.html" target="_self"><code class="filename">DEPLOY_DIR_IMAGE</code></a> | ||
| 46 | variable points to the appropriate directory containing images for | ||
| 47 | the current configuration. | ||
| 48 | </p> | ||
| 49 | <div class="itemizedlist"><ul class="itemizedlist" type="disc"> | ||
| 50 | <li class="listitem"><p><code class="filename"><em class="replaceable"><code>kernel-image</code></em></code>: | ||
| 51 | A kernel binary file. | ||
| 52 | The | ||
| 53 | <a class="link" href="../ref-manual/var-KERNEL_IMAGETYPE.html" target="_self"><code class="filename">KERNEL_IMAGETYPE</code></a> | ||
| 54 | variable setting determines the naming scheme for the | ||
| 55 | kernel image file. | ||
| 56 | Depending on that variable, the file could begin with | ||
| 57 | a variety of naming strings. | ||
| 58 | The <code class="filename">deploy/images/<em class="replaceable"><code>machine</code></em></code> | ||
| 59 | directory can contain multiple image files for the | ||
| 60 | machine.</p></li> | ||
| 61 | <li class="listitem"><p><code class="filename"><em class="replaceable"><code>root-filesystem-image</code></em></code>: | ||
| 62 | Root filesystems for the target device (e.g. | ||
| 63 | <code class="filename">*.ext3</code> or <code class="filename">*.bz2</code> | ||
| 64 | files). | ||
| 65 | The | ||
| 66 | <a class="link" href="../ref-manual/var-IMAGE_FSTYPES.html" target="_self"><code class="filename">IMAGE_FSTYPES</code></a> | ||
| 67 | variable setting determines the root filesystem image | ||
| 68 | type. | ||
| 69 | The <code class="filename">deploy/images/<em class="replaceable"><code>machine</code></em></code> | ||
| 70 | directory can contain multiple root filesystems for the | ||
| 71 | machine.</p></li> | ||
| 72 | <li class="listitem"><p><code class="filename"><em class="replaceable"><code>kernel-modules</code></em></code>: | ||
| 73 | Tarballs that contain all the modules built for the kernel. | ||
| 74 | Kernel module tarballs exist for legacy purposes and | ||
| 75 | can be suppressed by setting the | ||
| 76 | <a class="link" href="../ref-manual/var-MODULE_TARBALL_DEPLOY.html" target="_self"><code class="filename">MODULE_TARBALL_DEPLOY</code></a> | ||
| 77 | variable to "0". | ||
| 78 | The <code class="filename">deploy/images/<em class="replaceable"><code>machine</code></em></code> | ||
| 79 | directory can contain multiple kernel module tarballs | ||
| 80 | for the machine.</p></li> | ||
| 81 | <li class="listitem"><p><code class="filename"><em class="replaceable"><code>bootloaders</code></em></code>: | ||
| 82 | Bootloaders supporting the image, if applicable to the | ||
| 83 | target machine. | ||
| 84 | The <code class="filename">deploy/images/<em class="replaceable"><code>machine</code></em></code> | ||
| 85 | directory can contain multiple bootloaders for the | ||
| 86 | machine.</p></li> | ||
| 87 | <li class="listitem"><p><code class="filename"><em class="replaceable"><code>symlinks</code></em></code>: | ||
| 88 | The <code class="filename">deploy/images/<em class="replaceable"><code>machine</code></em></code> | ||
| 89 | folder contains | ||
| 90 | a symbolic link that points to the most recently built file | ||
| 91 | for each machine. | ||
| 92 | These links might be useful for external scripts that | ||
| 93 | need to obtain the latest version of each file. | ||
| 94 | </p></li> | ||
| 95 | </ul></div> | ||
| 96 | <p> | ||
| 97 | </p> | ||
| 98 | </div></body> | ||
| 99 | </html> | ||
diff --git a/documentation/getting-started/eclipse/html/getting-started/index.html b/documentation/getting-started/eclipse/html/getting-started/index.html new file mode 100644 index 0000000000..94826ce0c6 --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/index.html | |||
| @@ -0,0 +1,154 @@ | |||
| 1 | <html> | ||
| 2 | <head> | ||
| 3 | <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> | ||
| 4 | <title>Getting Started With Yocto Project</title> | ||
| 5 | <link rel="stylesheet" type="text/css" href="../book.css"> | ||
| 6 | <meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> | ||
| 7 | <link rel="home" href="index.html" title="Getting Started With Yocto Project"> | ||
| 8 | <link rel="next" href="overview-manual-intro.html" title="Chapter1.The Yocto Project Overview Manual"> | ||
| 9 | </head> | ||
| 10 | <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div lang="en" class="book" title="Getting Started With Yocto Project"> | ||
| 11 | <div class="titlepage"> | ||
| 12 | <div> | ||
| 13 | <div><h1 class="title"> | ||
| 14 | <a name="getting-started-manual"></a> | ||
| 15 | Getting Started With Yocto Project | ||
| 16 | </h1></div> | ||
| 17 | <div><div class="authorgroup"> | ||
| 18 | <div class="author"> | ||
| 19 | <h3 class="author"> | ||
| 20 | <span class="firstname">Scott</span> <span class="surname">Rifenbark</span> | ||
| 21 | </h3> | ||
| 22 | <div class="affiliation"> | ||
| 23 | <span class="orgname">Scotty's Documentation Services, INC<br></span> | ||
| 24 | </div> | ||
| 25 | <code class="email"><<a class="email" href="mailto:srifenbark@gmail.com">srifenbark@gmail.com</a>></code> | ||
| 26 | </div> | ||
| 27 | </div></div> | ||
| 28 | <div><p class="copyright">Copyright 2010-2018 Linux Foundation</p></div> | ||
| 29 | <div><div class="legalnotice" title="Legal Notice"> | ||
| 30 | <a name="idm45823191546992"></a> | ||
| 31 | <p> | ||
| 32 | Permission is granted to copy, distribute and/or modify this document under | ||
| 33 | the terms of the <a class="ulink" href="http://creativecommons.org/licenses/by-sa/2.0/uk/" target="_self"> | ||
| 34 | Creative Commons Attribution-Share Alike 2.0 UK: England & Wales</a> as published by | ||
| 35 | Creative Commons. | ||
| 36 | </p> | ||
| 37 | <div class="note" title="Manual Notes" style="margin-left: 0.5in; margin-right: 0.5in;"> | ||
| 38 | <h3 class="title">Manual Notes</h3> | ||
| 39 | <div class="itemizedlist"><ul class="itemizedlist" type="disc"> | ||
| 40 | <li class="listitem"><p> | ||
| 41 | This version of the | ||
| 42 | <span class="emphasis"><em>Yocto Project Overview Manual</em></span> | ||
| 43 | is for the 2.5 release of the | ||
| 44 | Yocto Project. | ||
| 45 | To be sure you have the latest version of the manual | ||
| 46 | for this release, use the manual from the | ||
| 47 | <a class="ulink" href="http://www.yoctoproject.org/documentation" target="_self">Yocto Project documentation page</a>. | ||
| 48 | </p></li> | ||
| 49 | <li class="listitem"><p> | ||
| 50 | For manuals associated with other releases of the Yocto | ||
| 51 | Project, go to the | ||
| 52 | <a class="ulink" href="http://www.yoctoproject.org/documentation" target="_self">Yocto Project documentation page</a> | ||
| 53 | and use the drop-down "Active Releases" button | ||
| 54 | and choose the manual associated with the desired | ||
| 55 | Yocto Project. | ||
| 56 | </p></li> | ||
| 57 | <li class="listitem"><p> | ||
| 58 | To report any inaccuracies or problems with this | ||
| 59 | manual, send an email to the Yocto Project | ||
| 60 | discussion group at | ||
| 61 | <code class="filename">yocto@yoctoproject.com</code> or log into | ||
| 62 | the freenode <code class="filename">#yocto</code> channel. | ||
| 63 | </p></li> | ||
| 64 | </ul></div> | ||
| 65 | </div> | ||
| 66 | </div></div> | ||
| 67 | <div><div class="revhistory"><table border="1" width="100%" summary="Revision history"> | ||
| 68 | <tr><th align="left" valign="top" colspan="2"><b>Revision History</b></th></tr> | ||
| 69 | <tr> | ||
| 70 | <td align="left">Revision 2.5</td> | ||
| 71 | <td align="left">April 2018</td> | ||
| 72 | </tr> | ||
| 73 | <tr><td align="left" colspan="2">The initial document released with the Yocto Project 2.5 Release.</td></tr> | ||
| 74 | </table></div></div> | ||
| 75 | </div> | ||
| 76 | <hr> | ||
| 77 | </div> | ||
| 78 | <div class="toc"> | ||
| 79 | <p><b>Table of Contents</b></p> | ||
| 80 | <dl> | ||
| 81 | <dt><span class="chapter"><a href="overview-manual-intro.html">1. The Yocto Project Overview Manual</a></span></dt> | ||
| 82 | <dd><dl> | ||
| 83 | <dt><span class="section"><a href="overview-welcome.html">1.1. Welcome</a></span></dt> | ||
| 84 | <dt><span class="section"><a href="overview-other-information.html">1.2. Other Information</a></span></dt> | ||
| 85 | </dl></dd> | ||
| 86 | <dt><span class="chapter"><a href="overview-development-environment.html">2. The Yocto Project Development Environment</a></span></dt> | ||
| 87 | <dd><dl> | ||
| 88 | <dt><span class="section"><a href="yp-intro.html">2.1. Introduction</a></span></dt> | ||
| 89 | <dt><span class="section"><a href="open-source-philosophy.html">2.2. Open Source Philosophy</a></span></dt> | ||
| 90 | <dt><span class="section"><a href="workflows.html">2.3. Workflows</a></span></dt> | ||
| 91 | <dt><span class="section"><a href="git.html">2.4. Git</a></span></dt> | ||
| 92 | <dd><dl> | ||
| 93 | <dt><span class="section"><a href="repositories-tags-and-branches.html">2.4.1. Repositories, Tags, and Branches</a></span></dt> | ||
| 94 | <dt><span class="section"><a href="basic-commands.html">2.4.2. Basic Commands</a></span></dt> | ||
| 95 | </dl></dd> | ||
| 96 | <dt><span class="section"><a href="yocto-project-repositories.html">2.5. Yocto Project Source Repositories</a></span></dt> | ||
| 97 | <dt><span class="section"><a href="licensing.html">2.6. Licensing</a></span></dt> | ||
| 98 | <dt><span class="section"><a href="recipe-syntax.html">2.7. Recipe Syntax</a></span></dt> | ||
| 99 | <dt><span class="section"><a href="development-concepts.html">2.8. Development Concepts</a></span></dt> | ||
| 100 | <dd><dl> | ||
| 101 | <dt><span class="section"><a href="user-configuration.html">2.8.1. User Configuration</a></span></dt> | ||
| 102 | <dt><span class="section"><a href="metadata-machine-configuration-and-policy-configuration.html">2.8.2. Metadata, Machine Configuration, and Policy Configuration</a></span></dt> | ||
| 103 | <dt><span class="section"><a href="sources-dev-environment.html">2.8.3. Sources</a></span></dt> | ||
| 104 | <dt><span class="section"><a href="package-feeds-dev-environment.html">2.8.4. Package Feeds</a></span></dt> | ||
| 105 | <dt><span class="section"><a href="bitbake-dev-environment.html">2.8.5. BitBake</a></span></dt> | ||
| 106 | <dt><span class="section"><a href="images-dev-environment.html">2.8.6. Images</a></span></dt> | ||
| 107 | <dt><span class="section"><a href="sdk-dev-environment.html">2.8.7. Application Development SDK</a></span></dt> | ||
| 108 | </dl></dd> | ||
| 109 | </dl></dd> | ||
| 110 | <dt><span class="chapter"><a href="overview-concepts.html">3. Yocto Project Concepts</a></span></dt> | ||
| 111 | <dd><dl> | ||
| 112 | <dt><span class="section"><a href="yocto-project-components.html">3.1. Yocto Project Components</a></span></dt> | ||
| 113 | <dd><dl> | ||
| 114 | <dt><span class="section"><a href="usingpoky-components-bitbake.html">3.1.1. BitBake</a></span></dt> | ||
| 115 | <dt><span class="section"><a href="usingpoky-components-metadata.html">3.1.2. Metadata (Recipes)</a></span></dt> | ||
| 116 | <dt><span class="section"><a href="metadata-virtual-providers.html">3.1.3. Metadata (Virtual Providers)</a></span></dt> | ||
| 117 | <dt><span class="section"><a href="usingpoky-components-classes.html">3.1.4. Classes</a></span></dt> | ||
| 118 | <dt><span class="section"><a href="usingpoky-components-configuration.html">3.1.5. Configuration</a></span></dt> | ||
| 119 | </dl></dd> | ||
| 120 | <dt><span class="section"><a href="cross-development-toolchain-generation.html">3.2. Cross-Development Toolchain Generation</a></span></dt> | ||
| 121 | <dt><span class="section"><a href="shared-state-cache.html">3.3. Shared State Cache</a></span></dt> | ||
| 122 | <dd><dl> | ||
| 123 | <dt><span class="section"><a href="overall-architecture.html">3.3.1. Overall Architecture</a></span></dt> | ||
| 124 | <dt><span class="section"><a href="overview-checksums.html">3.3.2. Checksums (Signatures)</a></span></dt> | ||
| 125 | <dt><span class="section"><a href="shared-state.html">3.3.3. Shared State</a></span></dt> | ||
| 126 | <dt><span class="section"><a href="tips-and-tricks.html">3.3.4. Tips and Tricks</a></span></dt> | ||
| 127 | </dl></dd> | ||
| 128 | <dt><span class="section"><a href="automatically-added-runtime-dependencies.html">3.4. Automatically Added Runtime Dependencies</a></span></dt> | ||
| 129 | <dt><span class="section"><a href="fakeroot-and-pseudo.html">3.5. Fakeroot and Pseudo</a></span></dt> | ||
| 130 | <dt><span class="section"><a href="wayland.html">3.6. Wayland</a></span></dt> | ||
| 131 | <dd><dl> | ||
| 132 | <dt><span class="section"><a href="wayland-support.html">3.6.1. Support</a></span></dt> | ||
| 133 | <dt><span class="section"><a href="enabling-wayland-in-an-image.html">3.6.2. Enabling Wayland in an Image</a></span></dt> | ||
| 134 | <dt><span class="section"><a href="running-weston.html">3.6.3. Running Weston</a></span></dt> | ||
| 135 | </dl></dd> | ||
| 136 | <dt><span class="section"><a href="overview-licenses.html">3.7. Licenses</a></span></dt> | ||
| 137 | <dd><dl> | ||
| 138 | <dt><span class="section"><a href="usingpoky-configuring-LIC_FILES_CHKSUM.html">3.7.1. Tracking License Changes</a></span></dt> | ||
| 139 | <dt><span class="section"><a href="enabling-commercially-licensed-recipes.html">3.7.2. Enabling Commercially Licensed Recipes</a></span></dt> | ||
| 140 | </dl></dd> | ||
| 141 | <dt><span class="section"><a href="x32.html">3.8. x32 psABI</a></span></dt> | ||
| 142 | </dl></dd> | ||
| 143 | </dl> | ||
| 144 | </div> | ||
| 145 | |||
| 146 | |||
| 147 | |||
| 148 | |||
| 149 | |||
| 150 | |||
| 151 | |||
| 152 | |||
| 153 | </div></body> | ||
| 154 | </html> | ||
diff --git a/documentation/getting-started/eclipse/html/getting-started/index.xml b/documentation/getting-started/eclipse/html/getting-started/index.xml new file mode 100644 index 0000000000..9edb4b92ac --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/index.xml | |||
| @@ -0,0 +1,2 @@ | |||
| 1 | <?xml version="1.0" encoding="utf-8" standalone="no"?> | ||
| 2 | <index/> | ||
diff --git a/documentation/getting-started/eclipse/html/getting-started/invalidating-shared-state.html b/documentation/getting-started/eclipse/html/getting-started/invalidating-shared-state.html new file mode 100644 index 0000000000..ef4a2aac5e --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/invalidating-shared-state.html | |||
| @@ -0,0 +1,77 @@ | |||
| 1 | <html> | ||
| 2 | <head> | ||
| 3 | <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> | ||
| 4 | <title>3.3.4.2.Invalidating Shared State</title> | ||
| 5 | <link rel="stylesheet" type="text/css" href="../book.css"> | ||
| 6 | <meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> | ||
| 7 | <link rel="home" href="index.html" title="Getting Started With Yocto Project"> | ||
| 8 | <link rel="up" href="tips-and-tricks.html" title="3.3.4.Tips and Tricks"> | ||
| 9 | <link rel="prev" href="overview-debugging.html" title="3.3.4.1.Debugging"> | ||
| 10 | <link rel="next" href="automatically-added-runtime-dependencies.html" title="3.4.Automatically Added Runtime Dependencies"> | ||
| 11 | </head> | ||
| 12 | <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="3.3.4.2.Invalidating Shared State"> | ||
| 13 | <div class="titlepage"><div><div><h4 class="title"> | ||
| 14 | <a name="invalidating-shared-state"></a>3.3.4.2.Invalidating Shared State</h4></div></div></div> | ||
| 15 | <p> | ||
| 16 | The OpenEmbedded build system uses checksums and shared | ||
| 17 | state cache to avoid unnecessarily rebuilding tasks. | ||
| 18 | Collectively, this scheme is known as "shared state code." | ||
| 19 | </p> | ||
| 20 | <p> | ||
| 21 | As with all schemes, this one has some drawbacks. | ||
| 22 | It is possible that you could make implicit changes to your | ||
| 23 | code that the checksum calculations do not take into | ||
| 24 | account. | ||
| 25 | These implicit changes affect a task's output but do not | ||
| 26 | trigger the shared state code into rebuilding a recipe. | ||
| 27 | Consider an example during which a tool changes its output. | ||
| 28 | Assume that the output of <code class="filename">rpmdeps</code> | ||
| 29 | changes. | ||
| 30 | The result of the change should be that all the | ||
| 31 | <code class="filename">package</code> and | ||
| 32 | <code class="filename">package_write_rpm</code> shared state cache | ||
| 33 | items become invalid. | ||
| 34 | However, because the change to the output is | ||
| 35 | external to the code and therefore implicit, | ||
| 36 | the associated shared state cache items do not become | ||
| 37 | invalidated. | ||
| 38 | In this case, the build process uses the cached items | ||
| 39 | rather than running the task again. | ||
| 40 | Obviously, these types of implicit changes can cause | ||
| 41 | problems. | ||
| 42 | </p> | ||
| 43 | <p> | ||
| 44 | To avoid these problems during the build, you need to | ||
| 45 | understand the effects of any changes you make. | ||
| 46 | Realize that changes you make directly to a function | ||
| 47 | are automatically factored into the checksum calculation. | ||
| 48 | Thus, these explicit changes invalidate the associated | ||
| 49 | area of shared state cache. | ||
| 50 | However, you need to be aware of any implicit changes that | ||
| 51 | are not obvious changes to the code and could affect | ||
| 52 | the output of a given task. | ||
| 53 | </p> | ||
| 54 | <p> | ||
| 55 | When you identify an implicit change, you can easily | ||
| 56 | take steps to invalidate the cache and force the tasks | ||
| 57 | to run. | ||
| 58 | The steps you can take are as simple as changing a | ||
| 59 | function's comments in the source code. | ||
| 60 | For example, to invalidate package shared state files, | ||
| 61 | change the comment statements of | ||
| 62 | <a class="link" href="../ref-manual/ref-tasks-package.html" target="_self"><code class="filename">do_package</code></a> | ||
| 63 | or the comments of one of the functions it calls. | ||
| 64 | Even though the change is purely cosmetic, it causes the | ||
| 65 | checksum to be recalculated and forces the OpenEmbedded | ||
| 66 | build system to run the task again. | ||
| 67 | </p> | ||
| 68 | <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"> | ||
| 69 | <h3 class="title">Note</h3> | ||
| 70 | For an example of a commit that makes a cosmetic | ||
| 71 | change to invalidate shared state, see this | ||
| 72 | <a class="ulink" href="http://git.yoctoproject.org/cgit.cgi/poky/commit/meta/classes/package.bbclass?id=737f8bbb4f27b4837047cb9b4fbfe01dfde36d54" target="_self">commit</a>. | ||
| 73 | </div> | ||
| 74 | <p> | ||
| 75 | </p> | ||
| 76 | </div></body> | ||
| 77 | </html> | ||
diff --git a/documentation/getting-started/eclipse/html/getting-started/license-flag-matching.html b/documentation/getting-started/eclipse/html/getting-started/license-flag-matching.html new file mode 100644 index 0000000000..1e08bafad1 --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/license-flag-matching.html | |||
| @@ -0,0 +1,126 @@ | |||
| 1 | <html> | ||
| 2 | <head> | ||
| 3 | <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> | ||
| 4 | <title>3.7.2.1.License Flag Matching</title> | ||
| 5 | <link rel="stylesheet" type="text/css" href="../book.css"> | ||
| 6 | <meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> | ||
| 7 | <link rel="home" href="index.html" title="Getting Started With Yocto Project"> | ||
| 8 | <link rel="up" href="enabling-commercially-licensed-recipes.html" title="3.7.2.Enabling Commercially Licensed Recipes"> | ||
| 9 | <link rel="prev" href="enabling-commercially-licensed-recipes.html" title="3.7.2.Enabling Commercially Licensed Recipes"> | ||
| 10 | <link rel="next" href="other-variables-related-to-commercial-licenses.html" title="3.7.2.2.Other Variables Related to Commercial Licenses"> | ||
| 11 | </head> | ||
| 12 | <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="3.7.2.1.License Flag Matching"> | ||
| 13 | <div class="titlepage"><div><div><h4 class="title"> | ||
| 14 | <a name="license-flag-matching"></a>3.7.2.1.License Flag Matching</h4></div></div></div> | ||
| 15 | <p> | ||
| 16 | License flag matching allows you to control what recipes | ||
| 17 | the OpenEmbedded build system includes in the build. | ||
| 18 | Fundamentally, the build system attempts to match | ||
| 19 | <a class="link" href="../ref-manual/var-LICENSE_FLAGS.html" target="_self"><code class="filename">LICENSE_FLAGS</code></a> | ||
| 20 | strings found in recipes against | ||
| 21 | <a class="link" href="../ref-manual/var-LICENSE_FLAGS_WHITELIST.html" target="_self"><code class="filename">LICENSE_FLAGS_WHITELIST</code></a> | ||
| 22 | strings found in the whitelist. | ||
| 23 | A match causes the build system to include a recipe in the | ||
| 24 | build, while failure to find a match causes the build | ||
| 25 | system to exclude a recipe. | ||
| 26 | </p> | ||
| 27 | <p> | ||
| 28 | In general, license flag matching is simple. | ||
| 29 | However, understanding some concepts will help you | ||
| 30 | correctly and effectively use matching. | ||
| 31 | </p> | ||
| 32 | <p> | ||
| 33 | Before a flag | ||
| 34 | defined by a particular recipe is tested against the | ||
| 35 | contents of the whitelist, the expanded string | ||
| 36 | <code class="filename">_${PN}</code> is appended to the flag. | ||
| 37 | This expansion makes each | ||
| 38 | <code class="filename">LICENSE_FLAGS</code> value recipe-specific. | ||
| 39 | After expansion, the string is then matched against the | ||
| 40 | whitelist. | ||
| 41 | Thus, specifying | ||
| 42 | <code class="filename">LICENSE_FLAGS = "commercial"</code> | ||
| 43 | in recipe "foo", for example, results in the string | ||
| 44 | <code class="filename">"commercial_foo"</code>. | ||
| 45 | And, to create a match, that string must appear in the | ||
| 46 | whitelist. | ||
| 47 | </p> | ||
| 48 | <p> | ||
| 49 | Judicious use of the <code class="filename">LICENSE_FLAGS</code> | ||
| 50 | strings and the contents of the | ||
| 51 | <code class="filename">LICENSE_FLAGS_WHITELIST</code> variable | ||
| 52 | allows you a lot of flexibility for including or excluding | ||
| 53 | recipes based on licensing. | ||
| 54 | For example, you can broaden the matching capabilities by | ||
| 55 | using license flags string subsets in the whitelist. | ||
| 56 | </p> | ||
| 57 | <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"> | ||
| 58 | <h3 class="title">Note</h3> | ||
| 59 | When using a string subset, be sure to use the part of | ||
| 60 | the expanded string that precedes the appended | ||
| 61 | underscore character (e.g. | ||
| 62 | <code class="filename">usethispart_1.3</code>, | ||
| 63 | <code class="filename">usethispart_1.4</code>, and so forth). | ||
| 64 | </div> | ||
| 65 | <p> | ||
| 66 | For example, simply specifying the string "commercial" in | ||
| 67 | the whitelist matches any expanded | ||
| 68 | <code class="filename">LICENSE_FLAGS</code> definition that starts | ||
| 69 | with the string "commercial" such as "commercial_foo" and | ||
| 70 | "commercial_bar", which are the strings the build system | ||
| 71 | automatically generates for hypothetical recipes named | ||
| 72 | "foo" and "bar" assuming those recipes simply specify the | ||
| 73 | following: | ||
| 74 | </p> | ||
| 75 | <pre class="literallayout"> | ||
| 76 | LICENSE_FLAGS = "commercial" | ||
| 77 | </pre> | ||
| 78 | <p> | ||
| 79 | Thus, you can choose to exhaustively | ||
| 80 | enumerate each license flag in the whitelist and | ||
| 81 | allow only specific recipes into the image, or | ||
| 82 | you can use a string subset that causes a broader range of | ||
| 83 | matches to allow a range of recipes into the image. | ||
| 84 | </p> | ||
| 85 | <p> | ||
| 86 | This scheme works even if the | ||
| 87 | <code class="filename">LICENSE_FLAGS</code> string already | ||
| 88 | has <code class="filename">_${PN}</code> appended. | ||
| 89 | For example, the build system turns the license flag | ||
| 90 | "commercial_1.2_foo" into "commercial_1.2_foo_foo" and | ||
| 91 | would match both the general "commercial" and the specific | ||
| 92 | "commercial_1.2_foo" strings found in the whitelist, as | ||
| 93 | expected. | ||
| 94 | </p> | ||
| 95 | <p> | ||
| 96 | Here are some other scenarios: | ||
| 97 | </p> | ||
| 98 | <div class="itemizedlist"><ul class="itemizedlist" type="disc"> | ||
| 99 | <li class="listitem"><p> | ||
| 100 | You can specify a versioned string in the recipe | ||
| 101 | such as "commercial_foo_1.2" in a "foo" recipe. | ||
| 102 | The build system expands this string to | ||
| 103 | "commercial_foo_1.2_foo". | ||
| 104 | Combine this license flag with a whitelist that has | ||
| 105 | the string "commercial" and you match the flag | ||
| 106 | along with any other flag that starts with the | ||
| 107 | string "commercial". | ||
| 108 | </p></li> | ||
| 109 | <li class="listitem"><p> | ||
| 110 | Under the same circumstances, you can use | ||
| 111 | "commercial_foo" in the whitelist and the build | ||
| 112 | system not only matches "commercial_foo_1.2" but | ||
| 113 | also matches any license flag with the string | ||
| 114 | "commercial_foo", regardless of the version. | ||
| 115 | </p></li> | ||
| 116 | <li class="listitem"><p> | ||
| 117 | You can be very specific and use both the | ||
| 118 | package and version parts in the whitelist (e.g. | ||
| 119 | "commercial_foo_1.2") to specifically match a | ||
| 120 | versioned recipe. | ||
| 121 | </p></li> | ||
| 122 | </ul></div> | ||
| 123 | <p> | ||
| 124 | </p> | ||
| 125 | </div></body> | ||
| 126 | </html> | ||
diff --git a/documentation/getting-started/eclipse/html/getting-started/licensing.html b/documentation/getting-started/eclipse/html/getting-started/licensing.html new file mode 100644 index 0000000000..ade868705c --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/licensing.html | |||
| @@ -0,0 +1,91 @@ | |||
| 1 | <html> | ||
| 2 | <head> | ||
| 3 | <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> | ||
| 4 | <title>2.6.Licensing</title> | ||
| 5 | <link rel="stylesheet" type="text/css" href="../book.css"> | ||
| 6 | <meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> | ||
| 7 | <link rel="home" href="index.html" title="Getting Started With Yocto Project"> | ||
| 8 | <link rel="up" href="overview-development-environment.html" title="Chapter2.The Yocto Project Development Environment"> | ||
| 9 | <link rel="prev" href="yocto-project-repositories.html" title="2.5.Yocto Project Source Repositories"> | ||
| 10 | <link rel="next" href="recipe-syntax.html" title="2.7.Recipe Syntax"> | ||
| 11 | </head> | ||
| 12 | <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="2.6.Licensing"> | ||
| 13 | <div class="titlepage"><div><div><h2 class="title" style="clear: both"> | ||
| 14 | <a name="licensing"></a>2.6.Licensing</h2></div></div></div> | ||
| 15 | <p> | ||
| 16 | Because open source projects are open to the public, they have | ||
| 17 | different licensing structures in place. | ||
| 18 | License evolution for both Open Source and Free Software has an | ||
| 19 | interesting history. | ||
| 20 | If you are interested in this history, you can find basic information | ||
| 21 | here: | ||
| 22 | </p> | ||
| 23 | <div class="itemizedlist"><ul class="itemizedlist" type="disc"> | ||
| 24 | <li class="listitem"><p> | ||
| 25 | <a class="ulink" href="http://en.wikipedia.org/wiki/Open-source_license" target="_self">Open source license history</a> | ||
| 26 | </p></li> | ||
| 27 | <li class="listitem"><p> | ||
| 28 | <a class="ulink" href="http://en.wikipedia.org/wiki/Free_software_license" target="_self">Free software license history</a> | ||
| 29 | </p></li> | ||
| 30 | </ul></div> | ||
| 31 | <p> | ||
| 32 | </p> | ||
| 33 | <p> | ||
| 34 | In general, the Yocto Project is broadly licensed under the | ||
| 35 | Massachusetts Institute of Technology (MIT) License. | ||
| 36 | MIT licensing permits the reuse of software within proprietary | ||
| 37 | software as long as the license is distributed with that software. | ||
| 38 | MIT is also compatible with the GNU General Public License (GPL). | ||
| 39 | Patches to the Yocto Project follow the upstream licensing scheme. | ||
| 40 | You can find information on the MIT license | ||
| 41 | <a class="ulink" href="http://www.opensource.org/licenses/mit-license.php" target="_self">here</a>. | ||
| 42 | You can find information on the GNU GPL | ||
| 43 | <a class="ulink" href="http://www.opensource.org/licenses/LGPL-3.0" target="_self">here</a>. | ||
| 44 | </p> | ||
| 45 | <p> | ||
| 46 | When you build an image using the Yocto Project, the build process | ||
| 47 | uses a known list of licenses to ensure compliance. | ||
| 48 | You can find this list in the | ||
| 49 | <a class="link" href="../ref-manual/source-directory.html" target="_self">Source Directory</a> | ||
| 50 | at <code class="filename">meta/files/common-licenses</code>. | ||
| 51 | Once the build completes, the list of all licenses found and used | ||
| 52 | during that build are kept in the | ||
| 53 | <a class="link" href="../ref-manual/build-directory.html" target="_self">Build Directory</a> | ||
| 54 | at <code class="filename">tmp/deploy/licenses</code>. | ||
| 55 | </p> | ||
| 56 | <p> | ||
| 57 | If a module requires a license that is not in the base list, the | ||
| 58 | build process generates a warning during the build. | ||
| 59 | These tools make it easier for a developer to be certain of the | ||
| 60 | licenses with which their shipped products must comply. | ||
| 61 | However, even with these tools it is still up to the developer to | ||
| 62 | resolve potential licensing issues. | ||
| 63 | </p> | ||
| 64 | <p> | ||
| 65 | The base list of licenses used by the build process is a combination | ||
| 66 | of the Software Package Data Exchange (SPDX) list and the Open | ||
| 67 | Source Initiative (OSI) projects. | ||
| 68 | <a class="ulink" href="http://spdx.org" target="_self">SPDX Group</a> is a working group of | ||
| 69 | the Linux Foundation that maintains a specification for a standard | ||
| 70 | format for communicating the components, licenses, and copyrights | ||
| 71 | associated with a software package. | ||
| 72 | <a class="ulink" href="http://opensource.org" target="_self">OSI</a> is a corporation | ||
| 73 | dedicated to the Open Source Definition and the effort for reviewing | ||
| 74 | and approving licenses that conform to the Open Source Definition | ||
| 75 | (OSD). | ||
| 76 | </p> | ||
| 77 | <p> | ||
| 78 | You can find a list of the combined SPDX and OSI licenses that the | ||
| 79 | Yocto Project uses in the | ||
| 80 | <code class="filename">meta/files/common-licenses</code> directory in your | ||
| 81 | <a class="link" href="../ref-manual/source-directory.html" target="_self">Source Directory</a>. | ||
| 82 | </p> | ||
| 83 | <p> | ||
| 84 | For information that can help you maintain compliance with various | ||
| 85 | open source licensing during the lifecycle of a product created using | ||
| 86 | the Yocto Project, see the | ||
| 87 | "<a class="link" href="../dev-manual/maintaining-open-source-license-compliance-during-your-products-lifecycle.html" target="_self">Maintaining Open Source License Compliance During Your Product's Lifecycle</a>" | ||
| 88 | section in the Yocto Project Development Tasks Manual. | ||
| 89 | </p> | ||
| 90 | </div></body> | ||
| 91 | </html> | ||
diff --git a/documentation/getting-started/eclipse/html/getting-started/local-projects.html b/documentation/getting-started/eclipse/html/getting-started/local-projects.html new file mode 100644 index 0000000000..9ed618701c --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/local-projects.html | |||
| @@ -0,0 +1,39 @@ | |||
| 1 | <html> | ||
| 2 | <head> | ||
| 3 | <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> | ||
| 4 | <title>2.8.3.2.Local Projects</title> | ||
| 5 | <link rel="stylesheet" type="text/css" href="../book.css"> | ||
| 6 | <meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> | ||
| 7 | <link rel="home" href="index.html" title="Getting Started With Yocto Project"> | ||
| 8 | <link rel="up" href="sources-dev-environment.html" title="2.8.3.Sources"> | ||
| 9 | <link rel="prev" href="upstream-project-releases.html" title="2.8.3.1.Upstream Project Releases"> | ||
| 10 | <link rel="next" href="scms.html" title="2.8.3.3.Source Control Managers (Optional)"> | ||
| 11 | </head> | ||
| 12 | <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="2.8.3.2.Local Projects"> | ||
| 13 | <div class="titlepage"><div><div><h4 class="title"> | ||
| 14 | <a name="local-projects"></a>2.8.3.2.Local Projects</h4></div></div></div> | ||
| 15 | <p> | ||
| 16 | Local projects are custom bits of software the user provides. | ||
| 17 | These bits reside somewhere local to a project - perhaps | ||
| 18 | a directory into which the user checks in items (e.g. | ||
| 19 | a local directory containing a development source tree | ||
| 20 | used by the group). | ||
| 21 | </p> | ||
| 22 | <p> | ||
| 23 | The canonical method through which to include a local project | ||
| 24 | is to use the | ||
| 25 | <a class="link" href="../ref-manual/ref-classes-externalsrc.html" target="_self"><code class="filename">externalsrc</code></a> | ||
| 26 | class to include that local project. | ||
| 27 | You use either the <code class="filename">local.conf</code> or a | ||
| 28 | recipe's append file to override or set the | ||
| 29 | recipe to point to the local directory on your disk to pull | ||
| 30 | in the whole source tree. | ||
| 31 | </p> | ||
| 32 | <p> | ||
| 33 | For information on how to use the | ||
| 34 | <code class="filename">externalsrc</code> class, see the | ||
| 35 | "<a class="link" href="../ref-manual/ref-classes-externalsrc.html" target="_self"><code class="filename">externalsrc.bbclass</code></a>" | ||
| 36 | section. | ||
| 37 | </p> | ||
| 38 | </div></body> | ||
| 39 | </html> | ||
diff --git a/documentation/getting-started/eclipse/html/getting-started/metadata-machine-configuration-and-policy-configuration.html b/documentation/getting-started/eclipse/html/getting-started/metadata-machine-configuration-and-policy-configuration.html new file mode 100644 index 0000000000..24f32f394f --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/metadata-machine-configuration-and-policy-configuration.html | |||
| @@ -0,0 +1,93 @@ | |||
| 1 | <html> | ||
| 2 | <head> | ||
| 3 | <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> | ||
| 4 | <title>2.8.2.Metadata, Machine Configuration, and Policy Configuration</title> | ||
| 5 | <link rel="stylesheet" type="text/css" href="../book.css"> | ||
| 6 | <meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> | ||
| 7 | <link rel="home" href="index.html" title="Getting Started With Yocto Project"> | ||
| 8 | <link rel="up" href="development-concepts.html" title="2.8.Development Concepts"> | ||
| 9 | <link rel="prev" href="user-configuration.html" title="2.8.1.User Configuration"> | ||
| 10 | <link rel="next" href="distro-layer.html" title="2.8.2.1.Distro Layer"> | ||
| 11 | </head> | ||
| 12 | <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="2.8.2.Metadata, Machine Configuration, and Policy Configuration"> | ||
| 13 | <div class="titlepage"><div><div><h3 class="title"> | ||
| 14 | <a name="metadata-machine-configuration-and-policy-configuration"></a>2.8.2.Metadata, Machine Configuration, and Policy Configuration</h3></div></div></div> | ||
| 15 | <p> | ||
| 16 | The previous section described the user configurations that | ||
| 17 | define BitBake's global behavior. | ||
| 18 | This section takes a closer look at the layers the build system | ||
| 19 | uses to further control the build. | ||
| 20 | These layers provide Metadata for the software, machine, and | ||
| 21 | policy. | ||
| 22 | </p> | ||
| 23 | <p> | ||
| 24 | In general, three types of layer input exist: | ||
| 25 | </p> | ||
| 26 | <div class="itemizedlist"><ul class="itemizedlist" type="disc"> | ||
| 27 | <li class="listitem"><p><span class="emphasis"><em>Policy Configuration:</em></span> | ||
| 28 | Distribution Layers provide top-level or general | ||
| 29 | policies for the image or SDK being built. | ||
| 30 | For example, this layer would dictate whether BitBake | ||
| 31 | produces RPM or IPK packages.</p></li> | ||
| 32 | <li class="listitem"><p><span class="emphasis"><em>Machine Configuration:</em></span> | ||
| 33 | Board Support Package (BSP) layers provide machine | ||
| 34 | configurations. | ||
| 35 | This type of information is specific to a particular | ||
| 36 | target architecture.</p></li> | ||
| 37 | <li class="listitem"><p><span class="emphasis"><em>Metadata:</em></span> | ||
| 38 | Software layers contain user-supplied recipe files, | ||
| 39 | patches, and append files. | ||
| 40 | </p></li> | ||
| 41 | </ul></div> | ||
| 42 | <p> | ||
| 43 | </p> | ||
| 44 | <p> | ||
| 45 | The following figure shows an expanded representation of the | ||
| 46 | Metadata, Machine Configuration, and Policy Configuration input | ||
| 47 | (layers) boxes of the | ||
| 48 | <a class="link" href="development-concepts.html#general-yocto-environment-figure">general Yocto Project Development Environment figure</a>: | ||
| 49 | </p> | ||
| 50 | <p> | ||
| 51 | </p> | ||
| 52 | <table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="720"><tr style="height: 675px"><td align="center"><img src="figures/layer-input.png" align="middle" width="720"></td></tr></table> | ||
| 53 | <p> | ||
| 54 | </p> | ||
| 55 | <p> | ||
| 56 | In general, all layers have a similar structure. | ||
| 57 | They all contain a licensing file | ||
| 58 | (e.g. <code class="filename">COPYING</code>) if the layer is to be | ||
| 59 | distributed, a <code class="filename">README</code> file as good practice | ||
| 60 | and especially if the layer is to be distributed, a | ||
| 61 | configuration directory, and recipe directories. | ||
| 62 | </p> | ||
| 63 | <p> | ||
| 64 | The Yocto Project has many layers that can be used. | ||
| 65 | You can see a web-interface listing of them on the | ||
| 66 | <a class="ulink" href="http://git.yoctoproject.org/" target="_self">Source Repositories</a> | ||
| 67 | page. | ||
| 68 | The layers are shown at the bottom categorized under | ||
| 69 | "Yocto Metadata Layers." | ||
| 70 | These layers are fundamentally a subset of the | ||
| 71 | <a class="ulink" href="http://layers.openembedded.org/layerindex/layers/" target="_self">OpenEmbedded Metadata Index</a>, | ||
| 72 | which lists all layers provided by the OpenEmbedded community. | ||
| 73 | </p> | ||
| 74 | <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"> | ||
| 75 | <h3 class="title">Note</h3> | ||
| 76 | Layers exist in the Yocto Project Source Repositories that | ||
| 77 | cannot be found in the OpenEmbedded Metadata Index. | ||
| 78 | These layers are either deprecated or experimental in nature. | ||
| 79 | </div> | ||
| 80 | <p> | ||
| 81 | </p> | ||
| 82 | <p> | ||
| 83 | BitBake uses the <code class="filename">conf/bblayers.conf</code> file, | ||
| 84 | which is part of the user configuration, to find what layers it | ||
| 85 | should be using as part of the build. | ||
| 86 | </p> | ||
| 87 | <p> | ||
| 88 | For more information on layers, see the | ||
| 89 | "<a class="link" href="../dev-manual/understanding-and-creating-layers.html" target="_self">Understanding and Creating Layers</a>" | ||
| 90 | section in the Yocto Project Development Tasks Manual. | ||
| 91 | </p> | ||
| 92 | </div></body> | ||
| 93 | </html> | ||
diff --git a/documentation/getting-started/eclipse/html/getting-started/metadata-virtual-providers.html b/documentation/getting-started/eclipse/html/getting-started/metadata-virtual-providers.html new file mode 100644 index 0000000000..ebbae37990 --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/metadata-virtual-providers.html | |||
| @@ -0,0 +1,74 @@ | |||
| 1 | <html> | ||
| 2 | <head> | ||
| 3 | <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> | ||
| 4 | <title>3.1.3.Metadata (Virtual Providers)</title> | ||
| 5 | <link rel="stylesheet" type="text/css" href="../book.css"> | ||
| 6 | <meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> | ||
| 7 | <link rel="home" href="index.html" title="Getting Started With Yocto Project"> | ||
| 8 | <link rel="up" href="yocto-project-components.html" title="3.1.Yocto Project Components"> | ||
| 9 | <link rel="prev" href="usingpoky-components-metadata.html" title="3.1.2.Metadata (Recipes)"> | ||
| 10 | <link rel="next" href="usingpoky-components-classes.html" title="3.1.4.Classes"> | ||
| 11 | </head> | ||
| 12 | <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="3.1.3.Metadata (Virtual Providers)"> | ||
| 13 | <div class="titlepage"><div><div><h3 class="title"> | ||
| 14 | <a name="metadata-virtual-providers"></a>3.1.3.Metadata (Virtual Providers)</h3></div></div></div> | ||
| 15 | <p> | ||
| 16 | Prior to the build, if you know that several different recipes | ||
| 17 | provide the same functionality, you can use a virtual provider | ||
| 18 | (i.e. <code class="filename">virtual/*</code>) as a placeholder for the | ||
| 19 | actual provider. | ||
| 20 | The actual provider would be determined at build time. | ||
| 21 | In this case, you should add <code class="filename">virtual/*</code> | ||
| 22 | to | ||
| 23 | <a class="link" href="../ref-manual/var-DEPENDS.html" target="_self"><code class="filename">DEPENDS</code></a>, | ||
| 24 | rather than listing the specified provider. | ||
| 25 | You would select the actual provider by setting the | ||
| 26 | <a class="link" href="../ref-manual/var-PREFERRED_PROVIDER.html" target="_self"><code class="filename">PREFERRED_PROVIDER</code></a> | ||
| 27 | variable (i.e. | ||
| 28 | <code class="filename">PREFERRED_PROVIDER_virtual/*</code>) | ||
| 29 | in the build's configuration file (e.g. | ||
| 30 | <code class="filename">poky/build/conf/local.conf</code>). | ||
| 31 | </p> | ||
| 32 | <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"> | ||
| 33 | <h3 class="title">Note</h3> | ||
| 34 | Any recipe that PROVIDES a <code class="filename">virtual/*</code> | ||
| 35 | item that is ultimately not selected through | ||
| 36 | <code class="filename">PREFERRED_PROVIDER</code> does not get built. | ||
| 37 | Preventing these recipes from building is usually the | ||
| 38 | desired behavior since this mechanism's purpose is to | ||
| 39 | select between mutually exclusive alternative providers. | ||
| 40 | </div> | ||
| 41 | <p> | ||
| 42 | </p> | ||
| 43 | <p> | ||
| 44 | The following lists specific examples of virtual providers: | ||
| 45 | </p> | ||
| 46 | <div class="itemizedlist"><ul class="itemizedlist" type="disc"> | ||
| 47 | <li class="listitem"><p> | ||
| 48 | <code class="filename">virtual/mesa</code>: | ||
| 49 | Provides <code class="filename">gbm.pc</code>. | ||
| 50 | </p></li> | ||
| 51 | <li class="listitem"><p> | ||
| 52 | <code class="filename">virtual/egl</code>: | ||
| 53 | Provides <code class="filename">egl.pc</code> and possibly | ||
| 54 | <code class="filename">wayland-egl.pc</code>. | ||
| 55 | </p></li> | ||
| 56 | <li class="listitem"><p> | ||
| 57 | <code class="filename">virtual/libgl</code>: | ||
| 58 | Provides <code class="filename">gl.pc</code> (i.e. libGL). | ||
| 59 | </p></li> | ||
| 60 | <li class="listitem"><p> | ||
| 61 | <code class="filename">virtual/libgles1</code>: | ||
| 62 | Provides <code class="filename">glesv1_cm.pc</code> | ||
| 63 | (i.e. libGLESv1_CM). | ||
| 64 | </p></li> | ||
| 65 | <li class="listitem"><p> | ||
| 66 | <code class="filename">virtual/libgles2</code>: | ||
| 67 | Provides <code class="filename">glesv2.pc</code> | ||
| 68 | (i.e. libGLESv2). | ||
| 69 | </p></li> | ||
| 70 | </ul></div> | ||
| 71 | <p> | ||
| 72 | </p> | ||
| 73 | </div></body> | ||
| 74 | </html> | ||
diff --git a/documentation/getting-started/eclipse/html/getting-started/open-source-philosophy.html b/documentation/getting-started/eclipse/html/getting-started/open-source-philosophy.html new file mode 100644 index 0000000000..bd9467e001 --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/open-source-philosophy.html | |||
| @@ -0,0 +1,54 @@ | |||
| 1 | <html> | ||
| 2 | <head> | ||
| 3 | <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> | ||
| 4 | <title>2.2.Open Source Philosophy</title> | ||
| 5 | <link rel="stylesheet" type="text/css" href="../book.css"> | ||
| 6 | <meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> | ||
| 7 | <link rel="home" href="index.html" title="Getting Started With Yocto Project"> | ||
| 8 | <link rel="up" href="overview-development-environment.html" title="Chapter2.The Yocto Project Development Environment"> | ||
| 9 | <link rel="prev" href="yp-intro.html" title="2.1.Introduction"> | ||
| 10 | <link rel="next" href="workflows.html" title="2.3.Workflows"> | ||
| 11 | </head> | ||
| 12 | <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="2.2.Open Source Philosophy"> | ||
| 13 | <div class="titlepage"><div><div><h2 class="title" style="clear: both"> | ||
| 14 | <a name="open-source-philosophy"></a>2.2.Open Source Philosophy</h2></div></div></div> | ||
| 15 | <p> | ||
| 16 | Open source philosophy is characterized by software development | ||
| 17 | directed by peer production and collaboration through an active | ||
| 18 | community of developers. | ||
| 19 | Contrast this to the more standard centralized development models | ||
| 20 | used by commercial software companies where a finite set of developers | ||
| 21 | produces a product for sale using a defined set of procedures that | ||
| 22 | ultimately result in an end product whose architecture and source | ||
| 23 | material are closed to the public. | ||
| 24 | </p> | ||
| 25 | <p> | ||
| 26 | Open source projects conceptually have differing concurrent agendas, | ||
| 27 | approaches, and production. | ||
| 28 | These facets of the development process can come from anyone in the | ||
| 29 | public (community) that has a stake in the software project. | ||
| 30 | The open source environment contains new copyright, licensing, domain, | ||
| 31 | and consumer issues that differ from the more traditional development | ||
| 32 | environment. | ||
| 33 | In an open source environment, the end product, source material, | ||
| 34 | and documentation are all available to the public at no cost. | ||
| 35 | </p> | ||
| 36 | <p> | ||
| 37 | A benchmark example of an open source project is the Linux kernel, | ||
| 38 | which was initially conceived and created by Finnish computer science | ||
| 39 | student Linus Torvalds in 1991. | ||
| 40 | Conversely, a good example of a non-open source project is the | ||
| 41 | <span class="trademark">Windows</span> family of operating | ||
| 42 | systems developed by | ||
| 43 | <span class="trademark">Microsoft</span> Corporation. | ||
| 44 | </p> | ||
| 45 | <p> | ||
| 46 | Wikipedia has a good historical description of the Open Source | ||
| 47 | Philosophy | ||
| 48 | <a class="ulink" href="http://en.wikipedia.org/wiki/Open_source" target="_self">here</a>. | ||
| 49 | You can also find helpful information on how to participate in the | ||
| 50 | Linux Community | ||
| 51 | <a class="ulink" href="http://ldn.linuxfoundation.org/book/how-participate-linux-community" target="_self">here</a>. | ||
| 52 | </p> | ||
| 53 | </div></body> | ||
| 54 | </html> | ||
diff --git a/documentation/getting-started/eclipse/html/getting-started/other-variables-related-to-commercial-licenses.html b/documentation/getting-started/eclipse/html/getting-started/other-variables-related-to-commercial-licenses.html new file mode 100644 index 0000000000..73d152bb40 --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/other-variables-related-to-commercial-licenses.html | |||
| @@ -0,0 +1,59 @@ | |||
| 1 | <html> | ||
| 2 | <head> | ||
| 3 | <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> | ||
| 4 | <title>3.7.2.2.Other Variables Related to Commercial Licenses</title> | ||
| 5 | <link rel="stylesheet" type="text/css" href="../book.css"> | ||
| 6 | <meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> | ||
| 7 | <link rel="home" href="index.html" title="Getting Started With Yocto Project"> | ||
| 8 | <link rel="up" href="enabling-commercially-licensed-recipes.html" title="3.7.2.Enabling Commercially Licensed Recipes"> | ||
| 9 | <link rel="prev" href="license-flag-matching.html" title="3.7.2.1.License Flag Matching"> | ||
| 10 | <link rel="next" href="x32.html" title="3.8.x32 psABI"> | ||
| 11 | </head> | ||
| 12 | <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="3.7.2.2.Other Variables Related to Commercial Licenses"> | ||
| 13 | <div class="titlepage"><div><div><h4 class="title"> | ||
| 14 | <a name="other-variables-related-to-commercial-licenses"></a>3.7.2.2.Other Variables Related to Commercial Licenses</h4></div></div></div> | ||
| 15 | <p> | ||
| 16 | Other helpful variables related to commercial | ||
| 17 | license handling exist and are defined in the | ||
| 18 | <code class="filename">poky/meta/conf/distro/include/default-distrovars.inc</code> file: | ||
| 19 | </p> | ||
| 20 | <pre class="literallayout"> | ||
| 21 | COMMERCIAL_AUDIO_PLUGINS ?= "" | ||
| 22 | COMMERCIAL_VIDEO_PLUGINS ?= "" | ||
| 23 | </pre> | ||
| 24 | <p> | ||
| 25 | If you want to enable these components, you can do so by | ||
| 26 | making sure you have statements similar to the following | ||
| 27 | in your <code class="filename">local.conf</code> configuration file: | ||
| 28 | </p> | ||
| 29 | <pre class="literallayout"> | ||
| 30 | COMMERCIAL_AUDIO_PLUGINS = "gst-plugins-ugly-mad \ | ||
| 31 | gst-plugins-ugly-mpegaudioparse" | ||
| 32 | COMMERCIAL_VIDEO_PLUGINS = "gst-plugins-ugly-mpeg2dec \ | ||
| 33 | gst-plugins-ugly-mpegstream gst-plugins-bad-mpegvideoparse" | ||
| 34 | LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly commercial_gst-plugins-bad commercial_qmmp" | ||
| 35 | </pre> | ||
| 36 | <p> | ||
| 37 | Of course, you could also create a matching whitelist | ||
| 38 | for those components using the more general "commercial" | ||
| 39 | in the whitelist, but that would also enable all the | ||
| 40 | other packages with | ||
| 41 | <a class="link" href="../ref-manual/var-LICENSE_FLAGS.html" target="_self"><code class="filename">LICENSE_FLAGS</code></a> | ||
| 42 | containing "commercial", which you may or may not want: | ||
| 43 | </p> | ||
| 44 | <pre class="literallayout"> | ||
| 45 | LICENSE_FLAGS_WHITELIST = "commercial" | ||
| 46 | </pre> | ||
| 47 | <p> | ||
| 48 | </p> | ||
| 49 | <p> | ||
| 50 | Specifying audio and video plug-ins as part of the | ||
| 51 | <code class="filename">COMMERCIAL_AUDIO_PLUGINS</code> and | ||
| 52 | <code class="filename">COMMERCIAL_VIDEO_PLUGINS</code> statements | ||
| 53 | (along with the enabling | ||
| 54 | <code class="filename">LICENSE_FLAGS_WHITELIST</code>) includes the | ||
| 55 | plug-ins or components into built images, thus adding | ||
| 56 | support for media formats or components. | ||
| 57 | </p> | ||
| 58 | </div></body> | ||
| 59 | </html> | ||
diff --git a/documentation/getting-started/eclipse/html/getting-started/overall-architecture.html b/documentation/getting-started/eclipse/html/getting-started/overall-architecture.html new file mode 100644 index 0000000000..974b05792a --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/overall-architecture.html | |||
| @@ -0,0 +1,40 @@ | |||
| 1 | <html> | ||
| 2 | <head> | ||
| 3 | <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> | ||
| 4 | <title>3.3.1.Overall Architecture</title> | ||
| 5 | <link rel="stylesheet" type="text/css" href="../book.css"> | ||
| 6 | <meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> | ||
| 7 | <link rel="home" href="index.html" title="Getting Started With Yocto Project"> | ||
| 8 | <link rel="up" href="shared-state-cache.html" title="3.3.Shared State Cache"> | ||
| 9 | <link rel="prev" href="shared-state-cache.html" title="3.3.Shared State Cache"> | ||
| 10 | <link rel="next" href="overview-checksums.html" title="3.3.2.Checksums (Signatures)"> | ||
| 11 | </head> | ||
| 12 | <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="3.3.1.Overall Architecture"> | ||
| 13 | <div class="titlepage"><div><div><h3 class="title"> | ||
| 14 | <a name="overall-architecture"></a>3.3.1.Overall Architecture</h3></div></div></div> | ||
| 15 | <p> | ||
| 16 | When determining what parts of the system need to be built, | ||
| 17 | BitBake works on a per-task basis rather than a per-recipe | ||
| 18 | basis. | ||
| 19 | You might wonder why using a per-task basis is preferred over | ||
| 20 | a per-recipe basis. | ||
| 21 | To help explain, consider having the IPK packaging backend | ||
| 22 | enabled and then switching to DEB. | ||
| 23 | In this case, the | ||
| 24 | <a class="link" href="../ref-manual/ref-tasks-install.html" target="_self"><code class="filename">do_install</code></a> | ||
| 25 | and | ||
| 26 | <a class="link" href="../ref-manual/ref-tasks-package.html" target="_self"><code class="filename">do_package</code></a> | ||
| 27 | task outputs are still valid. | ||
| 28 | However, with a per-recipe approach, the build would not | ||
| 29 | include the <code class="filename">.deb</code> files. | ||
| 30 | Consequently, you would have to invalidate the whole build and | ||
| 31 | rerun it. | ||
| 32 | Rerunning everything is not the best solution. | ||
| 33 | Also, in this case, the core must be "taught" much about | ||
| 34 | specific tasks. | ||
| 35 | This methodology does not scale well and does not allow users | ||
| 36 | to easily add new tasks in layers or as external recipes | ||
| 37 | without touching the packaged-staging core. | ||
| 38 | </p> | ||
| 39 | </div></body> | ||
| 40 | </html> | ||
diff --git a/documentation/getting-started/eclipse/html/getting-started/overview-checksums.html b/documentation/getting-started/eclipse/html/getting-started/overview-checksums.html new file mode 100644 index 0000000000..09ad110f71 --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/overview-checksums.html | |||
| @@ -0,0 +1,209 @@ | |||
| 1 | <html> | ||
| 2 | <head> | ||
| 3 | <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> | ||
| 4 | <title>3.3.2.Checksums (Signatures)</title> | ||
| 5 | <link rel="stylesheet" type="text/css" href="../book.css"> | ||
| 6 | <meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> | ||
| 7 | <link rel="home" href="index.html" title="Getting Started With Yocto Project"> | ||
| 8 | <link rel="up" href="shared-state-cache.html" title="3.3.Shared State Cache"> | ||
| 9 | <link rel="prev" href="overall-architecture.html" title="3.3.1.Overall Architecture"> | ||
| 10 | <link rel="next" href="shared-state.html" title="3.3.3.Shared State"> | ||
| 11 | </head> | ||
| 12 | <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="3.3.2.Checksums (Signatures)"> | ||
| 13 | <div class="titlepage"><div><div><h3 class="title"> | ||
| 14 | <a name="overview-checksums"></a>3.3.2.Checksums (Signatures)</h3></div></div></div> | ||
| 15 | <p> | ||
| 16 | The shared state code uses a checksum, which is a unique | ||
| 17 | signature of a task's inputs, to determine if a task needs to | ||
| 18 | be run again. | ||
| 19 | Because it is a change in a task's inputs that triggers a | ||
| 20 | rerun, the process needs to detect all the inputs to a given | ||
| 21 | task. | ||
| 22 | For shell tasks, this turns out to be fairly easy because | ||
| 23 | the build process generates a "run" shell script for each task | ||
| 24 | and it is possible to create a checksum that gives you a good | ||
| 25 | idea of when the task's data changes. | ||
| 26 | </p> | ||
| 27 | <p> | ||
| 28 | To complicate the problem, there are things that should not be | ||
| 29 | included in the checksum. | ||
| 30 | First, there is the actual specific build path of a given | ||
| 31 | task - the | ||
| 32 | <a class="link" href="../ref-manual/var-WORKDIR.html" target="_self"><code class="filename">WORKDIR</code></a>. | ||
| 33 | It does not matter if the work directory changes because it | ||
| 34 | should not affect the output for target packages. | ||
| 35 | Also, the build process has the objective of making native | ||
| 36 | or cross packages relocatable. | ||
| 37 | </p> | ||
| 38 | <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"> | ||
| 39 | <h3 class="title">Note</h3> | ||
| 40 | Both native and cross packages run on the build host. | ||
| 41 | However, cross packages generate output for the target | ||
| 42 | architecture. | ||
| 43 | </div> | ||
| 44 | <p> | ||
| 45 | The checksum therefore needs to exclude | ||
| 46 | <code class="filename">WORKDIR</code>. | ||
| 47 | The simplistic approach for excluding the work directory is to | ||
| 48 | set <code class="filename">WORKDIR</code> to some fixed value and | ||
| 49 | create the checksum for the "run" script. | ||
| 50 | </p> | ||
| 51 | <p> | ||
| 52 | Another problem results from the "run" scripts containing | ||
| 53 | functions that might or might not get called. | ||
| 54 | The incremental build solution contains code that figures out | ||
| 55 | dependencies between shell functions. | ||
| 56 | This code is used to prune the "run" scripts down to the | ||
| 57 | minimum set, thereby alleviating this problem and making the | ||
| 58 | "run" scripts much more readable as a bonus. | ||
| 59 | </p> | ||
| 60 | <p> | ||
| 61 | So far we have solutions for shell scripts. | ||
| 62 | What about Python tasks? | ||
| 63 | The same approach applies even though these tasks are more | ||
| 64 | difficult. | ||
| 65 | The process needs to figure out what variables a Python | ||
| 66 | function accesses and what functions it calls. | ||
| 67 | Again, the incremental build solution contains code that first | ||
| 68 | figures out the variable and function dependencies, and then | ||
| 69 | creates a checksum for the data used as the input to the task. | ||
| 70 | </p> | ||
| 71 | <p> | ||
| 72 | Like the <code class="filename">WORKDIR</code> case, situations exist | ||
| 73 | where dependencies should be ignored. | ||
| 74 | For these cases, you can instruct the build process to | ||
| 75 | ignore a dependency by using a line like the following: | ||
| 76 | </p> | ||
| 77 | <pre class="literallayout"> | ||
| 78 | PACKAGE_ARCHS[vardepsexclude] = "MACHINE" | ||
| 79 | </pre> | ||
| 80 | <p> | ||
| 81 | This example ensures that the | ||
| 82 | <a class="link" href="../ref-manual/var-PACKAGE_ARCHS.html" target="_self"><code class="filename">PACKAGE_ARCHS</code></a> | ||
| 83 | variable does not depend on the value of | ||
| 84 | <a class="link" href="../ref-manual/var-MACHINE.html" target="_self"><code class="filename">MACHINE</code></a>, | ||
| 85 | even if it does reference it. | ||
| 86 | </p> | ||
| 87 | <p> | ||
| 88 | Equally, there are cases where we need to add dependencies | ||
| 89 | BitBake is not able to find. | ||
| 90 | You can accomplish this by using a line like the following: | ||
| 91 | </p> | ||
| 92 | <pre class="literallayout"> | ||
| 93 | PACKAGE_ARCHS[vardeps] = "MACHINE" | ||
| 94 | </pre> | ||
| 95 | <p> | ||
| 96 | This example explicitly adds the <code class="filename">MACHINE</code> | ||
| 97 | variable as a dependency for | ||
| 98 | <code class="filename">PACKAGE_ARCHS</code>. | ||
| 99 | </p> | ||
| 100 | <p> | ||
| 101 | Consider a case with in-line Python, for example, where | ||
| 102 | BitBake is not able to figure out dependencies. | ||
| 103 | When running in debug mode (i.e. using | ||
| 104 | <code class="filename">-DDD</code>), BitBake produces output when it | ||
| 105 | discovers something for which it cannot figure out dependencies. | ||
| 106 | The Yocto Project team has currently not managed to cover | ||
| 107 | those dependencies in detail and is aware of the need to fix | ||
| 108 | this situation. | ||
| 109 | </p> | ||
| 110 | <p> | ||
| 111 | Thus far, this section has limited discussion to the direct | ||
| 112 | inputs into a task. | ||
| 113 | Information based on direct inputs is referred to as the | ||
| 114 | "basehash" in the code. | ||
| 115 | However, there is still the question of a task's indirect | ||
| 116 | inputs - the things that were already built and present in the | ||
| 117 | <a class="link" href="../ref-manual/build-directory.html" target="_self">Build Directory</a>. | ||
| 118 | The checksum (or signature) for a particular task needs to add | ||
| 119 | the hashes of all the tasks on which the particular task | ||
| 120 | depends. | ||
| 121 | Choosing which dependencies to add is a policy decision. | ||
| 122 | However, the effect is to generate a master checksum that | ||
| 123 | combines the basehash and the hashes of the task's | ||
| 124 | dependencies. | ||
| 125 | </p> | ||
| 126 | <p> | ||
| 127 | At the code level, there are a variety of ways both the | ||
| 128 | basehash and the dependent task hashes can be influenced. | ||
| 129 | Within the BitBake configuration file, we can give BitBake | ||
| 130 | some extra information to help it construct the basehash. | ||
| 131 | The following statement effectively results in a list of | ||
| 132 | global variable dependency excludes - variables never | ||
| 133 | included in any checksum: | ||
| 134 | </p> | ||
| 135 | <pre class="literallayout"> | ||
| 136 | BB_HASHBASE_WHITELIST ?= "TMPDIR FILE PATH PWD BB_TASKHASH BBPATH DL_DIR \ | ||
| 137 | SSTATE_DIR THISDIR FILESEXTRAPATHS FILE_DIRNAME HOME LOGNAME SHELL TERM \ | ||
| 138 | USER FILESPATH STAGING_DIR_HOST STAGING_DIR_TARGET COREBASE PRSERV_HOST \ | ||
| 139 | PRSERV_DUMPDIR PRSERV_DUMPFILE PRSERV_LOCKDOWN PARALLEL_MAKE \ | ||
| 140 | CCACHE_DIR EXTERNAL_TOOLCHAIN CCACHE CCACHE_DISABLE LICENSE_PATH SDKPKGSUFFIX" | ||
| 141 | </pre> | ||
| 142 | <p> | ||
| 143 | The previous example excludes | ||
| 144 | <a class="link" href="../ref-manual/var-WORKDIR.html" target="_self"><code class="filename">WORKDIR</code></a> | ||
| 145 | since that variable is actually constructed as a path within | ||
| 146 | <a class="link" href="../ref-manual/var-TMPDIR.html" target="_self"><code class="filename">TMPDIR</code></a>, | ||
| 147 | which is on the whitelist. | ||
| 148 | </p> | ||
| 149 | <p> | ||
| 150 | The rules for deciding which hashes of dependent tasks to | ||
| 151 | include through dependency chains are more complex and are | ||
| 152 | generally accomplished with a Python function. | ||
| 153 | The code in <code class="filename">meta/lib/oe/sstatesig.py</code> shows | ||
| 154 | two examples of this and also illustrates how you can insert | ||
| 155 | your own policy into the system if so desired. | ||
| 156 | This file defines the two basic signature generators | ||
| 157 | <a class="link" href="../ref-manual/oe-core.html" target="_self">OE-Core</a> | ||
| 158 | uses: "OEBasic" and "OEBasicHash". | ||
| 159 | By default, there is a dummy "noop" signature handler enabled | ||
| 160 | in BitBake. | ||
| 161 | This means that behavior is unchanged from previous versions. | ||
| 162 | OE-Core uses the "OEBasicHash" signature handler by default | ||
| 163 | through this setting in the <code class="filename">bitbake.conf</code> | ||
| 164 | file: | ||
| 165 | </p> | ||
| 166 | <pre class="literallayout"> | ||
| 167 | BB_SIGNATURE_HANDLER ?= "OEBasicHash" | ||
| 168 | </pre> | ||
| 169 | <p> | ||
| 170 | The "OEBasicHash" <code class="filename">BB_SIGNATURE_HANDLER</code> | ||
| 171 | is the same as the "OEBasic" version but adds the task hash to | ||
| 172 | the stamp files. | ||
| 173 | This results in any | ||
| 174 | <a class="link" href="../ref-manual/metadata.html" target="_self">Metadata</a> | ||
| 175 | change that changes the task hash, automatically | ||
| 176 | causing the task to be run again. | ||
| 177 | This removes the need to bump | ||
| 178 | <a class="link" href="../ref-manual/var-PR.html" target="_self"><code class="filename">PR</code></a> | ||
| 179 | values, and changes to Metadata automatically ripple across | ||
| 180 | the build. | ||
| 181 | </p> | ||
| 182 | <p> | ||
| 183 | It is also worth noting that the end result of these | ||
| 184 | signature generators is to make some dependency and hash | ||
| 185 | information available to the build. | ||
| 186 | This information includes: | ||
| 187 | </p> | ||
| 188 | <div class="itemizedlist"><ul class="itemizedlist" type="disc"> | ||
| 189 | <li class="listitem"><p> | ||
| 190 | <code class="filename">BB_BASEHASH_task-</code><em class="replaceable"><code>taskname</code></em>: | ||
| 191 | The base hashes for each task in the recipe. | ||
| 192 | </p></li> | ||
| 193 | <li class="listitem"><p> | ||
| 194 | <code class="filename">BB_BASEHASH_</code><em class="replaceable"><code>filename</code></em><code class="filename">:</code><em class="replaceable"><code>taskname</code></em>: | ||
| 195 | The base hashes for each dependent task. | ||
| 196 | </p></li> | ||
| 197 | <li class="listitem"><p> | ||
| 198 | <code class="filename">BBHASHDEPS_</code><em class="replaceable"><code>filename</code></em><code class="filename">:</code><em class="replaceable"><code>taskname</code></em>: | ||
| 199 | The task dependencies for each task. | ||
| 200 | </p></li> | ||
| 201 | <li class="listitem"><p> | ||
| 202 | <code class="filename">BB_TASKHASH</code>: | ||
| 203 | The hash of the currently running task. | ||
| 204 | </p></li> | ||
| 205 | </ul></div> | ||
| 206 | <p> | ||
| 207 | </p> | ||
| 208 | </div></body> | ||
| 209 | </html> | ||
diff --git a/documentation/getting-started/eclipse/html/getting-started/overview-concepts.html b/documentation/getting-started/eclipse/html/getting-started/overview-concepts.html new file mode 100644 index 0000000000..855d22e109 --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/overview-concepts.html | |||
| @@ -0,0 +1,57 @@ | |||
| 1 | <html> | ||
| 2 | <head> | ||
| 3 | <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> | ||
| 4 | <title>Chapter3.Yocto Project Concepts</title> | ||
| 5 | <link rel="stylesheet" type="text/css" href="../book.css"> | ||
| 6 | <meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> | ||
| 7 | <link rel="home" href="index.html" title="Getting Started With Yocto Project"> | ||
| 8 | <link rel="up" href="index.html" title="Getting Started With Yocto Project"> | ||
| 9 | <link rel="prev" href="sdk-dev-environment.html" title="2.8.7.Application Development SDK"> | ||
| 10 | <link rel="next" href="yocto-project-components.html" title="3.1.Yocto Project Components"> | ||
| 11 | </head> | ||
| 12 | <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="chapter" title="Chapter3.Yocto Project Concepts"> | ||
| 13 | <div class="titlepage"><div><div><h2 class="title"> | ||
| 14 | <a name="overview-concepts"></a>Chapter3.Yocto Project Concepts</h2></div></div></div> | ||
| 15 | <div class="toc"> | ||
| 16 | <p><b>Table of Contents</b></p> | ||
| 17 | <dl> | ||
| 18 | <dt><span class="section"><a href="yocto-project-components.html">3.1. Yocto Project Components</a></span></dt> | ||
| 19 | <dd><dl> | ||
| 20 | <dt><span class="section"><a href="usingpoky-components-bitbake.html">3.1.1. BitBake</a></span></dt> | ||
| 21 | <dt><span class="section"><a href="usingpoky-components-metadata.html">3.1.2. Metadata (Recipes)</a></span></dt> | ||
| 22 | <dt><span class="section"><a href="metadata-virtual-providers.html">3.1.3. Metadata (Virtual Providers)</a></span></dt> | ||
| 23 | <dt><span class="section"><a href="usingpoky-components-classes.html">3.1.4. Classes</a></span></dt> | ||
| 24 | <dt><span class="section"><a href="usingpoky-components-configuration.html">3.1.5. Configuration</a></span></dt> | ||
| 25 | </dl></dd> | ||
| 26 | <dt><span class="section"><a href="cross-development-toolchain-generation.html">3.2. Cross-Development Toolchain Generation</a></span></dt> | ||
| 27 | <dt><span class="section"><a href="shared-state-cache.html">3.3. Shared State Cache</a></span></dt> | ||
| 28 | <dd><dl> | ||
| 29 | <dt><span class="section"><a href="overall-architecture.html">3.3.1. Overall Architecture</a></span></dt> | ||
| 30 | <dt><span class="section"><a href="overview-checksums.html">3.3.2. Checksums (Signatures)</a></span></dt> | ||
| 31 | <dt><span class="section"><a href="shared-state.html">3.3.3. Shared State</a></span></dt> | ||
| 32 | <dt><span class="section"><a href="tips-and-tricks.html">3.3.4. Tips and Tricks</a></span></dt> | ||
| 33 | </dl></dd> | ||
| 34 | <dt><span class="section"><a href="automatically-added-runtime-dependencies.html">3.4. Automatically Added Runtime Dependencies</a></span></dt> | ||
| 35 | <dt><span class="section"><a href="fakeroot-and-pseudo.html">3.5. Fakeroot and Pseudo</a></span></dt> | ||
| 36 | <dt><span class="section"><a href="wayland.html">3.6. Wayland</a></span></dt> | ||
| 37 | <dd><dl> | ||
| 38 | <dt><span class="section"><a href="wayland-support.html">3.6.1. Support</a></span></dt> | ||
| 39 | <dt><span class="section"><a href="enabling-wayland-in-an-image.html">3.6.2. Enabling Wayland in an Image</a></span></dt> | ||
| 40 | <dt><span class="section"><a href="running-weston.html">3.6.3. Running Weston</a></span></dt> | ||
| 41 | </dl></dd> | ||
| 42 | <dt><span class="section"><a href="overview-licenses.html">3.7. Licenses</a></span></dt> | ||
| 43 | <dd><dl> | ||
| 44 | <dt><span class="section"><a href="usingpoky-configuring-LIC_FILES_CHKSUM.html">3.7.1. Tracking License Changes</a></span></dt> | ||
| 45 | <dt><span class="section"><a href="enabling-commercially-licensed-recipes.html">3.7.2. Enabling Commercially Licensed Recipes</a></span></dt> | ||
| 46 | </dl></dd> | ||
| 47 | <dt><span class="section"><a href="x32.html">3.8. x32 psABI</a></span></dt> | ||
| 48 | </dl> | ||
| 49 | </div> | ||
| 50 | <p> | ||
| 51 | This chapter describes concepts for various areas of the Yocto Project. | ||
| 52 | Currently, topics include Yocto Project components, cross-development | ||
| 53 | generation, shared state (sstate) cache, runtime dependencies, | ||
| 54 | Pseudo and Fakeroot, x32 psABI, Wayland support, and Licenses. | ||
| 55 | </p> | ||
| 56 | </div></body> | ||
| 57 | </html> | ||
diff --git a/documentation/getting-started/eclipse/html/getting-started/overview-debugging.html b/documentation/getting-started/eclipse/html/getting-started/overview-debugging.html new file mode 100644 index 0000000000..b8b4c880e7 --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/overview-debugging.html | |||
| @@ -0,0 +1,28 @@ | |||
| 1 | <html> | ||
| 2 | <head> | ||
| 3 | <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> | ||
| 4 | <title>3.3.4.1.Debugging</title> | ||
| 5 | <link rel="stylesheet" type="text/css" href="../book.css"> | ||
| 6 | <meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> | ||
| 7 | <link rel="home" href="index.html" title="Getting Started With Yocto Project"> | ||
| 8 | <link rel="up" href="tips-and-tricks.html" title="3.3.4.Tips and Tricks"> | ||
| 9 | <link rel="prev" href="tips-and-tricks.html" title="3.3.4.Tips and Tricks"> | ||
| 10 | <link rel="next" href="invalidating-shared-state.html" title="3.3.4.2.Invalidating Shared State"> | ||
| 11 | </head> | ||
| 12 | <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="3.3.4.1.Debugging"> | ||
| 13 | <div class="titlepage"><div><div><h4 class="title"> | ||
| 14 | <a name="overview-debugging"></a>3.3.4.1.Debugging</h4></div></div></div> | ||
| 15 | <p> | ||
| 16 | Seeing what metadata went into creating the input signature | ||
| 17 | of a shared state (sstate) task can be a useful debugging | ||
| 18 | aid. | ||
| 19 | This information is available in signature information | ||
| 20 | (<code class="filename">siginfo</code>) files in | ||
| 21 | <a class="link" href="../ref-manual/var-SSTATE_DIR.html" target="_self"><code class="filename">SSTATE_DIR</code></a>. | ||
| 22 | For information on how to view and interpret information in | ||
| 23 | <code class="filename">siginfo</code> files, see the | ||
| 24 | "<a class="link" href="../dev-manual/dev-viewing-task-variable-dependencies.html" target="_self">Viewing Task Variable Dependencies</a>" | ||
| 25 | section in the Yocto Project Development Tasks Manual. | ||
| 26 | </p> | ||
| 27 | </div></body> | ||
| 28 | </html> | ||
diff --git a/documentation/getting-started/eclipse/html/getting-started/overview-development-environment.html b/documentation/getting-started/eclipse/html/getting-started/overview-development-environment.html new file mode 100644 index 0000000000..c8030fee19 --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/overview-development-environment.html | |||
| @@ -0,0 +1,56 @@ | |||
| 1 | <html> | ||
| 2 | <head> | ||
| 3 | <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> | ||
| 4 | <title>Chapter2.The Yocto Project Development Environment</title> | ||
| 5 | <link rel="stylesheet" type="text/css" href="../book.css"> | ||
| 6 | <meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> | ||
| 7 | <link rel="home" href="index.html" title="Getting Started With Yocto Project"> | ||
| 8 | <link rel="up" href="index.html" title="Getting Started With Yocto Project"> | ||
| 9 | <link rel="prev" href="overview-other-information.html" title="1.2.Other Information"> | ||
| 10 | <link rel="next" href="yp-intro.html" title="2.1.Introduction"> | ||
| 11 | </head> | ||
| 12 | <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="chapter" title="Chapter2.The Yocto Project Development Environment"> | ||
| 13 | <div class="titlepage"><div><div><h2 class="title"> | ||
| 14 | <a name="overview-development-environment"></a>Chapter2.The Yocto Project Development Environment</h2></div></div></div> | ||
| 15 | <div class="toc"> | ||
| 16 | <p><b>Table of Contents</b></p> | ||
| 17 | <dl> | ||
| 18 | <dt><span class="section"><a href="yp-intro.html">2.1. Introduction</a></span></dt> | ||
| 19 | <dt><span class="section"><a href="open-source-philosophy.html">2.2. Open Source Philosophy</a></span></dt> | ||
| 20 | <dt><span class="section"><a href="workflows.html">2.3. Workflows</a></span></dt> | ||
| 21 | <dt><span class="section"><a href="git.html">2.4. Git</a></span></dt> | ||
| 22 | <dd><dl> | ||
| 23 | <dt><span class="section"><a href="repositories-tags-and-branches.html">2.4.1. Repositories, Tags, and Branches</a></span></dt> | ||
| 24 | <dt><span class="section"><a href="basic-commands.html">2.4.2. Basic Commands</a></span></dt> | ||
| 25 | </dl></dd> | ||
| 26 | <dt><span class="section"><a href="yocto-project-repositories.html">2.5. Yocto Project Source Repositories</a></span></dt> | ||
| 27 | <dt><span class="section"><a href="licensing.html">2.6. Licensing</a></span></dt> | ||
| 28 | <dt><span class="section"><a href="recipe-syntax.html">2.7. Recipe Syntax</a></span></dt> | ||
| 29 | <dt><span class="section"><a href="development-concepts.html">2.8. Development Concepts</a></span></dt> | ||
| 30 | <dd><dl> | ||
| 31 | <dt><span class="section"><a href="user-configuration.html">2.8.1. User Configuration</a></span></dt> | ||
| 32 | <dt><span class="section"><a href="metadata-machine-configuration-and-policy-configuration.html">2.8.2. Metadata, Machine Configuration, and Policy Configuration</a></span></dt> | ||
| 33 | <dt><span class="section"><a href="sources-dev-environment.html">2.8.3. Sources</a></span></dt> | ||
| 34 | <dt><span class="section"><a href="package-feeds-dev-environment.html">2.8.4. Package Feeds</a></span></dt> | ||
| 35 | <dt><span class="section"><a href="bitbake-dev-environment.html">2.8.5. BitBake</a></span></dt> | ||
| 36 | <dt><span class="section"><a href="images-dev-environment.html">2.8.6. Images</a></span></dt> | ||
| 37 | <dt><span class="section"><a href="sdk-dev-environment.html">2.8.7. Application Development SDK</a></span></dt> | ||
| 38 | </dl></dd> | ||
| 39 | </dl> | ||
| 40 | </div> | ||
| 41 | <p> | ||
| 42 | This chapter takes a look at the Yocto Project development | ||
| 43 | environment and also provides a detailed look at what goes on during | ||
| 44 | development in that environment. | ||
| 45 | The chapter provides Yocto Project Development environment concepts that | ||
| 46 | help you understand how work is accomplished in an open source environment, | ||
| 47 | which is very different as compared to work accomplished in a closed, | ||
| 48 | proprietary environment. | ||
| 49 | </p> | ||
| 50 | <p> | ||
| 51 | Specifically, this chapter addresses open source philosophy, workflows, | ||
| 52 | Git, source repositories, licensing, recipe syntax, and development | ||
| 53 | syntax. | ||
| 54 | </p> | ||
| 55 | </div></body> | ||
| 56 | </html> | ||
diff --git a/documentation/getting-started/eclipse/html/getting-started/overview-licenses.html b/documentation/getting-started/eclipse/html/getting-started/overview-licenses.html new file mode 100644 index 0000000000..eca1f71d2d --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/overview-licenses.html | |||
| @@ -0,0 +1,29 @@ | |||
| 1 | <html> | ||
| 2 | <head> | ||
| 3 | <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> | ||
| 4 | <title>3.7.Licenses</title> | ||
| 5 | <link rel="stylesheet" type="text/css" href="../book.css"> | ||
| 6 | <meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> | ||
| 7 | <link rel="home" href="index.html" title="Getting Started With Yocto Project"> | ||
| 8 | <link rel="up" href="overview-concepts.html" title="Chapter3.Yocto Project Concepts"> | ||
| 9 | <link rel="prev" href="running-weston.html" title="3.6.3.Running Weston"> | ||
| 10 | <link rel="next" href="usingpoky-configuring-LIC_FILES_CHKSUM.html" title="3.7.1.Tracking License Changes"> | ||
| 11 | </head> | ||
| 12 | <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="3.7.Licenses"> | ||
| 13 | <div class="titlepage"><div><div><h2 class="title" style="clear: both"> | ||
| 14 | <a name="overview-licenses"></a>3.7.Licenses</h2></div></div></div> | ||
| 15 | <p> | ||
| 16 | This section describes the mechanism by which the OpenEmbedded | ||
| 17 | build system tracks changes to licensing text. | ||
| 18 | The section also describes how to enable commercially licensed | ||
| 19 | recipes, which by default are disabled. | ||
| 20 | </p> | ||
| 21 | <p> | ||
| 22 | For information that can help you maintain compliance with | ||
| 23 | various open source licensing during the lifecycle of the product, | ||
| 24 | see the | ||
| 25 | "<a class="link" href="../dev-manual/maintaining-open-source-license-compliance-during-your-products-lifecycle.html" target="_self">Maintaining Open Source License Compliance During Your Project's Lifecycle</a>" | ||
| 26 | section in the Yocto Project Development Tasks Manual. | ||
| 27 | </p> | ||
| 28 | </div></body> | ||
| 29 | </html> | ||
diff --git a/documentation/getting-started/eclipse/html/getting-started/overview-manual-intro.html b/documentation/getting-started/eclipse/html/getting-started/overview-manual-intro.html new file mode 100644 index 0000000000..ab4e1f338f --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/overview-manual-intro.html | |||
| @@ -0,0 +1,23 @@ | |||
| 1 | <html> | ||
| 2 | <head> | ||
| 3 | <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> | ||
| 4 | <title>Chapter1.The Yocto Project Overview Manual</title> | ||
| 5 | <link rel="stylesheet" type="text/css" href="../book.css"> | ||
| 6 | <meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> | ||
| 7 | <link rel="home" href="index.html" title="Getting Started With Yocto Project"> | ||
| 8 | <link rel="up" href="index.html" title="Getting Started With Yocto Project"> | ||
| 9 | <link rel="prev" href="index.html" title="Getting Started With Yocto Project"> | ||
| 10 | <link rel="next" href="overview-welcome.html" title="1.1.Welcome"> | ||
| 11 | </head> | ||
| 12 | <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="chapter" title="Chapter1.The Yocto Project Overview Manual"> | ||
| 13 | <div class="titlepage"><div><div><h2 class="title"> | ||
| 14 | <a name="overview-manual-intro"></a>Chapter1.The Yocto Project Overview Manual</h2></div></div></div> | ||
| 15 | <div class="toc"> | ||
| 16 | <p><b>Table of Contents</b></p> | ||
| 17 | <dl> | ||
| 18 | <dt><span class="section"><a href="overview-welcome.html">1.1. Welcome</a></span></dt> | ||
| 19 | <dt><span class="section"><a href="overview-other-information.html">1.2. Other Information</a></span></dt> | ||
| 20 | </dl> | ||
| 21 | </div> | ||
| 22 | </div></body> | ||
| 23 | </html> | ||
diff --git a/documentation/getting-started/eclipse/html/getting-started/overview-other-information.html b/documentation/getting-started/eclipse/html/getting-started/overview-other-information.html new file mode 100644 index 0000000000..03210c6ebf --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/overview-other-information.html | |||
| @@ -0,0 +1,31 @@ | |||
| 1 | <html> | ||
| 2 | <head> | ||
| 3 | <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> | ||
| 4 | <title>1.2.Other Information</title> | ||
| 5 | <link rel="stylesheet" type="text/css" href="../book.css"> | ||
| 6 | <meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> | ||
| 7 | <link rel="home" href="index.html" title="Getting Started With Yocto Project"> | ||
| 8 | <link rel="up" href="overview-manual-intro.html" title="Chapter1.The Yocto Project Overview Manual"> | ||
| 9 | <link rel="prev" href="overview-welcome.html" title="1.1.Welcome"> | ||
| 10 | <link rel="next" href="overview-development-environment.html" title="Chapter2.The Yocto Project Development Environment"> | ||
| 11 | </head> | ||
| 12 | <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="1.2.Other Information"> | ||
| 13 | <div class="titlepage"><div><div><h2 class="title" style="clear: both"> | ||
| 14 | <a name="overview-other-information"></a>1.2.Other Information</h2></div></div></div> | ||
| 15 | <p> | ||
| 16 | Because this manual presents information for many different | ||
| 17 | topics, supplemental information is recommended for full | ||
| 18 | comprehension. | ||
| 19 | For additional introductory information on the Yocto Project, see | ||
| 20 | the <a class="ulink" href="http://www.yoctoproject.org" target="_self">Yocto Project Website</a>. | ||
| 21 | You can find an introductory to using the Yocto Project by working | ||
| 22 | through the | ||
| 23 | <a class="link" href="../yocto-project-qs/index.html" target="_self">Yocto Project Quick Start</a>. | ||
| 24 | </p> | ||
| 25 | <p> | ||
| 26 | For a comprehensive list of links and other documentation, see the | ||
| 27 | "<a class="link" href="../ref-manual/resources-links-and-related-documentation.html" target="_self">Links and Related Documentation</a>" | ||
| 28 | section in the Yocto Project Reference Manual. | ||
| 29 | </p> | ||
| 30 | </div></body> | ||
| 31 | </html> | ||
diff --git a/documentation/getting-started/eclipse/html/getting-started/overview-welcome.html b/documentation/getting-started/eclipse/html/getting-started/overview-welcome.html new file mode 100644 index 0000000000..1bc34e081c --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/overview-welcome.html | |||
| @@ -0,0 +1,85 @@ | |||
| 1 | <html> | ||
| 2 | <head> | ||
| 3 | <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> | ||
| 4 | <title>1.1.Welcome</title> | ||
| 5 | <link rel="stylesheet" type="text/css" href="../book.css"> | ||
| 6 | <meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> | ||
| 7 | <link rel="home" href="index.html" title="Getting Started With Yocto Project"> | ||
| 8 | <link rel="up" href="overview-manual-intro.html" title="Chapter1.The Yocto Project Overview Manual"> | ||
| 9 | <link rel="prev" href="overview-manual-intro.html" title="Chapter1.The Yocto Project Overview Manual"> | ||
| 10 | <link rel="next" href="overview-other-information.html" title="1.2.Other Information"> | ||
| 11 | </head> | ||
| 12 | <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="1.1.Welcome"> | ||
| 13 | <div class="titlepage"><div><div><h2 class="title" style="clear: both"> | ||
| 14 | <a name="overview-welcome"></a>1.1.Welcome</h2></div></div></div> | ||
| 15 | <p> | ||
| 16 | Welcome to the Yocto Project Overview Manual! | ||
| 17 | This manual introduces the Yocto Project by providing concepts, | ||
| 18 | software overviews, best-known-methods (BKMs), and any other | ||
| 19 | high-level introductory information suitable for a new Yocto | ||
| 20 | Project user. | ||
| 21 | </p> | ||
| 22 | <p> | ||
| 23 | The following list describes what you can get from this manual: | ||
| 24 | </p> | ||
| 25 | <div class="itemizedlist"><ul class="itemizedlist" type="disc"> | ||
| 26 | <li class="listitem"><p> | ||
| 27 | <span class="emphasis"><em>Major Topic:</em></span> | ||
| 28 | Provide a high-level description of this major topic. | ||
| 29 | </p></li> | ||
| 30 | <li class="listitem"><p> | ||
| 31 | <span class="emphasis"><em>Major Topic:</em></span> | ||
| 32 | Provide a high-level description of this major topic. | ||
| 33 | </p></li> | ||
| 34 | <li class="listitem"><p> | ||
| 35 | <span class="emphasis"><em>Major Topic:</em></span> | ||
| 36 | Provide a high-level description of this major topic. | ||
| 37 | </p></li> | ||
| 38 | <li class="listitem"><p> | ||
| 39 | <span class="emphasis"><em>Major Topic:</em></span> | ||
| 40 | Provide a high-level description of this major topic. | ||
| 41 | </p></li> | ||
| 42 | </ul></div> | ||
| 43 | <p> | ||
| 44 | </p> | ||
| 45 | <p> | ||
| 46 | This manual does not give you the following: | ||
| 47 | </p> | ||
| 48 | <div class="itemizedlist"><ul class="itemizedlist" type="disc"> | ||
| 49 | <li class="listitem"><p> | ||
| 50 | <span class="emphasis"><em>Step-by-step Instructions for Development Tasks:</em></span> | ||
| 51 | Instructional procedures reside in other manuals within | ||
| 52 | the Yocto Project documentation set. | ||
| 53 | For example, the | ||
| 54 | <a class="link" href="../dev-manual/index.html" target="_self">Yocto Project Development Tasks Manual</a> | ||
| 55 | provides examples on how to perform various development | ||
| 56 | tasks. | ||
| 57 | As another example, the | ||
| 58 | <a class="link" href="../sdk-manual/index.html" target="_self">Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</a> | ||
| 59 | manual contains detailed instructions on how to install an | ||
| 60 | SDK, which is used to develop applications for target | ||
| 61 | hardware. | ||
| 62 | </p></li> | ||
| 63 | <li class="listitem"><p> | ||
| 64 | <span class="emphasis"><em>Reference Material:</em></span> | ||
| 65 | This type of material resides in an appropriate reference | ||
| 66 | manual. | ||
| 67 | For example, system variables are documented in the | ||
| 68 | <a class="link" href="../ref-manual/index.html" target="_self">Yocto Project Reference Manual</a>. | ||
| 69 | As another example, the | ||
| 70 | <a class="link" href="../bsp-guide/index.html" target="_self">Yocto Project Board Support Package (BSP) Developer's Guide</a> | ||
| 71 | contains reference information on BSPs. | ||
| 72 | </p></li> | ||
| 73 | <li class="listitem"><p> | ||
| 74 | <span class="emphasis"><em>Detailed Public Information Not Specific to the | ||
| 75 | Yocto Project:</em></span> | ||
| 76 | For example, exhaustive information on how to use the | ||
| 77 | Source Control Manager Git is better covered with Internet | ||
| 78 | searches and official Git Documentation than through the | ||
| 79 | Yocto Project documentation. | ||
| 80 | </p></li> | ||
| 81 | </ul></div> | ||
| 82 | <p> | ||
| 83 | </p> | ||
| 84 | </div></body> | ||
| 85 | </html> | ||
diff --git a/documentation/getting-started/eclipse/html/getting-started/package-feeds-dev-environment.html b/documentation/getting-started/eclipse/html/getting-started/package-feeds-dev-environment.html new file mode 100644 index 0000000000..ad3d67f660 --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/package-feeds-dev-environment.html | |||
| @@ -0,0 +1,98 @@ | |||
| 1 | <html> | ||
| 2 | <head> | ||
| 3 | <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> | ||
| 4 | <title>2.8.4.Package Feeds</title> | ||
| 5 | <link rel="stylesheet" type="text/css" href="../book.css"> | ||
| 6 | <meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> | ||
| 7 | <link rel="home" href="index.html" title="Getting Started With Yocto Project"> | ||
| 8 | <link rel="up" href="development-concepts.html" title="2.8.Development Concepts"> | ||
| 9 | <link rel="prev" href="source-mirrors.html" title="2.8.3.4.Source Mirror(s)"> | ||
| 10 | <link rel="next" href="bitbake-dev-environment.html" title="2.8.5.BitBake"> | ||
| 11 | </head> | ||
| 12 | <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="2.8.4.Package Feeds"> | ||
| 13 | <div class="titlepage"><div><div><h3 class="title"> | ||
| 14 | <a name="package-feeds-dev-environment"></a>2.8.4.Package Feeds</h3></div></div></div> | ||
| 15 | <p> | ||
| 16 | When the OpenEmbedded build system generates an image or an SDK, | ||
| 17 | it gets the packages from a package feed area located in the | ||
| 18 | <a class="link" href="../ref-manual/build-directory.html" target="_self">Build Directory</a>. | ||
| 19 | The | ||
| 20 | <a class="link" href="development-concepts.html#general-yocto-environment-figure">general Yocto Project Development Environment figure</a> | ||
| 21 | shows this package feeds area in the upper-right corner. | ||
| 22 | </p> | ||
| 23 | <p> | ||
| 24 | This section looks a little closer into the package feeds area used | ||
| 25 | by the build system. | ||
| 26 | Here is a more detailed look at the area: | ||
| 27 | </p> | ||
| 28 | <table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="630"><tr style="height: 540px"><td align="center"><img src="figures/package-feeds.png" align="middle" width="630"></td></tr></table> | ||
| 29 | <p> | ||
| 30 | </p> | ||
| 31 | <p> | ||
| 32 | Package feeds are an intermediary step in the build process. | ||
| 33 | The OpenEmbedded build system provides classes to generate | ||
| 34 | different package types, and you specify which classes to enable | ||
| 35 | through the | ||
| 36 | <a class="link" href="../ref-manual/var-PACKAGE_CLASSES.html" target="_self"><code class="filename">PACKAGE_CLASSES</code></a> | ||
| 37 | variable. | ||
| 38 | Before placing the packages into package feeds, | ||
| 39 | the build process validates them with generated output quality | ||
| 40 | assurance checks through the | ||
| 41 | <a class="link" href="../ref-manual/ref-classes-insane.html" target="_self"><code class="filename">insane</code></a> | ||
| 42 | class. | ||
| 43 | </p> | ||
| 44 | <p> | ||
| 45 | The package feed area resides in the Build Directory. | ||
| 46 | The directory the build system uses to temporarily store packages | ||
| 47 | is determined by a combination of variables and the particular | ||
| 48 | package manager in use. | ||
| 49 | See the "Package Feeds" box in the illustration and note the | ||
| 50 | information to the right of that area. | ||
| 51 | In particular, the following defines where package files are | ||
| 52 | kept: | ||
| 53 | </p> | ||
| 54 | <div class="itemizedlist"><ul class="itemizedlist" type="disc"> | ||
| 55 | <li class="listitem"><p><a class="link" href="../ref-manual/var-DEPLOY_DIR.html" target="_self"><code class="filename">DEPLOY_DIR</code></a>: | ||
| 56 | Defined as <code class="filename">tmp/deploy</code> in the Build | ||
| 57 | Directory. | ||
| 58 | </p></li> | ||
| 59 | <li class="listitem"><p><code class="filename">DEPLOY_DIR_*</code>: | ||
| 60 | Depending on the package manager used, the package type | ||
| 61 | sub-folder. | ||
| 62 | Given RPM, IPK, or DEB packaging and tarball creation, the | ||
| 63 | <a class="link" href="../ref-manual/var-DEPLOY_DIR_RPM.html" target="_self"><code class="filename">DEPLOY_DIR_RPM</code></a>, | ||
| 64 | <a class="link" href="../ref-manual/var-DEPLOY_DIR_IPK.html" target="_self"><code class="filename">DEPLOY_DIR_IPK</code></a>, | ||
| 65 | <a class="link" href="../ref-manual/var-DEPLOY_DIR_DEB.html" target="_self"><code class="filename">DEPLOY_DIR_DEB</code></a>, | ||
| 66 | or | ||
| 67 | <a class="link" href="../ref-manual/var-DEPLOY_DIR_TAR.html" target="_self"><code class="filename">DEPLOY_DIR_TAR</code></a>, | ||
| 68 | variables are used, respectively. | ||
| 69 | </p></li> | ||
| 70 | <li class="listitem"><p><a class="link" href="../ref-manual/var-PACKAGE_ARCH.html" target="_self"><code class="filename">PACKAGE_ARCH</code></a>: | ||
| 71 | Defines architecture-specific sub-folders. | ||
| 72 | For example, packages could exist for the i586 or qemux86 | ||
| 73 | architectures. | ||
| 74 | </p></li> | ||
| 75 | </ul></div> | ||
| 76 | <p> | ||
| 77 | </p> | ||
| 78 | <p> | ||
| 79 | BitBake uses the <code class="filename">do_package_write_*</code> tasks to | ||
| 80 | generate packages and place them into the package holding area (e.g. | ||
| 81 | <code class="filename">do_package_write_ipk</code> for IPK packages). | ||
| 82 | See the | ||
| 83 | "<a class="link" href="../ref-manual/ref-tasks-package_write_deb.html" target="_self"><code class="filename">do_package_write_deb</code></a>", | ||
| 84 | "<a class="link" href="../ref-manual/ref-tasks-package_write_ipk.html" target="_self"><code class="filename">do_package_write_ipk</code></a>", | ||
| 85 | "<a class="link" href="../ref-manual/ref-tasks-package_write_rpm.html" target="_self"><code class="filename">do_package_write_rpm</code></a>", | ||
| 86 | and | ||
| 87 | "<a class="link" href="../ref-manual/ref-tasks-package_write_tar.html" target="_self"><code class="filename">do_package_write_tar</code></a>" | ||
| 88 | sections for additional information. | ||
| 89 | As an example, consider a scenario where an IPK packaging manager | ||
| 90 | is being used and package architecture support for both i586 | ||
| 91 | and qemux86 exist. | ||
| 92 | Packages for the i586 architecture are placed in | ||
| 93 | <code class="filename">build/tmp/deploy/ipk/i586</code>, while packages for | ||
| 94 | the qemux86 architecture are placed in | ||
| 95 | <code class="filename">build/tmp/deploy/ipk/qemux86</code>. | ||
| 96 | </p> | ||
| 97 | </div></body> | ||
| 98 | </html> | ||
diff --git a/documentation/getting-started/eclipse/html/getting-started/package-splitting-dev-environment.html b/documentation/getting-started/eclipse/html/getting-started/package-splitting-dev-environment.html new file mode 100644 index 0000000000..882d66c31c --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/package-splitting-dev-environment.html | |||
| @@ -0,0 +1,94 @@ | |||
| 1 | <html> | ||
| 2 | <head> | ||
| 3 | <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> | ||
| 4 | <title>2.8.5.4.Package Splitting</title> | ||
| 5 | <link rel="stylesheet" type="text/css" href="../book.css"> | ||
| 6 | <meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> | ||
| 7 | <link rel="home" href="index.html" title="Getting Started With Yocto Project"> | ||
| 8 | <link rel="up" href="bitbake-dev-environment.html" title="2.8.5.BitBake"> | ||
| 9 | <link rel="prev" href="configuration-and-compilation-dev-environment.html" title="2.8.5.3.Configuration and Compilation"> | ||
| 10 | <link rel="next" href="image-generation-dev-environment.html" title="2.8.5.5.Image Generation"> | ||
| 11 | </head> | ||
| 12 | <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="2.8.5.4.Package Splitting"> | ||
| 13 | <div class="titlepage"><div><div><h4 class="title"> | ||
| 14 | <a name="package-splitting-dev-environment"></a>2.8.5.4.Package Splitting</h4></div></div></div> | ||
| 15 | <p> | ||
| 16 | After source code is configured and compiled, the | ||
| 17 | OpenEmbedded build system analyzes | ||
| 18 | the results and splits the output into packages: | ||
| 19 | </p> | ||
| 20 | <table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="630"><tr style="height: 630px"><td align="center"><img src="figures/analysis-for-package-splitting.png" align="middle" width="630"></td></tr></table> | ||
| 21 | <p> | ||
| 22 | </p> | ||
| 23 | <p> | ||
| 24 | The | ||
| 25 | <a class="link" href="../ref-manual/ref-tasks-package.html" target="_self"><code class="filename">do_package</code></a> | ||
| 26 | and | ||
| 27 | <a class="link" href="../ref-manual/ref-tasks-packagedata.html" target="_self"><code class="filename">do_packagedata</code></a> | ||
| 28 | tasks combine to analyze | ||
| 29 | the files found in the | ||
| 30 | <a class="link" href="../ref-manual/var-D.html" target="_self"><code class="filename">D</code></a> directory | ||
| 31 | and split them into subsets based on available packages and | ||
| 32 | files. | ||
| 33 | The analyzing process involves the following as well as other | ||
| 34 | items: splitting out debugging symbols, | ||
| 35 | looking at shared library dependencies between packages, | ||
| 36 | and looking at package relationships. | ||
| 37 | The <code class="filename">do_packagedata</code> task creates package | ||
| 38 | metadata based on the analysis such that the | ||
| 39 | OpenEmbedded build system can generate the final packages. | ||
| 40 | Working, staged, and intermediate results of the analysis | ||
| 41 | and package splitting process use these areas: | ||
| 42 | </p> | ||
| 43 | <div class="itemizedlist"><ul class="itemizedlist" type="disc"> | ||
| 44 | <li class="listitem"><p><a class="link" href="../ref-manual/var-PKGD.html" target="_self"><code class="filename">PKGD</code></a> - | ||
| 45 | The destination directory for packages before they are | ||
| 46 | split. | ||
| 47 | </p></li> | ||
| 48 | <li class="listitem"><p><a class="link" href="../ref-manual/var-PKGDATA_DIR.html" target="_self"><code class="filename">PKGDATA_DIR</code></a> - | ||
| 49 | A shared, global-state directory that holds data | ||
| 50 | generated during the packaging process. | ||
| 51 | </p></li> | ||
| 52 | <li class="listitem"><p><a class="link" href="../ref-manual/var-PKGDESTWORK.html" target="_self"><code class="filename">PKGDESTWORK</code></a> - | ||
| 53 | A temporary work area used by the | ||
| 54 | <code class="filename">do_package</code> task. | ||
| 55 | </p></li> | ||
| 56 | <li class="listitem"><p><a class="link" href="../ref-manual/var-PKGDEST.html" target="_self"><code class="filename">PKGDEST</code></a> - | ||
| 57 | The parent directory for packages after they have | ||
| 58 | been split. | ||
| 59 | </p></li> | ||
| 60 | </ul></div> | ||
| 61 | <p> | ||
| 62 | The <a class="link" href="../ref-manual/var-FILES.html" target="_self"><code class="filename">FILES</code></a> | ||
| 63 | variable defines the files that go into each package in | ||
| 64 | <a class="link" href="../ref-manual/var-PACKAGES.html" target="_self"><code class="filename">PACKAGES</code></a>. | ||
| 65 | If you want details on how this is accomplished, you can | ||
| 66 | look at the | ||
| 67 | <a class="link" href="../ref-manual/ref-classes-package.html" target="_self"><code class="filename">package</code></a> | ||
| 68 | class. | ||
| 69 | </p> | ||
| 70 | <p> | ||
| 71 | Depending on the type of packages being created (RPM, DEB, or | ||
| 72 | IPK), the <code class="filename">do_package_write_*</code> task | ||
| 73 | creates the actual packages and places them in the | ||
| 74 | Package Feed area, which is | ||
| 75 | <code class="filename">${TMPDIR}/deploy</code>. | ||
| 76 | You can see the | ||
| 77 | "<a class="link" href="package-feeds-dev-environment.html" title="2.8.4.Package Feeds">Package Feeds</a>" | ||
| 78 | section for more detail on that part of the build process. | ||
| 79 | </p> | ||
| 80 | <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"> | ||
| 81 | <h3 class="title">Note</h3> | ||
| 82 | Support for creating feeds directly from the | ||
| 83 | <code class="filename">deploy/*</code> directories does not exist. | ||
| 84 | Creating such feeds usually requires some kind of feed | ||
| 85 | maintenance mechanism that would upload the new packages | ||
| 86 | into an official package feed (e.g. the | ||
| 87 | ngstrm distribution). | ||
| 88 | This functionality is highly distribution-specific | ||
| 89 | and thus is not provided out of the box. | ||
| 90 | </div> | ||
| 91 | <p> | ||
| 92 | </p> | ||
| 93 | </div></body> | ||
| 94 | </html> | ||
diff --git a/documentation/getting-started/eclipse/html/getting-started/patching-dev-environment.html b/documentation/getting-started/eclipse/html/getting-started/patching-dev-environment.html new file mode 100644 index 0000000000..60ae6b020b --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/patching-dev-environment.html | |||
| @@ -0,0 +1,48 @@ | |||
| 1 | <html> | ||
| 2 | <head> | ||
| 3 | <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> | ||
| 4 | <title>2.8.5.2.Patching</title> | ||
| 5 | <link rel="stylesheet" type="text/css" href="../book.css"> | ||
| 6 | <meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> | ||
| 7 | <link rel="home" href="index.html" title="Getting Started With Yocto Project"> | ||
| 8 | <link rel="up" href="bitbake-dev-environment.html" title="2.8.5.BitBake"> | ||
| 9 | <link rel="prev" href="source-fetching-dev-environment.html" title="2.8.5.1.Source Fetching"> | ||
| 10 | <link rel="next" href="configuration-and-compilation-dev-environment.html" title="2.8.5.3.Configuration and Compilation"> | ||
| 11 | </head> | ||
| 12 | <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="2.8.5.2.Patching"> | ||
| 13 | <div class="titlepage"><div><div><h4 class="title"> | ||
| 14 | <a name="patching-dev-environment"></a>2.8.5.2.Patching</h4></div></div></div> | ||
| 15 | <p> | ||
| 16 | Once source code is fetched and unpacked, BitBake locates | ||
| 17 | patch files and applies them to the source files: | ||
| 18 | </p> | ||
| 19 | <table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="540"><tr style="height: 450px"><td align="center"><img src="figures/patching.png" align="middle" width="540"></td></tr></table> | ||
| 20 | <p> | ||
| 21 | </p> | ||
| 22 | <p> | ||
| 23 | The | ||
| 24 | <a class="link" href="../ref-manual/ref-tasks-patch.html" target="_self"><code class="filename">do_patch</code></a> | ||
| 25 | task processes recipes by | ||
| 26 | using the | ||
| 27 | <a class="link" href="../ref-manual/var-SRC_URI.html" target="_self"><code class="filename">SRC_URI</code></a> | ||
| 28 | variable to locate applicable patch files, which by default | ||
| 29 | are <code class="filename">*.patch</code> or | ||
| 30 | <code class="filename">*.diff</code> files, or any file if | ||
| 31 | "apply=yes" is specified for the file in | ||
| 32 | <code class="filename">SRC_URI</code>. | ||
| 33 | </p> | ||
| 34 | <p> | ||
| 35 | BitBake finds and applies multiple patches for a single recipe | ||
| 36 | in the order in which it finds the patches. | ||
| 37 | Patches are applied to the recipe's source files located in the | ||
| 38 | <a class="link" href="../ref-manual/var-S.html" target="_self"><code class="filename">S</code></a> | ||
| 39 | directory. | ||
| 40 | </p> | ||
| 41 | <p> | ||
| 42 | For more information on how the source directories are | ||
| 43 | created, see the | ||
| 44 | "<a class="link" href="source-fetching-dev-environment.html" title="2.8.5.1.Source Fetching">Source Fetching</a>" | ||
| 45 | section. | ||
| 46 | </p> | ||
| 47 | </div></body> | ||
| 48 | </html> | ||
diff --git a/documentation/getting-started/eclipse/html/getting-started/recipe-syntax.html b/documentation/getting-started/eclipse/html/getting-started/recipe-syntax.html new file mode 100644 index 0000000000..fcf46d9d35 --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/recipe-syntax.html | |||
| @@ -0,0 +1,383 @@ | |||
| 1 | <html> | ||
| 2 | <head> | ||
| 3 | <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> | ||
| 4 | <title>2.7.Recipe Syntax</title> | ||
| 5 | <link rel="stylesheet" type="text/css" href="../book.css"> | ||
| 6 | <meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> | ||
| 7 | <link rel="home" href="index.html" title="Getting Started With Yocto Project"> | ||
| 8 | <link rel="up" href="overview-development-environment.html" title="Chapter2.The Yocto Project Development Environment"> | ||
| 9 | <link rel="prev" href="licensing.html" title="2.6.Licensing"> | ||
| 10 | <link rel="next" href="development-concepts.html" title="2.8.Development Concepts"> | ||
| 11 | </head> | ||
| 12 | <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="2.7.Recipe Syntax"> | ||
| 13 | <div class="titlepage"><div><div><h2 class="title" style="clear: both"> | ||
| 14 | <a name="recipe-syntax"></a>2.7.Recipe Syntax</h2></div></div></div> | ||
| 15 | <p> | ||
| 16 | Understanding recipe file syntax is important for | ||
| 17 | writing recipes. | ||
| 18 | The following list overviews the basic items that make up a | ||
| 19 | BitBake recipe file. | ||
| 20 | For more complete BitBake syntax descriptions, see the | ||
| 21 | "<a class="link" href="../bitbake-user-manual/bitbake-user-manual-metadata.html" target="_self">Syntax and Operators</a>" | ||
| 22 | chapter of the BitBake User Manual. | ||
| 23 | </p> | ||
| 24 | <div class="itemizedlist"><ul class="itemizedlist" type="disc"> | ||
| 25 | <li class="listitem"> | ||
| 26 | <p><span class="emphasis"><em>Variable Assignments and Manipulations:</em></span> | ||
| 27 | Variable assignments allow a value to be assigned to a | ||
| 28 | variable. | ||
| 29 | The assignment can be static text or might include | ||
| 30 | the contents of other variables. | ||
| 31 | In addition to the assignment, appending and prepending | ||
| 32 | operations are also supported.</p> | ||
| 33 | <p>The following example shows some of the ways | ||
| 34 | you can use variables in recipes: | ||
| 35 | </p> | ||
| 36 | <pre class="literallayout"> | ||
| 37 | S = "${WORKDIR}/postfix-${PV}" | ||
| 38 | CFLAGS += "-DNO_ASM" | ||
| 39 | SRC_URI_append = " file://fixup.patch" | ||
| 40 | </pre> | ||
| 41 | <p> | ||
| 42 | </p> | ||
| 43 | </li> | ||
| 44 | <li class="listitem"> | ||
| 45 | <p><span class="emphasis"><em>Functions:</em></span> | ||
| 46 | Functions provide a series of actions to be performed. | ||
| 47 | You usually use functions to override the default | ||
| 48 | implementation of a task function or to complement | ||
| 49 | a default function (i.e. append or prepend to an | ||
| 50 | existing function). | ||
| 51 | Standard functions use <code class="filename">sh</code> shell | ||
| 52 | syntax, although access to OpenEmbedded variables and | ||
| 53 | internal methods are also available.</p> | ||
| 54 | <p>The following is an example function from the | ||
| 55 | <code class="filename">sed</code> recipe: | ||
| 56 | </p> | ||
| 57 | <pre class="literallayout"> | ||
| 58 | do_install () { | ||
| 59 | autotools_do_install | ||
| 60 | install -d ${D}${base_bindir} | ||
| 61 | mv ${D}${bindir}/sed ${D}${base_bindir}/sed | ||
| 62 | rmdir ${D}${bindir}/ | ||
| 63 | } | ||
| 64 | </pre> | ||
| 65 | <p> | ||
| 66 | It is also possible to implement new functions that | ||
| 67 | are called between existing tasks as long as the | ||
| 68 | new functions are not replacing or complementing the | ||
| 69 | default functions. | ||
| 70 | You can implement functions in Python | ||
| 71 | instead of shell. | ||
| 72 | Both of these options are not seen in the majority of | ||
| 73 | recipes.</p> | ||
| 74 | </li> | ||
| 75 | <li class="listitem"> | ||
| 76 | <p><span class="emphasis"><em>Keywords:</em></span> | ||
| 77 | BitBake recipes use only a few keywords. | ||
| 78 | You use keywords to include common | ||
| 79 | functions (<code class="filename">inherit</code>), load parts | ||
| 80 | of a recipe from other files | ||
| 81 | (<code class="filename">include</code> and | ||
| 82 | <code class="filename">require</code>) and export variables | ||
| 83 | to the environment (<code class="filename">export</code>).</p> | ||
| 84 | <p>The following example shows the use of some of | ||
| 85 | these keywords: | ||
| 86 | </p> | ||
| 87 | <pre class="literallayout"> | ||
| 88 | export POSTCONF = "${STAGING_BINDIR}/postconf" | ||
| 89 | inherit autoconf | ||
| 90 | require otherfile.inc | ||
| 91 | </pre> | ||
| 92 | <p> | ||
| 93 | </p> | ||
| 94 | </li> | ||
| 95 | <li class="listitem"> | ||
| 96 | <p><span class="emphasis"><em>Comments:</em></span> | ||
| 97 | Any lines that begin with the hash character | ||
| 98 | (<code class="filename">#</code>) are treated as comment lines | ||
| 99 | and are ignored: | ||
| 100 | </p> | ||
| 101 | <pre class="literallayout"> | ||
| 102 | # This is a comment | ||
| 103 | </pre> | ||
| 104 | <p> | ||
| 105 | </p> | ||
| 106 | </li> | ||
| 107 | </ul></div> | ||
| 108 | <p> | ||
| 109 | </p> | ||
| 110 | <p> | ||
| 111 | This next list summarizes the most important and most commonly | ||
| 112 | used parts of the recipe syntax. | ||
| 113 | For more information on these parts of the syntax, you can | ||
| 114 | reference the | ||
| 115 | <a class="link" href="../bitbake-user-manual/bitbake-user-manual-metadata.html" target="_self">Syntax and Operators</a> | ||
| 116 | chapter in the BitBake User Manual. | ||
| 117 | </p> | ||
| 118 | <div class="itemizedlist"><ul class="itemizedlist" type="disc"> | ||
| 119 | <li class="listitem"> | ||
| 120 | <p><span class="emphasis"><em>Line Continuation: <code class="filename">\</code></em></span> - | ||
| 121 | Use the backward slash (<code class="filename">\</code>) | ||
| 122 | character to split a statement over multiple lines. | ||
| 123 | Place the slash character at the end of the line that | ||
| 124 | is to be continued on the next line: | ||
| 125 | </p> | ||
| 126 | <pre class="literallayout"> | ||
| 127 | VAR = "A really long \ | ||
| 128 | line" | ||
| 129 | </pre> | ||
| 130 | <p> | ||
| 131 | </p> | ||
| 132 | <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"> | ||
| 133 | <h3 class="title">Note</h3> | ||
| 134 | You cannot have any characters including spaces | ||
| 135 | or tabs after the slash character. | ||
| 136 | </div> | ||
| 137 | <p> | ||
| 138 | </p> | ||
| 139 | </li> | ||
| 140 | <li class="listitem"> | ||
| 141 | <p> | ||
| 142 | <span class="emphasis"><em>Using Variables: <code class="filename">${...}</code></em></span> - | ||
| 143 | Use the <code class="filename">${<em class="replaceable"><code>VARNAME</code></em>}</code> syntax to | ||
| 144 | access the contents of a variable: | ||
| 145 | </p> | ||
| 146 | <pre class="literallayout"> | ||
| 147 | SRC_URI = "${SOURCEFORGE_MIRROR}/libpng/zlib-${PV}.tar.gz" | ||
| 148 | </pre> | ||
| 149 | <p> | ||
| 150 | </p> | ||
| 151 | <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"> | ||
| 152 | <h3 class="title">Note</h3> | ||
| 153 | It is important to understand that the value of a | ||
| 154 | variable expressed in this form does not get | ||
| 155 | substituted automatically. | ||
| 156 | The expansion of these expressions happens | ||
| 157 | on-demand later (e.g. usually when a function that | ||
| 158 | makes reference to the variable executes). | ||
| 159 | This behavior ensures that the values are most | ||
| 160 | appropriate for the context in which they are | ||
| 161 | finally used. | ||
| 162 | On the rare occasion that you do need the variable | ||
| 163 | expression to be expanded immediately, you can use | ||
| 164 | the <code class="filename">:=</code> operator instead of | ||
| 165 | <code class="filename">=</code> when you make the | ||
| 166 | assignment, but this is not generally needed. | ||
| 167 | </div> | ||
| 168 | <p> | ||
| 169 | </p> | ||
| 170 | </li> | ||
| 171 | <li class="listitem"> | ||
| 172 | <p><span class="emphasis"><em>Quote All Assignments: <code class="filename">"<em class="replaceable"><code>value</code></em>"</code></em></span> - | ||
| 173 | Use double quotes around the value in all variable | ||
| 174 | assignments. | ||
| 175 | </p> | ||
| 176 | <pre class="literallayout"> | ||
| 177 | VAR1 = "${OTHERVAR}" | ||
| 178 | VAR2 = "The version is ${PV}" | ||
| 179 | </pre> | ||
| 180 | <p> | ||
| 181 | </p> | ||
| 182 | </li> | ||
| 183 | <li class="listitem"> | ||
| 184 | <p><span class="emphasis"><em>Conditional Assignment: <code class="filename">?=</code></em></span> - | ||
| 185 | Conditional assignment is used to assign a value to | ||
| 186 | a variable, but only when the variable is currently | ||
| 187 | unset. | ||
| 188 | Use the question mark followed by the equal sign | ||
| 189 | (<code class="filename">?=</code>) to make a "soft" assignment | ||
| 190 | used for conditional assignment. | ||
| 191 | Typically, "soft" assignments are used in the | ||
| 192 | <code class="filename">local.conf</code> file for variables | ||
| 193 | that are allowed to come through from the external | ||
| 194 | environment. | ||
| 195 | </p> | ||
| 196 | <p>Here is an example where | ||
| 197 | <code class="filename">VAR1</code> is set to "New value" if | ||
| 198 | it is currently empty. | ||
| 199 | However, if <code class="filename">VAR1</code> has already been | ||
| 200 | set, it remains unchanged: | ||
| 201 | </p> | ||
| 202 | <pre class="literallayout"> | ||
| 203 | VAR1 ?= "New value" | ||
| 204 | </pre> | ||
| 205 | <p> | ||
| 206 | In this next example, <code class="filename">VAR1</code> | ||
| 207 | is left with the value "Original value": | ||
| 208 | </p> | ||
| 209 | <pre class="literallayout"> | ||
| 210 | VAR1 = "Original value" | ||
| 211 | VAR1 ?= "New value" | ||
| 212 | </pre> | ||
| 213 | <p> | ||
| 214 | </p> | ||
| 215 | </li> | ||
| 216 | <li class="listitem"> | ||
| 217 | <p><span class="emphasis"><em>Appending: <code class="filename">+=</code></em></span> - | ||
| 218 | Use the plus character followed by the equals sign | ||
| 219 | (<code class="filename">+=</code>) to append values to existing | ||
| 220 | variables. | ||
| 221 | </p> | ||
| 222 | <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"> | ||
| 223 | <h3 class="title">Note</h3> | ||
| 224 | This operator adds a space between the existing | ||
| 225 | content of the variable and the new content. | ||
| 226 | </div> | ||
| 227 | <p>Here is an example: | ||
| 228 | </p> | ||
| 229 | <pre class="literallayout"> | ||
| 230 | SRC_URI += "file://fix-makefile.patch" | ||
| 231 | </pre> | ||
| 232 | <p> | ||
| 233 | </p> | ||
| 234 | </li> | ||
| 235 | <li class="listitem"> | ||
| 236 | <p><span class="emphasis"><em>Prepending: <code class="filename">=+</code></em></span> - | ||
| 237 | Use the equals sign followed by the plus character | ||
| 238 | (<code class="filename">=+</code>) to prepend values to existing | ||
| 239 | variables. | ||
| 240 | </p> | ||
| 241 | <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"> | ||
| 242 | <h3 class="title">Note</h3> | ||
| 243 | This operator adds a space between the new content | ||
| 244 | and the existing content of the variable. | ||
| 245 | </div> | ||
| 246 | <p>Here is an example: | ||
| 247 | </p> | ||
| 248 | <pre class="literallayout"> | ||
| 249 | VAR =+ "Starts" | ||
| 250 | </pre> | ||
| 251 | <p> | ||
| 252 | </p> | ||
| 253 | </li> | ||
| 254 | <li class="listitem"> | ||
| 255 | <p><span class="emphasis"><em>Appending: <code class="filename">_append</code></em></span> - | ||
| 256 | Use the <code class="filename">_append</code> operator to | ||
| 257 | append values to existing variables. | ||
| 258 | This operator does not add any additional space. | ||
| 259 | Also, the operator is applied after all the | ||
| 260 | <code class="filename">+=</code>, and | ||
| 261 | <code class="filename">=+</code> operators have been applied and | ||
| 262 | after all <code class="filename">=</code> assignments have | ||
| 263 | occurred. | ||
| 264 | </p> | ||
| 265 | <p>The following example shows the space being | ||
| 266 | explicitly added to the start to ensure the appended | ||
| 267 | value is not merged with the existing value: | ||
| 268 | </p> | ||
| 269 | <pre class="literallayout"> | ||
| 270 | SRC_URI_append = " file://fix-makefile.patch" | ||
| 271 | </pre> | ||
| 272 | <p> | ||
| 273 | You can also use the <code class="filename">_append</code> | ||
| 274 | operator with overrides, which results in the actions | ||
| 275 | only being performed for the specified target or | ||
| 276 | machine: | ||
| 277 | </p> | ||
| 278 | <pre class="literallayout"> | ||
| 279 | SRC_URI_append_sh4 = " file://fix-makefile.patch" | ||
| 280 | </pre> | ||
| 281 | <p> | ||
| 282 | </p> | ||
| 283 | </li> | ||
| 284 | <li class="listitem"> | ||
| 285 | <p><span class="emphasis"><em>Prepending: <code class="filename">_prepend</code></em></span> - | ||
| 286 | Use the <code class="filename">_prepend</code> operator to | ||
| 287 | prepend values to existing variables. | ||
| 288 | This operator does not add any additional space. | ||
| 289 | Also, the operator is applied after all the | ||
| 290 | <code class="filename">+=</code>, and | ||
| 291 | <code class="filename">=+</code> operators have been applied and | ||
| 292 | after all <code class="filename">=</code> assignments have | ||
| 293 | occurred. | ||
| 294 | </p> | ||
| 295 | <p>The following example shows the space being | ||
| 296 | explicitly added to the end to ensure the prepended | ||
| 297 | value is not merged with the existing value: | ||
| 298 | </p> | ||
| 299 | <pre class="literallayout"> | ||
| 300 | CFLAGS_prepend = "-I${S}/myincludes " | ||
| 301 | </pre> | ||
| 302 | <p> | ||
| 303 | You can also use the <code class="filename">_prepend</code> | ||
| 304 | operator with overrides, which results in the actions | ||
| 305 | only being performed for the specified target or | ||
| 306 | machine: | ||
| 307 | </p> | ||
| 308 | <pre class="literallayout"> | ||
| 309 | CFLAGS_prepend_sh4 = "-I${S}/myincludes " | ||
| 310 | </pre> | ||
| 311 | <p> | ||
| 312 | </p> | ||
| 313 | </li> | ||
| 314 | <li class="listitem"> | ||
| 315 | <p><span class="emphasis"><em>Overrides:</em></span> - | ||
| 316 | You can use overrides to set a value conditionally, | ||
| 317 | typically based on how the recipe is being built. | ||
| 318 | For example, to set the | ||
| 319 | <a class="link" href="../ref-manual/var-KBRANCH.html" target="_self"><code class="filename">KBRANCH</code></a> | ||
| 320 | variable's value to "standard/base" for any target | ||
| 321 | <a class="link" href="../ref-manual/var-MACHINE.html" target="_self"><code class="filename">MACHINE</code></a>, | ||
| 322 | except for qemuarm where it should be set to | ||
| 323 | "standard/arm-versatile-926ejs", you would do the | ||
| 324 | following: | ||
| 325 | </p> | ||
| 326 | <pre class="literallayout"> | ||
| 327 | KBRANCH = "standard/base" | ||
| 328 | KBRANCH_qemuarm = "standard/arm-versatile-926ejs" | ||
| 329 | </pre> | ||
| 330 | <p> | ||
| 331 | Overrides are also used to separate alternate values | ||
| 332 | of a variable in other situations. | ||
| 333 | For example, when setting variables such as | ||
| 334 | <a class="link" href="../ref-manual/var-FILES.html" target="_self"><code class="filename">FILES</code></a> | ||
| 335 | and | ||
| 336 | <a class="link" href="../ref-manual/var-RDEPENDS.html" target="_self"><code class="filename">RDEPENDS</code></a> | ||
| 337 | that are specific to individual packages produced by | ||
| 338 | a recipe, you should always use an override that | ||
| 339 | specifies the name of the package. | ||
| 340 | </p> | ||
| 341 | </li> | ||
| 342 | <li class="listitem"><p><span class="emphasis"><em>Indentation:</em></span> | ||
| 343 | Use spaces for indentation rather than than tabs. | ||
| 344 | For shell functions, both currently work. | ||
| 345 | However, it is a policy decision of the Yocto Project | ||
| 346 | to use tabs in shell functions. | ||
| 347 | Realize that some layers have a policy to use spaces | ||
| 348 | for all indentation. | ||
| 349 | </p></li> | ||
| 350 | <li class="listitem"> | ||
| 351 | <p><span class="emphasis"><em>Using Python for Complex Operations: <code class="filename">${@<em class="replaceable"><code>python_code</code></em>}</code></em></span> - | ||
| 352 | For more advanced processing, it is possible to use | ||
| 353 | Python code during variable assignments (e.g. | ||
| 354 | search and replacement on a variable).</p> | ||
| 355 | <p>You indicate Python code using the | ||
| 356 | <code class="filename">${@<em class="replaceable"><code>python_code</code></em>}</code> | ||
| 357 | syntax for the variable assignment: | ||
| 358 | </p> | ||
| 359 | <pre class="literallayout"> | ||
| 360 | SRC_URI = "ftp://ftp.info-zip.org/pub/infozip/src/zip${@d.getVar('PV',1).replace('.', '')}.tgz | ||
| 361 | </pre> | ||
| 362 | <p> | ||
| 363 | </p> | ||
| 364 | </li> | ||
| 365 | <li class="listitem"><p><span class="emphasis"><em>Shell Function Syntax:</em></span> | ||
| 366 | Write shell functions as if you were writing a shell | ||
| 367 | script when you describe a list of actions to take. | ||
| 368 | You should ensure that your script works with a generic | ||
| 369 | <code class="filename">sh</code> and that it does not require | ||
| 370 | any <code class="filename">bash</code> or other shell-specific | ||
| 371 | functionality. | ||
| 372 | The same considerations apply to various system | ||
| 373 | utilities (e.g. <code class="filename">sed</code>, | ||
| 374 | <code class="filename">grep</code>, <code class="filename">awk</code>, | ||
| 375 | and so forth) that you might wish to use. | ||
| 376 | If in doubt, you should check with multiple | ||
| 377 | implementations - including those from BusyBox. | ||
| 378 | </p></li> | ||
| 379 | </ul></div> | ||
| 380 | <p> | ||
| 381 | </p> | ||
| 382 | </div></body> | ||
| 383 | </html> | ||
diff --git a/documentation/getting-started/eclipse/html/getting-started/repositories-tags-and-branches.html b/documentation/getting-started/eclipse/html/getting-started/repositories-tags-and-branches.html new file mode 100644 index 0000000000..d813948375 --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/repositories-tags-and-branches.html | |||
| @@ -0,0 +1,173 @@ | |||
| 1 | <html> | ||
| 2 | <head> | ||
| 3 | <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> | ||
| 4 | <title>2.4.1.Repositories, Tags, and Branches</title> | ||
| 5 | <link rel="stylesheet" type="text/css" href="../book.css"> | ||
| 6 | <meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> | ||
| 7 | <link rel="home" href="index.html" title="Getting Started With Yocto Project"> | ||
| 8 | <link rel="up" href="git.html" title="2.4.Git"> | ||
| 9 | <link rel="prev" href="git.html" title="2.4.Git"> | ||
| 10 | <link rel="next" href="basic-commands.html" title="2.4.2.Basic Commands"> | ||
| 11 | </head> | ||
| 12 | <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="2.4.1.Repositories, Tags, and Branches"> | ||
| 13 | <div class="titlepage"><div><div><h3 class="title"> | ||
| 14 | <a name="repositories-tags-and-branches"></a>2.4.1.Repositories, Tags, and Branches</h3></div></div></div> | ||
| 15 | <p> | ||
| 16 | As mentioned briefly in the previous section and also in the | ||
| 17 | "<a class="link" href="workflows.html" title="2.3.Workflows">Workflows</a>" section, | ||
| 18 | the Yocto Project maintains source repositories at | ||
| 19 | <a class="ulink" href="http://git.yoctoproject.org/cgit.cgi" target="_self">http://git.yoctoproject.org/cgit.cgi</a>. | ||
| 20 | If you look at this web-interface of the repositories, each item | ||
| 21 | is a separate Git repository. | ||
| 22 | </p> | ||
| 23 | <p> | ||
| 24 | Git repositories use branching techniques that track content | ||
| 25 | change (not files) within a project (e.g. a new feature or updated | ||
| 26 | documentation). | ||
| 27 | Creating a tree-like structure based on project divergence allows | ||
| 28 | for excellent historical information over the life of a project. | ||
| 29 | This methodology also allows for an environment from which you can | ||
| 30 | do lots of local experimentation on projects as you develop | ||
| 31 | changes or new features. | ||
| 32 | </p> | ||
| 33 | <p> | ||
| 34 | A Git repository represents all development efforts for a given | ||
| 35 | project. | ||
| 36 | For example, the Git repository <code class="filename">poky</code> contains | ||
| 37 | all changes and developments for Poky over the course of its | ||
| 38 | entire life. | ||
| 39 | That means that all changes that make up all releases are captured. | ||
| 40 | The repository maintains a complete history of changes. | ||
| 41 | </p> | ||
| 42 | <p> | ||
| 43 | You can create a local copy of any repository by "cloning" it | ||
| 44 | with the <code class="filename">git clone</code> command. | ||
| 45 | When you clone a Git repository, you end up with an identical | ||
| 46 | copy of the repository on your development system. | ||
| 47 | Once you have a local copy of a repository, you can take steps to | ||
| 48 | develop locally. | ||
| 49 | For examples on how to clone Git repositories, see the | ||
| 50 | "<a class="link" href="../dev-manual/working-with-yocto-project-source-files.html" target="_self">Working With Yocto Project Source Files</a>" | ||
| 51 | section in the Yocto Project Development Tasks Manual. | ||
| 52 | </p> | ||
| 53 | <p> | ||
| 54 | It is important to understand that Git tracks content change and | ||
| 55 | not files. | ||
| 56 | Git uses "branches" to organize different development efforts. | ||
| 57 | For example, the <code class="filename">poky</code> repository has | ||
| 58 | several branches that include the current "sumo" | ||
| 59 | branch, the "master" branch, and many branches for past | ||
| 60 | Yocto Project releases. | ||
| 61 | You can see all the branches by going to | ||
| 62 | <a class="ulink" href="http://git.yoctoproject.org/cgit.cgi/poky/" target="_self">http://git.yoctoproject.org/cgit.cgi/poky/</a> and | ||
| 63 | clicking on the | ||
| 64 | <code class="filename"><a class="ulink" href="http://git.yoctoproject.org/cgit.cgi/poky/refs/heads" target="_self">[...]</a></code> | ||
| 65 | link beneath the "Branch" heading. | ||
| 66 | </p> | ||
| 67 | <p> | ||
| 68 | Each of these branches represents a specific area of development. | ||
| 69 | The "master" branch represents the current or most recent | ||
| 70 | development. | ||
| 71 | All other branches represent offshoots of the "master" branch. | ||
| 72 | </p> | ||
| 73 | <p> | ||
| 74 | When you create a local copy of a Git repository, the copy has | ||
| 75 | the same set of branches as the original. | ||
| 76 | This means you can use Git to create a local working area | ||
| 77 | (also called a branch) that tracks a specific development branch | ||
| 78 | from the upstream source Git repository. | ||
| 79 | in other words, you can define your local Git environment to | ||
| 80 | work on any development branch in the repository. | ||
| 81 | To help illustrate, consider the following example Git commands: | ||
| 82 | </p> | ||
| 83 | <pre class="literallayout"> | ||
| 84 | $ cd ~ | ||
| 85 | $ git clone git://git.yoctoproject.org/poky | ||
| 86 | $ cd poky | ||
| 87 | $ git checkout -b sumo origin/sumo | ||
| 88 | </pre> | ||
| 89 | <p> | ||
| 90 | In the previous example after moving to the home directory, the | ||
| 91 | <code class="filename">git clone</code> command creates a | ||
| 92 | local copy of the upstream <code class="filename">poky</code> Git repository. | ||
| 93 | By default, Git checks out the "master" branch for your work. | ||
| 94 | After changing the working directory to the new local repository | ||
| 95 | (i.e. <code class="filename">poky</code>), the | ||
| 96 | <code class="filename">git checkout</code> command creates | ||
| 97 | and checks out a local branch named "sumo", which | ||
| 98 | tracks the upstream "origin/sumo" branch. | ||
| 99 | Changes you make while in this branch would ultimately affect | ||
| 100 | the upstream "sumo" branch of the | ||
| 101 | <code class="filename">poky</code> repository. | ||
| 102 | </p> | ||
| 103 | <p> | ||
| 104 | It is important to understand that when you create and checkout a | ||
| 105 | local working branch based on a branch name, | ||
| 106 | your local environment matches the "tip" of that particular | ||
| 107 | development branch at the time you created your local branch, | ||
| 108 | which could be different from the files in the "master" branch | ||
| 109 | of the upstream repository. | ||
| 110 | In other words, creating and checking out a local branch based on | ||
| 111 | the "sumo" branch name is not the same as | ||
| 112 | cloning and checking out the "master" branch if the repository. | ||
| 113 | Keep reading to see how you create a local snapshot of a Yocto | ||
| 114 | Project Release. | ||
| 115 | </p> | ||
| 116 | <p> | ||
| 117 | Git uses "tags" to mark specific changes in a repository. | ||
| 118 | Typically, a tag is used to mark a special point such as the final | ||
| 119 | change before a project is released. | ||
| 120 | You can see the tags used with the <code class="filename">poky</code> Git | ||
| 121 | repository by going to | ||
| 122 | <a class="ulink" href="http://git.yoctoproject.org/cgit.cgi/poky/" target="_self">http://git.yoctoproject.org/cgit.cgi/poky/</a> and | ||
| 123 | clicking on the | ||
| 124 | <code class="filename"><a class="ulink" href="http://git.yoctoproject.org/cgit.cgi/poky/refs/tags" target="_self">[...]</a></code> | ||
| 125 | link beneath the "Tag" heading. | ||
| 126 | </p> | ||
| 127 | <p> | ||
| 128 | Some key tags for the <code class="filename">poky</code> are | ||
| 129 | <code class="filename">jethro-14.0.3</code>, | ||
| 130 | <code class="filename">morty-16.0.1</code>, | ||
| 131 | <code class="filename">pyro-17.0.0</code>, and | ||
| 132 | <code class="filename">sumo-20.0.0</code>. | ||
| 133 | These tags represent Yocto Project releases. | ||
| 134 | </p> | ||
| 135 | <p> | ||
| 136 | When you create a local copy of the Git repository, you also | ||
| 137 | have access to all the tags in the upstream repository. | ||
| 138 | Similar to branches, you can create and checkout a local working | ||
| 139 | Git branch based on a tag name. | ||
| 140 | When you do this, you get a snapshot of the Git repository that | ||
| 141 | reflects the state of the files when the change was made associated | ||
| 142 | with that tag. | ||
| 143 | The most common use is to checkout a working branch that matches | ||
| 144 | a specific Yocto Project release. | ||
| 145 | Here is an example: | ||
| 146 | </p> | ||
| 147 | <pre class="literallayout"> | ||
| 148 | $ cd ~ | ||
| 149 | $ git clone git://git.yoctoproject.org/poky | ||
| 150 | $ cd poky | ||
| 151 | $ git fetch --all --tags --prune | ||
| 152 | $ git checkout tags/pyro-17.0.0 -b my-pyro-17.0.0 | ||
| 153 | </pre> | ||
| 154 | <p> | ||
| 155 | In this example, the name of the top-level directory of your | ||
| 156 | local Yocto Project repository is <code class="filename">poky</code>. | ||
| 157 | After moving to the <code class="filename">poky</code> directory, the | ||
| 158 | <code class="filename">git fetch</code> command makes all the upstream | ||
| 159 | tags available locally in your repository. | ||
| 160 | Finally, the <code class="filename">git checkout</code> command | ||
| 161 | creates and checks out a branch named "my-pyro-17.0.0" that is | ||
| 162 | based on the specific change upstream in the repository | ||
| 163 | associated with the "pyro-17.0.0" tag. | ||
| 164 | The files in your repository now exactly match that particular | ||
| 165 | Yocto Project release as it is tagged in the upstream Git | ||
| 166 | repository. | ||
| 167 | It is important to understand that when you create and | ||
| 168 | checkout a local working branch based on a tag, your environment | ||
| 169 | matches a specific point in time and not the entire development | ||
| 170 | branch (i.e. the "tip" of the branch). | ||
| 171 | </p> | ||
| 172 | </div></body> | ||
| 173 | </html> | ||
diff --git a/documentation/getting-started/eclipse/html/getting-started/running-weston.html b/documentation/getting-started/eclipse/html/getting-started/running-weston.html new file mode 100644 index 0000000000..b68f574134 --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/running-weston.html | |||
| @@ -0,0 +1,53 @@ | |||
| 1 | <html> | ||
| 2 | <head> | ||
| 3 | <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> | ||
| 4 | <title>3.6.3.Running Weston</title> | ||
| 5 | <link rel="stylesheet" type="text/css" href="../book.css"> | ||
| 6 | <meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> | ||
| 7 | <link rel="home" href="index.html" title="Getting Started With Yocto Project"> | ||
| 8 | <link rel="up" href="wayland.html" title="3.6.Wayland"> | ||
| 9 | <link rel="prev" href="enable-installation-in-an-image.html" title="3.6.2.2.Installing"> | ||
| 10 | <link rel="next" href="overview-licenses.html" title="3.7.Licenses"> | ||
| 11 | </head> | ||
| 12 | <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="3.6.3.Running Weston"> | ||
| 13 | <div class="titlepage"><div><div><h3 class="title"> | ||
| 14 | <a name="running-weston"></a>3.6.3.Running Weston</h3></div></div></div> | ||
| 15 | <p> | ||
| 16 | To run Weston inside X11, enabling it as described earlier and | ||
| 17 | building a Sato image is sufficient. | ||
| 18 | If you are running your image under Sato, a Weston Launcher | ||
| 19 | appears in the "Utility" category. | ||
| 20 | </p> | ||
| 21 | <p> | ||
| 22 | Alternatively, you can run Weston through the command-line | ||
| 23 | interpretor (CLI), which is better suited for development work. | ||
| 24 | To run Weston under the CLI, you need to do the following after | ||
| 25 | your image is built: | ||
| 26 | </p> | ||
| 27 | <div class="orderedlist"><ol class="orderedlist" type="1"> | ||
| 28 | <li class="listitem"> | ||
| 29 | <p> | ||
| 30 | Run these commands to export | ||
| 31 | <code class="filename">XDG_RUNTIME_DIR</code>: | ||
| 32 | </p> | ||
| 33 | <pre class="literallayout"> | ||
| 34 | mkdir -p /tmp/$USER-weston | ||
| 35 | chmod 0700 /tmp/$USER-weston | ||
| 36 | export XDG_RUNTIME_DIR=/tmp/$USER-weston | ||
| 37 | </pre> | ||
| 38 | <p> | ||
| 39 | </p> | ||
| 40 | </li> | ||
| 41 | <li class="listitem"> | ||
| 42 | <p> | ||
| 43 | Launch Weston in the shell: | ||
| 44 | </p> | ||
| 45 | <pre class="literallayout"> | ||
| 46 | weston | ||
| 47 | </pre> | ||
| 48 | </li> | ||
| 49 | </ol></div> | ||
| 50 | <p> | ||
| 51 | </p> | ||
| 52 | </div></body> | ||
| 53 | </html> | ||
diff --git a/documentation/getting-started/eclipse/html/getting-started/scms.html b/documentation/getting-started/eclipse/html/getting-started/scms.html new file mode 100644 index 0000000000..f2ec54340c --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/scms.html | |||
| @@ -0,0 +1,42 @@ | |||
| 1 | <html> | ||
| 2 | <head> | ||
| 3 | <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> | ||
| 4 | <title>2.8.3.3.Source Control Managers (Optional)</title> | ||
| 5 | <link rel="stylesheet" type="text/css" href="../book.css"> | ||
| 6 | <meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> | ||
| 7 | <link rel="home" href="index.html" title="Getting Started With Yocto Project"> | ||
| 8 | <link rel="up" href="sources-dev-environment.html" title="2.8.3.Sources"> | ||
| 9 | <link rel="prev" href="local-projects.html" title="2.8.3.2.Local Projects"> | ||
| 10 | <link rel="next" href="source-mirrors.html" title="2.8.3.4.Source Mirror(s)"> | ||
| 11 | </head> | ||
| 12 | <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="2.8.3.3.Source Control Managers (Optional)"> | ||
| 13 | <div class="titlepage"><div><div><h4 class="title"> | ||
| 14 | <a name="scms"></a>2.8.3.3.Source Control Managers (Optional)</h4></div></div></div> | ||
| 15 | <p> | ||
| 16 | Another place the build system can get source files from is | ||
| 17 | through an SCM such as Git or Subversion. | ||
| 18 | In this case, a repository is cloned or checked out. | ||
| 19 | The | ||
| 20 | <a class="link" href="../ref-manual/ref-tasks-fetch.html" target="_self"><code class="filename">do_fetch</code></a> | ||
| 21 | task inside BitBake uses | ||
| 22 | the <a class="link" href="../ref-manual/var-SRC_URI.html" target="_self"><code class="filename">SRC_URI</code></a> | ||
| 23 | variable and the argument's prefix to determine the correct | ||
| 24 | fetcher module. | ||
| 25 | </p> | ||
| 26 | <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"> | ||
| 27 | <h3 class="title">Note</h3> | ||
| 28 | For information on how to have the OpenEmbedded build system | ||
| 29 | generate tarballs for Git repositories and place them in the | ||
| 30 | <a class="link" href="../ref-manual/var-DL_DIR.html" target="_self"><code class="filename">DL_DIR</code></a> | ||
| 31 | directory, see the | ||
| 32 | <a class="link" href="../ref-manual/var-BB_GENERATE_MIRROR_TARBALLS.html" target="_self"><code class="filename">BB_GENERATE_MIRROR_TARBALLS</code></a> | ||
| 33 | variable. | ||
| 34 | </div> | ||
| 35 | <p> | ||
| 36 | When fetching a repository, BitBake uses the | ||
| 37 | <a class="link" href="../ref-manual/var-SRCREV.html" target="_self"><code class="filename">SRCREV</code></a> | ||
| 38 | variable to determine the specific revision from which to | ||
| 39 | build. | ||
| 40 | </p> | ||
| 41 | </div></body> | ||
| 42 | </html> | ||
diff --git a/documentation/getting-started/eclipse/html/getting-started/sdk-dev-environment.html b/documentation/getting-started/eclipse/html/getting-started/sdk-dev-environment.html new file mode 100644 index 0000000000..d2cd6a480e --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/sdk-dev-environment.html | |||
| @@ -0,0 +1,150 @@ | |||
| 1 | <html> | ||
| 2 | <head> | ||
| 3 | <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> | ||
| 4 | <title>2.8.7.Application Development SDK</title> | ||
| 5 | <link rel="stylesheet" type="text/css" href="../book.css"> | ||
| 6 | <meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> | ||
| 7 | <link rel="home" href="index.html" title="Getting Started With Yocto Project"> | ||
| 8 | <link rel="up" href="development-concepts.html" title="2.8.Development Concepts"> | ||
| 9 | <link rel="prev" href="images-dev-environment.html" title="2.8.6.Images"> | ||
| 10 | <link rel="next" href="overview-concepts.html" title="Chapter3.Yocto Project Concepts"> | ||
| 11 | </head> | ||
| 12 | <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="2.8.7.Application Development SDK"> | ||
| 13 | <div class="titlepage"><div><div><h3 class="title"> | ||
| 14 | <a name="sdk-dev-environment"></a>2.8.7.Application Development SDK</h3></div></div></div> | ||
| 15 | <p> | ||
| 16 | In the | ||
| 17 | <a class="link" href="development-concepts.html#general-yocto-environment-figure">general Yocto Project Development Environment figure</a>, | ||
| 18 | the output labeled "Application Development SDK" represents an | ||
| 19 | SDK. | ||
| 20 | The SDK generation process differs depending on whether you build | ||
| 21 | a standard SDK | ||
| 22 | (e.g. <code class="filename">bitbake -c populate_sdk</code> <em class="replaceable"><code>imagename</code></em>) | ||
| 23 | or an extensible SDK | ||
| 24 | (e.g. <code class="filename">bitbake -c populate_sdk_ext</code> <em class="replaceable"><code>imagename</code></em>). | ||
| 25 | This section is going to take a closer look at this output: | ||
| 26 | </p> | ||
| 27 | <table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="810"><tr style="height: 653px"><td align="center"><img src="figures/sdk.png" align="middle" width="810"></td></tr></table> | ||
| 28 | <p> | ||
| 29 | </p> | ||
| 30 | <p> | ||
| 31 | The specific form of this output is a self-extracting | ||
| 32 | SDK installer (<code class="filename">*.sh</code>) that, when run, | ||
| 33 | installs the SDK, which consists of a cross-development | ||
| 34 | toolchain, a set of libraries and headers, and an SDK | ||
| 35 | environment setup script. | ||
| 36 | Running this installer essentially sets up your | ||
| 37 | cross-development environment. | ||
| 38 | You can think of the cross-toolchain as the "host" | ||
| 39 | part because it runs on the SDK machine. | ||
| 40 | You can think of the libraries and headers as the "target" | ||
| 41 | part because they are built for the target hardware. | ||
| 42 | The environment setup script is added so that you can initialize | ||
| 43 | the environment before using the tools. | ||
| 44 | </p> | ||
| 45 | <div class="note" title="Notes" style="margin-left: 0.5in; margin-right: 0.5in;"> | ||
| 46 | <h3 class="title">Notes</h3> | ||
| 47 | <div class="itemizedlist"><ul class="itemizedlist" type="disc"> | ||
| 48 | <li class="listitem"><p> | ||
| 49 | The Yocto Project supports several methods by which you can | ||
| 50 | set up this cross-development environment. | ||
| 51 | These methods include downloading pre-built SDK installers | ||
| 52 | or building and installing your own SDK installer. | ||
| 53 | </p></li> | ||
| 54 | <li class="listitem"><p> | ||
| 55 | For background information on cross-development toolchains | ||
| 56 | in the Yocto Project development environment, see the | ||
| 57 | "<a class="link" href="cross-development-toolchain-generation.html" title="3.2.Cross-Development Toolchain Generation">Cross-Development Toolchain Generation</a>" | ||
| 58 | section. | ||
| 59 | </p></li> | ||
| 60 | <li class="listitem"><p> | ||
| 61 | For information on setting up a cross-development | ||
| 62 | environment, see the | ||
| 63 | <a class="link" href="../sdk-manual/index.html" target="_self">Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</a> | ||
| 64 | manual. | ||
| 65 | </p></li> | ||
| 66 | </ul></div> | ||
| 67 | </div> | ||
| 68 | <p> | ||
| 69 | Once built, the SDK installers are written out to the | ||
| 70 | <code class="filename">deploy/sdk</code> folder inside the | ||
| 71 | <a class="link" href="../ref-manual/build-directory.html" target="_self">Build Directory</a> | ||
| 72 | as shown in the figure at the beginning of this section. | ||
| 73 | Depending on the type of SDK, several variables exist that help | ||
| 74 | configure these files. | ||
| 75 | The following list shows the variables associated with a standard | ||
| 76 | SDK: | ||
| 77 | </p> | ||
| 78 | <div class="itemizedlist"><ul class="itemizedlist" type="disc"> | ||
| 79 | <li class="listitem"><p><a class="link" href="../ref-manual/var-DEPLOY_DIR.html" target="_self"><code class="filename">DEPLOY_DIR</code></a>: | ||
| 80 | Points to the <code class="filename">deploy</code> | ||
| 81 | directory.</p></li> | ||
| 82 | <li class="listitem"><p><a class="link" href="../ref-manual/var-SDKMACHINE.html" target="_self"><code class="filename">SDKMACHINE</code></a>: | ||
| 83 | Specifies the architecture of the machine | ||
| 84 | on which the cross-development tools are run to | ||
| 85 | create packages for the target hardware. | ||
| 86 | </p></li> | ||
| 87 | <li class="listitem"><p><a class="link" href="../ref-manual/var-SDKIMAGE_FEATURES.html" target="_self"><code class="filename">SDKIMAGE_FEATURES</code></a>: | ||
| 88 | Lists the features to include in the "target" part | ||
| 89 | of the SDK. | ||
| 90 | </p></li> | ||
| 91 | <li class="listitem"><p><a class="link" href="../ref-manual/var-TOOLCHAIN_HOST_TASK.html" target="_self"><code class="filename">TOOLCHAIN_HOST_TASK</code></a>: | ||
| 92 | Lists packages that make up the host | ||
| 93 | part of the SDK (i.e. the part that runs on | ||
| 94 | the <code class="filename">SDKMACHINE</code>). | ||
| 95 | When you use | ||
| 96 | <code class="filename">bitbake -c populate_sdk <em class="replaceable"><code>imagename</code></em></code> | ||
| 97 | to create the SDK, a set of default packages | ||
| 98 | apply. | ||
| 99 | This variable allows you to add more packages. | ||
| 100 | </p></li> | ||
| 101 | <li class="listitem"><p><a class="link" href="../ref-manual/var-TOOLCHAIN_TARGET_TASK.html" target="_self"><code class="filename">TOOLCHAIN_TARGET_TASK</code></a>: | ||
| 102 | Lists packages that make up the target part | ||
| 103 | of the SDK (i.e. the part built for the | ||
| 104 | target hardware). | ||
| 105 | </p></li> | ||
| 106 | <li class="listitem"><p><a class="link" href="../ref-manual/var-SDKPATH.html" target="_self"><code class="filename">SDKPATH</code></a>: | ||
| 107 | Defines the default SDK installation path offered by the | ||
| 108 | installation script. | ||
| 109 | </p></li> | ||
| 110 | </ul></div> | ||
| 111 | <p> | ||
| 112 | This next list, shows the variables associated with an extensible | ||
| 113 | SDK: | ||
| 114 | </p> | ||
| 115 | <div class="itemizedlist"><ul class="itemizedlist" type="disc"> | ||
| 116 | <li class="listitem"><p><a class="link" href="../ref-manual/var-DEPLOY_DIR.html" target="_self"><code class="filename">DEPLOY_DIR</code></a>: | ||
| 117 | Points to the <code class="filename">deploy</code> directory. | ||
| 118 | </p></li> | ||
| 119 | <li class="listitem"><p><a class="link" href="../ref-manual/var-SDK_EXT_TYPE.html" target="_self"><code class="filename">SDK_EXT_TYPE</code></a>: | ||
| 120 | Controls whether or not shared state artifacts are copied | ||
| 121 | into the extensible SDK. | ||
| 122 | By default, all required shared state artifacts are copied | ||
| 123 | into the SDK. | ||
| 124 | </p></li> | ||
| 125 | <li class="listitem"><p><a class="link" href="../ref-manual/var-SDK_INCLUDE_PKGDATA.html" target="_self"><code class="filename">SDK_INCLUDE_PKGDATA</code></a>: | ||
| 126 | Specifies whether or not packagedata will be included in | ||
| 127 | the extensible SDK for all recipes in the "world" target. | ||
| 128 | </p></li> | ||
| 129 | <li class="listitem"><p><a class="link" href="../ref-manual/var-SDK_INCLUDE_TOOLCHAIN.html" target="_self"><code class="filename">SDK_INCLUDE_TOOLCHAIN</code></a>: | ||
| 130 | Specifies whether or not the toolchain will be included | ||
| 131 | when building the extensible SDK. | ||
| 132 | </p></li> | ||
| 133 | <li class="listitem"><p><a class="link" href="../ref-manual/var-SDK_LOCAL_CONF_WHITELIST.html" target="_self"><code class="filename">SDK_LOCAL_CONF_WHITELIST</code></a>: | ||
| 134 | A list of variables allowed through from the build system | ||
| 135 | configuration into the extensible SDK configuration. | ||
| 136 | </p></li> | ||
| 137 | <li class="listitem"><p><a class="link" href="../ref-manual/var-SDK_LOCAL_CONF_BLACKLIST.html" target="_self"><code class="filename">SDK_LOCAL_CONF_BLACKLIST</code></a>: | ||
| 138 | A list of variables not allowed through from the build | ||
| 139 | system configuration into the extensible SDK configuration. | ||
| 140 | </p></li> | ||
| 141 | <li class="listitem"><p><a class="link" href="../ref-manual/var-SDK_INHERIT_BLACKLIST.html" target="_self"><code class="filename">SDK_INHERIT_BLACKLIST</code></a>: | ||
| 142 | A list of classes to remove from the | ||
| 143 | <a class="link" href="../ref-manual/var-INHERIT.html" target="_self"><code class="filename">INHERIT</code></a> | ||
| 144 | value globally within the extensible SDK configuration. | ||
| 145 | </p></li> | ||
| 146 | </ul></div> | ||
| 147 | <p> | ||
| 148 | </p> | ||
| 149 | </div></body> | ||
| 150 | </html> | ||
diff --git a/documentation/getting-started/eclipse/html/getting-started/sdk-generation-dev-environment.html b/documentation/getting-started/eclipse/html/getting-started/sdk-generation-dev-environment.html new file mode 100644 index 0000000000..1dfda5fab5 --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/sdk-generation-dev-environment.html | |||
| @@ -0,0 +1,72 @@ | |||
| 1 | <html> | ||
| 2 | <head> | ||
| 3 | <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> | ||
| 4 | <title>2.8.5.6.SDK Generation</title> | ||
| 5 | <link rel="stylesheet" type="text/css" href="../book.css"> | ||
| 6 | <meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> | ||
| 7 | <link rel="home" href="index.html" title="Getting Started With Yocto Project"> | ||
| 8 | <link rel="up" href="bitbake-dev-environment.html" title="2.8.5.BitBake"> | ||
| 9 | <link rel="prev" href="image-generation-dev-environment.html" title="2.8.5.5.Image Generation"> | ||
| 10 | <link rel="next" href="stamp-files-and-the-rerunning-of-tasks.html" title="2.8.5.7.Stamp Files and the Rerunning of Tasks"> | ||
| 11 | </head> | ||
| 12 | <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="2.8.5.6.SDK Generation"> | ||
| 13 | <div class="titlepage"><div><div><h4 class="title"> | ||
| 14 | <a name="sdk-generation-dev-environment"></a>2.8.5.6.SDK Generation</h4></div></div></div> | ||
| 15 | <p> | ||
| 16 | The OpenEmbedded build system uses BitBake to generate the | ||
| 17 | Software Development Kit (SDK) installer script for both the | ||
| 18 | standard and extensible SDKs: | ||
| 19 | <img src="figures/sdk-generation.png" align="middle"> | ||
| 20 | </p> | ||
| 21 | <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"> | ||
| 22 | <h3 class="title">Note</h3> | ||
| 23 | For more information on the cross-development toolchain | ||
| 24 | generation, see the | ||
| 25 | "<a class="link" href="cross-development-toolchain-generation.html" title="3.2.Cross-Development Toolchain Generation">Cross-Development Toolchain Generation</a>" | ||
| 26 | section. | ||
| 27 | For information on advantages gained when building a | ||
| 28 | cross-development toolchain using the | ||
| 29 | <a class="link" href="../ref-manual/ref-tasks-populate_sdk.html" target="_self"><code class="filename">do_populate_sdk</code></a> | ||
| 30 | task, see the | ||
| 31 | "<a class="link" href="../sdk-manual/sdk-building-an-sdk-installer.html" target="_self">Building an SDK Installer</a>" | ||
| 32 | section in the Yocto Project Application Development and the | ||
| 33 | Extensible Software Development Kit (SDK) manual. | ||
| 34 | </div> | ||
| 35 | <p> | ||
| 36 | Like image generation, the SDK script process consists of | ||
| 37 | several stages and depends on many variables. | ||
| 38 | The <code class="filename">do_populate_sdk</code> and | ||
| 39 | <code class="filename">do_populate_sdk_ext</code> tasks use these | ||
| 40 | key variables to help create the list of packages to actually | ||
| 41 | install. | ||
| 42 | For information on the variables listed in the figure, see the | ||
| 43 | "<a class="link" href="sdk-dev-environment.html" title="2.8.7.Application Development SDK">Application Development SDK</a>" | ||
| 44 | section. | ||
| 45 | </p> | ||
| 46 | <p> | ||
| 47 | The <code class="filename">do_populate_sdk</code> task helps create | ||
| 48 | the standard SDK and handles two parts: a target part and a | ||
| 49 | host part. | ||
| 50 | The target part is the part built for the target hardware and | ||
| 51 | includes libraries and headers. | ||
| 52 | The host part is the part of the SDK that runs on the | ||
| 53 | <a class="link" href="../ref-manual/var-SDKMACHINE.html" target="_self"><code class="filename">SDKMACHINE</code></a>. | ||
| 54 | </p> | ||
| 55 | <p> | ||
| 56 | The <code class="filename">do_populate_sdk_ext</code> task helps create | ||
| 57 | the extensible SDK and handles host and target parts | ||
| 58 | differently than its counter part does for the standard SDK. | ||
| 59 | For the extensible SDK, the task encapsulates the build system, | ||
| 60 | which includes everything needed (host and target) for the SDK. | ||
| 61 | </p> | ||
| 62 | <p> | ||
| 63 | Regardless of the type of SDK being constructed, the | ||
| 64 | tasks perform some cleanup after which a cross-development | ||
| 65 | environment setup script and any needed configuration files | ||
| 66 | are created. | ||
| 67 | The final output is the Cross-development | ||
| 68 | toolchain installation script (<code class="filename">.sh</code> file), | ||
| 69 | which includes the environment setup script. | ||
| 70 | </p> | ||
| 71 | </div></body> | ||
| 72 | </html> | ||
diff --git a/documentation/getting-started/eclipse/html/getting-started/setscene-tasks-and-shared-state.html b/documentation/getting-started/eclipse/html/getting-started/setscene-tasks-and-shared-state.html new file mode 100644 index 0000000000..644e404b66 --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/setscene-tasks-and-shared-state.html | |||
| @@ -0,0 +1,122 @@ | |||
| 1 | <html> | ||
| 2 | <head> | ||
| 3 | <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> | ||
| 4 | <title>2.8.5.8.Setscene Tasks and Shared State</title> | ||
| 5 | <link rel="stylesheet" type="text/css" href="../book.css"> | ||
| 6 | <meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> | ||
| 7 | <link rel="home" href="index.html" title="Getting Started With Yocto Project"> | ||
| 8 | <link rel="up" href="bitbake-dev-environment.html" title="2.8.5.BitBake"> | ||
| 9 | <link rel="prev" href="stamp-files-and-the-rerunning-of-tasks.html" title="2.8.5.7.Stamp Files and the Rerunning of Tasks"> | ||
| 10 | <link rel="next" href="images-dev-environment.html" title="2.8.6.Images"> | ||
| 11 | </head> | ||
| 12 | <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="2.8.5.8.Setscene Tasks and Shared State"> | ||
| 13 | <div class="titlepage"><div><div><h4 class="title"> | ||
| 14 | <a name="setscene-tasks-and-shared-state"></a>2.8.5.8.Setscene Tasks and Shared State</h4></div></div></div> | ||
| 15 | <p> | ||
| 16 | The description of tasks so far assumes that BitBake needs to | ||
| 17 | build everything and there are no prebuilt objects available. | ||
| 18 | BitBake does support skipping tasks if prebuilt objects are | ||
| 19 | available. | ||
| 20 | These objects are usually made available in the form of a | ||
| 21 | shared state (sstate) cache. | ||
| 22 | </p> | ||
| 23 | <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"> | ||
| 24 | <h3 class="title">Note</h3> | ||
| 25 | For information on variables affecting sstate, see the | ||
| 26 | <a class="link" href="../ref-manual/var-SSTATE_DIR.html" target="_self"><code class="filename">SSTATE_DIR</code></a> | ||
| 27 | and | ||
| 28 | <a class="link" href="../ref-manual/var-SSTATE_MIRRORS.html" target="_self"><code class="filename">SSTATE_MIRRORS</code></a> | ||
| 29 | variables. | ||
| 30 | </div> | ||
| 31 | <p> | ||
| 32 | </p> | ||
| 33 | <p> | ||
| 34 | The idea of a setscene task (i.e | ||
| 35 | <code class="filename">do_</code><em class="replaceable"><code>taskname</code></em><code class="filename">_setscene</code>) | ||
| 36 | is a version of the task where | ||
| 37 | instead of building something, BitBake can skip to the end | ||
| 38 | result and simply place a set of files into specific locations | ||
| 39 | as needed. | ||
| 40 | In some cases, it makes sense to have a setscene task variant | ||
| 41 | (e.g. generating package files in the | ||
| 42 | <code class="filename">do_package_write_*</code> task). | ||
| 43 | In other cases, it does not make sense, (e.g. a | ||
| 44 | <a class="link" href="../ref-manual/ref-tasks-patch.html" target="_self"><code class="filename">do_patch</code></a> | ||
| 45 | task or | ||
| 46 | <a class="link" href="../ref-manual/ref-tasks-unpack.html" target="_self"><code class="filename">do_unpack</code></a> | ||
| 47 | task) since the work involved would be equal to or greater than | ||
| 48 | the underlying task. | ||
| 49 | </p> | ||
| 50 | <p> | ||
| 51 | In the OpenEmbedded build system, the common tasks that have | ||
| 52 | setscene variants are | ||
| 53 | <a class="link" href="../ref-manual/ref-tasks-package.html" target="_self"><code class="filename">do_package</code></a>, | ||
| 54 | <code class="filename">do_package_write_*</code>, | ||
| 55 | <a class="link" href="../ref-manual/ref-tasks-deploy.html" target="_self"><code class="filename">do_deploy</code></a>, | ||
| 56 | <a class="link" href="../ref-manual/ref-tasks-packagedata.html" target="_self"><code class="filename">do_packagedata</code></a>, | ||
| 57 | and | ||
| 58 | <a class="link" href="../ref-manual/ref-tasks-populate_sysroot.html" target="_self"><code class="filename">do_populate_sysroot</code></a>. | ||
| 59 | Notice that these are most of the tasks whose output is an | ||
| 60 | end result. | ||
| 61 | </p> | ||
| 62 | <p> | ||
| 63 | The OpenEmbedded build system has knowledge of the relationship | ||
| 64 | between these tasks and other tasks that precede them. | ||
| 65 | For example, if BitBake runs | ||
| 66 | <code class="filename">do_populate_sysroot_setscene</code> for | ||
| 67 | something, there is little point in running any of the | ||
| 68 | <code class="filename">do_fetch</code>, <code class="filename">do_unpack</code>, | ||
| 69 | <code class="filename">do_patch</code>, | ||
| 70 | <code class="filename">do_configure</code>, | ||
| 71 | <code class="filename">do_compile</code>, and | ||
| 72 | <code class="filename">do_install</code> tasks. | ||
| 73 | However, if <code class="filename">do_package</code> needs to be run, | ||
| 74 | BitBake would need to run those other tasks. | ||
| 75 | </p> | ||
| 76 | <p> | ||
| 77 | It becomes more complicated if everything can come from an | ||
| 78 | sstate cache because some objects are simply not required at | ||
| 79 | all. | ||
| 80 | For example, you do not need a compiler or native tools, such | ||
| 81 | as quilt, if there is nothing to compile or patch. | ||
| 82 | If the <code class="filename">do_package_write_*</code> packages are | ||
| 83 | available from sstate, BitBake does not need the | ||
| 84 | <code class="filename">do_package</code> task data. | ||
| 85 | </p> | ||
| 86 | <p> | ||
| 87 | To handle all these complexities, BitBake runs in two phases. | ||
| 88 | The first is the "setscene" stage. | ||
| 89 | During this stage, BitBake first checks the sstate cache for | ||
| 90 | any targets it is planning to build. | ||
| 91 | BitBake does a fast check to see if the object exists rather | ||
| 92 | than a complete download. | ||
| 93 | If nothing exists, the second phase, which is the setscene | ||
| 94 | stage, completes and the main build proceeds. | ||
| 95 | </p> | ||
| 96 | <p> | ||
| 97 | If objects are found in the sstate cache, the OpenEmbedded | ||
| 98 | build system works backwards from the end targets specified | ||
| 99 | by the user. | ||
| 100 | For example, if an image is being built, the OpenEmbedded build | ||
| 101 | system first looks for the packages needed for that image and | ||
| 102 | the tools needed to construct an image. | ||
| 103 | If those are available, the compiler is not needed. | ||
| 104 | Thus, the compiler is not even downloaded. | ||
| 105 | If something was found to be unavailable, or the download or | ||
| 106 | setscene task fails, the OpenEmbedded build system then tries | ||
| 107 | to install dependencies, such as the compiler, from the cache. | ||
| 108 | </p> | ||
| 109 | <p> | ||
| 110 | The availability of objects in the sstate cache is handled by | ||
| 111 | the function specified by the | ||
| 112 | <a class="link" href="../bitbake-user-manual/var-BB_HASHCHECK_FUNCTION.html" target="_self"><code class="filename">BB_HASHCHECK_FUNCTION</code></a> | ||
| 113 | variable and returns a list of the objects that are available. | ||
| 114 | The function specified by the | ||
| 115 | <a class="link" href="../bitbake-user-manual/var-BB_SETSCENE_DEPVALID.html" target="_self"><code class="filename">BB_SETSCENE_DEPVALID</code></a> | ||
| 116 | variable is the function that determines whether a given | ||
| 117 | dependency needs to be followed, and whether for any given | ||
| 118 | relationship the function needs to be passed. | ||
| 119 | The function returns a True or False value. | ||
| 120 | </p> | ||
| 121 | </div></body> | ||
| 122 | </html> | ||
diff --git a/documentation/getting-started/eclipse/html/getting-started/shared-state-cache.html b/documentation/getting-started/eclipse/html/getting-started/shared-state-cache.html new file mode 100644 index 0000000000..c5c6be04a3 --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/shared-state-cache.html | |||
| @@ -0,0 +1,93 @@ | |||
| 1 | <html> | ||
| 2 | <head> | ||
| 3 | <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> | ||
| 4 | <title>3.3.Shared State Cache</title> | ||
| 5 | <link rel="stylesheet" type="text/css" href="../book.css"> | ||
| 6 | <meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> | ||
| 7 | <link rel="home" href="index.html" title="Getting Started With Yocto Project"> | ||
| 8 | <link rel="up" href="overview-concepts.html" title="Chapter3.Yocto Project Concepts"> | ||
| 9 | <link rel="prev" href="cross-development-toolchain-generation.html" title="3.2.Cross-Development Toolchain Generation"> | ||
| 10 | <link rel="next" href="overall-architecture.html" title="3.3.1.Overall Architecture"> | ||
| 11 | </head> | ||
| 12 | <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="3.3.Shared State Cache"> | ||
| 13 | <div class="titlepage"><div><div><h2 class="title" style="clear: both"> | ||
| 14 | <a name="shared-state-cache"></a>3.3.Shared State Cache</h2></div></div></div> | ||
| 15 | <p> | ||
| 16 | By design, the OpenEmbedded build system builds everything from | ||
| 17 | scratch unless BitBake can determine that parts do not need to be | ||
| 18 | rebuilt. | ||
| 19 | Fundamentally, building from scratch is attractive as it means all | ||
| 20 | parts are built fresh and there is no possibility of stale data | ||
| 21 | causing problems. | ||
| 22 | When developers hit problems, they typically default back to | ||
| 23 | building from scratch so they know the state of things from the | ||
| 24 | start. | ||
| 25 | </p> | ||
| 26 | <p> | ||
| 27 | Building an image from scratch is both an advantage and a | ||
| 28 | disadvantage to the process. | ||
| 29 | As mentioned in the previous paragraph, building from scratch | ||
| 30 | ensures that everything is current and starts from a known state. | ||
| 31 | However, building from scratch also takes much longer as it | ||
| 32 | generally means rebuilding things that do not necessarily need | ||
| 33 | to be rebuilt. | ||
| 34 | </p> | ||
| 35 | <p> | ||
| 36 | The Yocto Project implements shared state code that supports | ||
| 37 | incremental builds. | ||
| 38 | The implementation of the shared state code answers the following | ||
| 39 | questions that were fundamental roadblocks within the OpenEmbedded | ||
| 40 | incremental build support system: | ||
| 41 | </p> | ||
| 42 | <div class="itemizedlist"><ul class="itemizedlist" type="disc"> | ||
| 43 | <li class="listitem"><p> | ||
| 44 | What pieces of the system have changed and what pieces have | ||
| 45 | not changed? | ||
| 46 | </p></li> | ||
| 47 | <li class="listitem"><p> | ||
| 48 | How are changed pieces of software removed and replaced? | ||
| 49 | </p></li> | ||
| 50 | <li class="listitem"><p> | ||
| 51 | How are pre-built components that do not need to be rebuilt | ||
| 52 | from scratch used when they are available? | ||
| 53 | </p></li> | ||
| 54 | </ul></div> | ||
| 55 | <p> | ||
| 56 | </p> | ||
| 57 | <p> | ||
| 58 | For the first question, the build system detects changes in the | ||
| 59 | "inputs" to a given task by creating a checksum (or signature) of | ||
| 60 | the task's inputs. | ||
| 61 | If the checksum changes, the system assumes the inputs have changed | ||
| 62 | and the task needs to be rerun. | ||
| 63 | For the second question, the shared state (sstate) code tracks | ||
| 64 | which tasks add which output to the build process. | ||
| 65 | This means the output from a given task can be removed, upgraded | ||
| 66 | or otherwise manipulated. | ||
| 67 | The third question is partly addressed by the solution for the | ||
| 68 | second question assuming the build system can fetch the sstate | ||
| 69 | objects from remote locations and install them if they are deemed | ||
| 70 | to be valid. | ||
| 71 | </p> | ||
| 72 | <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"> | ||
| 73 | <h3 class="title">Note</h3> | ||
| 74 | The OpenEmbedded build system does not maintain | ||
| 75 | <a class="link" href="../ref-manual/var-PR.html" target="_self"><code class="filename">PR</code></a> | ||
| 76 | information as part of the shared state packages. | ||
| 77 | Consequently, considerations exist that affect maintaining | ||
| 78 | shared state feeds. | ||
| 79 | For information on how the OpenEmbedded build system | ||
| 80 | works with packages and can track incrementing | ||
| 81 | <code class="filename">PR</code> information, see the | ||
| 82 | "<a class="link" href="../dev-manual/automatically-incrementing-a-binary-package-revision-number.html" target="_self">Automatically Incrementing a Binary Package Revision Number</a>" | ||
| 83 | section in the Yocto Project Development Tasks Manual. | ||
| 84 | </div> | ||
| 85 | <p> | ||
| 86 | </p> | ||
| 87 | <p> | ||
| 88 | The rest of this section goes into detail about the overall | ||
| 89 | incremental build architecture, the checksums (signatures), shared | ||
| 90 | state, and some tips and tricks. | ||
| 91 | </p> | ||
| 92 | </div></body> | ||
| 93 | </html> | ||
diff --git a/documentation/getting-started/eclipse/html/getting-started/shared-state.html b/documentation/getting-started/eclipse/html/getting-started/shared-state.html new file mode 100644 index 0000000000..4389684f3b --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/shared-state.html | |||
| @@ -0,0 +1,268 @@ | |||
| 1 | <html> | ||
| 2 | <head> | ||
| 3 | <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> | ||
| 4 | <title>3.3.3.Shared State</title> | ||
| 5 | <link rel="stylesheet" type="text/css" href="../book.css"> | ||
| 6 | <meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> | ||
| 7 | <link rel="home" href="index.html" title="Getting Started With Yocto Project"> | ||
| 8 | <link rel="up" href="shared-state-cache.html" title="3.3.Shared State Cache"> | ||
| 9 | <link rel="prev" href="overview-checksums.html" title="3.3.2.Checksums (Signatures)"> | ||
| 10 | <link rel="next" href="tips-and-tricks.html" title="3.3.4.Tips and Tricks"> | ||
| 11 | </head> | ||
| 12 | <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="3.3.3.Shared State"> | ||
| 13 | <div class="titlepage"><div><div><h3 class="title"> | ||
| 14 | <a name="shared-state"></a>3.3.3.Shared State</h3></div></div></div> | ||
| 15 | <p> | ||
| 16 | Checksums and dependencies, as discussed in the previous | ||
| 17 | section, solve half the problem of supporting a shared state. | ||
| 18 | The other part of the problem is being able to use checksum | ||
| 19 | information during the build and being able to reuse or rebuild | ||
| 20 | specific components. | ||
| 21 | </p> | ||
| 22 | <p> | ||
| 23 | The | ||
| 24 | <a class="link" href="../ref-manual/ref-classes-sstate.html" target="_self"><code class="filename">sstate</code></a> | ||
| 25 | class is a relatively generic implementation of how to | ||
| 26 | "capture" a snapshot of a given task. | ||
| 27 | The idea is that the build process does not care about the | ||
| 28 | source of a task's output. | ||
| 29 | Output could be freshly built or it could be downloaded and | ||
| 30 | unpacked from somewhere - the build process does not need to | ||
| 31 | worry about its origin. | ||
| 32 | </p> | ||
| 33 | <p> | ||
| 34 | There are two types of output, one is just about creating a | ||
| 35 | directory in | ||
| 36 | <a class="link" href="../ref-manual/var-WORKDIR.html" target="_self"><code class="filename">WORKDIR</code></a>. | ||
| 37 | A good example is the output of either | ||
| 38 | <a class="link" href="../ref-manual/ref-tasks-install.html" target="_self"><code class="filename">do_install</code></a> | ||
| 39 | or | ||
| 40 | <a class="link" href="../ref-manual/ref-tasks-package.html" target="_self"><code class="filename">do_package</code></a>. | ||
| 41 | The other type of output occurs when a set of data is merged | ||
| 42 | into a shared directory tree such as the sysroot. | ||
| 43 | </p> | ||
| 44 | <p> | ||
| 45 | The Yocto Project team has tried to keep the details of the | ||
| 46 | implementation hidden in <code class="filename">sstate</code> class. | ||
| 47 | From a user's perspective, adding shared state wrapping to a task | ||
| 48 | is as simple as this | ||
| 49 | <a class="link" href="../ref-manual/ref-tasks-deploy.html" target="_self"><code class="filename">do_deploy</code></a> | ||
| 50 | example taken from the | ||
| 51 | <a class="link" href="../ref-manual/ref-classes-deploy.html" target="_self"><code class="filename">deploy</code></a> | ||
| 52 | class: | ||
| 53 | </p> | ||
| 54 | <pre class="literallayout"> | ||
| 55 | DEPLOYDIR = "${WORKDIR}/deploy-${PN}" | ||
| 56 | SSTATETASKS += "do_deploy" | ||
| 57 | do_deploy[sstate-inputdirs] = "${DEPLOYDIR}" | ||
| 58 | do_deploy[sstate-outputdirs] = "${DEPLOY_DIR_IMAGE}" | ||
| 59 | |||
| 60 | python do_deploy_setscene () { | ||
| 61 | sstate_setscene(d) | ||
| 62 | } | ||
| 63 | addtask do_deploy_setscene | ||
| 64 | do_deploy[dirs] = "${DEPLOYDIR} ${B}" | ||
| 65 | </pre> | ||
| 66 | <p> | ||
| 67 | The following list explains the previous example: | ||
| 68 | </p> | ||
| 69 | <div class="itemizedlist"><ul class="itemizedlist" type="disc"> | ||
| 70 | <li class="listitem"><p> | ||
| 71 | Adding "do_deploy" to <code class="filename">SSTATETASKS</code> | ||
| 72 | adds some required sstate-related processing, which is | ||
| 73 | implemented in the | ||
| 74 | <a class="link" href="../ref-manual/ref-classes-sstate.html" target="_self"><code class="filename">sstate</code></a> | ||
| 75 | class, to before and after the | ||
| 76 | <a class="link" href="../ref-manual/ref-tasks-deploy.html" target="_self"><code class="filename">do_deploy</code></a> | ||
| 77 | task. | ||
| 78 | </p></li> | ||
| 79 | <li class="listitem"><p> | ||
| 80 | The | ||
| 81 | <code class="filename">do_deploy[sstate-inputdirs] = "${DEPLOYDIR}"</code> | ||
| 82 | declares that <code class="filename">do_deploy</code> places its | ||
| 83 | output in <code class="filename">${DEPLOYDIR}</code> when run | ||
| 84 | normally (i.e. when not using the sstate cache). | ||
| 85 | This output becomes the input to the shared state cache. | ||
| 86 | </p></li> | ||
| 87 | <li class="listitem"> | ||
| 88 | <p> | ||
| 89 | The | ||
| 90 | <code class="filename">do_deploy[sstate-outputdirs] = "${DEPLOY_DIR_IMAGE}"</code> | ||
| 91 | line causes the contents of the shared state cache to be | ||
| 92 | copied to <code class="filename">${DEPLOY_DIR_IMAGE}</code>. | ||
| 93 | </p> | ||
| 94 | <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"> | ||
| 95 | <h3 class="title">Note</h3> | ||
| 96 | If <code class="filename">do_deploy</code> is not already in | ||
| 97 | the shared state cache or if its input checksum | ||
| 98 | (signature) has changed from when the output was | ||
| 99 | cached, the task will be run to populate the shared | ||
| 100 | state cache, after which the contents of the shared | ||
| 101 | state cache is copied to | ||
| 102 | <code class="filename">${DEPLOY_DIR_IMAGE}</code>. | ||
| 103 | If <code class="filename">do_deploy</code> is in the shared | ||
| 104 | state cache and its signature indicates that the | ||
| 105 | cached output is still valid (i.e. if no | ||
| 106 | relevant task inputs have changed), then the | ||
| 107 | contents of the shared state cache will be copied | ||
| 108 | directly to | ||
| 109 | <code class="filename">${DEPLOY_DIR_IMAGE}</code> by the | ||
| 110 | <code class="filename">do_deploy_setscene</code> task | ||
| 111 | instead, skipping the | ||
| 112 | <code class="filename">do_deploy</code> task. | ||
| 113 | </div> | ||
| 114 | <p> | ||
| 115 | </p> | ||
| 116 | </li> | ||
| 117 | <li class="listitem"> | ||
| 118 | <p> | ||
| 119 | The following task definition is glue logic needed to | ||
| 120 | make the previous settings effective: | ||
| 121 | </p> | ||
| 122 | <pre class="literallayout"> | ||
| 123 | python do_deploy_setscene () { | ||
| 124 | sstate_setscene(d) | ||
| 125 | } | ||
| 126 | addtask do_deploy_setscene | ||
| 127 | </pre> | ||
| 128 | <p> | ||
| 129 | <code class="filename">sstate_setscene()</code> takes the flags | ||
| 130 | above as input and accelerates the | ||
| 131 | <code class="filename">do_deploy</code> task through the | ||
| 132 | shared state cache if possible. | ||
| 133 | If the task was accelerated, | ||
| 134 | <code class="filename">sstate_setscene()</code> returns True. | ||
| 135 | Otherwise, it returns False, and the normal | ||
| 136 | <code class="filename">do_deploy</code> task runs. | ||
| 137 | For more information, see the | ||
| 138 | "<a class="link" href="../bitbake-user-manual/setscene.html" target="_self">setscene</a>" | ||
| 139 | section in the BitBake User Manual. | ||
| 140 | </p> | ||
| 141 | </li> | ||
| 142 | <li class="listitem"> | ||
| 143 | <p> | ||
| 144 | The <code class="filename">do_deploy[dirs] = "${DEPLOYDIR} ${B}"</code> | ||
| 145 | line creates <code class="filename">${DEPLOYDIR}</code> and | ||
| 146 | <code class="filename">${B}</code> before the | ||
| 147 | <code class="filename">do_deploy</code> task runs, and also sets | ||
| 148 | the current working directory of | ||
| 149 | <code class="filename">do_deploy</code> to | ||
| 150 | <code class="filename">${B}</code>. | ||
| 151 | For more information, see the | ||
| 152 | "<a class="link" href="../bitbake-user-manual/variable-flags.html" target="_self">Variable Flags</a>" | ||
| 153 | section in the BitBake User Manual. | ||
| 154 | </p> | ||
| 155 | <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"> | ||
| 156 | <h3 class="title">Note</h3> | ||
| 157 | In cases where | ||
| 158 | <code class="filename">sstate-inputdirs</code> and | ||
| 159 | <code class="filename">sstate-outputdirs</code> would be the | ||
| 160 | same, you can use | ||
| 161 | <code class="filename">sstate-plaindirs</code>. | ||
| 162 | For example, to preserve the | ||
| 163 | <code class="filename">${PKGD}</code> and | ||
| 164 | <code class="filename">${PKGDEST}</code> output from the | ||
| 165 | <a class="link" href="../ref-manual/ref-tasks-package.html" target="_self"><code class="filename">do_package</code></a> | ||
| 166 | task, use the following: | ||
| 167 | <pre class="literallayout"> | ||
| 168 | do_package[sstate-plaindirs] = "${PKGD} ${PKGDEST}" | ||
| 169 | </pre> | ||
| 170 | </div> | ||
| 171 | <p> | ||
| 172 | </p> | ||
| 173 | </li> | ||
| 174 | <li class="listitem"> | ||
| 175 | <p> | ||
| 176 | <code class="filename">sstate-inputdirs</code> and | ||
| 177 | <code class="filename">sstate-outputdirs</code> can also be used | ||
| 178 | with multiple directories. | ||
| 179 | For example, the following declares | ||
| 180 | <code class="filename">PKGDESTWORK</code> and | ||
| 181 | <code class="filename">SHLIBWORK</code> as shared state | ||
| 182 | input directories, which populates the shared state | ||
| 183 | cache, and <code class="filename">PKGDATA_DIR</code> and | ||
| 184 | <code class="filename">SHLIBSDIR</code> as the corresponding | ||
| 185 | shared state output directories: | ||
| 186 | </p> | ||
| 187 | <pre class="literallayout"> | ||
| 188 | do_package[sstate-inputdirs] = "${PKGDESTWORK} ${SHLIBSWORKDIR}" | ||
| 189 | do_package[sstate-outputdirs] = "${PKGDATA_DIR} ${SHLIBSDIR}" | ||
| 190 | </pre> | ||
| 191 | <p> | ||
| 192 | </p> | ||
| 193 | </li> | ||
| 194 | <li class="listitem"> | ||
| 195 | <p> | ||
| 196 | These methods also include the ability to take a | ||
| 197 | lockfile when manipulating shared state directory | ||
| 198 | structures, for cases where file additions or removals | ||
| 199 | are sensitive: | ||
| 200 | </p> | ||
| 201 | <pre class="literallayout"> | ||
| 202 | do_package[sstate-lockfile] = "${PACKAGELOCK}" | ||
| 203 | </pre> | ||
| 204 | <p> | ||
| 205 | </p> | ||
| 206 | </li> | ||
| 207 | </ul></div> | ||
| 208 | <p> | ||
| 209 | </p> | ||
| 210 | <p> | ||
| 211 | Behind the scenes, the shared state code works by looking in | ||
| 212 | <a class="link" href="../ref-manual/var-SSTATE_DIR.html" target="_self"><code class="filename">SSTATE_DIR</code></a> | ||
| 213 | and | ||
| 214 | <a class="link" href="../ref-manual/var-SSTATE_MIRRORS.html" target="_self"><code class="filename">SSTATE_MIRRORS</code></a> | ||
| 215 | for shared state files. | ||
| 216 | Here is an example: | ||
| 217 | </p> | ||
| 218 | <pre class="literallayout"> | ||
| 219 | SSTATE_MIRRORS ?= "\ | ||
| 220 | file://.* http://someserver.tld/share/sstate/PATH;downloadfilename=PATH \n \ | ||
| 221 | file://.* file:///some/local/dir/sstate/PATH" | ||
| 222 | </pre> | ||
| 223 | <p> | ||
| 224 | </p> | ||
| 225 | <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"> | ||
| 226 | <h3 class="title">Note</h3> | ||
| 227 | The shared state directory | ||
| 228 | (<code class="filename">SSTATE_DIR</code>) is organized into | ||
| 229 | two-character subdirectories, where the subdirectory | ||
| 230 | names are based on the first two characters of the hash. | ||
| 231 | If the shared state directory structure for a mirror has the | ||
| 232 | same structure as <code class="filename">SSTATE_DIR</code>, you must | ||
| 233 | specify "PATH" as part of the URI to enable the build system | ||
| 234 | to map to the appropriate subdirectory. | ||
| 235 | </div> | ||
| 236 | <p> | ||
| 237 | </p> | ||
| 238 | <p> | ||
| 239 | The shared state package validity can be detected just by | ||
| 240 | looking at the filename since the filename contains the task | ||
| 241 | checksum (or signature) as described earlier in this section. | ||
| 242 | If a valid shared state package is found, the build process | ||
| 243 | downloads it and uses it to accelerate the task. | ||
| 244 | </p> | ||
| 245 | <p> | ||
| 246 | The build processes use the <code class="filename">*_setscene</code> | ||
| 247 | tasks for the task acceleration phase. | ||
| 248 | BitBake goes through this phase before the main execution | ||
| 249 | code and tries to accelerate any tasks for which it can find | ||
| 250 | shared state packages. | ||
| 251 | If a shared state package for a task is available, the | ||
| 252 | shared state package is used. | ||
| 253 | This means the task and any tasks on which it is dependent | ||
| 254 | are not executed. | ||
| 255 | </p> | ||
| 256 | <p> | ||
| 257 | As a real world example, the aim is when building an IPK-based | ||
| 258 | image, only the | ||
| 259 | <a class="link" href="../ref-manual/ref-tasks-package_write_ipk.html" target="_self"><code class="filename">do_package_write_ipk</code></a> | ||
| 260 | tasks would have their shared state packages fetched and | ||
| 261 | extracted. | ||
| 262 | Since the sysroot is not used, it would never get extracted. | ||
| 263 | This is another reason why a task-based approach is preferred | ||
| 264 | over a recipe-based approach, which would have to install the | ||
| 265 | output from every task. | ||
| 266 | </p> | ||
| 267 | </div></body> | ||
| 268 | </html> | ||
diff --git a/documentation/getting-started/eclipse/html/getting-started/software-layer.html b/documentation/getting-started/eclipse/html/getting-started/software-layer.html new file mode 100644 index 0000000000..26e169a281 --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/software-layer.html | |||
| @@ -0,0 +1,27 @@ | |||
| 1 | <html> | ||
| 2 | <head> | ||
| 3 | <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> | ||
| 4 | <title>2.8.2.3.Software Layer</title> | ||
| 5 | <link rel="stylesheet" type="text/css" href="../book.css"> | ||
| 6 | <meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> | ||
| 7 | <link rel="home" href="index.html" title="Getting Started With Yocto Project"> | ||
| 8 | <link rel="up" href="metadata-machine-configuration-and-policy-configuration.html" title="2.8.2.Metadata, Machine Configuration, and Policy Configuration"> | ||
| 9 | <link rel="prev" href="bsp-layer.html" title="2.8.2.2.BSP Layer"> | ||
| 10 | <link rel="next" href="sources-dev-environment.html" title="2.8.3.Sources"> | ||
| 11 | </head> | ||
| 12 | <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="2.8.2.3.Software Layer"> | ||
| 13 | <div class="titlepage"><div><div><h4 class="title"> | ||
| 14 | <a name="software-layer"></a>2.8.2.3.Software Layer</h4></div></div></div> | ||
| 15 | <p> | ||
| 16 | The software layer provides the Metadata for additional | ||
| 17 | software packages used during the build. | ||
| 18 | This layer does not include Metadata that is specific to the | ||
| 19 | distribution or the machine, which are found in their | ||
| 20 | respective layers. | ||
| 21 | </p> | ||
| 22 | <p> | ||
| 23 | This layer contains any new recipes that your project needs | ||
| 24 | in the form of recipe files. | ||
| 25 | </p> | ||
| 26 | </div></body> | ||
| 27 | </html> | ||
diff --git a/documentation/getting-started/eclipse/html/getting-started/source-fetching-dev-environment.html b/documentation/getting-started/eclipse/html/getting-started/source-fetching-dev-environment.html new file mode 100644 index 0000000000..afcdafdc76 --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/source-fetching-dev-environment.html | |||
| @@ -0,0 +1,93 @@ | |||
| 1 | <html> | ||
| 2 | <head> | ||
| 3 | <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> | ||
| 4 | <title>2.8.5.1.Source Fetching</title> | ||
| 5 | <link rel="stylesheet" type="text/css" href="../book.css"> | ||
| 6 | <meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> | ||
| 7 | <link rel="home" href="index.html" title="Getting Started With Yocto Project"> | ||
| 8 | <link rel="up" href="bitbake-dev-environment.html" title="2.8.5.BitBake"> | ||
| 9 | <link rel="prev" href="bitbake-dev-environment.html" title="2.8.5.BitBake"> | ||
| 10 | <link rel="next" href="patching-dev-environment.html" title="2.8.5.2.Patching"> | ||
| 11 | </head> | ||
| 12 | <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="2.8.5.1.Source Fetching"> | ||
| 13 | <div class="titlepage"><div><div><h4 class="title"> | ||
| 14 | <a name="source-fetching-dev-environment"></a>2.8.5.1.Source Fetching</h4></div></div></div> | ||
| 15 | <p> | ||
| 16 | The first stages of building a recipe are to fetch and unpack | ||
| 17 | the source code: | ||
| 18 | </p> | ||
| 19 | <table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="585"><tr style="height: 450px"><td align="center"><img src="figures/source-fetching.png" align="middle" width="585"></td></tr></table> | ||
| 20 | <p> | ||
| 21 | </p> | ||
| 22 | <p> | ||
| 23 | The | ||
| 24 | <a class="link" href="../ref-manual/ref-tasks-fetch.html" target="_self"><code class="filename">do_fetch</code></a> | ||
| 25 | and | ||
| 26 | <a class="link" href="../ref-manual/ref-tasks-unpack.html" target="_self"><code class="filename">do_unpack</code></a> | ||
| 27 | tasks fetch the source files and unpack them into the work | ||
| 28 | directory. | ||
| 29 | </p> | ||
| 30 | <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"> | ||
| 31 | <h3 class="title">Note</h3> | ||
| 32 | For every local file (e.g. <code class="filename">file://</code>) | ||
| 33 | that is part of a recipe's | ||
| 34 | <a class="link" href="../ref-manual/var-SRC_URI.html" target="_self"><code class="filename">SRC_URI</code></a> | ||
| 35 | statement, the OpenEmbedded build system takes a checksum | ||
| 36 | of the file for the recipe and inserts the checksum into | ||
| 37 | the signature for the <code class="filename">do_fetch</code>. | ||
| 38 | If any local file has been modified, the | ||
| 39 | <code class="filename">do_fetch</code> task and all tasks that | ||
| 40 | depend on it are re-executed. | ||
| 41 | </div> | ||
| 42 | <p> | ||
| 43 | By default, everything is accomplished in the | ||
| 44 | <a class="link" href="../ref-manual/build-directory.html" target="_self">Build Directory</a>, | ||
| 45 | which has a defined structure. | ||
| 46 | For additional general information on the Build Directory, | ||
| 47 | see the | ||
| 48 | "<a class="link" href="../ref-manual/structure-core-build.html" target="_self"><code class="filename">build/</code></a>" | ||
| 49 | section in the Yocto Project Reference Manual. | ||
| 50 | </p> | ||
| 51 | <p> | ||
| 52 | Unpacked source files are pointed to by the | ||
| 53 | <a class="link" href="../ref-manual/var-S.html" target="_self"><code class="filename">S</code></a> | ||
| 54 | variable. | ||
| 55 | Each recipe has an area in the Build Directory where the | ||
| 56 | unpacked source code resides. | ||
| 57 | The name of that directory for any given recipe is defined from | ||
| 58 | several different variables. | ||
| 59 | You can see the variables that define these directories | ||
| 60 | by looking at the figure: | ||
| 61 | </p> | ||
| 62 | <div class="itemizedlist"><ul class="itemizedlist" type="disc"> | ||
| 63 | <li class="listitem"><p><a class="link" href="../ref-manual/var-TMPDIR.html" target="_self"><code class="filename">TMPDIR</code></a> - | ||
| 64 | The base directory where the OpenEmbedded build system | ||
| 65 | performs all its work during the build. | ||
| 66 | </p></li> | ||
| 67 | <li class="listitem"><p><a class="link" href="../ref-manual/var-PACKAGE_ARCH.html" target="_self"><code class="filename">PACKAGE_ARCH</code></a> - | ||
| 68 | The architecture of the built package or packages. | ||
| 69 | </p></li> | ||
| 70 | <li class="listitem"><p><a class="link" href="../ref-manual/var-TARGET_OS.html" target="_self"><code class="filename">TARGET_OS</code></a> - | ||
| 71 | The operating system of the target device. | ||
| 72 | </p></li> | ||
| 73 | <li class="listitem"><p><a class="link" href="../ref-manual/var-PN.html" target="_self"><code class="filename">PN</code></a> - | ||
| 74 | The name of the built package. | ||
| 75 | </p></li> | ||
| 76 | <li class="listitem"><p><a class="link" href="../ref-manual/var-PV.html" target="_self"><code class="filename">PV</code></a> - | ||
| 77 | The version of the recipe used to build the package. | ||
| 78 | </p></li> | ||
| 79 | <li class="listitem"><p><a class="link" href="../ref-manual/var-PR.html" target="_self"><code class="filename">PR</code></a> - | ||
| 80 | The revision of the recipe used to build the package. | ||
| 81 | </p></li> | ||
| 82 | <li class="listitem"><p><a class="link" href="../ref-manual/var-WORKDIR.html" target="_self"><code class="filename">WORKDIR</code></a> - | ||
| 83 | The location within <code class="filename">TMPDIR</code> where | ||
| 84 | a specific package is built. | ||
| 85 | </p></li> | ||
| 86 | <li class="listitem"><p><a class="link" href="../ref-manual/var-S.html" target="_self"><code class="filename">S</code></a> - | ||
| 87 | Contains the unpacked source files for a given recipe. | ||
| 88 | </p></li> | ||
| 89 | </ul></div> | ||
| 90 | <p> | ||
| 91 | </p> | ||
| 92 | </div></body> | ||
| 93 | </html> | ||
diff --git a/documentation/getting-started/eclipse/html/getting-started/source-mirrors.html b/documentation/getting-started/eclipse/html/getting-started/source-mirrors.html new file mode 100644 index 0000000000..178903c96e --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/source-mirrors.html | |||
| @@ -0,0 +1,37 @@ | |||
| 1 | <html> | ||
| 2 | <head> | ||
| 3 | <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> | ||
| 4 | <title>2.8.3.4.Source Mirror(s)</title> | ||
| 5 | <link rel="stylesheet" type="text/css" href="../book.css"> | ||
| 6 | <meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> | ||
| 7 | <link rel="home" href="index.html" title="Getting Started With Yocto Project"> | ||
| 8 | <link rel="up" href="sources-dev-environment.html" title="2.8.3.Sources"> | ||
| 9 | <link rel="prev" href="scms.html" title="2.8.3.3.Source Control Managers (Optional)"> | ||
| 10 | <link rel="next" href="package-feeds-dev-environment.html" title="2.8.4.Package Feeds"> | ||
| 11 | </head> | ||
| 12 | <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="2.8.3.4.Source Mirror(s)"> | ||
| 13 | <div class="titlepage"><div><div><h4 class="title"> | ||
| 14 | <a name="source-mirrors"></a>2.8.3.4.Source Mirror(s)</h4></div></div></div> | ||
| 15 | <p> | ||
| 16 | Two kinds of mirrors exist: pre-mirrors and regular mirrors. | ||
| 17 | The | ||
| 18 | <a class="link" href="../ref-manual/var-PREMIRRORS.html" target="_self"><code class="filename">PREMIRRORS</code></a> | ||
| 19 | and | ||
| 20 | <a class="link" href="../ref-manual/var-MIRRORS.html" target="_self"><code class="filename">MIRRORS</code></a> | ||
| 21 | variables point to these, respectively. | ||
| 22 | BitBake checks pre-mirrors before looking upstream for any | ||
| 23 | source files. | ||
| 24 | Pre-mirrors are appropriate when you have a shared directory | ||
| 25 | that is not a directory defined by the | ||
| 26 | <a class="link" href="../ref-manual/var-DL_DIR.html" target="_self"><code class="filename">DL_DIR</code></a> | ||
| 27 | variable. | ||
| 28 | A Pre-mirror typically points to a shared directory that is | ||
| 29 | local to your organization. | ||
| 30 | </p> | ||
| 31 | <p> | ||
| 32 | Regular mirrors can be any site across the Internet that is | ||
| 33 | used as an alternative location for source code should the | ||
| 34 | primary site not be functioning for some reason or another. | ||
| 35 | </p> | ||
| 36 | </div></body> | ||
| 37 | </html> | ||
diff --git a/documentation/getting-started/eclipse/html/getting-started/sources-dev-environment.html b/documentation/getting-started/eclipse/html/getting-started/sources-dev-environment.html new file mode 100644 index 0000000000..ab7718074f --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/sources-dev-environment.html | |||
| @@ -0,0 +1,80 @@ | |||
| 1 | <html> | ||
| 2 | <head> | ||
| 3 | <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> | ||
| 4 | <title>2.8.3.Sources</title> | ||
| 5 | <link rel="stylesheet" type="text/css" href="../book.css"> | ||
| 6 | <meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> | ||
| 7 | <link rel="home" href="index.html" title="Getting Started With Yocto Project"> | ||
| 8 | <link rel="up" href="development-concepts.html" title="2.8.Development Concepts"> | ||
| 9 | <link rel="prev" href="software-layer.html" title="2.8.2.3.Software Layer"> | ||
| 10 | <link rel="next" href="upstream-project-releases.html" title="2.8.3.1.Upstream Project Releases"> | ||
| 11 | </head> | ||
| 12 | <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="2.8.3.Sources"> | ||
| 13 | <div class="titlepage"><div><div><h3 class="title"> | ||
| 14 | <a name="sources-dev-environment"></a>2.8.3.Sources</h3></div></div></div> | ||
| 15 | <p> | ||
| 16 | In order for the OpenEmbedded build system to create an image or | ||
| 17 | any target, it must be able to access source files. | ||
| 18 | The | ||
| 19 | <a class="link" href="development-concepts.html#general-yocto-environment-figure">general Yocto Project Development Environment figure</a> | ||
| 20 | represents source files using the "Upstream Project Releases", | ||
| 21 | "Local Projects", and "SCMs (optional)" boxes. | ||
| 22 | The figure represents mirrors, which also play a role in locating | ||
| 23 | source files, with the "Source Mirror(s)" box. | ||
| 24 | </p> | ||
| 25 | <p> | ||
| 26 | The method by which source files are ultimately organized is | ||
| 27 | a function of the project. | ||
| 28 | For example, for released software, projects tend to use tarballs | ||
| 29 | or other archived files that can capture the state of a release | ||
| 30 | guaranteeing that it is statically represented. | ||
| 31 | On the other hand, for a project that is more dynamic or | ||
| 32 | experimental in nature, a project might keep source files in a | ||
| 33 | repository controlled by a Source Control Manager (SCM) such as | ||
| 34 | Git. | ||
| 35 | Pulling source from a repository allows you to control | ||
| 36 | the point in the repository (the revision) from which you want to | ||
| 37 | build software. | ||
| 38 | Finally, a combination of the two might exist, which would give the | ||
| 39 | consumer a choice when deciding where to get source files. | ||
| 40 | </p> | ||
| 41 | <p> | ||
| 42 | BitBake uses the | ||
| 43 | <a class="link" href="../ref-manual/var-SRC_URI.html" target="_self"><code class="filename">SRC_URI</code></a> | ||
| 44 | variable to point to source files regardless of their location. | ||
| 45 | Each recipe must have a <code class="filename">SRC_URI</code> variable | ||
| 46 | that points to the source. | ||
| 47 | </p> | ||
| 48 | <p> | ||
| 49 | Another area that plays a significant role in where source files | ||
| 50 | come from is pointed to by the | ||
| 51 | <a class="link" href="../ref-manual/var-DL_DIR.html" target="_self"><code class="filename">DL_DIR</code></a> | ||
| 52 | variable. | ||
| 53 | This area is a cache that can hold previously downloaded source. | ||
| 54 | You can also instruct the OpenEmbedded build system to create | ||
| 55 | tarballs from Git repositories, which is not the default behavior, | ||
| 56 | and store them in the <code class="filename">DL_DIR</code> by using the | ||
| 57 | <a class="link" href="../ref-manual/var-BB_GENERATE_MIRROR_TARBALLS.html" target="_self"><code class="filename">BB_GENERATE_MIRROR_TARBALLS</code></a> | ||
| 58 | variable. | ||
| 59 | </p> | ||
| 60 | <p> | ||
| 61 | Judicious use of a <code class="filename">DL_DIR</code> directory can | ||
| 62 | save the build system a trip across the Internet when looking | ||
| 63 | for files. | ||
| 64 | A good method for using a download directory is to have | ||
| 65 | <code class="filename">DL_DIR</code> point to an area outside of your | ||
| 66 | Build Directory. | ||
| 67 | Doing so allows you to safely delete the Build Directory | ||
| 68 | if needed without fear of removing any downloaded source file. | ||
| 69 | </p> | ||
| 70 | <p> | ||
| 71 | The remainder of this section provides a deeper look into the | ||
| 72 | source files and the mirrors. | ||
| 73 | Here is a more detailed look at the source file area of the | ||
| 74 | base figure: | ||
| 75 | </p> | ||
| 76 | <table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="630"><tr style="height: 675px"><td align="center"><img src="figures/source-input.png" align="middle" width="630"></td></tr></table> | ||
| 77 | <p> | ||
| 78 | </p> | ||
| 79 | </div></body> | ||
| 80 | </html> | ||
diff --git a/documentation/getting-started/eclipse/html/getting-started/stamp-files-and-the-rerunning-of-tasks.html b/documentation/getting-started/eclipse/html/getting-started/stamp-files-and-the-rerunning-of-tasks.html new file mode 100644 index 0000000000..b649c69b2b --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/stamp-files-and-the-rerunning-of-tasks.html | |||
| @@ -0,0 +1,83 @@ | |||
| 1 | <html> | ||
| 2 | <head> | ||
| 3 | <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> | ||
| 4 | <title>2.8.5.7.Stamp Files and the Rerunning of Tasks</title> | ||
| 5 | <link rel="stylesheet" type="text/css" href="../book.css"> | ||
| 6 | <meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> | ||
| 7 | <link rel="home" href="index.html" title="Getting Started With Yocto Project"> | ||
| 8 | <link rel="up" href="bitbake-dev-environment.html" title="2.8.5.BitBake"> | ||
| 9 | <link rel="prev" href="sdk-generation-dev-environment.html" title="2.8.5.6.SDK Generation"> | ||
| 10 | <link rel="next" href="setscene-tasks-and-shared-state.html" title="2.8.5.8.Setscene Tasks and Shared State"> | ||
| 11 | </head> | ||
| 12 | <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="2.8.5.7.Stamp Files and the Rerunning of Tasks"> | ||
| 13 | <div class="titlepage"><div><div><h4 class="title"> | ||
| 14 | <a name="stamp-files-and-the-rerunning-of-tasks"></a>2.8.5.7.Stamp Files and the Rerunning of Tasks</h4></div></div></div> | ||
| 15 | <p> | ||
| 16 | For each task that completes successfully, BitBake writes a | ||
| 17 | stamp file into the | ||
| 18 | <a class="link" href="../ref-manual/var-STAMPS_DIR.html" target="_self"><code class="filename">STAMPS_DIR</code></a> | ||
| 19 | directory. | ||
| 20 | The beginning of the stamp file's filename is determined by the | ||
| 21 | <a class="link" href="../ref-manual/var-STAMP.html" target="_self"><code class="filename">STAMP</code></a> | ||
| 22 | variable, and the end of the name consists of the task's name | ||
| 23 | and current | ||
| 24 | <a class="link" href="overview-checksums.html" title="3.3.2.Checksums (Signatures)">input checksum</a>. | ||
| 25 | </p> | ||
| 26 | <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"> | ||
| 27 | <h3 class="title">Note</h3> | ||
| 28 | This naming scheme assumes that | ||
| 29 | <a class="link" href="../bitbake-user-manual/var-BB_SIGNATURE_HANDLER.html" target="_self"><code class="filename">BB_SIGNATURE_HANDLER</code></a> | ||
| 30 | is "OEBasicHash", which is almost always the case in | ||
| 31 | current OpenEmbedded. | ||
| 32 | </div> | ||
| 33 | <p> | ||
| 34 | To determine if a task needs to be rerun, BitBake checks if a | ||
| 35 | stamp file with a matching input checksum exists for the task. | ||
| 36 | If such a stamp file exists, the task's output is assumed to | ||
| 37 | exist and still be valid. | ||
| 38 | If the file does not exist, the task is rerun. | ||
| 39 | </p> | ||
| 40 | <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"> | ||
| 41 | <h3 class="title">Note</h3> | ||
| 42 | <p>The stamp mechanism is more general than the shared | ||
| 43 | state (sstate) cache mechanism described in the | ||
| 44 | "<a class="link" href="setscene-tasks-and-shared-state.html" title="2.8.5.8.Setscene Tasks and Shared State">Setscene Tasks and Shared State</a>" | ||
| 45 | section. | ||
| 46 | BitBake avoids rerunning any task that has a valid | ||
| 47 | stamp file, not just tasks that can be accelerated through | ||
| 48 | the sstate cache.</p> | ||
| 49 | <p>However, you should realize that stamp files only | ||
| 50 | serve as a marker that some work has been done and that | ||
| 51 | these files do not record task output. | ||
| 52 | The actual task output would usually be somewhere in | ||
| 53 | <a class="link" href="../ref-manual/var-TMPDIR.html" target="_self"><code class="filename">TMPDIR</code></a> | ||
| 54 | (e.g. in some recipe's | ||
| 55 | <a class="link" href="../ref-manual/var-WORKDIR.html" target="_self"><code class="filename">WORKDIR</code></a>.) | ||
| 56 | What the sstate cache mechanism adds is a way to cache task | ||
| 57 | output that can then be shared between build machines. | ||
| 58 | </p> | ||
| 59 | </div> | ||
| 60 | <p> | ||
| 61 | Since <code class="filename">STAMPS_DIR</code> is usually a subdirectory | ||
| 62 | of <code class="filename">TMPDIR</code>, removing | ||
| 63 | <code class="filename">TMPDIR</code> will also remove | ||
| 64 | <code class="filename">STAMPS_DIR</code>, which means tasks will | ||
| 65 | properly be rerun to repopulate <code class="filename">TMPDIR</code>. | ||
| 66 | </p> | ||
| 67 | <p> | ||
| 68 | If you want some task to always be considered "out of date", | ||
| 69 | you can mark it with the | ||
| 70 | <a class="link" href="../bitbake-user-manual/variable-flags.html" target="_self"><code class="filename">nostamp</code></a> | ||
| 71 | varflag. | ||
| 72 | If some other task depends on such a task, then that task will | ||
| 73 | also always be considered out of date, which might not be what | ||
| 74 | you want. | ||
| 75 | </p> | ||
| 76 | <p> | ||
| 77 | For details on how to view information about a task's | ||
| 78 | signature, see the | ||
| 79 | "<a class="link" href="../dev-manual/dev-viewing-task-variable-dependencies.html" target="_self">Viewing Task Variable Dependencies</a>" | ||
| 80 | section in the Yocto Project Development Tasks Manual. | ||
| 81 | </p> | ||
| 82 | </div></body> | ||
| 83 | </html> | ||
diff --git a/documentation/getting-started/eclipse/html/getting-started/tips-and-tricks.html b/documentation/getting-started/eclipse/html/getting-started/tips-and-tricks.html new file mode 100644 index 0000000000..d0c8522d95 --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/tips-and-tricks.html | |||
| @@ -0,0 +1,22 @@ | |||
| 1 | <html> | ||
| 2 | <head> | ||
| 3 | <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> | ||
| 4 | <title>3.3.4.Tips and Tricks</title> | ||
| 5 | <link rel="stylesheet" type="text/css" href="../book.css"> | ||
| 6 | <meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> | ||
| 7 | <link rel="home" href="index.html" title="Getting Started With Yocto Project"> | ||
| 8 | <link rel="up" href="shared-state-cache.html" title="3.3.Shared State Cache"> | ||
| 9 | <link rel="prev" href="shared-state.html" title="3.3.3.Shared State"> | ||
| 10 | <link rel="next" href="overview-debugging.html" title="3.3.4.1.Debugging"> | ||
| 11 | </head> | ||
| 12 | <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="3.3.4.Tips and Tricks"> | ||
| 13 | <div class="titlepage"><div><div><h3 class="title"> | ||
| 14 | <a name="tips-and-tricks"></a>3.3.4.Tips and Tricks</h3></div></div></div> | ||
| 15 | <p> | ||
| 16 | The code in the build system that supports incremental builds | ||
| 17 | is not simple code. | ||
| 18 | This section presents some tips and tricks that help you work | ||
| 19 | around issues related to shared state code. | ||
| 20 | </p> | ||
| 21 | </div></body> | ||
| 22 | </html> | ||
diff --git a/documentation/getting-started/eclipse/html/getting-started/upstream-project-releases.html b/documentation/getting-started/eclipse/html/getting-started/upstream-project-releases.html new file mode 100644 index 0000000000..ef9bc18dde --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/upstream-project-releases.html | |||
| @@ -0,0 +1,25 @@ | |||
| 1 | <html> | ||
| 2 | <head> | ||
| 3 | <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> | ||
| 4 | <title>2.8.3.1.Upstream Project Releases</title> | ||
| 5 | <link rel="stylesheet" type="text/css" href="../book.css"> | ||
| 6 | <meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> | ||
| 7 | <link rel="home" href="index.html" title="Getting Started With Yocto Project"> | ||
| 8 | <link rel="up" href="sources-dev-environment.html" title="2.8.3.Sources"> | ||
| 9 | <link rel="prev" href="sources-dev-environment.html" title="2.8.3.Sources"> | ||
| 10 | <link rel="next" href="local-projects.html" title="2.8.3.2.Local Projects"> | ||
| 11 | </head> | ||
| 12 | <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="2.8.3.1.Upstream Project Releases"> | ||
| 13 | <div class="titlepage"><div><div><h4 class="title"> | ||
| 14 | <a name="upstream-project-releases"></a>2.8.3.1.Upstream Project Releases</h4></div></div></div> | ||
| 15 | <p> | ||
| 16 | Upstream project releases exist anywhere in the form of an | ||
| 17 | archived file (e.g. tarball or zip file). | ||
| 18 | These files correspond to individual recipes. | ||
| 19 | For example, the figure uses specific releases each for | ||
| 20 | BusyBox, Qt, and Dbus. | ||
| 21 | An archive file can be for any released product that can be | ||
| 22 | built using a recipe. | ||
| 23 | </p> | ||
| 24 | </div></body> | ||
| 25 | </html> | ||
diff --git a/documentation/getting-started/eclipse/html/getting-started/user-configuration.html b/documentation/getting-started/eclipse/html/getting-started/user-configuration.html new file mode 100644 index 0000000000..6f10791e7a --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/user-configuration.html | |||
| @@ -0,0 +1,232 @@ | |||
| 1 | <html> | ||
| 2 | <head> | ||
| 3 | <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> | ||
| 4 | <title>2.8.1.User Configuration</title> | ||
| 5 | <link rel="stylesheet" type="text/css" href="../book.css"> | ||
| 6 | <meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> | ||
| 7 | <link rel="home" href="index.html" title="Getting Started With Yocto Project"> | ||
| 8 | <link rel="up" href="development-concepts.html" title="2.8.Development Concepts"> | ||
| 9 | <link rel="prev" href="development-concepts.html" title="2.8.Development Concepts"> | ||
| 10 | <link rel="next" href="metadata-machine-configuration-and-policy-configuration.html" title="2.8.2.Metadata, Machine Configuration, and Policy Configuration"> | ||
| 11 | </head> | ||
| 12 | <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="2.8.1.User Configuration"> | ||
| 13 | <div class="titlepage"><div><div><h3 class="title"> | ||
| 14 | <a name="user-configuration"></a>2.8.1.User Configuration</h3></div></div></div> | ||
| 15 | <p> | ||
| 16 | User configuration helps define the build. | ||
| 17 | Through user configuration, you can tell BitBake the | ||
| 18 | target architecture for which you are building the image, | ||
| 19 | where to store downloaded source, and other build properties. | ||
| 20 | </p> | ||
| 21 | <p> | ||
| 22 | The following figure shows an expanded representation of the | ||
| 23 | "User Configuration" box of the | ||
| 24 | <a class="link" href="development-concepts.html#general-yocto-environment-figure">general Yocto Project Development Environment figure</a>: | ||
| 25 | </p> | ||
| 26 | <p> | ||
| 27 | </p> | ||
| 28 | <table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="720"><tr style="height: 405px"><td align="center"><img src="figures/user-configuration.png" align="middle" height="405"></td></tr></table> | ||
| 29 | <p> | ||
| 30 | </p> | ||
| 31 | <p> | ||
| 32 | BitBake needs some basic configuration files in order to complete | ||
| 33 | a build. | ||
| 34 | These files are <code class="filename">*.conf</code> files. | ||
| 35 | The minimally necessary ones reside as example files in the | ||
| 36 | <a class="link" href="../ref-manual/source-directory.html" target="_self">Source Directory</a>. | ||
| 37 | For simplicity, this section refers to the Source Directory as | ||
| 38 | the "Poky Directory." | ||
| 39 | </p> | ||
| 40 | <p> | ||
| 41 | When you clone the <code class="filename">poky</code> Git repository or you | ||
| 42 | download and unpack a Yocto Project release, you can set up the | ||
| 43 | Source Directory to be named anything you want. | ||
| 44 | For this discussion, the cloned repository uses the default | ||
| 45 | name <code class="filename">poky</code>. | ||
| 46 | </p> | ||
| 47 | <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"> | ||
| 48 | <h3 class="title">Note</h3> | ||
| 49 | The Poky repository is primarily an aggregation of existing | ||
| 50 | repositories. | ||
| 51 | It is not a canonical upstream source. | ||
| 52 | </div> | ||
| 53 | <p> | ||
| 54 | </p> | ||
| 55 | <p> | ||
| 56 | The <code class="filename">meta-poky</code> layer inside Poky contains | ||
| 57 | a <code class="filename">conf</code> directory that has example | ||
| 58 | configuration files. | ||
| 59 | These example files are used as a basis for creating actual | ||
| 60 | configuration files when you source the build environment | ||
| 61 | script | ||
| 62 | (i.e. | ||
| 63 | <a class="link" href="../ref-manual/structure-core-script.html" target="_self"><code class="filename">oe-init-build-env</code></a>). | ||
| 64 | </p> | ||
| 65 | <p> | ||
| 66 | Sourcing the build environment script creates a | ||
| 67 | <a class="link" href="../ref-manual/build-directory.html" target="_self">Build Directory</a> | ||
| 68 | if one does not already exist. | ||
| 69 | BitBake uses the Build Directory for all its work during builds. | ||
| 70 | The Build Directory has a <code class="filename">conf</code> directory that | ||
| 71 | contains default versions of your <code class="filename">local.conf</code> | ||
| 72 | and <code class="filename">bblayers.conf</code> configuration files. | ||
| 73 | These default configuration files are created only if versions | ||
| 74 | do not already exist in the Build Directory at the time you | ||
| 75 | source the build environment setup script. | ||
| 76 | </p> | ||
| 77 | <p> | ||
| 78 | Because the Poky repository is fundamentally an aggregation of | ||
| 79 | existing repositories, some users might be familiar with running | ||
| 80 | the <code class="filename">oe-init-build-env</code> script in the context | ||
| 81 | of separate OpenEmbedded-Core and BitBake repositories rather than a | ||
| 82 | single Poky repository. | ||
| 83 | This discussion assumes the script is executed from within a cloned | ||
| 84 | or unpacked version of Poky. | ||
| 85 | </p> | ||
| 86 | <p> | ||
| 87 | Depending on where the script is sourced, different sub-scripts | ||
| 88 | are called to set up the Build Directory (Yocto or OpenEmbedded). | ||
| 89 | Specifically, the script | ||
| 90 | <code class="filename">scripts/oe-setup-builddir</code> inside the | ||
| 91 | poky directory sets up the Build Directory and seeds the directory | ||
| 92 | (if necessary) with configuration files appropriate for the | ||
| 93 | Yocto Project development environment. | ||
| 94 | </p> | ||
| 95 | <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"> | ||
| 96 | <h3 class="title">Note</h3> | ||
| 97 | The <code class="filename">scripts/oe-setup-builddir</code> script | ||
| 98 | uses the <code class="filename">$TEMPLATECONF</code> variable to | ||
| 99 | determine which sample configuration files to locate. | ||
| 100 | </div> | ||
| 101 | <p> | ||
| 102 | </p> | ||
| 103 | <p> | ||
| 104 | The <code class="filename">local.conf</code> file provides many | ||
| 105 | basic variables that define a build environment. | ||
| 106 | Here is a list of a few. | ||
| 107 | To see the default configurations in a <code class="filename">local.conf</code> | ||
| 108 | file created by the build environment script, see the | ||
| 109 | <code class="filename">local.conf.sample</code> in the | ||
| 110 | <code class="filename">meta-poky</code> layer: | ||
| 111 | </p> | ||
| 112 | <div class="itemizedlist"><ul class="itemizedlist" type="disc"> | ||
| 113 | <li class="listitem"><p><span class="emphasis"><em>Parallelism Options:</em></span> | ||
| 114 | Controlled by the | ||
| 115 | <a class="link" href="../ref-manual/var-BB_NUMBER_THREADS.html" target="_self"><code class="filename">BB_NUMBER_THREADS</code></a>, | ||
| 116 | <a class="link" href="../ref-manual/var-PARALLEL_MAKE.html" target="_self"><code class="filename">PARALLEL_MAKE</code></a>, | ||
| 117 | and | ||
| 118 | <a class="link" href="../bitbake-user-manual/var-BB_NUMBER_PARSE_THREADS.html" target="_self"><code class="filename">BB_NUMBER_PARSE_THREADS</code></a> | ||
| 119 | variables.</p></li> | ||
| 120 | <li class="listitem"><p><span class="emphasis"><em>Target Machine Selection:</em></span> | ||
| 121 | Controlled by the | ||
| 122 | <a class="link" href="../ref-manual/var-MACHINE.html" target="_self"><code class="filename">MACHINE</code></a> | ||
| 123 | variable.</p></li> | ||
| 124 | <li class="listitem"><p><span class="emphasis"><em>Download Directory:</em></span> | ||
| 125 | Controlled by the | ||
| 126 | <a class="link" href="../ref-manual/var-DL_DIR.html" target="_self"><code class="filename">DL_DIR</code></a> | ||
| 127 | variable.</p></li> | ||
| 128 | <li class="listitem"><p><span class="emphasis"><em>Shared State Directory:</em></span> | ||
| 129 | Controlled by the | ||
| 130 | <a class="link" href="../ref-manual/var-SSTATE_DIR.html" target="_self"><code class="filename">SSTATE_DIR</code></a> | ||
| 131 | variable.</p></li> | ||
| 132 | <li class="listitem"><p><span class="emphasis"><em>Build Output:</em></span> | ||
| 133 | Controlled by the | ||
| 134 | <a class="link" href="../ref-manual/var-TMPDIR.html" target="_self"><code class="filename">TMPDIR</code></a> | ||
| 135 | variable.</p></li> | ||
| 136 | </ul></div> | ||
| 137 | <p> | ||
| 138 | </p> | ||
| 139 | <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"> | ||
| 140 | <h3 class="title">Note</h3> | ||
| 141 | Configurations set in the <code class="filename">conf/local.conf</code> | ||
| 142 | file can also be set in the | ||
| 143 | <code class="filename">conf/site.conf</code> and | ||
| 144 | <code class="filename">conf/auto.conf</code> configuration files. | ||
| 145 | </div> | ||
| 146 | <p> | ||
| 147 | </p> | ||
| 148 | <p> | ||
| 149 | The <code class="filename">bblayers.conf</code> file tells BitBake what | ||
| 150 | layers you want considered during the build. | ||
| 151 | By default, the layers listed in this file include layers | ||
| 152 | minimally needed by the build system. | ||
| 153 | However, you must manually add any custom layers you have created. | ||
| 154 | You can find more information on working with the | ||
| 155 | <code class="filename">bblayers.conf</code> file in the | ||
| 156 | "<a class="link" href="../dev-manual/enabling-your-layer.html" target="_self">Enabling Your Layer</a>" | ||
| 157 | section in the Yocto Project Development Tasks Manual. | ||
| 158 | </p> | ||
| 159 | <p> | ||
| 160 | The files <code class="filename">site.conf</code> and | ||
| 161 | <code class="filename">auto.conf</code> are not created by the environment | ||
| 162 | initialization script. | ||
| 163 | If you want the <code class="filename">site.conf</code> file, you need to | ||
| 164 | create that yourself. | ||
| 165 | The <code class="filename">auto.conf</code> file is typically created by | ||
| 166 | an autobuilder: | ||
| 167 | </p> | ||
| 168 | <div class="itemizedlist"><ul class="itemizedlist" type="disc"> | ||
| 169 | <li class="listitem"> | ||
| 170 | <p><span class="emphasis"><em><code class="filename">site.conf</code>:</em></span> | ||
| 171 | You can use the <code class="filename">conf/site.conf</code> | ||
| 172 | configuration file to configure multiple build directories. | ||
| 173 | For example, suppose you had several build environments and | ||
| 174 | they shared some common features. | ||
| 175 | You can set these default build properties here. | ||
| 176 | A good example is perhaps the packaging format to use | ||
| 177 | through the | ||
| 178 | <a class="link" href="../ref-manual/var-PACKAGE_CLASSES.html" target="_self"><code class="filename">PACKAGE_CLASSES</code></a> | ||
| 179 | variable.</p> | ||
| 180 | <p>One useful scenario for using the | ||
| 181 | <code class="filename">conf/site.conf</code> file is to extend your | ||
| 182 | <a class="link" href="../ref-manual/var-BBPATH.html" target="_self"><code class="filename">BBPATH</code></a> | ||
| 183 | variable to include the path to a | ||
| 184 | <code class="filename">conf/site.conf</code>. | ||
| 185 | Then, when BitBake looks for Metadata using | ||
| 186 | <code class="filename">BBPATH</code>, it finds the | ||
| 187 | <code class="filename">conf/site.conf</code> file and applies your | ||
| 188 | common configurations found in the file. | ||
| 189 | To override configurations in a particular build directory, | ||
| 190 | alter the similar configurations within that build | ||
| 191 | directory's <code class="filename">conf/local.conf</code> file. | ||
| 192 | </p> | ||
| 193 | </li> | ||
| 194 | <li class="listitem"><p><span class="emphasis"><em><code class="filename">auto.conf</code>:</em></span> | ||
| 195 | The file is usually created and written to by | ||
| 196 | an autobuilder. | ||
| 197 | The settings put into the file are typically the same as | ||
| 198 | you would find in the <code class="filename">conf/local.conf</code> | ||
| 199 | or the <code class="filename">conf/site.conf</code> files. | ||
| 200 | </p></li> | ||
| 201 | </ul></div> | ||
| 202 | <p> | ||
| 203 | </p> | ||
| 204 | <p> | ||
| 205 | You can edit all configuration files to further define | ||
| 206 | any particular build environment. | ||
| 207 | This process is represented by the "User Configuration Edits" | ||
| 208 | box in the figure. | ||
| 209 | </p> | ||
| 210 | <p> | ||
| 211 | When you launch your build with the | ||
| 212 | <code class="filename">bitbake <em class="replaceable"><code>target</code></em></code> | ||
| 213 | command, BitBake sorts out the configurations to ultimately | ||
| 214 | define your build environment. | ||
| 215 | It is important to understand that the OpenEmbedded build system | ||
| 216 | reads the configuration files in a specific order: | ||
| 217 | <code class="filename">site.conf</code>, <code class="filename">auto.conf</code>, | ||
| 218 | and <code class="filename">local.conf</code>. | ||
| 219 | And, the build system applies the normal assignment statement | ||
| 220 | rules. | ||
| 221 | Because the files are parsed in a specific order, variable | ||
| 222 | assignments for the same variable could be affected. | ||
| 223 | For example, if the <code class="filename">auto.conf</code> file and | ||
| 224 | the <code class="filename">local.conf</code> set | ||
| 225 | <em class="replaceable"><code>variable1</code></em> to different values, because | ||
| 226 | the build system parses <code class="filename">local.conf</code> after | ||
| 227 | <code class="filename">auto.conf</code>, | ||
| 228 | <em class="replaceable"><code>variable1</code></em> is assigned the value from | ||
| 229 | the <code class="filename">local.conf</code> file. | ||
| 230 | </p> | ||
| 231 | </div></body> | ||
| 232 | </html> | ||
diff --git a/documentation/getting-started/eclipse/html/getting-started/usingpoky-LIC_FILES_CHKSUM-explanation-of-syntax.html b/documentation/getting-started/eclipse/html/getting-started/usingpoky-LIC_FILES_CHKSUM-explanation-of-syntax.html new file mode 100644 index 0000000000..7e43ebd923 --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/usingpoky-LIC_FILES_CHKSUM-explanation-of-syntax.html | |||
| @@ -0,0 +1,76 @@ | |||
| 1 | <html> | ||
| 2 | <head> | ||
| 3 | <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> | ||
| 4 | <title>3.7.1.2.Explanation of Syntax</title> | ||
| 5 | <link rel="stylesheet" type="text/css" href="../book.css"> | ||
| 6 | <meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> | ||
| 7 | <link rel="home" href="index.html" title="Getting Started With Yocto Project"> | ||
| 8 | <link rel="up" href="usingpoky-configuring-LIC_FILES_CHKSUM.html" title="3.7.1.Tracking License Changes"> | ||
| 9 | <link rel="prev" href="usingpoky-specifying-LIC_FILES_CHKSUM.html" title="3.7.1.1.Specifying the LIC_FILES_CHKSUM Variable"> | ||
| 10 | <link rel="next" href="enabling-commercially-licensed-recipes.html" title="3.7.2.Enabling Commercially Licensed Recipes"> | ||
| 11 | </head> | ||
| 12 | <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="3.7.1.2.Explanation of Syntax"> | ||
| 13 | <div class="titlepage"><div><div><h4 class="title"> | ||
| 14 | <a name="usingpoky-LIC_FILES_CHKSUM-explanation-of-syntax"></a>3.7.1.2.Explanation of Syntax</h4></div></div></div> | ||
| 15 | <p> | ||
| 16 | As mentioned in the previous section, the | ||
| 17 | <code class="filename">LIC_FILES_CHKSUM</code> variable lists all | ||
| 18 | the important files that contain the license text for the | ||
| 19 | source code. | ||
| 20 | It is possible to specify a checksum for an entire file, | ||
| 21 | or a specific section of a file (specified by beginning and | ||
| 22 | ending line numbers with the "beginline" and "endline" | ||
| 23 | parameters, respectively). | ||
| 24 | The latter is useful for source files with a license | ||
| 25 | notice header, README documents, and so forth. | ||
| 26 | If you do not use the "beginline" parameter, then it is | ||
| 27 | assumed that the text begins on the first line of the file. | ||
| 28 | Similarly, if you do not use the "endline" parameter, | ||
| 29 | it is assumed that the license text ends with the last | ||
| 30 | line of the file. | ||
| 31 | </p> | ||
| 32 | <p> | ||
| 33 | The "md5" parameter stores the md5 checksum of the license | ||
| 34 | text. | ||
| 35 | If the license text changes in any way as compared to | ||
| 36 | this parameter then a mismatch occurs. | ||
| 37 | This mismatch triggers a build failure and notifies | ||
| 38 | the developer. | ||
| 39 | Notification allows the developer to review and address | ||
| 40 | the license text changes. | ||
| 41 | Also note that if a mismatch occurs during the build, | ||
| 42 | the correct md5 checksum is placed in the build log and | ||
| 43 | can be easily copied to the recipe. | ||
| 44 | </p> | ||
| 45 | <p> | ||
| 46 | There is no limit to how many files you can specify using | ||
| 47 | the <code class="filename">LIC_FILES_CHKSUM</code> variable. | ||
| 48 | Generally, however, every project requires a few | ||
| 49 | specifications for license tracking. | ||
| 50 | Many projects have a "COPYING" file that stores the | ||
| 51 | license information for all the source code files. | ||
| 52 | This practice allows you to just track the "COPYING" | ||
| 53 | file as long as it is kept up to date. | ||
| 54 | </p> | ||
| 55 | <div class="note" title="Tips" style="margin-left: 0.5in; margin-right: 0.5in;"> | ||
| 56 | <h3 class="title">Tips</h3> | ||
| 57 | <div class="itemizedlist"><ul class="itemizedlist" type="disc"> | ||
| 58 | <li class="listitem"><p> | ||
| 59 | If you specify an empty or invalid "md5" | ||
| 60 | parameter, BitBake returns an md5 mis-match | ||
| 61 | error and displays the correct "md5" parameter | ||
| 62 | value during the build. | ||
| 63 | The correct parameter is also captured in | ||
| 64 | the build log. | ||
| 65 | </p></li> | ||
| 66 | <li class="listitem"><p> | ||
| 67 | If the whole file contains only license text, | ||
| 68 | you do not need to use the "beginline" and | ||
| 69 | "endline" parameters. | ||
| 70 | </p></li> | ||
| 71 | </ul></div> | ||
| 72 | </div> | ||
| 73 | <p> | ||
| 74 | </p> | ||
| 75 | </div></body> | ||
| 76 | </html> | ||
diff --git a/documentation/getting-started/eclipse/html/getting-started/usingpoky-components-bitbake.html b/documentation/getting-started/eclipse/html/getting-started/usingpoky-components-bitbake.html new file mode 100644 index 0000000000..39fa32b154 --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/usingpoky-components-bitbake.html | |||
| @@ -0,0 +1,82 @@ | |||
| 1 | <html> | ||
| 2 | <head> | ||
| 3 | <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> | ||
| 4 | <title>3.1.1.BitBake</title> | ||
| 5 | <link rel="stylesheet" type="text/css" href="../book.css"> | ||
| 6 | <meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> | ||
| 7 | <link rel="home" href="index.html" title="Getting Started With Yocto Project"> | ||
| 8 | <link rel="up" href="yocto-project-components.html" title="3.1.Yocto Project Components"> | ||
| 9 | <link rel="prev" href="yocto-project-components.html" title="3.1.Yocto Project Components"> | ||
| 10 | <link rel="next" href="usingpoky-components-metadata.html" title="3.1.2.Metadata (Recipes)"> | ||
| 11 | </head> | ||
| 12 | <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="3.1.1.BitBake"> | ||
| 13 | <div class="titlepage"><div><div><h3 class="title"> | ||
| 14 | <a name="usingpoky-components-bitbake"></a>3.1.1.BitBake</h3></div></div></div> | ||
| 15 | <p> | ||
| 16 | BitBake is the tool at the heart of the OpenEmbedded build | ||
| 17 | system and is responsible for parsing the | ||
| 18 | <a class="link" href="../ref-manual/metadata.html" target="_self">Metadata</a>, | ||
| 19 | generating a list of tasks from it, and then executing those | ||
| 20 | tasks. | ||
| 21 | </p> | ||
| 22 | <p> | ||
| 23 | This section briefly introduces BitBake. | ||
| 24 | If you want more information on BitBake, see the | ||
| 25 | <a class="link" href="../bitbake-user-manual/bitbake-user-manual.html" target="_self">BitBake User Manual</a>. | ||
| 26 | </p> | ||
| 27 | <p> | ||
| 28 | To see a list of the options BitBake supports, use either of | ||
| 29 | the following commands: | ||
| 30 | </p> | ||
| 31 | <pre class="literallayout"> | ||
| 32 | $ bitbake -h | ||
| 33 | $ bitbake --help | ||
| 34 | </pre> | ||
| 35 | <p> | ||
| 36 | </p> | ||
| 37 | <p> | ||
| 38 | The most common usage for BitBake is | ||
| 39 | <code class="filename">bitbake <em class="replaceable"><code>packagename</code></em></code>, | ||
| 40 | where <code class="filename">packagename</code> is the name of the | ||
| 41 | package you want to build (referred to as the "target" in this | ||
| 42 | manual). | ||
| 43 | The target often equates to the first part of a recipe's | ||
| 44 | filename (e.g. "foo" for a recipe named | ||
| 45 | <code class="filename">foo_1.3.0-r0.bb</code>). | ||
| 46 | So, to process the | ||
| 47 | <code class="filename">matchbox-desktop_1.2.3.bb</code> recipe file, you | ||
| 48 | might type the following: | ||
| 49 | </p> | ||
| 50 | <pre class="literallayout"> | ||
| 51 | $ bitbake matchbox-desktop | ||
| 52 | </pre> | ||
| 53 | <p> | ||
| 54 | Several different versions of | ||
| 55 | <code class="filename">matchbox-desktop</code> might exist. | ||
| 56 | BitBake chooses the one selected by the distribution | ||
| 57 | configuration. | ||
| 58 | You can get more details about how BitBake chooses between | ||
| 59 | different target versions and providers in the | ||
| 60 | "<a class="link" href="../bitbake-user-manual/bb-bitbake-preferences.html" target="_self">Preferences</a>" | ||
| 61 | section of the BitBake User Manual. | ||
| 62 | </p> | ||
| 63 | <p> | ||
| 64 | BitBake also tries to execute any dependent tasks first. | ||
| 65 | So for example, before building | ||
| 66 | <code class="filename">matchbox-desktop</code>, BitBake would build a | ||
| 67 | cross compiler and <code class="filename">glibc</code> if they had not | ||
| 68 | already been built. | ||
| 69 | </p> | ||
| 70 | <p> | ||
| 71 | A useful BitBake option to consider is the | ||
| 72 | <code class="filename">-k</code> or <code class="filename">--continue</code> | ||
| 73 | option. | ||
| 74 | This option instructs BitBake to try and continue processing | ||
| 75 | the job as long as possible even after encountering an error. | ||
| 76 | When an error occurs, the target that failed and those that | ||
| 77 | depend on it cannot be remade. | ||
| 78 | However, when you use this option other dependencies can | ||
| 79 | still be processed. | ||
| 80 | </p> | ||
| 81 | </div></body> | ||
| 82 | </html> | ||
diff --git a/documentation/getting-started/eclipse/html/getting-started/usingpoky-components-classes.html b/documentation/getting-started/eclipse/html/getting-started/usingpoky-components-classes.html new file mode 100644 index 0000000000..809906c999 --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/usingpoky-components-classes.html | |||
| @@ -0,0 +1,30 @@ | |||
| 1 | <html> | ||
| 2 | <head> | ||
| 3 | <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> | ||
| 4 | <title>3.1.4.Classes</title> | ||
| 5 | <link rel="stylesheet" type="text/css" href="../book.css"> | ||
| 6 | <meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> | ||
| 7 | <link rel="home" href="index.html" title="Getting Started With Yocto Project"> | ||
| 8 | <link rel="up" href="yocto-project-components.html" title="3.1.Yocto Project Components"> | ||
| 9 | <link rel="prev" href="metadata-virtual-providers.html" title="3.1.3.Metadata (Virtual Providers)"> | ||
| 10 | <link rel="next" href="usingpoky-components-configuration.html" title="3.1.5.Configuration"> | ||
| 11 | </head> | ||
| 12 | <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="3.1.4.Classes"> | ||
| 13 | <div class="titlepage"><div><div><h3 class="title"> | ||
| 14 | <a name="usingpoky-components-classes"></a>3.1.4.Classes</h3></div></div></div> | ||
| 15 | <p> | ||
| 16 | Class files (<code class="filename">.bbclass</code>) contain information | ||
| 17 | that is useful to share between | ||
| 18 | <a class="link" href="../ref-manual/metadata.html" target="_self">Metadata</a> | ||
| 19 | files. | ||
| 20 | An example is the | ||
| 21 | <a class="link" href="../ref-manual/ref-classes-autotools.html" target="_self"><code class="filename">autotools</code></a> | ||
| 22 | class, which contains common settings for any application that | ||
| 23 | Autotools uses. | ||
| 24 | The | ||
| 25 | "<a class="link" href="../ref-manual/ref-classes.html" target="_self">Classes</a>" | ||
| 26 | chapter in the Yocto Project Reference Manual provides | ||
| 27 | details about classes and how to use them. | ||
| 28 | </p> | ||
| 29 | </div></body> | ||
| 30 | </html> | ||
diff --git a/documentation/getting-started/eclipse/html/getting-started/usingpoky-components-configuration.html b/documentation/getting-started/eclipse/html/getting-started/usingpoky-components-configuration.html new file mode 100644 index 0000000000..a1ca039c9b --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/usingpoky-components-configuration.html | |||
| @@ -0,0 +1,27 @@ | |||
| 1 | <html> | ||
| 2 | <head> | ||
| 3 | <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> | ||
| 4 | <title>3.1.5.Configuration</title> | ||
| 5 | <link rel="stylesheet" type="text/css" href="../book.css"> | ||
| 6 | <meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> | ||
| 7 | <link rel="home" href="index.html" title="Getting Started With Yocto Project"> | ||
| 8 | <link rel="up" href="yocto-project-components.html" title="3.1.Yocto Project Components"> | ||
| 9 | <link rel="prev" href="usingpoky-components-classes.html" title="3.1.4.Classes"> | ||
| 10 | <link rel="next" href="cross-development-toolchain-generation.html" title="3.2.Cross-Development Toolchain Generation"> | ||
| 11 | </head> | ||
| 12 | <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="3.1.5.Configuration"> | ||
| 13 | <div class="titlepage"><div><div><h3 class="title"> | ||
| 14 | <a name="usingpoky-components-configuration"></a>3.1.5.Configuration</h3></div></div></div> | ||
| 15 | <p> | ||
| 16 | The configuration files (<code class="filename">.conf</code>) define | ||
| 17 | various configuration variables that govern the OpenEmbedded | ||
| 18 | build process. | ||
| 19 | These files fall into several areas that define machine | ||
| 20 | configuration options, distribution configuration options, | ||
| 21 | compiler tuning options, general common configuration options, | ||
| 22 | and user configuration options in | ||
| 23 | <code class="filename">local.conf</code>, which is found in the | ||
| 24 | <a class="link" href="../ref-manual/build-directory.html" target="_self">Build Directory</a>. | ||
| 25 | </p> | ||
| 26 | </div></body> | ||
| 27 | </html> | ||
diff --git a/documentation/getting-started/eclipse/html/getting-started/usingpoky-components-metadata.html b/documentation/getting-started/eclipse/html/getting-started/usingpoky-components-metadata.html new file mode 100644 index 0000000000..b25324502e --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/usingpoky-components-metadata.html | |||
| @@ -0,0 +1,35 @@ | |||
| 1 | <html> | ||
| 2 | <head> | ||
| 3 | <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> | ||
| 4 | <title>3.1.2.Metadata (Recipes)</title> | ||
| 5 | <link rel="stylesheet" type="text/css" href="../book.css"> | ||
| 6 | <meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> | ||
| 7 | <link rel="home" href="index.html" title="Getting Started With Yocto Project"> | ||
| 8 | <link rel="up" href="yocto-project-components.html" title="3.1.Yocto Project Components"> | ||
| 9 | <link rel="prev" href="usingpoky-components-bitbake.html" title="3.1.1.BitBake"> | ||
| 10 | <link rel="next" href="metadata-virtual-providers.html" title="3.1.3.Metadata (Virtual Providers)"> | ||
| 11 | </head> | ||
| 12 | <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="3.1.2.Metadata (Recipes)"> | ||
| 13 | <div class="titlepage"><div><div><h3 class="title"> | ||
| 14 | <a name="usingpoky-components-metadata"></a>3.1.2.Metadata (Recipes)</h3></div></div></div> | ||
| 15 | <p> | ||
| 16 | Files that have the <code class="filename">.bb</code> suffix are | ||
| 17 | "recipes" files. | ||
| 18 | In general, a recipe contains information about a single piece | ||
| 19 | of software. | ||
| 20 | This information includes the location from which to download | ||
| 21 | the unaltered source, any source patches to be applied to that | ||
| 22 | source (if needed), which special configuration options to | ||
| 23 | apply, how to compile the source files, and how to package the | ||
| 24 | compiled output. | ||
| 25 | </p> | ||
| 26 | <p> | ||
| 27 | The term "package" is sometimes used to refer to recipes. | ||
| 28 | However, since the word "package" is used for the packaged | ||
| 29 | output from the OpenEmbedded build system (i.e. | ||
| 30 | <code class="filename">.ipk</code> or <code class="filename">.deb</code> files), | ||
| 31 | this document avoids using the term "package" when referring | ||
| 32 | to recipes. | ||
| 33 | </p> | ||
| 34 | </div></body> | ||
| 35 | </html> | ||
diff --git a/documentation/getting-started/eclipse/html/getting-started/usingpoky-configuring-LIC_FILES_CHKSUM.html b/documentation/getting-started/eclipse/html/getting-started/usingpoky-configuring-LIC_FILES_CHKSUM.html new file mode 100644 index 0000000000..ee59e3bc10 --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/usingpoky-configuring-LIC_FILES_CHKSUM.html | |||
| @@ -0,0 +1,24 @@ | |||
| 1 | <html> | ||
| 2 | <head> | ||
| 3 | <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> | ||
| 4 | <title>3.7.1.Tracking License Changes</title> | ||
| 5 | <link rel="stylesheet" type="text/css" href="../book.css"> | ||
| 6 | <meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> | ||
| 7 | <link rel="home" href="index.html" title="Getting Started With Yocto Project"> | ||
| 8 | <link rel="up" href="overview-licenses.html" title="3.7.Licenses"> | ||
| 9 | <link rel="prev" href="overview-licenses.html" title="3.7.Licenses"> | ||
| 10 | <link rel="next" href="usingpoky-specifying-LIC_FILES_CHKSUM.html" title="3.7.1.1.Specifying the LIC_FILES_CHKSUM Variable"> | ||
| 11 | </head> | ||
| 12 | <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="3.7.1.Tracking License Changes"> | ||
| 13 | <div class="titlepage"><div><div><h3 class="title"> | ||
| 14 | <a name="usingpoky-configuring-LIC_FILES_CHKSUM"></a>3.7.1.Tracking License Changes</h3></div></div></div> | ||
| 15 | <p> | ||
| 16 | The license of an upstream project might change in the future. | ||
| 17 | In order to prevent these changes going unnoticed, the | ||
| 18 | <a class="link" href="../ref-manual/var-LIC_FILES_CHKSUM.html" target="_self"><code class="filename">LIC_FILES_CHKSUM</code></a> | ||
| 19 | variable tracks changes to the license text. The checksums are | ||
| 20 | validated at the end of the configure step, and if the | ||
| 21 | checksums do not match, the build will fail. | ||
| 22 | </p> | ||
| 23 | </div></body> | ||
| 24 | </html> | ||
diff --git a/documentation/getting-started/eclipse/html/getting-started/usingpoky-specifying-LIC_FILES_CHKSUM.html b/documentation/getting-started/eclipse/html/getting-started/usingpoky-specifying-LIC_FILES_CHKSUM.html new file mode 100644 index 0000000000..ed9a3cc501 --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/usingpoky-specifying-LIC_FILES_CHKSUM.html | |||
| @@ -0,0 +1,82 @@ | |||
| 1 | <html> | ||
| 2 | <head> | ||
| 3 | <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> | ||
| 4 | <title>3.7.1.1.Specifying the LIC_FILES_CHKSUM Variable</title> | ||
| 5 | <link rel="stylesheet" type="text/css" href="../book.css"> | ||
| 6 | <meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> | ||
| 7 | <link rel="home" href="index.html" title="Getting Started With Yocto Project"> | ||
| 8 | <link rel="up" href="usingpoky-configuring-LIC_FILES_CHKSUM.html" title="3.7.1.Tracking License Changes"> | ||
| 9 | <link rel="prev" href="usingpoky-configuring-LIC_FILES_CHKSUM.html" title="3.7.1.Tracking License Changes"> | ||
| 10 | <link rel="next" href="usingpoky-LIC_FILES_CHKSUM-explanation-of-syntax.html" title="3.7.1.2.Explanation of Syntax"> | ||
| 11 | </head> | ||
| 12 | <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="3.7.1.1.Specifying the LIC_FILES_CHKSUM Variable"> | ||
| 13 | <div class="titlepage"><div><div><h4 class="title"> | ||
| 14 | <a name="usingpoky-specifying-LIC_FILES_CHKSUM"></a>3.7.1.1.Specifying the <code class="filename">LIC_FILES_CHKSUM</code> Variable</h4></div></div></div> | ||
| 15 | <p> | ||
| 16 | The <code class="filename">LIC_FILES_CHKSUM</code> | ||
| 17 | variable contains checksums of the license text in the | ||
| 18 | source code for the recipe. | ||
| 19 | Following is an example of how to specify | ||
| 20 | <code class="filename">LIC_FILES_CHKSUM</code>: | ||
| 21 | </p> | ||
| 22 | <pre class="literallayout"> | ||
| 23 | LIC_FILES_CHKSUM = "file://COPYING;md5=xxxx \ | ||
| 24 | file://licfile1.txt;beginline=5;endline=29;md5=yyyy \ | ||
| 25 | file://licfile2.txt;endline=50;md5=zzzz \ | ||
| 26 | ..." | ||
| 27 | </pre> | ||
| 28 | <p> | ||
| 29 | </p> | ||
| 30 | <div class="note" title="Notes" style="margin-left: 0.5in; margin-right: 0.5in;"> | ||
| 31 | <h3 class="title">Notes</h3> | ||
| 32 | <div class="itemizedlist"><ul class="itemizedlist" type="disc"> | ||
| 33 | <li class="listitem"><p> | ||
| 34 | When using "beginline" and "endline", realize | ||
| 35 | that line numbering begins with one and not | ||
| 36 | zero. | ||
| 37 | Also, the included lines are inclusive (i.e. | ||
| 38 | lines five through and including 29 in the | ||
| 39 | previous example for | ||
| 40 | <code class="filename">licfile1.txt</code>). | ||
| 41 | </p></li> | ||
| 42 | <li class="listitem"><p> | ||
| 43 | When a license check fails, the selected license | ||
| 44 | text is included as part of the QA message. | ||
| 45 | Using this output, you can determine the exact | ||
| 46 | start and finish for the needed license text. | ||
| 47 | </p></li> | ||
| 48 | </ul></div> | ||
| 49 | </div> | ||
| 50 | <p> | ||
| 51 | </p> | ||
| 52 | <p> | ||
| 53 | The build system uses the | ||
| 54 | <a class="link" href="../ref-manual/var-S.html" target="_self"><code class="filename">S</code></a> | ||
| 55 | variable as the default directory when searching files | ||
| 56 | listed in <code class="filename">LIC_FILES_CHKSUM</code>. | ||
| 57 | The previous example employs the default directory. | ||
| 58 | </p> | ||
| 59 | <p> | ||
| 60 | Consider this next example: | ||
| 61 | </p> | ||
| 62 | <pre class="literallayout"> | ||
| 63 | LIC_FILES_CHKSUM = "file://src/ls.c;beginline=5;endline=16;\ | ||
| 64 | md5=bb14ed3c4cda583abc85401304b5cd4e" | ||
| 65 | LIC_FILES_CHKSUM = "file://${WORKDIR}/license.html;md5=5c94767cedb5d6987c902ac850ded2c6" | ||
| 66 | </pre> | ||
| 67 | <p> | ||
| 68 | </p> | ||
| 69 | <p> | ||
| 70 | The first line locates a file in | ||
| 71 | <code class="filename">${S}/src/ls.c</code> and isolates lines five | ||
| 72 | through 16 as license text. | ||
| 73 | The second line refers to a file in | ||
| 74 | <a class="link" href="../ref-manual/var-WORKDIR.html" target="_self"><code class="filename">WORKDIR</code></a>. | ||
| 75 | </p> | ||
| 76 | <p> | ||
| 77 | Note that <code class="filename">LIC_FILES_CHKSUM</code> variable is | ||
| 78 | mandatory for all recipes, unless the | ||
| 79 | <code class="filename">LICENSE</code> variable is set to "CLOSED". | ||
| 80 | </p> | ||
| 81 | </div></body> | ||
| 82 | </html> | ||
diff --git a/documentation/getting-started/eclipse/html/getting-started/wayland-support.html b/documentation/getting-started/eclipse/html/getting-started/wayland-support.html new file mode 100644 index 0000000000..da810a4439 --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/wayland-support.html | |||
| @@ -0,0 +1,46 @@ | |||
| 1 | <html> | ||
| 2 | <head> | ||
| 3 | <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> | ||
| 4 | <title>3.6.1.Support</title> | ||
| 5 | <link rel="stylesheet" type="text/css" href="../book.css"> | ||
| 6 | <meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> | ||
| 7 | <link rel="home" href="index.html" title="Getting Started With Yocto Project"> | ||
| 8 | <link rel="up" href="wayland.html" title="3.6.Wayland"> | ||
| 9 | <link rel="prev" href="wayland.html" title="3.6.Wayland"> | ||
| 10 | <link rel="next" href="enabling-wayland-in-an-image.html" title="3.6.2.Enabling Wayland in an Image"> | ||
| 11 | </head> | ||
| 12 | <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="3.6.1.Support"> | ||
| 13 | <div class="titlepage"><div><div><h3 class="title"> | ||
| 14 | <a name="wayland-support"></a>3.6.1.Support</h3></div></div></div> | ||
| 15 | <p> | ||
| 16 | The Wayland protocol libraries and the reference Weston | ||
| 17 | compositor ship as integrated packages in the | ||
| 18 | <code class="filename">meta</code> layer of the | ||
| 19 | <a class="link" href="../ref-manual/source-directory.html" target="_self">Source Directory</a>. | ||
| 20 | Specifically, you can find the recipes that build both Wayland | ||
| 21 | and Weston at | ||
| 22 | <code class="filename">meta/recipes-graphics/wayland</code>. | ||
| 23 | </p> | ||
| 24 | <p> | ||
| 25 | You can build both the Wayland and Weston packages for use only | ||
| 26 | with targets that accept the | ||
| 27 | <a class="ulink" href="https://en.wikipedia.org/wiki/Mesa_(computer_graphics)" target="_self">Mesa 3D and Direct Rendering Infrastructure</a>, | ||
| 28 | which is also known as Mesa DRI. | ||
| 29 | This implies that you cannot build and use the packages if your | ||
| 30 | target uses, for example, the | ||
| 31 | <span class="trademark">Intel</span> Embedded Media | ||
| 32 | and Graphics Driver | ||
| 33 | (<span class="trademark">Intel</span> EMGD) that | ||
| 34 | overrides Mesa DRI. | ||
| 35 | </p> | ||
| 36 | <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"> | ||
| 37 | <h3 class="title">Note</h3> | ||
| 38 | Due to lack of EGL support, Weston 1.0.3 will not run | ||
| 39 | directly on the emulated QEMU hardware. | ||
| 40 | However, this version of Weston will run under X emulation | ||
| 41 | without issues. | ||
| 42 | </div> | ||
| 43 | <p> | ||
| 44 | </p> | ||
| 45 | </div></body> | ||
| 46 | </html> | ||
diff --git a/documentation/getting-started/eclipse/html/getting-started/wayland.html b/documentation/getting-started/eclipse/html/getting-started/wayland.html new file mode 100644 index 0000000000..0747c9238c --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/wayland.html | |||
| @@ -0,0 +1,34 @@ | |||
| 1 | <html> | ||
| 2 | <head> | ||
| 3 | <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> | ||
| 4 | <title>3.6.Wayland</title> | ||
| 5 | <link rel="stylesheet" type="text/css" href="../book.css"> | ||
| 6 | <meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> | ||
| 7 | <link rel="home" href="index.html" title="Getting Started With Yocto Project"> | ||
| 8 | <link rel="up" href="overview-concepts.html" title="Chapter3.Yocto Project Concepts"> | ||
| 9 | <link rel="prev" href="fakeroot-and-pseudo.html" title="3.5.Fakeroot and Pseudo"> | ||
| 10 | <link rel="next" href="wayland-support.html" title="3.6.1.Support"> | ||
| 11 | </head> | ||
| 12 | <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="3.6.Wayland"> | ||
| 13 | <div class="titlepage"><div><div><h2 class="title" style="clear: both"> | ||
| 14 | <a name="wayland"></a>3.6.Wayland</h2></div></div></div> | ||
| 15 | <p> | ||
| 16 | <a class="ulink" href="http://en.wikipedia.org/wiki/Wayland_(display_server_protocol)" target="_self">Wayland</a> | ||
| 17 | is a computer display server protocol that | ||
| 18 | provides a method for compositing window managers to communicate | ||
| 19 | directly with applications and video hardware and expects them to | ||
| 20 | communicate with input hardware using other libraries. | ||
| 21 | Using Wayland with supporting targets can result in better control | ||
| 22 | over graphics frame rendering than an application might otherwise | ||
| 23 | achieve. | ||
| 24 | </p> | ||
| 25 | <p> | ||
| 26 | The Yocto Project provides the Wayland protocol libraries and the | ||
| 27 | reference | ||
| 28 | <a class="ulink" href="http://en.wikipedia.org/wiki/Wayland_(display_server_protocol)#Weston" target="_self">Weston</a> | ||
| 29 | compositor as part of its release. | ||
| 30 | This section describes what you need to do to implement Wayland and | ||
| 31 | use the compositor when building an image for a supporting target. | ||
| 32 | </p> | ||
| 33 | </div></body> | ||
| 34 | </html> | ||
diff --git a/documentation/getting-started/eclipse/html/getting-started/workflows.html b/documentation/getting-started/eclipse/html/getting-started/workflows.html new file mode 100644 index 0000000000..9d53975678 --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/workflows.html | |||
| @@ -0,0 +1,207 @@ | |||
| 1 | <html> | ||
| 2 | <head> | ||
| 3 | <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> | ||
| 4 | <title>2.3.Workflows</title> | ||
| 5 | <link rel="stylesheet" type="text/css" href="../book.css"> | ||
| 6 | <meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> | ||
| 7 | <link rel="home" href="index.html" title="Getting Started With Yocto Project"> | ||
| 8 | <link rel="up" href="overview-development-environment.html" title="Chapter2.The Yocto Project Development Environment"> | ||
| 9 | <link rel="prev" href="open-source-philosophy.html" title="2.2.Open Source Philosophy"> | ||
| 10 | <link rel="next" href="git.html" title="2.4.Git"> | ||
| 11 | </head> | ||
| 12 | <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="2.3.Workflows"> | ||
| 13 | <div class="titlepage"><div><div><h2 class="title" style="clear: both"> | ||
| 14 | <a name="workflows"></a>2.3.Workflows</h2></div></div></div> | ||
| 15 | <p> | ||
| 16 | This section provides workflow concepts using the Yocto Project and | ||
| 17 | Git. | ||
| 18 | In particular, the information covers basic practices that describe | ||
| 19 | roles and actions in a collaborative development environment. | ||
| 20 | </p> | ||
| 21 | <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"> | ||
| 22 | <h3 class="title">Note</h3> | ||
| 23 | If you are familiar with this type of development environment, you | ||
| 24 | might not want to read this section. | ||
| 25 | </div> | ||
| 26 | <p> | ||
| 27 | </p> | ||
| 28 | <p> | ||
| 29 | The Yocto Project files are maintained using Git in "master" | ||
| 30 | branches whose Git histories track every change and whose structures | ||
| 31 | provides branches for all diverging functionality. | ||
| 32 | Although there is no need to use Git, many open source projects do so. | ||
| 33 | </p> | ||
| 34 | <p> | ||
| 35 | |||
| 36 | </p> | ||
| 37 | <p> | ||
| 38 | For the Yocto Project, a key individual called the "maintainer" is | ||
| 39 | responsible for the "master" branch of a given Git repository. | ||
| 40 | The "master" branch is the “upstream” repository from which final or | ||
| 41 | most recent builds of the project occur. | ||
| 42 | The maintainer is responsible for accepting changes from other | ||
| 43 | developers and for organizing the underlying branch structure to | ||
| 44 | reflect release strategies and so forth. | ||
| 45 | </p> | ||
| 46 | <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"> | ||
| 47 | <h3 class="title">Note</h3>For information on finding out who is responsible for (maintains) | ||
| 48 | a particular area of code, see the | ||
| 49 | "<a class="link" href="../dev-manual/how-to-submit-a-change.html" target="_self">Submitting a Change to the Yocto Project</a>" | ||
| 50 | section of the Yocto Project Development Tasks Manual. | ||
| 51 | </div> | ||
| 52 | <p> | ||
| 53 | </p> | ||
| 54 | <p> | ||
| 55 | The Yocto Project <code class="filename">poky</code> Git repository also has an | ||
| 56 | upstream contribution Git repository named | ||
| 57 | <code class="filename">poky-contrib</code>. | ||
| 58 | You can see all the branches in this repository using the web interface | ||
| 59 | of the | ||
| 60 | <a class="ulink" href="http://git.yoctoproject.org" target="_self">Source Repositories</a> organized | ||
| 61 | within the "Poky Support" area. | ||
| 62 | These branches temporarily hold changes to the project that have been | ||
| 63 | submitted or committed by the Yocto Project development team and by | ||
| 64 | community members who contribute to the project. | ||
| 65 | The maintainer determines if the changes are qualified to be moved | ||
| 66 | from the "contrib" branches into the "master" branch of the Git | ||
| 67 | repository. | ||
| 68 | </p> | ||
| 69 | <p> | ||
| 70 | Developers (including contributing community members) create and | ||
| 71 | maintain cloned repositories of the upstream "master" branch. | ||
| 72 | The cloned repositories are local to their development platforms and | ||
| 73 | are used to develop changes. | ||
| 74 | When a developer is satisfied with a particular feature or change, | ||
| 75 | they "push" the changes to the appropriate "contrib" repository. | ||
| 76 | </p> | ||
| 77 | <p> | ||
| 78 | Developers are responsible for keeping their local repository | ||
| 79 | up-to-date with "master". | ||
| 80 | They are also responsible for straightening out any conflicts that | ||
| 81 | might arise within files that are being worked on simultaneously by | ||
| 82 | more than one person. | ||
| 83 | All this work is done locally on the developer’s machine before | ||
| 84 | anything is pushed to a "contrib" area and examined at the maintainer’s | ||
| 85 | level. | ||
| 86 | </p> | ||
| 87 | <p> | ||
| 88 | A somewhat formal method exists by which developers commit changes | ||
| 89 | and push them into the "contrib" area and subsequently request that | ||
| 90 | the maintainer include them into "master". | ||
| 91 | This process is called “submitting a patch” or "submitting a change." | ||
| 92 | For information on submitting patches and changes, see the | ||
| 93 | "<a class="link" href="../dev-manual/how-to-submit-a-change.html" target="_self">Submitting a Change to the Yocto Project</a>" | ||
| 94 | section in the Yocto Project Development Tasks Manual. | ||
| 95 | </p> | ||
| 96 | <p> | ||
| 97 | To summarize the development workflow: a single point of entry | ||
| 98 | exists for changes into the project’s "master" branch of the | ||
| 99 | Git repository, which is controlled by the project’s maintainer. | ||
| 100 | And, a set of developers exist who independently develop, test, and | ||
| 101 | submit changes to "contrib" areas for the maintainer to examine. | ||
| 102 | The maintainer then chooses which changes are going to become a | ||
| 103 | permanent part of the project. | ||
| 104 | </p> | ||
| 105 | <p> | ||
| 106 | </p> | ||
| 107 | <table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="540"><tr style="height: 270px"><td align="left"><img src="figures/git-workflow.png" align="left" height="270"></td></tr></table> | ||
| 108 | <p> | ||
| 109 | </p> | ||
| 110 | <p> | ||
| 111 | While each development environment is unique, there are some best | ||
| 112 | practices or methods that help development run smoothly. | ||
| 113 | The following list describes some of these practices. | ||
| 114 | For more information about Git workflows, see the workflow topics in | ||
| 115 | the | ||
| 116 | <a class="ulink" href="http://book.git-scm.com" target="_self">Git Community Book</a>. | ||
| 117 | </p> | ||
| 118 | <div class="itemizedlist"><ul class="itemizedlist" type="disc"> | ||
| 119 | <li class="listitem"> | ||
| 120 | <p> | ||
| 121 | <span class="emphasis"><em>Make Small Changes:</em></span> | ||
| 122 | It is best to keep the changes you commit small as compared to | ||
| 123 | bundling many disparate changes into a single commit. | ||
| 124 | This practice not only keeps things manageable but also allows | ||
| 125 | the maintainer to more easily include or refuse changes.</p> | ||
| 126 | <p>It is also good practice to leave the repository in a | ||
| 127 | state that allows you to still successfully build your project. | ||
| 128 | In other words, do not commit half of a feature, | ||
| 129 | then add the other half as a separate, later commit. | ||
| 130 | Each commit should take you from one buildable project state | ||
| 131 | to another buildable state. | ||
| 132 | </p> | ||
| 133 | </li> | ||
| 134 | <li class="listitem"><p> | ||
| 135 | <span class="emphasis"><em>Use Branches Liberally:</em></span> | ||
| 136 | It is very easy to create, use, and delete local branches in | ||
| 137 | your working Git repository. | ||
| 138 | You can name these branches anything you like. | ||
| 139 | It is helpful to give them names associated with the particular | ||
| 140 | feature or change on which you are working. | ||
| 141 | Once you are done with a feature or change and have merged it | ||
| 142 | into your local master branch, simply discard the temporary | ||
| 143 | branch. | ||
| 144 | </p></li> | ||
| 145 | <li class="listitem"><p> | ||
| 146 | <span class="emphasis"><em>Merge Changes:</em></span> | ||
| 147 | The <code class="filename">git merge</code> command allows you to take | ||
| 148 | the changes from one branch and fold them into another branch. | ||
| 149 | This process is especially helpful when more than a single | ||
| 150 | developer might be working on different parts of the same | ||
| 151 | feature. | ||
| 152 | Merging changes also automatically identifies any collisions | ||
| 153 | or "conflicts" that might happen as a result of the same lines | ||
| 154 | of code being altered by two different developers. | ||
| 155 | </p></li> | ||
| 156 | <li class="listitem"><p> | ||
| 157 | <span class="emphasis"><em>Manage Branches:</em></span> | ||
| 158 | Because branches are easy to use, you should use a system | ||
| 159 | where branches indicate varying levels of code readiness. | ||
| 160 | For example, you can have a "work" branch to develop in, a | ||
| 161 | "test" branch where the code or change is tested, a "stage" | ||
| 162 | branch where changes are ready to be committed, and so forth. | ||
| 163 | As your project develops, you can merge code across the | ||
| 164 | branches to reflect ever-increasing stable states of the | ||
| 165 | development. | ||
| 166 | </p></li> | ||
| 167 | <li class="listitem"><p> | ||
| 168 | <span class="emphasis"><em>Use Push and Pull:</em></span> | ||
| 169 | The push-pull workflow is based on the concept of developers | ||
| 170 | "pushing" local commits to a remote repository, which is | ||
| 171 | usually a contribution repository. | ||
| 172 | This workflow is also based on developers "pulling" known | ||
| 173 | states of the project down into their local development | ||
| 174 | repositories. | ||
| 175 | The workflow easily allows you to pull changes submitted by | ||
| 176 | other developers from the upstream repository into your | ||
| 177 | work area ensuring that you have the most recent software | ||
| 178 | on which to develop. | ||
| 179 | The Yocto Project has two scripts named | ||
| 180 | <code class="filename">create-pull-request</code> and | ||
| 181 | <code class="filename">send-pull-request</code> that ship with the | ||
| 182 | release to facilitate this workflow. | ||
| 183 | You can find these scripts in the <code class="filename">scripts</code> | ||
| 184 | folder of the | ||
| 185 | <a class="link" href="../ref-manual/source-directory.html" target="_self">Source Directory</a>. | ||
| 186 | For information on how to use these scripts, see the | ||
| 187 | "<a class="link" href="../dev-manual/pushing-a-change-upstream.html" target="_self">Using Scripts to Push a Change Upstream and Request a Pull</a>" | ||
| 188 | section in the Yocto Project Development Tasks Manual. | ||
| 189 | </p></li> | ||
| 190 | <li class="listitem"><p> | ||
| 191 | <span class="emphasis"><em>Patch Workflow:</em></span> | ||
| 192 | This workflow allows you to notify the maintainer through an | ||
| 193 | email that you have a change (or patch) you would like | ||
| 194 | considered for the "master" branch of the Git repository. | ||
| 195 | To send this type of change, you format the patch and then | ||
| 196 | send the email using the Git commands | ||
| 197 | <code class="filename">git format-patch</code> and | ||
| 198 | <code class="filename">git send-email</code>. | ||
| 199 | For information on how to use these scripts, see the | ||
| 200 | "<a class="link" href="../dev-manual/how-to-submit-a-change.html" target="_self">Submitting a Change to the Yocto Project</a>" | ||
| 201 | section in the Yocto Project Development Tasks Manual. | ||
| 202 | </p></li> | ||
| 203 | </ul></div> | ||
| 204 | <p> | ||
| 205 | </p> | ||
| 206 | </div></body> | ||
| 207 | </html> | ||
diff --git a/documentation/getting-started/eclipse/html/getting-started/x32.html b/documentation/getting-started/eclipse/html/getting-started/x32.html new file mode 100644 index 0000000000..daffedbeea --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/x32.html | |||
| @@ -0,0 +1,75 @@ | |||
| 1 | <html> | ||
| 2 | <head> | ||
| 3 | <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> | ||
| 4 | <title>3.8.x32 psABI</title> | ||
| 5 | <link rel="stylesheet" type="text/css" href="../book.css"> | ||
| 6 | <meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> | ||
| 7 | <link rel="home" href="index.html" title="Getting Started With Yocto Project"> | ||
| 8 | <link rel="up" href="overview-concepts.html" title="Chapter3.Yocto Project Concepts"> | ||
| 9 | <link rel="prev" href="other-variables-related-to-commercial-licenses.html" title="3.7.2.2.Other Variables Related to Commercial Licenses"> | ||
| 10 | </head> | ||
| 11 | <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="3.8.x32 psABI"> | ||
| 12 | <div class="titlepage"><div><div><h2 class="title" style="clear: both"> | ||
| 13 | <a name="x32"></a>3.8.x32 psABI</h2></div></div></div> | ||
| 14 | <p> | ||
| 15 | x32 processor-specific Application Binary Interface | ||
| 16 | (<a class="ulink" href="https://software.intel.com/en-us/node/628948" target="_self">x32 psABI</a>) | ||
| 17 | is a native 32-bit processor-specific ABI for | ||
| 18 | <span class="trademark">Intel</span> 64 (x86-64) | ||
| 19 | architectures. | ||
| 20 | An ABI defines the calling conventions between functions in a | ||
| 21 | processing environment. | ||
| 22 | The interface determines what registers are used and what the sizes are | ||
| 23 | for various C data types. | ||
| 24 | </p> | ||
| 25 | <p> | ||
| 26 | Some processing environments prefer using 32-bit applications even | ||
| 27 | when running on Intel 64-bit platforms. | ||
| 28 | Consider the i386 psABI, which is a very old 32-bit ABI for Intel | ||
| 29 | 64-bit platforms. | ||
| 30 | The i386 psABI does not provide efficient use and access of the | ||
| 31 | Intel 64-bit processor resources, leaving the system underutilized. | ||
| 32 | Now consider the x86_64 psABI. | ||
| 33 | This ABI is newer and uses 64-bits for data sizes and program | ||
| 34 | pointers. | ||
| 35 | The extra bits increase the footprint size of the programs, | ||
| 36 | libraries, and also increases the memory and file system size | ||
| 37 | requirements. | ||
| 38 | Executing under the x32 psABI enables user programs to utilize CPU | ||
| 39 | and system resources more efficiently while keeping the memory | ||
| 40 | footprint of the applications low. | ||
| 41 | Extra bits are used for registers but not for addressing mechanisms. | ||
| 42 | </p> | ||
| 43 | <p> | ||
| 44 | The Yocto Project supports the final specifications of x32 psABI | ||
| 45 | as follows: | ||
| 46 | </p> | ||
| 47 | <div class="itemizedlist"><ul class="itemizedlist" type="disc"> | ||
| 48 | <li class="listitem"><p> | ||
| 49 | You can create packages and images in x32 psABI format on | ||
| 50 | x86_64 architecture targets. | ||
| 51 | </p></li> | ||
| 52 | <li class="listitem"><p> | ||
| 53 | You can successfully build recipes with the x32 toolchain. | ||
| 54 | </p></li> | ||
| 55 | <li class="listitem"><p> | ||
| 56 | You can create and boot | ||
| 57 | <code class="filename">core-image-minimal</code> and | ||
| 58 | <code class="filename">core-image-sato</code> images. | ||
| 59 | </p></li> | ||
| 60 | <li class="listitem"><p> | ||
| 61 | RPM Package Manager (RPM) support exists for x32 binaries. | ||
| 62 | </p></li> | ||
| 63 | <li class="listitem"><p> | ||
| 64 | Support for large images exists. | ||
| 65 | </p></li> | ||
| 66 | </ul></div> | ||
| 67 | <p> | ||
| 68 | </p> | ||
| 69 | <p> | ||
| 70 | For steps on how to use x32 psABI, see the | ||
| 71 | "<a class="link" href="../dev-manual/using-x32-psabi.html" target="_self">Using x32 psABI</a>" | ||
| 72 | section in the Yocto Project Development Tasks Manual. | ||
| 73 | </p> | ||
| 74 | </div></body> | ||
| 75 | </html> | ||
diff --git a/documentation/getting-started/eclipse/html/getting-started/yocto-project-components.html b/documentation/getting-started/eclipse/html/getting-started/yocto-project-components.html new file mode 100644 index 0000000000..0ad63b2402 --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/yocto-project-components.html | |||
| @@ -0,0 +1,62 @@ | |||
| 1 | <html> | ||
| 2 | <head> | ||
| 3 | <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> | ||
| 4 | <title>3.1.Yocto Project Components</title> | ||
| 5 | <link rel="stylesheet" type="text/css" href="../book.css"> | ||
| 6 | <meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> | ||
| 7 | <link rel="home" href="index.html" title="Getting Started With Yocto Project"> | ||
| 8 | <link rel="up" href="overview-concepts.html" title="Chapter3.Yocto Project Concepts"> | ||
| 9 | <link rel="prev" href="overview-concepts.html" title="Chapter3.Yocto Project Concepts"> | ||
| 10 | <link rel="next" href="usingpoky-components-bitbake.html" title="3.1.1.BitBake"> | ||
| 11 | </head> | ||
| 12 | <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="3.1.Yocto Project Components"> | ||
| 13 | <div class="titlepage"><div><div><h2 class="title" style="clear: both"> | ||
| 14 | <a name="yocto-project-components"></a>3.1.Yocto Project Components</h2></div></div></div> | ||
| 15 | <p> | ||
| 16 | The | ||
| 17 | <a class="link" href="../ref-manual/bitbake-term.html" target="_self">BitBake</a> | ||
| 18 | task executor together with various types of configuration files | ||
| 19 | form the OpenEmbedded Core. | ||
| 20 | This section overviews these components by describing their use and | ||
| 21 | how they interact. | ||
| 22 | </p> | ||
| 23 | <p> | ||
| 24 | BitBake handles the parsing and execution of the data files. | ||
| 25 | The data itself is of various types: | ||
| 26 | </p> | ||
| 27 | <div class="itemizedlist"><ul class="itemizedlist" type="disc"> | ||
| 28 | <li class="listitem"><p> | ||
| 29 | <span class="emphasis"><em>Recipes:</em></span> | ||
| 30 | Provides details about particular pieces of software. | ||
| 31 | </p></li> | ||
| 32 | <li class="listitem"><p> | ||
| 33 | <span class="emphasis"><em>Class Data:</em></span> | ||
| 34 | Abstracts common build information (e.g. how to build a | ||
| 35 | Linux kernel). | ||
| 36 | </p></li> | ||
| 37 | <li class="listitem"><p> | ||
| 38 | <span class="emphasis"><em>Configuration Data:</em></span> | ||
| 39 | Defines machine-specific settings, policy decisions, and | ||
| 40 | so forth. | ||
| 41 | Configuration data acts as the glue to bind everything | ||
| 42 | together. | ||
| 43 | </p></li> | ||
| 44 | </ul></div> | ||
| 45 | <p> | ||
| 46 | </p> | ||
| 47 | <p> | ||
| 48 | BitBake knows how to combine multiple data sources together and | ||
| 49 | refers to each data source as a layer. | ||
| 50 | For information on layers, see the | ||
| 51 | "<a class="link" href="../dev-manual/understanding-and-creating-layers.html" target="_self">Understanding and Creating Layers</a>" | ||
| 52 | section of the Yocto Project Development Tasks Manual. | ||
| 53 | </p> | ||
| 54 | <p> | ||
| 55 | Following are some brief details on these core components. | ||
| 56 | For additional information on how these components interact during | ||
| 57 | a build, see the | ||
| 58 | "<a class="link" href="development-concepts.html" title="2.8.Development Concepts">Development Concepts</a>" | ||
| 59 | section. | ||
| 60 | </p> | ||
| 61 | </div></body> | ||
| 62 | </html> | ||
diff --git a/documentation/getting-started/eclipse/html/getting-started/yocto-project-repositories.html b/documentation/getting-started/eclipse/html/getting-started/yocto-project-repositories.html new file mode 100644 index 0000000000..3dcc2af5eb --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/yocto-project-repositories.html | |||
| @@ -0,0 +1,135 @@ | |||
| 1 | <html> | ||
| 2 | <head> | ||
| 3 | <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> | ||
| 4 | <title>2.5.Yocto Project Source Repositories</title> | ||
| 5 | <link rel="stylesheet" type="text/css" href="../book.css"> | ||
| 6 | <meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> | ||
| 7 | <link rel="home" href="index.html" title="Getting Started With Yocto Project"> | ||
| 8 | <link rel="up" href="overview-development-environment.html" title="Chapter2.The Yocto Project Development Environment"> | ||
| 9 | <link rel="prev" href="basic-commands.html" title="2.4.2.Basic Commands"> | ||
| 10 | <link rel="next" href="licensing.html" title="2.6.Licensing"> | ||
| 11 | </head> | ||
| 12 | <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="2.5.Yocto Project Source Repositories"> | ||
| 13 | <div class="titlepage"><div><div><h2 class="title" style="clear: both"> | ||
| 14 | <a name="yocto-project-repositories"></a>2.5.Yocto Project Source Repositories</h2></div></div></div> | ||
| 15 | <p> | ||
| 16 | The Yocto Project team maintains complete source repositories for all | ||
| 17 | Yocto Project files at | ||
| 18 | <a class="ulink" href="http://git.yoctoproject.org/cgit/cgit.cgi" target="_self">http://git.yoctoproject.org/cgit/cgit.cgi</a>. | ||
| 19 | This web-based source code browser is organized into categories by | ||
| 20 | function such as IDE Plugins, Matchbox, Poky, Yocto Linux Kernel, and | ||
| 21 | so forth. | ||
| 22 | From the interface, you can click on any particular item in the "Name" | ||
| 23 | column and see the URL at the bottom of the page that you need to clone | ||
| 24 | a Git repository for that particular item. | ||
| 25 | Having a local Git repository of the | ||
| 26 | <a class="link" href="../ref-manual/source-directory.html" target="_self">Source Directory</a>, | ||
| 27 | which is usually named "poky", allows | ||
| 28 | you to make changes, contribute to the history, and ultimately enhance | ||
| 29 | the Yocto Project's tools, Board Support Packages, and so forth. | ||
| 30 | </p> | ||
| 31 | <p> | ||
| 32 | For any supported release of Yocto Project, you can also go to the | ||
| 33 | <a class="ulink" href="http://www.yoctoproject.org" target="_self">Yocto Project Website</a> and | ||
| 34 | select the "Downloads" tab and get a released tarball of the | ||
| 35 | <code class="filename">poky</code> repository or any supported BSP tarballs. | ||
| 36 | Unpacking these tarballs gives you a snapshot of the released | ||
| 37 | files. | ||
| 38 | </p> | ||
| 39 | <div class="note" title="Notes" style="margin-left: 0.5in; margin-right: 0.5in;"> | ||
| 40 | <h3 class="title">Notes</h3> | ||
| 41 | <div class="itemizedlist"><ul class="itemizedlist" type="disc"> | ||
| 42 | <li class="listitem"><p> | ||
| 43 | The recommended method for setting up the Yocto Project | ||
| 44 | <a class="link" href="../ref-manual/source-directory.html" target="_self">Source Directory</a> | ||
| 45 | and the files for supported BSPs | ||
| 46 | (e.g., <code class="filename">meta-intel</code>) is to use | ||
| 47 | <a class="link" href="git.html" title="2.4.Git">Git</a> to create a local copy of | ||
| 48 | the upstream repositories. | ||
| 49 | </p></li> | ||
| 50 | <li class="listitem"><p> | ||
| 51 | Be sure to always work in matching branches for both | ||
| 52 | the selected BSP repository and the | ||
| 53 | <a class="link" href="../ref-manual/source-directory.html" target="_self">Source Directory</a> | ||
| 54 | (i.e. <code class="filename">poky</code>) repository. | ||
| 55 | For example, if you have checked out the "master" branch | ||
| 56 | of <code class="filename">poky</code> and you are going to use | ||
| 57 | <code class="filename">meta-intel</code>, be sure to checkout the | ||
| 58 | "master" branch of <code class="filename">meta-intel</code>. | ||
| 59 | </p></li> | ||
| 60 | </ul></div> | ||
| 61 | </div> | ||
| 62 | <p> | ||
| 63 | </p> | ||
| 64 | <p> | ||
| 65 | In summary, here is where you can get the project files needed for | ||
| 66 | development: | ||
| 67 | </p> | ||
| 68 | <div class="itemizedlist"><ul class="itemizedlist" type="disc"> | ||
| 69 | <li class="listitem"> | ||
| 70 | <p><a name="source-repositories"></a> | ||
| 71 | <span class="emphasis"><em> | ||
| 72 | <a class="ulink" href="http://git.yoctoproject.org/cgit/cgit.cgi" target="_self">Source Repositories:</a> | ||
| 73 | </em></span> | ||
| 74 | This area contains IDE Plugins, Matchbox, Poky, Poky Support, | ||
| 75 | Tools, Yocto Linux Kernel, and Yocto Metadata Layers. | ||
| 76 | You can create local copies of Git repositories for each of | ||
| 77 | these areas.</p> | ||
| 78 | <p> | ||
| 79 | </p> | ||
| 80 | <table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="540"><tr style="height: 360px"><td align="center"><img src="figures/source-repos.png" align="middle" width="540"></td></tr></table> | ||
| 81 | <p> | ||
| 82 | For steps on how to view and access these upstream Git | ||
| 83 | repositories, see the | ||
| 84 | "<a class="link" href="../dev-manual/accessing-source-repositories.html" target="_self">Accessing Source Repositories</a>" | ||
| 85 | Section in the Yocto Project Development Tasks Manual. | ||
| 86 | </p> | ||
| 87 | </li> | ||
| 88 | <li class="listitem"> | ||
| 89 | <p><a name="index-downloads"></a> | ||
| 90 | <span class="emphasis"><em> | ||
| 91 | <a class="ulink" href="http://downloads.yoctoproject.org/releases/" target="_self">Index of /releases:</a> | ||
| 92 | </em></span> | ||
| 93 | This is an index of releases such as | ||
| 94 | the <span class="trademark">Eclipse</span>™ | ||
| 95 | Yocto Plug-in, miscellaneous support, Poky, Pseudo, installers | ||
| 96 | for cross-development toolchains, and all released versions of | ||
| 97 | Yocto Project in the form of images or tarballs. | ||
| 98 | Downloading and extracting these files does not produce a local | ||
| 99 | copy of the Git repository but rather a snapshot of a | ||
| 100 | particular release or image.</p> | ||
| 101 | <p> | ||
| 102 | </p> | ||
| 103 | <table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="540"><tr style="height: 315px"><td align="center"><img src="figures/index-downloads.png" align="middle" height="315"></td></tr></table> | ||
| 104 | <p> | ||
| 105 | For steps on how to view and access these files, see the | ||
| 106 | "<a class="link" href="../dev-manual/accessing-index-of-releases.html" target="_self">Accessing Index of Releases</a>" | ||
| 107 | section in the Yocto Project Development Tasks Manual. | ||
| 108 | </p> | ||
| 109 | </li> | ||
| 110 | <li class="listitem"> | ||
| 111 | <p><a name="downloads-page"></a> | ||
| 112 | <span class="emphasis"><em>"Downloads" page for the | ||
| 113 | <a class="ulink" href="http://www.yoctoproject.org" target="_self">Yocto Project Website</a>: | ||
| 114 | </em></span></p> | ||
| 115 | <p class="writernotes">This section will change due to | ||
| 116 | reworking of the YP Website.</p> | ||
| 117 | <p>The Yocto Project website includes a "Downloads" tab | ||
| 118 | that allows you to download any Yocto Project | ||
| 119 | release and Board Support Package (BSP) in tarball form. | ||
| 120 | The tarballs are similar to those found in the | ||
| 121 | <a class="ulink" href="http://downloads.yoctoproject.org/releases/" target="_self">Index of /releases:</a> area.</p> | ||
| 122 | <p> | ||
| 123 | </p> | ||
| 124 | <table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="540"><tr style="height: 360px"><td align="center"><img src="figures/yp-download.png" align="middle" width="540"></td></tr></table> | ||
| 125 | <p> | ||
| 126 | For steps on how to use the "Downloads" page, see the | ||
| 127 | "<a class="link" href="../dev-manual/using-the-downloads-page.html" target="_self">Using the Downloads Page</a>" | ||
| 128 | section in the Yocto Project Development Tasks Manual. | ||
| 129 | </p> | ||
| 130 | </li> | ||
| 131 | </ul></div> | ||
| 132 | <p> | ||
| 133 | </p> | ||
| 134 | </div></body> | ||
| 135 | </html> | ||
diff --git a/documentation/getting-started/eclipse/html/getting-started/yp-intro.html b/documentation/getting-started/eclipse/html/getting-started/yp-intro.html new file mode 100644 index 0000000000..42ad0d3088 --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/yp-intro.html | |||
| @@ -0,0 +1,119 @@ | |||
| 1 | <html> | ||
| 2 | <head> | ||
| 3 | <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> | ||
| 4 | <title>2.1.Introduction</title> | ||
| 5 | <link rel="stylesheet" type="text/css" href="../book.css"> | ||
| 6 | <meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> | ||
| 7 | <link rel="home" href="index.html" title="Getting Started With Yocto Project"> | ||
| 8 | <link rel="up" href="overview-development-environment.html" title="Chapter2.The Yocto Project Development Environment"> | ||
| 9 | <link rel="prev" href="overview-development-environment.html" title="Chapter2.The Yocto Project Development Environment"> | ||
| 10 | <link rel="next" href="open-source-philosophy.html" title="2.2.Open Source Philosophy"> | ||
| 11 | </head> | ||
| 12 | <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="2.1.Introduction"> | ||
| 13 | <div class="titlepage"><div><div><h2 class="title" style="clear: both"> | ||
| 14 | <a name="yp-intro"></a>2.1.Introduction</h2></div></div></div> | ||
| 15 | <p> | ||
| 16 | The Yocto Project is an open-source collaboration project whose | ||
| 17 | focus is for developers of embedded Linux systems. | ||
| 18 | Among other things, the Yocto Project uses an | ||
| 19 | <a class="link" href="../ref-manual/build-system-term.html" target="_self">OpenEmbedded build system</a>. | ||
| 20 | The build system, which is based on the OpenEmbedded (OE) project and | ||
| 21 | uses the | ||
| 22 | <a class="link" href="../ref-manual/bitbake-term.html" target="_self">BitBake</a> tool, | ||
| 23 | constructs complete Linux images for architectures based on ARM, MIPS, | ||
| 24 | PowerPC, x86 and x86-64. | ||
| 25 | </p> | ||
| 26 | <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"> | ||
| 27 | <h3 class="title">Note</h3> | ||
| 28 | Historically, the OpenEmbedded build system, which is the | ||
| 29 | combination of BitBake and OE components, formed a reference | ||
| 30 | build host that was known as | ||
| 31 | "<a class="link" href="../ref-manual/poky.html" target="_self">Poky</a>" | ||
| 32 | (<span class="emphasis"><em>Pah</em></span>-kee). | ||
| 33 | The term "Poky", as used throughout the Yocto Project Documentation | ||
| 34 | set, can have different meanings. | ||
| 35 | </div> | ||
| 36 | <p> | ||
| 37 | The Yocto Project provides various ancillary tools for the embedded | ||
| 38 | developer and also features the Sato reference User Interface, which | ||
| 39 | is optimized for stylus-driven, low-resolution screens. | ||
| 40 | </p> | ||
| 41 | <div class="mediaobject" align="center"><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="720"><tr><td align="center"><img src="figures/YP-flow-diagram.png" align="middle" width="720"></td></tr></table></div> | ||
| 42 | <p> | ||
| 43 | Here are some highlights for the Yocto Project: | ||
| 44 | </p> | ||
| 45 | <div class="itemizedlist"><ul class="itemizedlist" type="disc"> | ||
| 46 | <li class="listitem"><p> | ||
| 47 | Provides a recent Linux kernel along with a set of system | ||
| 48 | commands and libraries suitable for the embedded | ||
| 49 | environment. | ||
| 50 | </p></li> | ||
| 51 | <li class="listitem"><p> | ||
| 52 | Makes available system components such as X11, GTK+, Qt, | ||
| 53 | Clutter, and SDL (among others) so you can create a rich user | ||
| 54 | experience on devices that have display hardware. | ||
| 55 | For devices that do not have a display or where you wish to | ||
| 56 | use alternative UI frameworks, these components need not be | ||
| 57 | installed. | ||
| 58 | </p></li> | ||
| 59 | <li class="listitem"><p> | ||
| 60 | Creates a focused and stable core compatible with the | ||
| 61 | OpenEmbedded project with which you can easily and reliably | ||
| 62 | build and develop. | ||
| 63 | </p></li> | ||
| 64 | <li class="listitem"><p> | ||
| 65 | Fully supports a wide range of hardware and device emulation | ||
| 66 | through the Quick EMUlator (QEMU). | ||
| 67 | </p></li> | ||
| 68 | <li class="listitem"><p> | ||
| 69 | Provides a layer mechanism that allows you to easily extend | ||
| 70 | the system, make customizations, and keep them organized. | ||
| 71 | </p></li> | ||
| 72 | </ul></div> | ||
| 73 | <p> | ||
| 74 | You can use the Yocto Project to generate images for many kinds | ||
| 75 | of devices. | ||
| 76 | As mentioned earlier, the Yocto Project supports creation of | ||
| 77 | reference images that you can boot within and emulate using QEMU. | ||
| 78 | The standard example machines target QEMU full-system | ||
| 79 | emulation for 32-bit and 64-bit variants of x86, ARM, MIPS, and | ||
| 80 | PowerPC architectures. | ||
| 81 | Beyond emulation, you can use the layer mechanism to extend | ||
| 82 | support to just about any platform that Linux can run on and that | ||
| 83 | a toolchain can target. | ||
| 84 | </p> | ||
| 85 | <p> | ||
| 86 | Another Yocto Project feature is the Sato reference User | ||
| 87 | Interface. | ||
| 88 | This optional UI that is based on GTK+ is intended for devices with | ||
| 89 | restricted screen sizes and is included as part of the | ||
| 90 | OpenEmbedded Core layer so that developers can test parts of the | ||
| 91 | software stack. | ||
| 92 | </p> | ||
| 93 | <p> | ||
| 94 | While the Yocto Project does not provide a strict testing framework, | ||
| 95 | it does provide or generate for you artifacts that let you perform | ||
| 96 | target-level and emulated testing and debugging. | ||
| 97 | Additionally, if you are an | ||
| 98 | <span class="trademark">Eclipse</span>™ IDE user, you can | ||
| 99 | install an Eclipse Yocto Plug-in to allow you to develop within that | ||
| 100 | familiar environment. | ||
| 101 | </p> | ||
| 102 | <p> | ||
| 103 | By default, using the Yocto Project to build an image creates a Poky | ||
| 104 | distribution. | ||
| 105 | However, you can create your own distribution by providing key | ||
| 106 | <a class="link" href="../ref-manual/metadata.html" target="_self">Metadata</a>. | ||
| 107 | A good example is Angstrom, which has had a distribution | ||
| 108 | based on the Yocto Project since its inception. | ||
| 109 | Other examples include commercial distributions like | ||
| 110 | <a class="ulink" href="https://www.yoctoproject.org/organization/wind-river-systems" target="_self">Wind River Linux</a>, | ||
| 111 | <a class="ulink" href="https://www.yoctoproject.org/organization/mentor-graphics" target="_self">Mentor Embedded Linux</a>, | ||
| 112 | <a class="ulink" href="https://www.yoctoproject.org/organization/enea-ab" target="_self">ENEA Linux</a> | ||
| 113 | and <a class="ulink" href="https://www.yoctoproject.org/ecosystem/member-organizations" target="_self">others</a>. | ||
| 114 | See the "<a class="link" href="../dev-manual/creating-your-own-distribution.html" target="_self">Creating Your Own Distribution</a>" | ||
| 115 | section in the Yocto Project Development Tasks Manual for more | ||
| 116 | information. | ||
| 117 | </p> | ||
| 118 | </div></body> | ||
| 119 | </html> | ||
diff --git a/documentation/getting-started/figures/YP-flow-diagram.png b/documentation/getting-started/figures/YP-flow-diagram.png new file mode 100644 index 0000000000..8264410504 --- /dev/null +++ b/documentation/getting-started/figures/YP-flow-diagram.png | |||
| Binary files differ | |||
diff --git a/documentation/getting-started/figures/analysis-for-package-splitting.png b/documentation/getting-started/figures/analysis-for-package-splitting.png new file mode 100644 index 0000000000..04f2794ea9 --- /dev/null +++ b/documentation/getting-started/figures/analysis-for-package-splitting.png | |||
| Binary files differ | |||
diff --git a/documentation/getting-started/figures/configuration-compile-autoreconf.png b/documentation/getting-started/figures/configuration-compile-autoreconf.png new file mode 100644 index 0000000000..a07464f04c --- /dev/null +++ b/documentation/getting-started/figures/configuration-compile-autoreconf.png | |||
| Binary files differ | |||
diff --git a/documentation/getting-started/figures/cross-development-toolchains.png b/documentation/getting-started/figures/cross-development-toolchains.png new file mode 100644 index 0000000000..d36670a198 --- /dev/null +++ b/documentation/getting-started/figures/cross-development-toolchains.png | |||
| Binary files differ | |||
diff --git a/documentation/getting-started/figures/getting-started-title.png b/documentation/getting-started/figures/getting-started-title.png new file mode 100644 index 0000000000..f38b078ab7 --- /dev/null +++ b/documentation/getting-started/figures/getting-started-title.png | |||
| Binary files differ | |||
diff --git a/documentation/getting-started/figures/git-workflow.png b/documentation/getting-started/figures/git-workflow.png new file mode 100644 index 0000000000..e401330a12 --- /dev/null +++ b/documentation/getting-started/figures/git-workflow.png | |||
| Binary files differ | |||
diff --git a/documentation/getting-started/figures/image-generation.png b/documentation/getting-started/figures/image-generation.png new file mode 100644 index 0000000000..71a48dc6f4 --- /dev/null +++ b/documentation/getting-started/figures/image-generation.png | |||
| Binary files differ | |||
diff --git a/documentation/getting-started/figures/images.png b/documentation/getting-started/figures/images.png new file mode 100644 index 0000000000..d99eac1fbf --- /dev/null +++ b/documentation/getting-started/figures/images.png | |||
| Binary files differ | |||
diff --git a/documentation/getting-started/figures/index-downloads.png b/documentation/getting-started/figures/index-downloads.png new file mode 100644 index 0000000000..96303b8781 --- /dev/null +++ b/documentation/getting-started/figures/index-downloads.png | |||
| Binary files differ | |||
diff --git a/documentation/getting-started/figures/layer-input.png b/documentation/getting-started/figures/layer-input.png new file mode 100644 index 0000000000..0a4f2e74f3 --- /dev/null +++ b/documentation/getting-started/figures/layer-input.png | |||
| Binary files differ | |||
diff --git a/documentation/getting-started/figures/package-feeds.png b/documentation/getting-started/figures/package-feeds.png new file mode 100644 index 0000000000..37c9c32506 --- /dev/null +++ b/documentation/getting-started/figures/package-feeds.png | |||
| Binary files differ | |||
diff --git a/documentation/getting-started/figures/patching.png b/documentation/getting-started/figures/patching.png new file mode 100644 index 0000000000..8ecd018502 --- /dev/null +++ b/documentation/getting-started/figures/patching.png | |||
| Binary files differ | |||
diff --git a/documentation/getting-started/figures/sdk-generation.png b/documentation/getting-started/figures/sdk-generation.png new file mode 100755 index 0000000000..adbe1f4acf --- /dev/null +++ b/documentation/getting-started/figures/sdk-generation.png | |||
| Binary files differ | |||
diff --git a/documentation/getting-started/figures/sdk.png b/documentation/getting-started/figures/sdk.png new file mode 100644 index 0000000000..5c36b7548b --- /dev/null +++ b/documentation/getting-started/figures/sdk.png | |||
| Binary files differ | |||
diff --git a/documentation/getting-started/figures/source-fetching.png b/documentation/getting-started/figures/source-fetching.png new file mode 100644 index 0000000000..26aefb50c2 --- /dev/null +++ b/documentation/getting-started/figures/source-fetching.png | |||
| Binary files differ | |||
diff --git a/documentation/getting-started/figures/source-input.png b/documentation/getting-started/figures/source-input.png new file mode 100644 index 0000000000..f7515058ef --- /dev/null +++ b/documentation/getting-started/figures/source-input.png | |||
| Binary files differ | |||
diff --git a/documentation/getting-started/figures/source-repos.png b/documentation/getting-started/figures/source-repos.png new file mode 100644 index 0000000000..603300b6d2 --- /dev/null +++ b/documentation/getting-started/figures/source-repos.png | |||
| Binary files differ | |||
diff --git a/documentation/getting-started/figures/user-configuration.png b/documentation/getting-started/figures/user-configuration.png new file mode 100644 index 0000000000..c298401fc3 --- /dev/null +++ b/documentation/getting-started/figures/user-configuration.png | |||
| Binary files differ | |||
diff --git a/documentation/getting-started/figures/yocto-environment-ref.png b/documentation/getting-started/figures/yocto-environment-ref.png new file mode 100644 index 0000000000..650c6c8030 --- /dev/null +++ b/documentation/getting-started/figures/yocto-environment-ref.png | |||
| Binary files differ | |||
diff --git a/documentation/getting-started/figures/yp-download.png b/documentation/getting-started/figures/yp-download.png new file mode 100644 index 0000000000..5770be6883 --- /dev/null +++ b/documentation/getting-started/figures/yp-download.png | |||
| Binary files differ | |||
diff --git a/documentation/getting-started/getting-started-concepts.xml b/documentation/getting-started/getting-started-concepts.xml new file mode 100644 index 0000000000..59741d2e35 --- /dev/null +++ b/documentation/getting-started/getting-started-concepts.xml | |||
| @@ -0,0 +1,1929 @@ | |||
| 1 | <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" | ||
| 2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" | ||
| 3 | [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > | ||
| 4 | |||
| 5 | <chapter id='overview-concepts'> | ||
| 6 | <title>Yocto Project Concepts</title> | ||
| 7 | |||
| 8 | <para> | ||
| 9 | This chapter describes concepts for various areas of the Yocto Project. | ||
| 10 | Currently, topics include Yocto Project components, cross-development | ||
| 11 | generation, shared state (sstate) cache, runtime dependencies, | ||
| 12 | Pseudo and Fakeroot, x32 psABI, Wayland support, and Licenses. | ||
| 13 | </para> | ||
| 14 | |||
| 15 | <section id='yocto-project-components'> | ||
| 16 | <title>Yocto Project Components</title> | ||
| 17 | |||
| 18 | <para> | ||
| 19 | The | ||
| 20 | <ulink url='&YOCTO_DOCS_REF_URL;#bitbake-term'>BitBake</ulink> | ||
| 21 | task executor together with various types of configuration files | ||
| 22 | form the OpenEmbedded Core. | ||
| 23 | This section overviews these components by describing their use and | ||
| 24 | how they interact. | ||
| 25 | </para> | ||
| 26 | |||
| 27 | <para> | ||
| 28 | BitBake handles the parsing and execution of the data files. | ||
| 29 | The data itself is of various types: | ||
| 30 | <itemizedlist> | ||
| 31 | <listitem><para> | ||
| 32 | <emphasis>Recipes:</emphasis> | ||
| 33 | Provides details about particular pieces of software. | ||
| 34 | </para></listitem> | ||
| 35 | <listitem><para> | ||
| 36 | <emphasis>Class Data:</emphasis> | ||
| 37 | Abstracts common build information (e.g. how to build a | ||
| 38 | Linux kernel). | ||
| 39 | </para></listitem> | ||
| 40 | <listitem><para> | ||
| 41 | <emphasis>Configuration Data:</emphasis> | ||
| 42 | Defines machine-specific settings, policy decisions, and | ||
| 43 | so forth. | ||
| 44 | Configuration data acts as the glue to bind everything | ||
| 45 | together. | ||
| 46 | </para></listitem> | ||
| 47 | </itemizedlist> | ||
| 48 | </para> | ||
| 49 | |||
| 50 | <para> | ||
| 51 | BitBake knows how to combine multiple data sources together and | ||
| 52 | refers to each data source as a layer. | ||
| 53 | For information on layers, see the | ||
| 54 | "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>" | ||
| 55 | section of the Yocto Project Development Tasks Manual. | ||
| 56 | </para> | ||
| 57 | |||
| 58 | <para> | ||
| 59 | Following are some brief details on these core components. | ||
| 60 | For additional information on how these components interact during | ||
| 61 | a build, see the | ||
| 62 | "<link linkend='development-concepts'>Development Concepts</link>" | ||
| 63 | section. | ||
| 64 | </para> | ||
| 65 | |||
| 66 | <section id='usingpoky-components-bitbake'> | ||
| 67 | <title>BitBake</title> | ||
| 68 | |||
| 69 | <para> | ||
| 70 | BitBake is the tool at the heart of the OpenEmbedded build | ||
| 71 | system and is responsible for parsing the | ||
| 72 | <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink>, | ||
| 73 | generating a list of tasks from it, and then executing those | ||
| 74 | tasks. | ||
| 75 | </para> | ||
| 76 | |||
| 77 | <para> | ||
| 78 | This section briefly introduces BitBake. | ||
| 79 | If you want more information on BitBake, see the | ||
| 80 | <ulink url='&YOCTO_DOCS_BB_URL;#bitbake-user-manual'>BitBake User Manual</ulink>. | ||
| 81 | </para> | ||
| 82 | |||
| 83 | <para> | ||
| 84 | To see a list of the options BitBake supports, use either of | ||
| 85 | the following commands: | ||
| 86 | <literallayout class='monospaced'> | ||
| 87 | $ bitbake -h | ||
| 88 | $ bitbake --help | ||
| 89 | </literallayout> | ||
| 90 | </para> | ||
| 91 | |||
| 92 | <para> | ||
| 93 | The most common usage for BitBake is | ||
| 94 | <filename>bitbake <replaceable>packagename</replaceable></filename>, | ||
| 95 | where <filename>packagename</filename> is the name of the | ||
| 96 | package you want to build (referred to as the "target" in this | ||
| 97 | manual). | ||
| 98 | The target often equates to the first part of a recipe's | ||
| 99 | filename (e.g. "foo" for a recipe named | ||
| 100 | <filename>foo_1.3.0-r0.bb</filename>). | ||
| 101 | So, to process the | ||
| 102 | <filename>matchbox-desktop_1.2.3.bb</filename> recipe file, you | ||
| 103 | might type the following: | ||
| 104 | <literallayout class='monospaced'> | ||
| 105 | $ bitbake matchbox-desktop | ||
| 106 | </literallayout> | ||
| 107 | Several different versions of | ||
| 108 | <filename>matchbox-desktop</filename> might exist. | ||
| 109 | BitBake chooses the one selected by the distribution | ||
| 110 | configuration. | ||
| 111 | You can get more details about how BitBake chooses between | ||
| 112 | different target versions and providers in the | ||
| 113 | "<ulink url='&YOCTO_DOCS_BB_URL;#bb-bitbake-preferences'>Preferences</ulink>" | ||
| 114 | section of the BitBake User Manual. | ||
| 115 | </para> | ||
| 116 | |||
| 117 | <para> | ||
| 118 | BitBake also tries to execute any dependent tasks first. | ||
| 119 | So for example, before building | ||
| 120 | <filename>matchbox-desktop</filename>, BitBake would build a | ||
| 121 | cross compiler and <filename>glibc</filename> if they had not | ||
| 122 | already been built. | ||
| 123 | </para> | ||
| 124 | |||
| 125 | <para> | ||
| 126 | A useful BitBake option to consider is the | ||
| 127 | <filename>-k</filename> or <filename>--continue</filename> | ||
| 128 | option. | ||
| 129 | This option instructs BitBake to try and continue processing | ||
| 130 | the job as long as possible even after encountering an error. | ||
| 131 | When an error occurs, the target that failed and those that | ||
| 132 | depend on it cannot be remade. | ||
| 133 | However, when you use this option other dependencies can | ||
| 134 | still be processed. | ||
| 135 | </para> | ||
| 136 | </section> | ||
| 137 | |||
| 138 | <section id='usingpoky-components-metadata'> | ||
| 139 | <title>Metadata (Recipes)</title> | ||
| 140 | |||
| 141 | <para> | ||
| 142 | Files that have the <filename>.bb</filename> suffix are | ||
| 143 | "recipes" files. | ||
| 144 | In general, a recipe contains information about a single piece | ||
| 145 | of software. | ||
| 146 | This information includes the location from which to download | ||
| 147 | the unaltered source, any source patches to be applied to that | ||
| 148 | source (if needed), which special configuration options to | ||
| 149 | apply, how to compile the source files, and how to package the | ||
| 150 | compiled output. | ||
| 151 | </para> | ||
| 152 | |||
| 153 | <para> | ||
| 154 | The term "package" is sometimes used to refer to recipes. | ||
| 155 | However, since the word "package" is used for the packaged | ||
| 156 | output from the OpenEmbedded build system (i.e. | ||
| 157 | <filename>.ipk</filename> or <filename>.deb</filename> files), | ||
| 158 | this document avoids using the term "package" when referring | ||
| 159 | to recipes. | ||
| 160 | </para> | ||
| 161 | </section> | ||
| 162 | |||
| 163 | <section id='metadata-virtual-providers'> | ||
| 164 | <title>Metadata (Virtual Providers)</title> | ||
| 165 | |||
| 166 | <para> | ||
| 167 | Prior to the build, if you know that several different recipes | ||
| 168 | provide the same functionality, you can use a virtual provider | ||
| 169 | (i.e. <filename>virtual/*</filename>) as a placeholder for the | ||
| 170 | actual provider. | ||
| 171 | The actual provider would be determined at build time. | ||
| 172 | In this case, you should add <filename>virtual/*</filename> | ||
| 173 | to | ||
| 174 | <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>, | ||
| 175 | rather than listing the specified provider. | ||
| 176 | You would select the actual provider by setting the | ||
| 177 | <ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER</filename></ulink> | ||
| 178 | variable (i.e. | ||
| 179 | <filename>PREFERRED_PROVIDER_virtual/*</filename>) | ||
| 180 | in the build's configuration file (e.g. | ||
| 181 | <filename>poky/build/conf/local.conf</filename>). | ||
| 182 | <note> | ||
| 183 | Any recipe that PROVIDES a <filename>virtual/*</filename> | ||
| 184 | item that is ultimately not selected through | ||
| 185 | <filename>PREFERRED_PROVIDER</filename> does not get built. | ||
| 186 | Preventing these recipes from building is usually the | ||
| 187 | desired behavior since this mechanism's purpose is to | ||
| 188 | select between mutually exclusive alternative providers. | ||
| 189 | </note> | ||
| 190 | </para> | ||
| 191 | |||
| 192 | <para> | ||
| 193 | The following lists specific examples of virtual providers: | ||
| 194 | <itemizedlist> | ||
| 195 | <listitem><para> | ||
| 196 | <filename>virtual/mesa</filename>: | ||
| 197 | Provides <filename>gbm.pc</filename>. | ||
| 198 | </para></listitem> | ||
| 199 | <listitem><para> | ||
| 200 | <filename>virtual/egl</filename>: | ||
| 201 | Provides <filename>egl.pc</filename> and possibly | ||
| 202 | <filename>wayland-egl.pc</filename>. | ||
| 203 | </para></listitem> | ||
| 204 | <listitem><para> | ||
| 205 | <filename>virtual/libgl</filename>: | ||
| 206 | Provides <filename>gl.pc</filename> (i.e. libGL). | ||
| 207 | </para></listitem> | ||
| 208 | <listitem><para> | ||
| 209 | <filename>virtual/libgles1</filename>: | ||
| 210 | Provides <filename>glesv1_cm.pc</filename> | ||
| 211 | (i.e. libGLESv1_CM). | ||
| 212 | </para></listitem> | ||
| 213 | <listitem><para> | ||
| 214 | <filename>virtual/libgles2</filename>: | ||
| 215 | Provides <filename>glesv2.pc</filename> | ||
| 216 | (i.e. libGLESv2). | ||
| 217 | </para></listitem> | ||
| 218 | </itemizedlist> | ||
| 219 | </para> | ||
| 220 | </section> | ||
| 221 | |||
| 222 | <section id='usingpoky-components-classes'> | ||
| 223 | <title>Classes</title> | ||
| 224 | |||
| 225 | <para> | ||
| 226 | Class files (<filename>.bbclass</filename>) contain information | ||
| 227 | that is useful to share between | ||
| 228 | <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink> | ||
| 229 | files. | ||
| 230 | An example is the | ||
| 231 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-autotools'><filename>autotools</filename></ulink> | ||
| 232 | class, which contains common settings for any application that | ||
| 233 | Autotools uses. | ||
| 234 | The | ||
| 235 | "<ulink url='&YOCTO_DOCS_REF_URL;#ref-classes'>Classes</ulink>" | ||
| 236 | chapter in the Yocto Project Reference Manual provides | ||
| 237 | details about classes and how to use them. | ||
| 238 | </para> | ||
| 239 | </section> | ||
| 240 | |||
| 241 | <section id='usingpoky-components-configuration'> | ||
| 242 | <title>Configuration</title> | ||
| 243 | |||
| 244 | <para> | ||
| 245 | The configuration files (<filename>.conf</filename>) define | ||
| 246 | various configuration variables that govern the OpenEmbedded | ||
| 247 | build process. | ||
| 248 | These files fall into several areas that define machine | ||
| 249 | configuration options, distribution configuration options, | ||
| 250 | compiler tuning options, general common configuration options, | ||
| 251 | and user configuration options in | ||
| 252 | <filename>local.conf</filename>, which is found in the | ||
| 253 | <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>. | ||
| 254 | </para> | ||
| 255 | </section> | ||
| 256 | </section> | ||
| 257 | |||
| 258 | <section id="cross-development-toolchain-generation"> | ||
| 259 | <title>Cross-Development Toolchain Generation</title> | ||
| 260 | |||
| 261 | <para> | ||
| 262 | The Yocto Project does most of the work for you when it comes to | ||
| 263 | creating | ||
| 264 | <ulink url='&YOCTO_DOCS_REF_URL;#cross-development-toolchain'>cross-development toolchains</ulink>. | ||
| 265 | This section provides some technical background on how | ||
| 266 | cross-development toolchains are created and used. | ||
| 267 | For more information on toolchains, you can also see the | ||
| 268 | <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink> | ||
| 269 | manual. | ||
| 270 | </para> | ||
| 271 | |||
| 272 | <para> | ||
| 273 | In the Yocto Project development environment, cross-development | ||
| 274 | toolchains are used to build the image and applications that run | ||
| 275 | on the target hardware. | ||
| 276 | With just a few commands, the OpenEmbedded build system creates | ||
| 277 | these necessary toolchains for you. | ||
| 278 | </para> | ||
| 279 | |||
| 280 | <para> | ||
| 281 | The following figure shows a high-level build environment regarding | ||
| 282 | toolchain construction and use. | ||
| 283 | </para> | ||
| 284 | |||
| 285 | <para> | ||
| 286 | <imagedata fileref="figures/cross-development-toolchains.png" width="8in" depth="6in" align="center" /> | ||
| 287 | </para> | ||
| 288 | |||
| 289 | <para> | ||
| 290 | Most of the work occurs on the Build Host. | ||
| 291 | This is the machine used to build images and generally work within the | ||
| 292 | the Yocto Project environment. | ||
| 293 | When you run BitBake to create an image, the OpenEmbedded build system | ||
| 294 | uses the host <filename>gcc</filename> compiler to bootstrap a | ||
| 295 | cross-compiler named <filename>gcc-cross</filename>. | ||
| 296 | The <filename>gcc-cross</filename> compiler is what BitBake uses to | ||
| 297 | compile source files when creating the target image. | ||
| 298 | You can think of <filename>gcc-cross</filename> simply as an | ||
| 299 | automatically generated cross-compiler that is used internally within | ||
| 300 | BitBake only. | ||
| 301 | <note> | ||
| 302 | The extensible SDK does not use | ||
| 303 | <filename>gcc-cross-canadian</filename> since this SDK | ||
| 304 | ships a copy of the OpenEmbedded build system and the sysroot | ||
| 305 | within it contains <filename>gcc-cross</filename>. | ||
| 306 | </note> | ||
| 307 | </para> | ||
| 308 | |||
| 309 | <para> | ||
| 310 | The chain of events that occurs when <filename>gcc-cross</filename> is | ||
| 311 | bootstrapped is as follows: | ||
| 312 | <literallayout class='monospaced'> | ||
| 313 | gcc -> binutils-cross -> gcc-cross-initial -> linux-libc-headers -> glibc-initial -> glibc -> gcc-cross -> gcc-runtime | ||
| 314 | </literallayout> | ||
| 315 | <itemizedlist> | ||
| 316 | <listitem><para> | ||
| 317 | <filename>gcc</filename>: | ||
| 318 | The build host's GNU Compiler Collection (GCC). | ||
| 319 | </para></listitem> | ||
| 320 | <listitem><para> | ||
| 321 | <filename>binutils-cross</filename>: | ||
| 322 | The bare minimum binary utilities needed in order to run | ||
| 323 | the <filename>gcc-cross-initial</filename> phase of the | ||
| 324 | bootstrap operation. | ||
| 325 | </para></listitem> | ||
| 326 | <listitem><para> | ||
| 327 | <filename>gcc-cross-initial</filename>: | ||
| 328 | An early stage of the bootstrap process for creating | ||
| 329 | the cross-compiler. | ||
| 330 | This stage builds enough of the <filename>gcc-cross</filename>, | ||
| 331 | the C library, and other pieces needed to finish building the | ||
| 332 | final cross-compiler in later stages. | ||
| 333 | This tool is a "native" package (i.e. it is designed to run on | ||
| 334 | the build host). | ||
| 335 | </para></listitem> | ||
| 336 | <listitem><para> | ||
| 337 | <filename>linux-libc-headers</filename>: | ||
| 338 | Headers needed for the cross-compiler. | ||
| 339 | </para></listitem> | ||
| 340 | <listitem><para> | ||
| 341 | <filename>glibc-initial</filename>: | ||
| 342 | An initial version of the Embedded GLIBC needed to bootstrap | ||
| 343 | <filename>glibc</filename>. | ||
| 344 | </para></listitem> | ||
| 345 | <listitem><para> | ||
| 346 | <filename>gcc-cross</filename>: | ||
| 347 | The final stage of the bootstrap process for the | ||
| 348 | cross-compiler. | ||
| 349 | This stage results in the actual cross-compiler that | ||
| 350 | BitBake uses when it builds an image for a targeted | ||
| 351 | device. | ||
| 352 | <note> | ||
| 353 | If you are replacing this cross compiler toolchain | ||
| 354 | with a custom version, you must replace | ||
| 355 | <filename>gcc-cross</filename>. | ||
| 356 | </note> | ||
| 357 | This tool is also a "native" package (i.e. it is | ||
| 358 | designed to run on the build host). | ||
| 359 | </para></listitem> | ||
| 360 | <listitem><para> | ||
| 361 | <filename>gcc-runtime</filename>: | ||
| 362 | Runtime libraries resulting from the toolchain bootstrapping | ||
| 363 | process. | ||
| 364 | This tool produces a binary that consists of the | ||
| 365 | runtime libraries need for the targeted device. | ||
| 366 | </para></listitem> | ||
| 367 | </itemizedlist> | ||
| 368 | </para> | ||
| 369 | |||
| 370 | <para> | ||
| 371 | You can use the OpenEmbedded build system to build an installer for | ||
| 372 | the relocatable SDK used to develop applications. | ||
| 373 | When you run the installer, it installs the toolchain, which contains | ||
| 374 | the development tools (e.g., the | ||
| 375 | <filename>gcc-cross-canadian</filename>), | ||
| 376 | <filename>binutils-cross-canadian</filename>, and other | ||
| 377 | <filename>nativesdk-*</filename> tools, | ||
| 378 | which are tools native to the SDK (i.e. native to | ||
| 379 | <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_ARCH'><filename>SDK_ARCH</filename></ulink>), | ||
| 380 | you need to cross-compile and test your software. | ||
| 381 | The figure shows the commands you use to easily build out this | ||
| 382 | toolchain. | ||
| 383 | This cross-development toolchain is built to execute on the | ||
| 384 | <ulink url='&YOCTO_DOCS_REF_URL;#var-SDKMACHINE'><filename>SDKMACHINE</filename></ulink>, | ||
| 385 | which might or might not be the same | ||
| 386 | machine as the Build Host. | ||
| 387 | <note> | ||
| 388 | If your target architecture is supported by the Yocto Project, | ||
| 389 | you can take advantage of pre-built images that ship with the | ||
| 390 | Yocto Project and already contain cross-development toolchain | ||
| 391 | installers. | ||
| 392 | </note> | ||
| 393 | </para> | ||
| 394 | |||
| 395 | <para> | ||
| 396 | Here is the bootstrap process for the relocatable toolchain: | ||
| 397 | <literallayout class='monospaced'> | ||
| 398 | gcc -> binutils-crosssdk -> gcc-crosssdk-initial -> linux-libc-headers -> | ||
| 399 | glibc-initial -> nativesdk-glibc -> gcc-crosssdk -> gcc-cross-canadian | ||
| 400 | </literallayout> | ||
| 401 | <itemizedlist> | ||
| 402 | <listitem><para> | ||
| 403 | <filename>gcc</filename>: | ||
| 404 | The build host's GNU Compiler Collection (GCC). | ||
| 405 | </para></listitem> | ||
| 406 | <listitem><para> | ||
| 407 | <filename>binutils-crosssdk</filename>: | ||
| 408 | The bare minimum binary utilities needed in order to run | ||
| 409 | the <filename>gcc-crosssdk-initial</filename> phase of the | ||
| 410 | bootstrap operation. | ||
| 411 | </para></listitem> | ||
| 412 | <listitem><para> | ||
| 413 | <filename>gcc-crosssdk-initial</filename>: | ||
| 414 | An early stage of the bootstrap process for creating | ||
| 415 | the cross-compiler. | ||
| 416 | This stage builds enough of the | ||
| 417 | <filename>gcc-crosssdk</filename> and supporting pieces so that | ||
| 418 | the final stage of the bootstrap process can produce the | ||
| 419 | finished cross-compiler. | ||
| 420 | This tool is a "native" binary that runs on the build host. | ||
| 421 | </para></listitem> | ||
| 422 | <listitem><para> | ||
| 423 | <filename>linux-libc-headers</filename>: | ||
| 424 | Headers needed for the cross-compiler. | ||
| 425 | </para></listitem> | ||
| 426 | <listitem><para> | ||
| 427 | <filename>glibc-initial</filename>: | ||
| 428 | An initial version of the Embedded GLIBC needed to bootstrap | ||
| 429 | <filename>nativesdk-glibc</filename>. | ||
| 430 | </para></listitem> | ||
| 431 | <listitem><para> | ||
| 432 | <filename>nativesdk-glibc</filename>: | ||
| 433 | The Embedded GLIBC needed to bootstrap the | ||
| 434 | <filename>gcc-crosssdk</filename>. | ||
| 435 | </para></listitem> | ||
| 436 | <listitem><para> | ||
| 437 | <filename>gcc-crosssdk</filename>: | ||
| 438 | The final stage of the bootstrap process for the | ||
| 439 | relocatable cross-compiler. | ||
| 440 | The <filename>gcc-crosssdk</filename> is a transitory compiler | ||
| 441 | and never leaves the build host. | ||
| 442 | Its purpose is to help in the bootstrap process to create the | ||
| 443 | eventual relocatable <filename>gcc-cross-canadian</filename> | ||
| 444 | compiler, which is relocatable. | ||
| 445 | This tool is also a "native" package (i.e. it is | ||
| 446 | designed to run on the build host). | ||
| 447 | </para></listitem> | ||
| 448 | <listitem><para> | ||
| 449 | <filename>gcc-cross-canadian</filename>: | ||
| 450 | The final relocatable cross-compiler. | ||
| 451 | When run on the | ||
| 452 | <ulink url='&YOCTO_DOCS_REF_URL;#var-SDKMACHINE'><filename>SDKMACHINE</filename></ulink>, | ||
| 453 | this tool | ||
| 454 | produces executable code that runs on the target device. | ||
| 455 | Only one cross-canadian compiler is produced per architecture | ||
| 456 | since they can be targeted at different processor optimizations | ||
| 457 | using configurations passed to the compiler through the | ||
| 458 | compile commands. | ||
| 459 | This circumvents the need for multiple compilers and thus | ||
| 460 | reduces the size of the toolchains. | ||
| 461 | </para></listitem> | ||
| 462 | </itemizedlist> | ||
| 463 | </para> | ||
| 464 | |||
| 465 | <note> | ||
| 466 | For information on advantages gained when building a | ||
| 467 | cross-development toolchain installer, see the | ||
| 468 | "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-building-an-sdk-installer'>Building an SDK Installer</ulink>" | ||
| 469 | section in the Yocto Project Application Development and the | ||
| 470 | Extensible Software Development Kit (eSDK) manual. | ||
| 471 | </note> | ||
| 472 | </section> | ||
| 473 | |||
| 474 | |||
| 475 | |||
| 476 | |||
| 477 | <section id="shared-state-cache"> | ||
| 478 | <title>Shared State Cache</title> | ||
| 479 | |||
| 480 | <para> | ||
| 481 | By design, the OpenEmbedded build system builds everything from | ||
| 482 | scratch unless BitBake can determine that parts do not need to be | ||
| 483 | rebuilt. | ||
| 484 | Fundamentally, building from scratch is attractive as it means all | ||
| 485 | parts are built fresh and there is no possibility of stale data | ||
| 486 | causing problems. | ||
| 487 | When developers hit problems, they typically default back to | ||
| 488 | building from scratch so they know the state of things from the | ||
| 489 | start. | ||
| 490 | </para> | ||
| 491 | |||
| 492 | <para> | ||
| 493 | Building an image from scratch is both an advantage and a | ||
| 494 | disadvantage to the process. | ||
| 495 | As mentioned in the previous paragraph, building from scratch | ||
| 496 | ensures that everything is current and starts from a known state. | ||
| 497 | However, building from scratch also takes much longer as it | ||
| 498 | generally means rebuilding things that do not necessarily need | ||
| 499 | to be rebuilt. | ||
| 500 | </para> | ||
| 501 | |||
| 502 | <para> | ||
| 503 | The Yocto Project implements shared state code that supports | ||
| 504 | incremental builds. | ||
| 505 | The implementation of the shared state code answers the following | ||
| 506 | questions that were fundamental roadblocks within the OpenEmbedded | ||
| 507 | incremental build support system: | ||
| 508 | <itemizedlist> | ||
| 509 | <listitem><para> | ||
| 510 | What pieces of the system have changed and what pieces have | ||
| 511 | not changed? | ||
| 512 | </para></listitem> | ||
| 513 | <listitem><para> | ||
| 514 | How are changed pieces of software removed and replaced? | ||
| 515 | </para></listitem> | ||
| 516 | <listitem><para> | ||
| 517 | How are pre-built components that do not need to be rebuilt | ||
| 518 | from scratch used when they are available? | ||
| 519 | </para></listitem> | ||
| 520 | </itemizedlist> | ||
| 521 | </para> | ||
| 522 | |||
| 523 | <para> | ||
| 524 | For the first question, the build system detects changes in the | ||
| 525 | "inputs" to a given task by creating a checksum (or signature) of | ||
| 526 | the task's inputs. | ||
| 527 | If the checksum changes, the system assumes the inputs have changed | ||
| 528 | and the task needs to be rerun. | ||
| 529 | For the second question, the shared state (sstate) code tracks | ||
| 530 | which tasks add which output to the build process. | ||
| 531 | This means the output from a given task can be removed, upgraded | ||
| 532 | or otherwise manipulated. | ||
| 533 | The third question is partly addressed by the solution for the | ||
| 534 | second question assuming the build system can fetch the sstate | ||
| 535 | objects from remote locations and install them if they are deemed | ||
| 536 | to be valid. | ||
| 537 | <note> | ||
| 538 | The OpenEmbedded build system does not maintain | ||
| 539 | <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink> | ||
| 540 | information as part of the shared state packages. | ||
| 541 | Consequently, considerations exist that affect maintaining | ||
| 542 | shared state feeds. | ||
| 543 | For information on how the OpenEmbedded build system | ||
| 544 | works with packages and can track incrementing | ||
| 545 | <filename>PR</filename> information, see the | ||
| 546 | "<ulink url='&YOCTO_DOCS_DEV_URL;#automatically-incrementing-a-binary-package-revision-number'>Automatically Incrementing a Binary Package Revision Number</ulink>" | ||
| 547 | section in the Yocto Project Development Tasks Manual. | ||
| 548 | </note> | ||
| 549 | </para> | ||
| 550 | |||
| 551 | <para> | ||
| 552 | The rest of this section goes into detail about the overall | ||
| 553 | incremental build architecture, the checksums (signatures), shared | ||
| 554 | state, and some tips and tricks. | ||
| 555 | </para> | ||
| 556 | |||
| 557 | <section id='overall-architecture'> | ||
| 558 | <title>Overall Architecture</title> | ||
| 559 | |||
| 560 | <para> | ||
| 561 | When determining what parts of the system need to be built, | ||
| 562 | BitBake works on a per-task basis rather than a per-recipe | ||
| 563 | basis. | ||
| 564 | You might wonder why using a per-task basis is preferred over | ||
| 565 | a per-recipe basis. | ||
| 566 | To help explain, consider having the IPK packaging backend | ||
| 567 | enabled and then switching to DEB. | ||
| 568 | In this case, the | ||
| 569 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink> | ||
| 570 | and | ||
| 571 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package'><filename>do_package</filename></ulink> | ||
| 572 | task outputs are still valid. | ||
| 573 | However, with a per-recipe approach, the build would not | ||
| 574 | include the <filename>.deb</filename> files. | ||
| 575 | Consequently, you would have to invalidate the whole build and | ||
| 576 | rerun it. | ||
| 577 | Rerunning everything is not the best solution. | ||
| 578 | Also, in this case, the core must be "taught" much about | ||
| 579 | specific tasks. | ||
| 580 | This methodology does not scale well and does not allow users | ||
| 581 | to easily add new tasks in layers or as external recipes | ||
| 582 | without touching the packaged-staging core. | ||
| 583 | </para> | ||
| 584 | </section> | ||
| 585 | |||
| 586 | <section id='overview-checksums'> | ||
| 587 | <title>Checksums (Signatures)</title> | ||
| 588 | |||
| 589 | <para> | ||
| 590 | The shared state code uses a checksum, which is a unique | ||
| 591 | signature of a task's inputs, to determine if a task needs to | ||
| 592 | be run again. | ||
| 593 | Because it is a change in a task's inputs that triggers a | ||
| 594 | rerun, the process needs to detect all the inputs to a given | ||
| 595 | task. | ||
| 596 | For shell tasks, this turns out to be fairly easy because | ||
| 597 | the build process generates a "run" shell script for each task | ||
| 598 | and it is possible to create a checksum that gives you a good | ||
| 599 | idea of when the task's data changes. | ||
| 600 | </para> | ||
| 601 | |||
| 602 | <para> | ||
| 603 | To complicate the problem, there are things that should not be | ||
| 604 | included in the checksum. | ||
| 605 | First, there is the actual specific build path of a given | ||
| 606 | task - the | ||
| 607 | <ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>. | ||
| 608 | It does not matter if the work directory changes because it | ||
| 609 | should not affect the output for target packages. | ||
| 610 | Also, the build process has the objective of making native | ||
| 611 | or cross packages relocatable. | ||
| 612 | <note> | ||
| 613 | Both native and cross packages run on the build host. | ||
| 614 | However, cross packages generate output for the target | ||
| 615 | architecture. | ||
| 616 | </note> | ||
| 617 | The checksum therefore needs to exclude | ||
| 618 | <filename>WORKDIR</filename>. | ||
| 619 | The simplistic approach for excluding the work directory is to | ||
| 620 | set <filename>WORKDIR</filename> to some fixed value and | ||
| 621 | create the checksum for the "run" script. | ||
| 622 | </para> | ||
| 623 | |||
| 624 | <para> | ||
| 625 | Another problem results from the "run" scripts containing | ||
| 626 | functions that might or might not get called. | ||
| 627 | The incremental build solution contains code that figures out | ||
| 628 | dependencies between shell functions. | ||
| 629 | This code is used to prune the "run" scripts down to the | ||
| 630 | minimum set, thereby alleviating this problem and making the | ||
| 631 | "run" scripts much more readable as a bonus. | ||
| 632 | </para> | ||
| 633 | |||
| 634 | <para> | ||
| 635 | So far we have solutions for shell scripts. | ||
| 636 | What about Python tasks? | ||
| 637 | The same approach applies even though these tasks are more | ||
| 638 | difficult. | ||
| 639 | The process needs to figure out what variables a Python | ||
| 640 | function accesses and what functions it calls. | ||
| 641 | Again, the incremental build solution contains code that first | ||
| 642 | figures out the variable and function dependencies, and then | ||
| 643 | creates a checksum for the data used as the input to the task. | ||
| 644 | </para> | ||
| 645 | |||
| 646 | <para> | ||
| 647 | Like the <filename>WORKDIR</filename> case, situations exist | ||
| 648 | where dependencies should be ignored. | ||
| 649 | For these cases, you can instruct the build process to | ||
| 650 | ignore a dependency by using a line like the following: | ||
| 651 | <literallayout class='monospaced'> | ||
| 652 | PACKAGE_ARCHS[vardepsexclude] = "MACHINE" | ||
| 653 | </literallayout> | ||
| 654 | This example ensures that the | ||
| 655 | <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_ARCHS'><filename>PACKAGE_ARCHS</filename></ulink> | ||
| 656 | variable does not depend on the value of | ||
| 657 | <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>, | ||
| 658 | even if it does reference it. | ||
| 659 | </para> | ||
| 660 | |||
| 661 | <para> | ||
| 662 | Equally, there are cases where we need to add dependencies | ||
| 663 | BitBake is not able to find. | ||
| 664 | You can accomplish this by using a line like the following: | ||
| 665 | <literallayout class='monospaced'> | ||
| 666 | PACKAGE_ARCHS[vardeps] = "MACHINE" | ||
| 667 | </literallayout> | ||
| 668 | This example explicitly adds the <filename>MACHINE</filename> | ||
| 669 | variable as a dependency for | ||
| 670 | <filename>PACKAGE_ARCHS</filename>. | ||
| 671 | </para> | ||
| 672 | |||
| 673 | <para> | ||
| 674 | Consider a case with in-line Python, for example, where | ||
| 675 | BitBake is not able to figure out dependencies. | ||
| 676 | When running in debug mode (i.e. using | ||
| 677 | <filename>-DDD</filename>), BitBake produces output when it | ||
| 678 | discovers something for which it cannot figure out dependencies. | ||
| 679 | The Yocto Project team has currently not managed to cover | ||
| 680 | those dependencies in detail and is aware of the need to fix | ||
| 681 | this situation. | ||
| 682 | </para> | ||
| 683 | |||
| 684 | <para> | ||
| 685 | Thus far, this section has limited discussion to the direct | ||
| 686 | inputs into a task. | ||
| 687 | Information based on direct inputs is referred to as the | ||
| 688 | "basehash" in the code. | ||
| 689 | However, there is still the question of a task's indirect | ||
| 690 | inputs - the things that were already built and present in the | ||
| 691 | <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>. | ||
| 692 | The checksum (or signature) for a particular task needs to add | ||
| 693 | the hashes of all the tasks on which the particular task | ||
| 694 | depends. | ||
| 695 | Choosing which dependencies to add is a policy decision. | ||
| 696 | However, the effect is to generate a master checksum that | ||
| 697 | combines the basehash and the hashes of the task's | ||
| 698 | dependencies. | ||
| 699 | </para> | ||
| 700 | |||
| 701 | <para> | ||
| 702 | At the code level, there are a variety of ways both the | ||
| 703 | basehash and the dependent task hashes can be influenced. | ||
| 704 | Within the BitBake configuration file, we can give BitBake | ||
| 705 | some extra information to help it construct the basehash. | ||
| 706 | The following statement effectively results in a list of | ||
| 707 | global variable dependency excludes - variables never | ||
| 708 | included in any checksum: | ||
| 709 | <literallayout class='monospaced'> | ||
| 710 | BB_HASHBASE_WHITELIST ?= "TMPDIR FILE PATH PWD BB_TASKHASH BBPATH DL_DIR \ | ||
| 711 | SSTATE_DIR THISDIR FILESEXTRAPATHS FILE_DIRNAME HOME LOGNAME SHELL TERM \ | ||
| 712 | USER FILESPATH STAGING_DIR_HOST STAGING_DIR_TARGET COREBASE PRSERV_HOST \ | ||
| 713 | PRSERV_DUMPDIR PRSERV_DUMPFILE PRSERV_LOCKDOWN PARALLEL_MAKE \ | ||
| 714 | CCACHE_DIR EXTERNAL_TOOLCHAIN CCACHE CCACHE_DISABLE LICENSE_PATH SDKPKGSUFFIX" | ||
| 715 | </literallayout> | ||
| 716 | The previous example excludes | ||
| 717 | <ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink> | ||
| 718 | since that variable is actually constructed as a path within | ||
| 719 | <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>, | ||
| 720 | which is on the whitelist. | ||
| 721 | </para> | ||
| 722 | |||
| 723 | <para> | ||
| 724 | The rules for deciding which hashes of dependent tasks to | ||
| 725 | include through dependency chains are more complex and are | ||
| 726 | generally accomplished with a Python function. | ||
| 727 | The code in <filename>meta/lib/oe/sstatesig.py</filename> shows | ||
| 728 | two examples of this and also illustrates how you can insert | ||
| 729 | your own policy into the system if so desired. | ||
| 730 | This file defines the two basic signature generators | ||
| 731 | <ulink url='&YOCTO_DOCS_REF_URL;#oe-core'>OE-Core</ulink> | ||
| 732 | uses: "OEBasic" and "OEBasicHash". | ||
| 733 | By default, there is a dummy "noop" signature handler enabled | ||
| 734 | in BitBake. | ||
| 735 | This means that behavior is unchanged from previous versions. | ||
| 736 | OE-Core uses the "OEBasicHash" signature handler by default | ||
| 737 | through this setting in the <filename>bitbake.conf</filename> | ||
| 738 | file: | ||
| 739 | <literallayout class='monospaced'> | ||
| 740 | BB_SIGNATURE_HANDLER ?= "OEBasicHash" | ||
| 741 | </literallayout> | ||
| 742 | The "OEBasicHash" <filename>BB_SIGNATURE_HANDLER</filename> | ||
| 743 | is the same as the "OEBasic" version but adds the task hash to | ||
| 744 | the stamp files. | ||
| 745 | This results in any | ||
| 746 | <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink> | ||
| 747 | change that changes the task hash, automatically | ||
| 748 | causing the task to be run again. | ||
| 749 | This removes the need to bump | ||
| 750 | <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink> | ||
| 751 | values, and changes to Metadata automatically ripple across | ||
| 752 | the build. | ||
| 753 | </para> | ||
| 754 | |||
| 755 | <para> | ||
| 756 | It is also worth noting that the end result of these | ||
| 757 | signature generators is to make some dependency and hash | ||
| 758 | information available to the build. | ||
| 759 | This information includes: | ||
| 760 | <itemizedlist> | ||
| 761 | <listitem><para> | ||
| 762 | <filename>BB_BASEHASH_task-</filename><replaceable>taskname</replaceable>: | ||
| 763 | The base hashes for each task in the recipe. | ||
| 764 | </para></listitem> | ||
| 765 | <listitem><para> | ||
| 766 | <filename>BB_BASEHASH_</filename><replaceable>filename</replaceable><filename>:</filename><replaceable>taskname</replaceable>: | ||
| 767 | The base hashes for each dependent task. | ||
| 768 | </para></listitem> | ||
| 769 | <listitem><para> | ||
| 770 | <filename>BBHASHDEPS_</filename><replaceable>filename</replaceable><filename>:</filename><replaceable>taskname</replaceable>: | ||
| 771 | The task dependencies for each task. | ||
| 772 | </para></listitem> | ||
| 773 | <listitem><para> | ||
| 774 | <filename>BB_TASKHASH</filename>: | ||
| 775 | The hash of the currently running task. | ||
| 776 | </para></listitem> | ||
| 777 | </itemizedlist> | ||
| 778 | </para> | ||
| 779 | </section> | ||
| 780 | |||
| 781 | <section id='shared-state'> | ||
| 782 | <title>Shared State</title> | ||
| 783 | |||
| 784 | <para> | ||
| 785 | Checksums and dependencies, as discussed in the previous | ||
| 786 | section, solve half the problem of supporting a shared state. | ||
| 787 | The other part of the problem is being able to use checksum | ||
| 788 | information during the build and being able to reuse or rebuild | ||
| 789 | specific components. | ||
| 790 | </para> | ||
| 791 | |||
| 792 | <para> | ||
| 793 | The | ||
| 794 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-sstate'><filename>sstate</filename></ulink> | ||
| 795 | class is a relatively generic implementation of how to | ||
| 796 | "capture" a snapshot of a given task. | ||
| 797 | The idea is that the build process does not care about the | ||
| 798 | source of a task's output. | ||
| 799 | Output could be freshly built or it could be downloaded and | ||
| 800 | unpacked from somewhere - the build process does not need to | ||
| 801 | worry about its origin. | ||
| 802 | </para> | ||
| 803 | |||
| 804 | <para> | ||
| 805 | There are two types of output, one is just about creating a | ||
| 806 | directory in | ||
| 807 | <ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>. | ||
| 808 | A good example is the output of either | ||
| 809 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink> | ||
| 810 | or | ||
| 811 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package'><filename>do_package</filename></ulink>. | ||
| 812 | The other type of output occurs when a set of data is merged | ||
| 813 | into a shared directory tree such as the sysroot. | ||
| 814 | </para> | ||
| 815 | |||
| 816 | <para> | ||
| 817 | The Yocto Project team has tried to keep the details of the | ||
| 818 | implementation hidden in <filename>sstate</filename> class. | ||
| 819 | From a user's perspective, adding shared state wrapping to a task | ||
| 820 | is as simple as this | ||
| 821 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-deploy'><filename>do_deploy</filename></ulink> | ||
| 822 | example taken from the | ||
| 823 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-deploy'><filename>deploy</filename></ulink> | ||
| 824 | class: | ||
| 825 | <literallayout class='monospaced'> | ||
| 826 | DEPLOYDIR = "${WORKDIR}/deploy-${PN}" | ||
| 827 | SSTATETASKS += "do_deploy" | ||
| 828 | do_deploy[sstate-inputdirs] = "${DEPLOYDIR}" | ||
| 829 | do_deploy[sstate-outputdirs] = "${DEPLOY_DIR_IMAGE}" | ||
| 830 | |||
| 831 | python do_deploy_setscene () { | ||
| 832 | sstate_setscene(d) | ||
| 833 | } | ||
| 834 | addtask do_deploy_setscene | ||
| 835 | do_deploy[dirs] = "${DEPLOYDIR} ${B}" | ||
| 836 | </literallayout> | ||
| 837 | The following list explains the previous example: | ||
| 838 | <itemizedlist> | ||
| 839 | <listitem><para> | ||
| 840 | Adding "do_deploy" to <filename>SSTATETASKS</filename> | ||
| 841 | adds some required sstate-related processing, which is | ||
| 842 | implemented in the | ||
| 843 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-sstate'><filename>sstate</filename></ulink> | ||
| 844 | class, to before and after the | ||
| 845 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-deploy'><filename>do_deploy</filename></ulink> | ||
| 846 | task. | ||
| 847 | </para></listitem> | ||
| 848 | <listitem><para> | ||
| 849 | The | ||
| 850 | <filename>do_deploy[sstate-inputdirs] = "${DEPLOYDIR}"</filename> | ||
| 851 | declares that <filename>do_deploy</filename> places its | ||
| 852 | output in <filename>${DEPLOYDIR}</filename> when run | ||
| 853 | normally (i.e. when not using the sstate cache). | ||
| 854 | This output becomes the input to the shared state cache. | ||
| 855 | </para></listitem> | ||
| 856 | <listitem><para> | ||
| 857 | The | ||
| 858 | <filename>do_deploy[sstate-outputdirs] = "${DEPLOY_DIR_IMAGE}"</filename> | ||
| 859 | line causes the contents of the shared state cache to be | ||
| 860 | copied to <filename>${DEPLOY_DIR_IMAGE}</filename>. | ||
| 861 | <note> | ||
| 862 | If <filename>do_deploy</filename> is not already in | ||
| 863 | the shared state cache or if its input checksum | ||
| 864 | (signature) has changed from when the output was | ||
| 865 | cached, the task will be run to populate the shared | ||
| 866 | state cache, after which the contents of the shared | ||
| 867 | state cache is copied to | ||
| 868 | <filename>${DEPLOY_DIR_IMAGE}</filename>. | ||
| 869 | If <filename>do_deploy</filename> is in the shared | ||
| 870 | state cache and its signature indicates that the | ||
| 871 | cached output is still valid (i.e. if no | ||
| 872 | relevant task inputs have changed), then the | ||
| 873 | contents of the shared state cache will be copied | ||
| 874 | directly to | ||
| 875 | <filename>${DEPLOY_DIR_IMAGE}</filename> by the | ||
| 876 | <filename>do_deploy_setscene</filename> task | ||
| 877 | instead, skipping the | ||
| 878 | <filename>do_deploy</filename> task. | ||
| 879 | </note> | ||
| 880 | </para></listitem> | ||
| 881 | <listitem><para> | ||
| 882 | The following task definition is glue logic needed to | ||
| 883 | make the previous settings effective: | ||
| 884 | <literallayout class='monospaced'> | ||
| 885 | python do_deploy_setscene () { | ||
| 886 | sstate_setscene(d) | ||
| 887 | } | ||
| 888 | addtask do_deploy_setscene | ||
| 889 | </literallayout> | ||
| 890 | <filename>sstate_setscene()</filename> takes the flags | ||
| 891 | above as input and accelerates the | ||
| 892 | <filename>do_deploy</filename> task through the | ||
| 893 | shared state cache if possible. | ||
| 894 | If the task was accelerated, | ||
| 895 | <filename>sstate_setscene()</filename> returns True. | ||
| 896 | Otherwise, it returns False, and the normal | ||
| 897 | <filename>do_deploy</filename> task runs. | ||
| 898 | For more information, see the | ||
| 899 | "<ulink url='&YOCTO_DOCS_BB_URL;#setscene'>setscene</ulink>" | ||
| 900 | section in the BitBake User Manual. | ||
| 901 | </para></listitem> | ||
| 902 | <listitem><para> | ||
| 903 | The <filename>do_deploy[dirs] = "${DEPLOYDIR} ${B}"</filename> | ||
| 904 | line creates <filename>${DEPLOYDIR}</filename> and | ||
| 905 | <filename>${B}</filename> before the | ||
| 906 | <filename>do_deploy</filename> task runs, and also sets | ||
| 907 | the current working directory of | ||
| 908 | <filename>do_deploy</filename> to | ||
| 909 | <filename>${B}</filename>. | ||
| 910 | For more information, see the | ||
| 911 | "<ulink url='&YOCTO_DOCS_BB_URL;#variable-flags'>Variable Flags</ulink>" | ||
| 912 | section in the BitBake User Manual. | ||
| 913 | <note> | ||
| 914 | In cases where | ||
| 915 | <filename>sstate-inputdirs</filename> and | ||
| 916 | <filename>sstate-outputdirs</filename> would be the | ||
| 917 | same, you can use | ||
| 918 | <filename>sstate-plaindirs</filename>. | ||
| 919 | For example, to preserve the | ||
| 920 | <filename>${PKGD}</filename> and | ||
| 921 | <filename>${PKGDEST}</filename> output from the | ||
| 922 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package'><filename>do_package</filename></ulink> | ||
| 923 | task, use the following: | ||
| 924 | <literallayout class='monospaced'> | ||
| 925 | do_package[sstate-plaindirs] = "${PKGD} ${PKGDEST}" | ||
| 926 | </literallayout> | ||
| 927 | </note> | ||
| 928 | </para></listitem> | ||
| 929 | <listitem><para> | ||
| 930 | <filename>sstate-inputdirs</filename> and | ||
| 931 | <filename>sstate-outputdirs</filename> can also be used | ||
| 932 | with multiple directories. | ||
| 933 | For example, the following declares | ||
| 934 | <filename>PKGDESTWORK</filename> and | ||
| 935 | <filename>SHLIBWORK</filename> as shared state | ||
| 936 | input directories, which populates the shared state | ||
| 937 | cache, and <filename>PKGDATA_DIR</filename> and | ||
| 938 | <filename>SHLIBSDIR</filename> as the corresponding | ||
| 939 | shared state output directories: | ||
| 940 | <literallayout class='monospaced'> | ||
| 941 | do_package[sstate-inputdirs] = "${PKGDESTWORK} ${SHLIBSWORKDIR}" | ||
| 942 | do_package[sstate-outputdirs] = "${PKGDATA_DIR} ${SHLIBSDIR}" | ||
| 943 | </literallayout> | ||
| 944 | </para></listitem> | ||
| 945 | <listitem><para> | ||
| 946 | These methods also include the ability to take a | ||
| 947 | lockfile when manipulating shared state directory | ||
| 948 | structures, for cases where file additions or removals | ||
| 949 | are sensitive: | ||
| 950 | <literallayout class='monospaced'> | ||
| 951 | do_package[sstate-lockfile] = "${PACKAGELOCK}" | ||
| 952 | </literallayout> | ||
| 953 | </para></listitem> | ||
| 954 | </itemizedlist> | ||
| 955 | </para> | ||
| 956 | |||
| 957 | <para> | ||
| 958 | Behind the scenes, the shared state code works by looking in | ||
| 959 | <ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_DIR'><filename>SSTATE_DIR</filename></ulink> | ||
| 960 | and | ||
| 961 | <ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></ulink> | ||
| 962 | for shared state files. | ||
| 963 | Here is an example: | ||
| 964 | <literallayout class='monospaced'> | ||
| 965 | SSTATE_MIRRORS ?= "\ | ||
| 966 | file://.* http://someserver.tld/share/sstate/PATH;downloadfilename=PATH \n \ | ||
| 967 | file://.* file:///some/local/dir/sstate/PATH" | ||
| 968 | </literallayout> | ||
| 969 | <note> | ||
| 970 | The shared state directory | ||
| 971 | (<filename>SSTATE_DIR</filename>) is organized into | ||
| 972 | two-character subdirectories, where the subdirectory | ||
| 973 | names are based on the first two characters of the hash. | ||
| 974 | If the shared state directory structure for a mirror has the | ||
| 975 | same structure as <filename>SSTATE_DIR</filename>, you must | ||
| 976 | specify "PATH" as part of the URI to enable the build system | ||
| 977 | to map to the appropriate subdirectory. | ||
| 978 | </note> | ||
| 979 | </para> | ||
| 980 | |||
| 981 | <para> | ||
| 982 | The shared state package validity can be detected just by | ||
| 983 | looking at the filename since the filename contains the task | ||
| 984 | checksum (or signature) as described earlier in this section. | ||
| 985 | If a valid shared state package is found, the build process | ||
| 986 | downloads it and uses it to accelerate the task. | ||
| 987 | </para> | ||
| 988 | |||
| 989 | <para> | ||
| 990 | The build processes use the <filename>*_setscene</filename> | ||
| 991 | tasks for the task acceleration phase. | ||
| 992 | BitBake goes through this phase before the main execution | ||
| 993 | code and tries to accelerate any tasks for which it can find | ||
| 994 | shared state packages. | ||
| 995 | If a shared state package for a task is available, the | ||
| 996 | shared state package is used. | ||
| 997 | This means the task and any tasks on which it is dependent | ||
| 998 | are not executed. | ||
| 999 | </para> | ||
| 1000 | |||
| 1001 | <para> | ||
| 1002 | As a real world example, the aim is when building an IPK-based | ||
| 1003 | image, only the | ||
| 1004 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package_write_ipk'><filename>do_package_write_ipk</filename></ulink> | ||
| 1005 | tasks would have their shared state packages fetched and | ||
| 1006 | extracted. | ||
| 1007 | Since the sysroot is not used, it would never get extracted. | ||
| 1008 | This is another reason why a task-based approach is preferred | ||
| 1009 | over a recipe-based approach, which would have to install the | ||
| 1010 | output from every task. | ||
| 1011 | </para> | ||
| 1012 | </section> | ||
| 1013 | |||
| 1014 | <section id='tips-and-tricks'> | ||
| 1015 | <title>Tips and Tricks</title> | ||
| 1016 | |||
| 1017 | <para> | ||
| 1018 | The code in the build system that supports incremental builds | ||
| 1019 | is not simple code. | ||
| 1020 | This section presents some tips and tricks that help you work | ||
| 1021 | around issues related to shared state code. | ||
| 1022 | </para> | ||
| 1023 | |||
| 1024 | <section id='overview-debugging'> | ||
| 1025 | <title>Debugging</title> | ||
| 1026 | |||
| 1027 | <para> | ||
| 1028 | Seeing what metadata went into creating the input signature | ||
| 1029 | of a shared state (sstate) task can be a useful debugging | ||
| 1030 | aid. | ||
| 1031 | This information is available in signature information | ||
| 1032 | (<filename>siginfo</filename>) files in | ||
| 1033 | <ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_DIR'><filename>SSTATE_DIR</filename></ulink>. | ||
| 1034 | For information on how to view and interpret information in | ||
| 1035 | <filename>siginfo</filename> files, see the | ||
| 1036 | "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-viewing-task-variable-dependencies'>Viewing Task Variable Dependencies</ulink>" | ||
| 1037 | section in the Yocto Project Development Tasks Manual. | ||
| 1038 | </para> | ||
| 1039 | </section> | ||
| 1040 | |||
| 1041 | <section id='invalidating-shared-state'> | ||
| 1042 | <title>Invalidating Shared State</title> | ||
| 1043 | |||
| 1044 | <para> | ||
| 1045 | The OpenEmbedded build system uses checksums and shared | ||
| 1046 | state cache to avoid unnecessarily rebuilding tasks. | ||
| 1047 | Collectively, this scheme is known as "shared state code." | ||
| 1048 | </para> | ||
| 1049 | |||
| 1050 | <para> | ||
| 1051 | As with all schemes, this one has some drawbacks. | ||
| 1052 | It is possible that you could make implicit changes to your | ||
| 1053 | code that the checksum calculations do not take into | ||
| 1054 | account. | ||
| 1055 | These implicit changes affect a task's output but do not | ||
| 1056 | trigger the shared state code into rebuilding a recipe. | ||
| 1057 | Consider an example during which a tool changes its output. | ||
| 1058 | Assume that the output of <filename>rpmdeps</filename> | ||
| 1059 | changes. | ||
| 1060 | The result of the change should be that all the | ||
| 1061 | <filename>package</filename> and | ||
| 1062 | <filename>package_write_rpm</filename> shared state cache | ||
| 1063 | items become invalid. | ||
| 1064 | However, because the change to the output is | ||
| 1065 | external to the code and therefore implicit, | ||
| 1066 | the associated shared state cache items do not become | ||
| 1067 | invalidated. | ||
| 1068 | In this case, the build process uses the cached items | ||
| 1069 | rather than running the task again. | ||
| 1070 | Obviously, these types of implicit changes can cause | ||
| 1071 | problems. | ||
| 1072 | </para> | ||
| 1073 | |||
| 1074 | <para> | ||
| 1075 | To avoid these problems during the build, you need to | ||
| 1076 | understand the effects of any changes you make. | ||
| 1077 | Realize that changes you make directly to a function | ||
| 1078 | are automatically factored into the checksum calculation. | ||
| 1079 | Thus, these explicit changes invalidate the associated | ||
| 1080 | area of shared state cache. | ||
| 1081 | However, you need to be aware of any implicit changes that | ||
| 1082 | are not obvious changes to the code and could affect | ||
| 1083 | the output of a given task. | ||
| 1084 | </para> | ||
| 1085 | |||
| 1086 | <para> | ||
| 1087 | When you identify an implicit change, you can easily | ||
| 1088 | take steps to invalidate the cache and force the tasks | ||
| 1089 | to run. | ||
| 1090 | The steps you can take are as simple as changing a | ||
| 1091 | function's comments in the source code. | ||
| 1092 | For example, to invalidate package shared state files, | ||
| 1093 | change the comment statements of | ||
| 1094 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package'><filename>do_package</filename></ulink> | ||
| 1095 | or the comments of one of the functions it calls. | ||
| 1096 | Even though the change is purely cosmetic, it causes the | ||
| 1097 | checksum to be recalculated and forces the OpenEmbedded | ||
| 1098 | build system to run the task again. | ||
| 1099 | <note> | ||
| 1100 | For an example of a commit that makes a cosmetic | ||
| 1101 | change to invalidate shared state, see this | ||
| 1102 | <ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/commit/meta/classes/package.bbclass?id=737f8bbb4f27b4837047cb9b4fbfe01dfde36d54'>commit</ulink>. | ||
| 1103 | </note> | ||
| 1104 | </para> | ||
| 1105 | </section> | ||
| 1106 | </section> | ||
| 1107 | </section> | ||
| 1108 | |||
| 1109 | <section id='automatically-added-runtime-dependencies'> | ||
| 1110 | <title>Automatically Added Runtime Dependencies</title> | ||
| 1111 | |||
| 1112 | <para> | ||
| 1113 | The OpenEmbedded build system automatically adds common types of | ||
| 1114 | runtime dependencies between packages, which means that you do not | ||
| 1115 | need to explicitly declare the packages using | ||
| 1116 | <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink>. | ||
| 1117 | Three automatic mechanisms exist (<filename>shlibdeps</filename>, | ||
| 1118 | <filename>pcdeps</filename>, and <filename>depchains</filename>) | ||
| 1119 | that handle shared libraries, package configuration (pkg-config) | ||
| 1120 | modules, and <filename>-dev</filename> and | ||
| 1121 | <filename>-dbg</filename> packages, respectively. | ||
| 1122 | For other types of runtime dependencies, you must manually declare | ||
| 1123 | the dependencies. | ||
| 1124 | <itemizedlist> | ||
| 1125 | <listitem><para> | ||
| 1126 | <filename>shlibdeps</filename>: | ||
| 1127 | During the | ||
| 1128 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package'><filename>do_package</filename></ulink> | ||
| 1129 | task of each recipe, all shared libraries installed by the | ||
| 1130 | recipe are located. | ||
| 1131 | For each shared library, the package that contains the | ||
| 1132 | shared library is registered as providing the shared | ||
| 1133 | library. | ||
| 1134 | More specifically, the package is registered as providing | ||
| 1135 | the | ||
| 1136 | <ulink url='https://en.wikipedia.org/wiki/Soname'>soname</ulink> | ||
| 1137 | of the library. | ||
| 1138 | The resulting shared-library-to-package mapping | ||
| 1139 | is saved globally in | ||
| 1140 | <ulink url='&YOCTO_DOCS_REF_URL;#var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></ulink> | ||
| 1141 | by the | ||
| 1142 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-packagedata'><filename>do_packagedata</filename></ulink> | ||
| 1143 | task.</para> | ||
| 1144 | |||
| 1145 | <para>Simultaneously, all executables and shared libraries | ||
| 1146 | installed by the recipe are inspected to see what shared | ||
| 1147 | libraries they link against. | ||
| 1148 | For each shared library dependency that is found, | ||
| 1149 | <filename>PKGDATA_DIR</filename> is queried to | ||
| 1150 | see if some package (likely from a different recipe) | ||
| 1151 | contains the shared library. | ||
| 1152 | If such a package is found, a runtime dependency is added | ||
| 1153 | from the package that depends on the shared library to the | ||
| 1154 | package that contains the library.</para> | ||
| 1155 | |||
| 1156 | <para>The automatically added runtime dependency also | ||
| 1157 | includes a version restriction. | ||
| 1158 | This version restriction specifies that at least the | ||
| 1159 | current version of the package that provides the shared | ||
| 1160 | library must be used, as if | ||
| 1161 | "<replaceable>package</replaceable> (>= <replaceable>version</replaceable>)" | ||
| 1162 | had been added to | ||
| 1163 | <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink>. | ||
| 1164 | This forces an upgrade of the package containing the shared | ||
| 1165 | library when installing the package that depends on the | ||
| 1166 | library, if needed.</para> | ||
| 1167 | |||
| 1168 | <para>If you want to avoid a package being registered as | ||
| 1169 | providing a particular shared library (e.g. because the library | ||
| 1170 | is for internal use only), then add the library to | ||
| 1171 | <ulink url='&YOCTO_DOCS_REF_URL;#var-PRIVATE_LIBS'><filename>PRIVATE_LIBS</filename></ulink> | ||
| 1172 | inside the package's recipe. | ||
| 1173 | </para></listitem> | ||
| 1174 | <listitem><para> | ||
| 1175 | <filename>pcdeps</filename>: | ||
| 1176 | During the | ||
| 1177 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package'><filename>do_package</filename></ulink> | ||
| 1178 | task of each recipe, all pkg-config modules | ||
| 1179 | (<filename>*.pc</filename> files) installed by the recipe | ||
| 1180 | are located. | ||
| 1181 | For each module, the package that contains the module is | ||
| 1182 | registered as providing the module. | ||
| 1183 | The resulting module-to-package mapping is saved globally in | ||
| 1184 | <ulink url='&YOCTO_DOCS_REF_URL;#var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></ulink> | ||
| 1185 | by the | ||
| 1186 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-packagedata'><filename>do_packagedata</filename></ulink> | ||
| 1187 | task.</para> | ||
| 1188 | |||
| 1189 | <para>Simultaneously, all pkg-config modules installed by | ||
| 1190 | the recipe are inspected to see what other pkg-config | ||
| 1191 | modules they depend on. | ||
| 1192 | A module is seen as depending on another module if it | ||
| 1193 | contains a "Requires:" line that specifies the other module. | ||
| 1194 | For each module dependency, | ||
| 1195 | <filename>PKGDATA_DIR</filename> is queried to see if some | ||
| 1196 | package contains the module. | ||
| 1197 | If such a package is found, a runtime dependency is added | ||
| 1198 | from the package that depends on the module to the package | ||
| 1199 | that contains the module. | ||
| 1200 | <note> | ||
| 1201 | The <filename>pcdeps</filename> mechanism most often | ||
| 1202 | infers dependencies between <filename>-dev</filename> | ||
| 1203 | packages. | ||
| 1204 | </note> | ||
| 1205 | </para></listitem> | ||
| 1206 | <listitem><para> | ||
| 1207 | <filename>depchains</filename>: | ||
| 1208 | If a package <filename>foo</filename> depends on a package | ||
| 1209 | <filename>bar</filename>, then <filename>foo-dev</filename> | ||
| 1210 | and <filename>foo-dbg</filename> are also made to depend on | ||
| 1211 | <filename>bar-dev</filename> and | ||
| 1212 | <filename>bar-dbg</filename>, respectively. | ||
| 1213 | Taking the <filename>-dev</filename> packages as an | ||
| 1214 | example, the <filename>bar-dev</filename> package might | ||
| 1215 | provide headers and shared library symlinks needed by | ||
| 1216 | <filename>foo-dev</filename>, which shows the need | ||
| 1217 | for a dependency between the packages.</para> | ||
| 1218 | |||
| 1219 | <para>The dependencies added by | ||
| 1220 | <filename>depchains</filename> are in the form of | ||
| 1221 | <ulink url='&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS'><filename>RRECOMMENDS</filename></ulink>. | ||
| 1222 | <note> | ||
| 1223 | By default, <filename>foo-dev</filename> also has an | ||
| 1224 | <filename>RDEPENDS</filename>-style dependency on | ||
| 1225 | <filename>foo</filename>, because the default value of | ||
| 1226 | <filename>RDEPENDS_${PN}-dev</filename> (set in | ||
| 1227 | <filename>bitbake.conf</filename>) includes | ||
| 1228 | "${PN}". | ||
| 1229 | </note></para> | ||
| 1230 | |||
| 1231 | <para>To ensure that the dependency chain is never broken, | ||
| 1232 | <filename>-dev</filename> and <filename>-dbg</filename> | ||
| 1233 | packages are always generated by default, even if the | ||
| 1234 | packages turn out to be empty. | ||
| 1235 | See the | ||
| 1236 | <ulink url='&YOCTO_DOCS_REF_URL;#var-ALLOW_EMPTY'><filename>ALLOW_EMPTY</filename></ulink> | ||
| 1237 | variable for more information. | ||
| 1238 | </para></listitem> | ||
| 1239 | </itemizedlist> | ||
| 1240 | </para> | ||
| 1241 | |||
| 1242 | <para> | ||
| 1243 | The <filename>do_package</filename> task depends on the | ||
| 1244 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-packagedata'><filename>do_packagedata</filename></ulink> | ||
| 1245 | task of each recipe in | ||
| 1246 | <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink> | ||
| 1247 | through use of a | ||
| 1248 | <filename>[</filename><ulink url='&YOCTO_DOCS_BB_URL;#variable-flags'><filename>deptask</filename></ulink><filename>]</filename> | ||
| 1249 | declaration, which guarantees that the required | ||
| 1250 | shared-library/module-to-package mapping information will be available | ||
| 1251 | when needed as long as <filename>DEPENDS</filename> has been | ||
| 1252 | correctly set. | ||
| 1253 | </para> | ||
| 1254 | </section> | ||
| 1255 | |||
| 1256 | <section id='fakeroot-and-pseudo'> | ||
| 1257 | <title>Fakeroot and Pseudo</title> | ||
| 1258 | |||
| 1259 | <para> | ||
| 1260 | Some tasks are easier to implement when allowed to perform certain | ||
| 1261 | operations that are normally reserved for the root user (e.g. | ||
| 1262 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink>, | ||
| 1263 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package_write_deb'><filename>do_package_write*</filename></ulink>, | ||
| 1264 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-rootfs'><filename>do_rootfs</filename></ulink>, | ||
| 1265 | and | ||
| 1266 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-image'><filename>do_image*</filename></ulink>). | ||
| 1267 | For example, the <filename>do_install</filename> task benefits | ||
| 1268 | from being able to set the UID and GID of installed files to | ||
| 1269 | arbitrary values. | ||
| 1270 | </para> | ||
| 1271 | |||
| 1272 | <para> | ||
| 1273 | One approach to allowing tasks to perform root-only operations | ||
| 1274 | would be to require BitBake to run as root. | ||
| 1275 | However, this method is cumbersome and has security issues. | ||
| 1276 | The approach that is actually used is to run tasks that benefit | ||
| 1277 | from root privileges in a "fake" root environment. | ||
| 1278 | Within this environment, the task and its child processes believe | ||
| 1279 | that they are running as the root user, and see an internally | ||
| 1280 | consistent view of the filesystem. | ||
| 1281 | As long as generating the final output (e.g. a package or an image) | ||
| 1282 | does not require root privileges, the fact that some earlier | ||
| 1283 | steps ran in a fake root environment does not cause problems. | ||
| 1284 | </para> | ||
| 1285 | |||
| 1286 | <para> | ||
| 1287 | The capability to run tasks in a fake root environment is known as | ||
| 1288 | "<ulink url='http://man.he.net/man1/fakeroot'>fakeroot</ulink>", | ||
| 1289 | which is derived from the BitBake keyword/variable | ||
| 1290 | flag that requests a fake root environment for a task. | ||
| 1291 | </para> | ||
| 1292 | |||
| 1293 | <para> | ||
| 1294 | In the OpenEmbedded build system, the program that implements | ||
| 1295 | fakeroot is known as Pseudo. | ||
| 1296 | Pseudo overrides system calls by using the environment variable | ||
| 1297 | <filename>LD_PRELOAD</filename>, which results in the illusion | ||
| 1298 | of running as root. | ||
| 1299 | To keep track of "fake" file ownership and permissions resulting | ||
| 1300 | from operations that require root permissions, Pseudo uses | ||
| 1301 | an SQLite 3 database. | ||
| 1302 | This database is stored in | ||
| 1303 | <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}/pseudo/files.db</filename> | ||
| 1304 | for individual recipes. | ||
| 1305 | Storing the database in a file as opposed to in memory | ||
| 1306 | gives persistence between tasks and builds, which is not | ||
| 1307 | accomplished using fakeroot. | ||
| 1308 | <note><title>Caution</title> | ||
| 1309 | If you add your own task that manipulates the same files or | ||
| 1310 | directories as a fakeroot task, then that task also needs to | ||
| 1311 | run under fakeroot. | ||
| 1312 | Otherwise, the task cannot run root-only operations, and | ||
| 1313 | cannot see the fake file ownership and permissions set by the | ||
| 1314 | other task. | ||
| 1315 | You need to also add a dependency on | ||
| 1316 | <filename>virtual/fakeroot-native:do_populate_sysroot</filename>, | ||
| 1317 | giving the following: | ||
| 1318 | <literallayout class='monospaced'> | ||
| 1319 | fakeroot do_mytask () { | ||
| 1320 | ... | ||
| 1321 | } | ||
| 1322 | do_mytask[depends] += "virtual/fakeroot-native:do_populate_sysroot" | ||
| 1323 | </literallayout> | ||
| 1324 | </note> | ||
| 1325 | For more information, see the | ||
| 1326 | <ulink url='&YOCTO_DOCS_BB_URL;#var-FAKEROOT'><filename>FAKEROOT*</filename></ulink> | ||
| 1327 | variables in the BitBake User Manual. | ||
| 1328 | You can also reference the | ||
| 1329 | "<ulink url='http://www.ibm.com/developerworks/opensource/library/os-aapseudo1/index.html'>Pseudo</ulink>" | ||
| 1330 | and | ||
| 1331 | "<ulink url='https://github.com/wrpseudo/pseudo/wiki/WhyNotFakeroot'>Why Not Fakeroot?</ulink>" | ||
| 1332 | articles for background information on Pseudo. | ||
| 1333 | </para> | ||
| 1334 | </section> | ||
| 1335 | |||
| 1336 | <section id="wayland"> | ||
| 1337 | <title>Wayland</title> | ||
| 1338 | |||
| 1339 | <para> | ||
| 1340 | <ulink url='http://en.wikipedia.org/wiki/Wayland_(display_server_protocol)'>Wayland</ulink> | ||
| 1341 | is a computer display server protocol that | ||
| 1342 | provides a method for compositing window managers to communicate | ||
| 1343 | directly with applications and video hardware and expects them to | ||
| 1344 | communicate with input hardware using other libraries. | ||
| 1345 | Using Wayland with supporting targets can result in better control | ||
| 1346 | over graphics frame rendering than an application might otherwise | ||
| 1347 | achieve. | ||
| 1348 | </para> | ||
| 1349 | |||
| 1350 | <para> | ||
| 1351 | The Yocto Project provides the Wayland protocol libraries and the | ||
| 1352 | reference | ||
| 1353 | <ulink url='http://en.wikipedia.org/wiki/Wayland_(display_server_protocol)#Weston'>Weston</ulink> | ||
| 1354 | compositor as part of its release. | ||
| 1355 | This section describes what you need to do to implement Wayland and | ||
| 1356 | use the compositor when building an image for a supporting target. | ||
| 1357 | </para> | ||
| 1358 | |||
| 1359 | <section id="wayland-support"> | ||
| 1360 | <title>Support</title> | ||
| 1361 | |||
| 1362 | <para> | ||
| 1363 | The Wayland protocol libraries and the reference Weston | ||
| 1364 | compositor ship as integrated packages in the | ||
| 1365 | <filename>meta</filename> layer of the | ||
| 1366 | <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>. | ||
| 1367 | Specifically, you can find the recipes that build both Wayland | ||
| 1368 | and Weston at | ||
| 1369 | <filename>meta/recipes-graphics/wayland</filename>. | ||
| 1370 | </para> | ||
| 1371 | |||
| 1372 | <para> | ||
| 1373 | You can build both the Wayland and Weston packages for use only | ||
| 1374 | with targets that accept the | ||
| 1375 | <ulink url='https://en.wikipedia.org/wiki/Mesa_(computer_graphics)'>Mesa 3D and Direct Rendering Infrastructure</ulink>, | ||
| 1376 | which is also known as Mesa DRI. | ||
| 1377 | This implies that you cannot build and use the packages if your | ||
| 1378 | target uses, for example, the | ||
| 1379 | <trademark class='registered'>Intel</trademark> Embedded Media | ||
| 1380 | and Graphics Driver | ||
| 1381 | (<trademark class='registered'>Intel</trademark> EMGD) that | ||
| 1382 | overrides Mesa DRI. | ||
| 1383 | <note> | ||
| 1384 | Due to lack of EGL support, Weston 1.0.3 will not run | ||
| 1385 | directly on the emulated QEMU hardware. | ||
| 1386 | However, this version of Weston will run under X emulation | ||
| 1387 | without issues. | ||
| 1388 | </note> | ||
| 1389 | </para> | ||
| 1390 | </section> | ||
| 1391 | |||
| 1392 | <section id="enabling-wayland-in-an-image"> | ||
| 1393 | <title>Enabling Wayland in an Image</title> | ||
| 1394 | |||
| 1395 | <para> | ||
| 1396 | To enable Wayland, you need to enable it to be built and enable | ||
| 1397 | it to be included in the image. | ||
| 1398 | </para> | ||
| 1399 | |||
| 1400 | <section id="enable-building"> | ||
| 1401 | <title>Building</title> | ||
| 1402 | |||
| 1403 | <para> | ||
| 1404 | To cause Mesa to build the <filename>wayland-egl</filename> | ||
| 1405 | platform and Weston to build Wayland with Kernel Mode | ||
| 1406 | Setting | ||
| 1407 | (<ulink url='https://wiki.archlinux.org/index.php/Kernel_Mode_Setting'>KMS</ulink>) | ||
| 1408 | support, include the "wayland" flag in the | ||
| 1409 | <ulink url="&YOCTO_DOCS_REF_URL;#var-DISTRO_FEATURES"><filename>DISTRO_FEATURES</filename></ulink> | ||
| 1410 | statement in your <filename>local.conf</filename> file: | ||
| 1411 | <literallayout class='monospaced'> | ||
| 1412 | DISTRO_FEATURES_append = " wayland" | ||
| 1413 | </literallayout> | ||
| 1414 | <note> | ||
| 1415 | If X11 has been enabled elsewhere, Weston will build | ||
| 1416 | Wayland with X11 support | ||
| 1417 | </note> | ||
| 1418 | </para> | ||
| 1419 | </section> | ||
| 1420 | |||
| 1421 | <section id="enable-installation-in-an-image"> | ||
| 1422 | <title>Installing</title> | ||
| 1423 | |||
| 1424 | <para> | ||
| 1425 | To install the Wayland feature into an image, you must | ||
| 1426 | include the following | ||
| 1427 | <ulink url='&YOCTO_DOCS_REF_URL;#var-CORE_IMAGE_EXTRA_INSTALL'><filename>CORE_IMAGE_EXTRA_INSTALL</filename></ulink> | ||
| 1428 | statement in your <filename>local.conf</filename> file: | ||
| 1429 | <literallayout class='monospaced'> | ||
| 1430 | CORE_IMAGE_EXTRA_INSTALL += "wayland weston" | ||
| 1431 | </literallayout> | ||
| 1432 | </para> | ||
| 1433 | </section> | ||
| 1434 | </section> | ||
| 1435 | |||
| 1436 | <section id="running-weston"> | ||
| 1437 | <title>Running Weston</title> | ||
| 1438 | |||
| 1439 | <para> | ||
| 1440 | To run Weston inside X11, enabling it as described earlier and | ||
| 1441 | building a Sato image is sufficient. | ||
| 1442 | If you are running your image under Sato, a Weston Launcher | ||
| 1443 | appears in the "Utility" category. | ||
| 1444 | </para> | ||
| 1445 | |||
| 1446 | <para> | ||
| 1447 | Alternatively, you can run Weston through the command-line | ||
| 1448 | interpretor (CLI), which is better suited for development work. | ||
| 1449 | To run Weston under the CLI, you need to do the following after | ||
| 1450 | your image is built: | ||
| 1451 | <orderedlist> | ||
| 1452 | <listitem><para> | ||
| 1453 | Run these commands to export | ||
| 1454 | <filename>XDG_RUNTIME_DIR</filename>: | ||
| 1455 | <literallayout class='monospaced'> | ||
| 1456 | mkdir -p /tmp/$USER-weston | ||
| 1457 | chmod 0700 /tmp/$USER-weston | ||
| 1458 | export XDG_RUNTIME_DIR=/tmp/$USER-weston | ||
| 1459 | </literallayout> | ||
| 1460 | </para></listitem> | ||
| 1461 | <listitem><para> | ||
| 1462 | Launch Weston in the shell: | ||
| 1463 | <literallayout class='monospaced'> | ||
| 1464 | weston | ||
| 1465 | </literallayout></para></listitem> | ||
| 1466 | </orderedlist> | ||
| 1467 | </para> | ||
| 1468 | </section> | ||
| 1469 | </section> | ||
| 1470 | |||
| 1471 | <section id="overview-licenses"> | ||
| 1472 | <title>Licenses</title> | ||
| 1473 | |||
| 1474 | <para> | ||
| 1475 | This section describes the mechanism by which the OpenEmbedded | ||
| 1476 | build system tracks changes to licensing text. | ||
| 1477 | The section also describes how to enable commercially licensed | ||
| 1478 | recipes, which by default are disabled. | ||
| 1479 | </para> | ||
| 1480 | |||
| 1481 | <para> | ||
| 1482 | For information that can help you maintain compliance with | ||
| 1483 | various open source licensing during the lifecycle of the product, | ||
| 1484 | see the | ||
| 1485 | "<ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-open-source-license-compliance-during-your-products-lifecycle'>Maintaining Open Source License Compliance During Your Project's Lifecycle</ulink>" | ||
| 1486 | section in the Yocto Project Development Tasks Manual. | ||
| 1487 | </para> | ||
| 1488 | |||
| 1489 | <section id="usingpoky-configuring-LIC_FILES_CHKSUM"> | ||
| 1490 | <title>Tracking License Changes</title> | ||
| 1491 | |||
| 1492 | <para> | ||
| 1493 | The license of an upstream project might change in the future. | ||
| 1494 | In order to prevent these changes going unnoticed, the | ||
| 1495 | <ulink url='&YOCTO_DOCS_REF_URL;#var-LIC_FILES_CHKSUM'><filename>LIC_FILES_CHKSUM</filename></ulink> | ||
| 1496 | variable tracks changes to the license text. The checksums are | ||
| 1497 | validated at the end of the configure step, and if the | ||
| 1498 | checksums do not match, the build will fail. | ||
| 1499 | </para> | ||
| 1500 | |||
| 1501 | <section id="usingpoky-specifying-LIC_FILES_CHKSUM"> | ||
| 1502 | <title>Specifying the <filename>LIC_FILES_CHKSUM</filename> Variable</title> | ||
| 1503 | |||
| 1504 | <para> | ||
| 1505 | The <filename>LIC_FILES_CHKSUM</filename> | ||
| 1506 | variable contains checksums of the license text in the | ||
| 1507 | source code for the recipe. | ||
| 1508 | Following is an example of how to specify | ||
| 1509 | <filename>LIC_FILES_CHKSUM</filename>: | ||
| 1510 | <literallayout class='monospaced'> | ||
| 1511 | LIC_FILES_CHKSUM = "file://COPYING;md5=xxxx \ | ||
| 1512 | file://licfile1.txt;beginline=5;endline=29;md5=yyyy \ | ||
| 1513 | file://licfile2.txt;endline=50;md5=zzzz \ | ||
| 1514 | ..." | ||
| 1515 | </literallayout> | ||
| 1516 | <note><title>Notes</title> | ||
| 1517 | <itemizedlist> | ||
| 1518 | <listitem><para> | ||
| 1519 | When using "beginline" and "endline", realize | ||
| 1520 | that line numbering begins with one and not | ||
| 1521 | zero. | ||
| 1522 | Also, the included lines are inclusive (i.e. | ||
| 1523 | lines five through and including 29 in the | ||
| 1524 | previous example for | ||
| 1525 | <filename>licfile1.txt</filename>). | ||
| 1526 | </para></listitem> | ||
| 1527 | <listitem><para> | ||
| 1528 | When a license check fails, the selected license | ||
| 1529 | text is included as part of the QA message. | ||
| 1530 | Using this output, you can determine the exact | ||
| 1531 | start and finish for the needed license text. | ||
| 1532 | </para></listitem> | ||
| 1533 | </itemizedlist> | ||
| 1534 | </note> | ||
| 1535 | </para> | ||
| 1536 | |||
| 1537 | <para> | ||
| 1538 | The build system uses the | ||
| 1539 | <ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink> | ||
| 1540 | variable as the default directory when searching files | ||
| 1541 | listed in <filename>LIC_FILES_CHKSUM</filename>. | ||
| 1542 | The previous example employs the default directory. | ||
| 1543 | </para> | ||
| 1544 | |||
| 1545 | <para> | ||
| 1546 | Consider this next example: | ||
| 1547 | <literallayout class='monospaced'> | ||
| 1548 | LIC_FILES_CHKSUM = "file://src/ls.c;beginline=5;endline=16;\ | ||
| 1549 | md5=bb14ed3c4cda583abc85401304b5cd4e" | ||
| 1550 | LIC_FILES_CHKSUM = "file://${WORKDIR}/license.html;md5=5c94767cedb5d6987c902ac850ded2c6" | ||
| 1551 | </literallayout> | ||
| 1552 | </para> | ||
| 1553 | |||
| 1554 | <para> | ||
| 1555 | The first line locates a file in | ||
| 1556 | <filename>${S}/src/ls.c</filename> and isolates lines five | ||
| 1557 | through 16 as license text. | ||
| 1558 | The second line refers to a file in | ||
| 1559 | <ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>. | ||
| 1560 | </para> | ||
| 1561 | |||
| 1562 | <para> | ||
| 1563 | Note that <filename>LIC_FILES_CHKSUM</filename> variable is | ||
| 1564 | mandatory for all recipes, unless the | ||
| 1565 | <filename>LICENSE</filename> variable is set to "CLOSED". | ||
| 1566 | </para> | ||
| 1567 | </section> | ||
| 1568 | |||
| 1569 | <section id="usingpoky-LIC_FILES_CHKSUM-explanation-of-syntax"> | ||
| 1570 | <title>Explanation of Syntax</title> | ||
| 1571 | |||
| 1572 | <para> | ||
| 1573 | As mentioned in the previous section, the | ||
| 1574 | <filename>LIC_FILES_CHKSUM</filename> variable lists all | ||
| 1575 | the important files that contain the license text for the | ||
| 1576 | source code. | ||
| 1577 | It is possible to specify a checksum for an entire file, | ||
| 1578 | or a specific section of a file (specified by beginning and | ||
| 1579 | ending line numbers with the "beginline" and "endline" | ||
| 1580 | parameters, respectively). | ||
| 1581 | The latter is useful for source files with a license | ||
| 1582 | notice header, README documents, and so forth. | ||
| 1583 | If you do not use the "beginline" parameter, then it is | ||
| 1584 | assumed that the text begins on the first line of the file. | ||
| 1585 | Similarly, if you do not use the "endline" parameter, | ||
| 1586 | it is assumed that the license text ends with the last | ||
| 1587 | line of the file. | ||
| 1588 | </para> | ||
| 1589 | |||
| 1590 | <para> | ||
| 1591 | The "md5" parameter stores the md5 checksum of the license | ||
| 1592 | text. | ||
| 1593 | If the license text changes in any way as compared to | ||
| 1594 | this parameter then a mismatch occurs. | ||
| 1595 | This mismatch triggers a build failure and notifies | ||
| 1596 | the developer. | ||
| 1597 | Notification allows the developer to review and address | ||
| 1598 | the license text changes. | ||
| 1599 | Also note that if a mismatch occurs during the build, | ||
| 1600 | the correct md5 checksum is placed in the build log and | ||
| 1601 | can be easily copied to the recipe. | ||
| 1602 | </para> | ||
| 1603 | |||
| 1604 | <para> | ||
| 1605 | There is no limit to how many files you can specify using | ||
| 1606 | the <filename>LIC_FILES_CHKSUM</filename> variable. | ||
| 1607 | Generally, however, every project requires a few | ||
| 1608 | specifications for license tracking. | ||
| 1609 | Many projects have a "COPYING" file that stores the | ||
| 1610 | license information for all the source code files. | ||
| 1611 | This practice allows you to just track the "COPYING" | ||
| 1612 | file as long as it is kept up to date. | ||
| 1613 | <note><title>Tips</title> | ||
| 1614 | <itemizedlist> | ||
| 1615 | <listitem><para> | ||
| 1616 | If you specify an empty or invalid "md5" | ||
| 1617 | parameter, BitBake returns an md5 mis-match | ||
| 1618 | error and displays the correct "md5" parameter | ||
| 1619 | value during the build. | ||
| 1620 | The correct parameter is also captured in | ||
| 1621 | the build log. | ||
| 1622 | </para></listitem> | ||
| 1623 | <listitem><para> | ||
| 1624 | If the whole file contains only license text, | ||
| 1625 | you do not need to use the "beginline" and | ||
| 1626 | "endline" parameters. | ||
| 1627 | </para></listitem> | ||
| 1628 | </itemizedlist> | ||
| 1629 | </note> | ||
| 1630 | </para> | ||
| 1631 | </section> | ||
| 1632 | </section> | ||
| 1633 | |||
| 1634 | <section id="enabling-commercially-licensed-recipes"> | ||
| 1635 | <title>Enabling Commercially Licensed Recipes</title> | ||
| 1636 | |||
| 1637 | <para> | ||
| 1638 | By default, the OpenEmbedded build system disables | ||
| 1639 | components that have commercial or other special licensing | ||
| 1640 | requirements. | ||
| 1641 | Such requirements are defined on a | ||
| 1642 | recipe-by-recipe basis through the | ||
| 1643 | <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_FLAGS'><filename>LICENSE_FLAGS</filename></ulink> | ||
| 1644 | variable definition in the affected recipe. | ||
| 1645 | For instance, the | ||
| 1646 | <filename>poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly</filename> | ||
| 1647 | recipe contains the following statement: | ||
| 1648 | <literallayout class='monospaced'> | ||
| 1649 | LICENSE_FLAGS = "commercial" | ||
| 1650 | </literallayout> | ||
| 1651 | Here is a slightly more complicated example that contains both | ||
| 1652 | an explicit recipe name and version (after variable expansion): | ||
| 1653 | <literallayout class='monospaced'> | ||
| 1654 | LICENSE_FLAGS = "license_${PN}_${PV}" | ||
| 1655 | </literallayout> | ||
| 1656 | In order for a component restricted by a | ||
| 1657 | <filename>LICENSE_FLAGS</filename> definition to be enabled and | ||
| 1658 | included in an image, it needs to have a matching entry in the | ||
| 1659 | global | ||
| 1660 | <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_FLAGS_WHITELIST'><filename>LICENSE_FLAGS_WHITELIST</filename></ulink> | ||
| 1661 | variable, which is a variable typically defined in your | ||
| 1662 | <filename>local.conf</filename> file. | ||
| 1663 | For example, to enable the | ||
| 1664 | <filename>poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly</filename> | ||
| 1665 | package, you could add either the string | ||
| 1666 | "commercial_gst-plugins-ugly" or the more general string | ||
| 1667 | "commercial" to <filename>LICENSE_FLAGS_WHITELIST</filename>. | ||
| 1668 | See the | ||
| 1669 | "<link linkend='license-flag-matching'>License Flag Matching</link>" | ||
| 1670 | section for a full | ||
| 1671 | explanation of how <filename>LICENSE_FLAGS</filename> matching | ||
| 1672 | works. | ||
| 1673 | Here is the example: | ||
| 1674 | <literallayout class='monospaced'> | ||
| 1675 | LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly" | ||
| 1676 | </literallayout> | ||
| 1677 | Likewise, to additionally enable the package built from the | ||
| 1678 | recipe containing | ||
| 1679 | <filename>LICENSE_FLAGS = "license_${PN}_${PV}"</filename>, | ||
| 1680 | and assuming that the actual recipe name was | ||
| 1681 | <filename>emgd_1.10.bb</filename>, the following string would | ||
| 1682 | enable that package as well as the original | ||
| 1683 | <filename>gst-plugins-ugly</filename> package: | ||
| 1684 | <literallayout class='monospaced'> | ||
| 1685 | LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly license_emgd_1.10" | ||
| 1686 | </literallayout> | ||
| 1687 | As a convenience, you do not need to specify the complete | ||
| 1688 | license string in the whitelist for every package. | ||
| 1689 | You can use an abbreviated form, which consists | ||
| 1690 | of just the first portion or portions of the license | ||
| 1691 | string before the initial underscore character or characters. | ||
| 1692 | A partial string will match any license that contains the | ||
| 1693 | given string as the first portion of its license. | ||
| 1694 | For example, the following whitelist string will also match | ||
| 1695 | both of the packages previously mentioned as well as any other | ||
| 1696 | packages that have licenses starting with "commercial" or | ||
| 1697 | "license". | ||
| 1698 | <literallayout class='monospaced'> | ||
| 1699 | LICENSE_FLAGS_WHITELIST = "commercial license" | ||
| 1700 | </literallayout> | ||
| 1701 | </para> | ||
| 1702 | |||
| 1703 | <section id="license-flag-matching"> | ||
| 1704 | <title>License Flag Matching</title> | ||
| 1705 | |||
| 1706 | <para> | ||
| 1707 | License flag matching allows you to control what recipes | ||
| 1708 | the OpenEmbedded build system includes in the build. | ||
| 1709 | Fundamentally, the build system attempts to match | ||
| 1710 | <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_FLAGS'><filename>LICENSE_FLAGS</filename></ulink> | ||
| 1711 | strings found in recipes against | ||
| 1712 | <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_FLAGS_WHITELIST'><filename>LICENSE_FLAGS_WHITELIST</filename></ulink> | ||
| 1713 | strings found in the whitelist. | ||
| 1714 | A match causes the build system to include a recipe in the | ||
| 1715 | build, while failure to find a match causes the build | ||
| 1716 | system to exclude a recipe. | ||
| 1717 | </para> | ||
| 1718 | |||
| 1719 | <para> | ||
| 1720 | In general, license flag matching is simple. | ||
| 1721 | However, understanding some concepts will help you | ||
| 1722 | correctly and effectively use matching. | ||
| 1723 | </para> | ||
| 1724 | |||
| 1725 | <para> | ||
| 1726 | Before a flag | ||
| 1727 | defined by a particular recipe is tested against the | ||
| 1728 | contents of the whitelist, the expanded string | ||
| 1729 | <filename>_${PN}</filename> is appended to the flag. | ||
| 1730 | This expansion makes each | ||
| 1731 | <filename>LICENSE_FLAGS</filename> value recipe-specific. | ||
| 1732 | After expansion, the string is then matched against the | ||
| 1733 | whitelist. | ||
| 1734 | Thus, specifying | ||
| 1735 | <filename>LICENSE_FLAGS = "commercial"</filename> | ||
| 1736 | in recipe "foo", for example, results in the string | ||
| 1737 | <filename>"commercial_foo"</filename>. | ||
| 1738 | And, to create a match, that string must appear in the | ||
| 1739 | whitelist. | ||
| 1740 | </para> | ||
| 1741 | |||
| 1742 | <para> | ||
| 1743 | Judicious use of the <filename>LICENSE_FLAGS</filename> | ||
| 1744 | strings and the contents of the | ||
| 1745 | <filename>LICENSE_FLAGS_WHITELIST</filename> variable | ||
| 1746 | allows you a lot of flexibility for including or excluding | ||
| 1747 | recipes based on licensing. | ||
| 1748 | For example, you can broaden the matching capabilities by | ||
| 1749 | using license flags string subsets in the whitelist. | ||
| 1750 | <note> | ||
| 1751 | When using a string subset, be sure to use the part of | ||
| 1752 | the expanded string that precedes the appended | ||
| 1753 | underscore character (e.g. | ||
| 1754 | <filename>usethispart_1.3</filename>, | ||
| 1755 | <filename>usethispart_1.4</filename>, and so forth). | ||
| 1756 | </note> | ||
| 1757 | For example, simply specifying the string "commercial" in | ||
| 1758 | the whitelist matches any expanded | ||
| 1759 | <filename>LICENSE_FLAGS</filename> definition that starts | ||
| 1760 | with the string "commercial" such as "commercial_foo" and | ||
| 1761 | "commercial_bar", which are the strings the build system | ||
| 1762 | automatically generates for hypothetical recipes named | ||
| 1763 | "foo" and "bar" assuming those recipes simply specify the | ||
| 1764 | following: | ||
| 1765 | <literallayout class='monospaced'> | ||
| 1766 | LICENSE_FLAGS = "commercial" | ||
| 1767 | </literallayout> | ||
| 1768 | Thus, you can choose to exhaustively | ||
| 1769 | enumerate each license flag in the whitelist and | ||
| 1770 | allow only specific recipes into the image, or | ||
| 1771 | you can use a string subset that causes a broader range of | ||
| 1772 | matches to allow a range of recipes into the image. | ||
| 1773 | </para> | ||
| 1774 | |||
| 1775 | <para> | ||
| 1776 | This scheme works even if the | ||
| 1777 | <filename>LICENSE_FLAGS</filename> string already | ||
| 1778 | has <filename>_${PN}</filename> appended. | ||
| 1779 | For example, the build system turns the license flag | ||
| 1780 | "commercial_1.2_foo" into "commercial_1.2_foo_foo" and | ||
| 1781 | would match both the general "commercial" and the specific | ||
| 1782 | "commercial_1.2_foo" strings found in the whitelist, as | ||
| 1783 | expected. | ||
| 1784 | </para> | ||
| 1785 | |||
| 1786 | <para> | ||
| 1787 | Here are some other scenarios: | ||
| 1788 | <itemizedlist> | ||
| 1789 | <listitem><para> | ||
| 1790 | You can specify a versioned string in the recipe | ||
| 1791 | such as "commercial_foo_1.2" in a "foo" recipe. | ||
| 1792 | The build system expands this string to | ||
| 1793 | "commercial_foo_1.2_foo". | ||
| 1794 | Combine this license flag with a whitelist that has | ||
| 1795 | the string "commercial" and you match the flag | ||
| 1796 | along with any other flag that starts with the | ||
| 1797 | string "commercial". | ||
| 1798 | </para></listitem> | ||
| 1799 | <listitem><para> | ||
| 1800 | Under the same circumstances, you can use | ||
| 1801 | "commercial_foo" in the whitelist and the build | ||
| 1802 | system not only matches "commercial_foo_1.2" but | ||
| 1803 | also matches any license flag with the string | ||
| 1804 | "commercial_foo", regardless of the version. | ||
| 1805 | </para></listitem> | ||
| 1806 | <listitem><para> | ||
| 1807 | You can be very specific and use both the | ||
| 1808 | package and version parts in the whitelist (e.g. | ||
| 1809 | "commercial_foo_1.2") to specifically match a | ||
| 1810 | versioned recipe. | ||
| 1811 | </para></listitem> | ||
| 1812 | </itemizedlist> | ||
| 1813 | </para> | ||
| 1814 | </section> | ||
| 1815 | |||
| 1816 | <section id="other-variables-related-to-commercial-licenses"> | ||
| 1817 | <title>Other Variables Related to Commercial Licenses</title> | ||
| 1818 | |||
| 1819 | <para> | ||
| 1820 | Other helpful variables related to commercial | ||
| 1821 | license handling exist and are defined in the | ||
| 1822 | <filename>poky/meta/conf/distro/include/default-distrovars.inc</filename> file: | ||
| 1823 | <literallayout class='monospaced'> | ||
| 1824 | COMMERCIAL_AUDIO_PLUGINS ?= "" | ||
| 1825 | COMMERCIAL_VIDEO_PLUGINS ?= "" | ||
| 1826 | </literallayout> | ||
| 1827 | If you want to enable these components, you can do so by | ||
| 1828 | making sure you have statements similar to the following | ||
| 1829 | in your <filename>local.conf</filename> configuration file: | ||
| 1830 | <literallayout class='monospaced'> | ||
| 1831 | COMMERCIAL_AUDIO_PLUGINS = "gst-plugins-ugly-mad \ | ||
| 1832 | gst-plugins-ugly-mpegaudioparse" | ||
| 1833 | COMMERCIAL_VIDEO_PLUGINS = "gst-plugins-ugly-mpeg2dec \ | ||
| 1834 | gst-plugins-ugly-mpegstream gst-plugins-bad-mpegvideoparse" | ||
| 1835 | LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly commercial_gst-plugins-bad commercial_qmmp" | ||
| 1836 | </literallayout> | ||
| 1837 | Of course, you could also create a matching whitelist | ||
| 1838 | for those components using the more general "commercial" | ||
| 1839 | in the whitelist, but that would also enable all the | ||
| 1840 | other packages with | ||
| 1841 | <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_FLAGS'><filename>LICENSE_FLAGS</filename></ulink> | ||
| 1842 | containing "commercial", which you may or may not want: | ||
| 1843 | <literallayout class='monospaced'> | ||
| 1844 | LICENSE_FLAGS_WHITELIST = "commercial" | ||
| 1845 | </literallayout> | ||
| 1846 | </para> | ||
| 1847 | |||
| 1848 | <para> | ||
| 1849 | Specifying audio and video plug-ins as part of the | ||
| 1850 | <filename>COMMERCIAL_AUDIO_PLUGINS</filename> and | ||
| 1851 | <filename>COMMERCIAL_VIDEO_PLUGINS</filename> statements | ||
| 1852 | (along with the enabling | ||
| 1853 | <filename>LICENSE_FLAGS_WHITELIST</filename>) includes the | ||
| 1854 | plug-ins or components into built images, thus adding | ||
| 1855 | support for media formats or components. | ||
| 1856 | </para> | ||
| 1857 | </section> | ||
| 1858 | </section> | ||
| 1859 | </section> | ||
| 1860 | |||
| 1861 | <section id='x32'> | ||
| 1862 | <title>x32 psABI</title> | ||
| 1863 | |||
| 1864 | <para> | ||
| 1865 | x32 processor-specific Application Binary Interface | ||
| 1866 | (<ulink url='https://software.intel.com/en-us/node/628948'>x32 psABI</ulink>) | ||
| 1867 | is a native 32-bit processor-specific ABI for | ||
| 1868 | <trademark class='registered'>Intel</trademark> 64 (x86-64) | ||
| 1869 | architectures. | ||
| 1870 | An ABI defines the calling conventions between functions in a | ||
| 1871 | processing environment. | ||
| 1872 | The interface determines what registers are used and what the sizes are | ||
| 1873 | for various C data types. | ||
| 1874 | </para> | ||
| 1875 | |||
| 1876 | <para> | ||
| 1877 | Some processing environments prefer using 32-bit applications even | ||
| 1878 | when running on Intel 64-bit platforms. | ||
| 1879 | Consider the i386 psABI, which is a very old 32-bit ABI for Intel | ||
| 1880 | 64-bit platforms. | ||
| 1881 | The i386 psABI does not provide efficient use and access of the | ||
| 1882 | Intel 64-bit processor resources, leaving the system underutilized. | ||
| 1883 | Now consider the x86_64 psABI. | ||
| 1884 | This ABI is newer and uses 64-bits for data sizes and program | ||
| 1885 | pointers. | ||
| 1886 | The extra bits increase the footprint size of the programs, | ||
| 1887 | libraries, and also increases the memory and file system size | ||
| 1888 | requirements. | ||
| 1889 | Executing under the x32 psABI enables user programs to utilize CPU | ||
| 1890 | and system resources more efficiently while keeping the memory | ||
| 1891 | footprint of the applications low. | ||
| 1892 | Extra bits are used for registers but not for addressing mechanisms. | ||
| 1893 | </para> | ||
| 1894 | |||
| 1895 | <para> | ||
| 1896 | The Yocto Project supports the final specifications of x32 psABI | ||
| 1897 | as follows: | ||
| 1898 | <itemizedlist> | ||
| 1899 | <listitem><para> | ||
| 1900 | You can create packages and images in x32 psABI format on | ||
| 1901 | x86_64 architecture targets. | ||
| 1902 | </para></listitem> | ||
| 1903 | <listitem><para> | ||
| 1904 | You can successfully build recipes with the x32 toolchain. | ||
| 1905 | </para></listitem> | ||
| 1906 | <listitem><para> | ||
| 1907 | You can create and boot | ||
| 1908 | <filename>core-image-minimal</filename> and | ||
| 1909 | <filename>core-image-sato</filename> images. | ||
| 1910 | </para></listitem> | ||
| 1911 | <listitem><para> | ||
| 1912 | RPM Package Manager (RPM) support exists for x32 binaries. | ||
| 1913 | </para></listitem> | ||
| 1914 | <listitem><para> | ||
| 1915 | Support for large images exists. | ||
| 1916 | </para></listitem> | ||
| 1917 | </itemizedlist> | ||
| 1918 | </para> | ||
| 1919 | |||
| 1920 | <para> | ||
| 1921 | For steps on how to use x32 psABI, see the | ||
| 1922 | "<ulink url='&YOCTO_DOCS_DEV_URL;#using-x32-psabi'>Using x32 psABI</ulink>" | ||
| 1923 | section in the Yocto Project Development Tasks Manual. | ||
| 1924 | </para> | ||
| 1925 | </section> | ||
| 1926 | </chapter> | ||
| 1927 | <!-- | ||
| 1928 | vim: expandtab tw=80 ts=4 | ||
| 1929 | --> | ||
diff --git a/documentation/getting-started/getting-started-customization.xsl b/documentation/getting-started/getting-started-customization.xsl new file mode 100644 index 0000000000..9733bf87b2 --- /dev/null +++ b/documentation/getting-started/getting-started-customization.xsl | |||
| @@ -0,0 +1,27 @@ | |||
| 1 | <?xml version='1.0'?> | ||
| 2 | <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns="http://www.w3.org/1999/xhtml" xmlns:fo="http://www.w3.org/1999/XSL/Format" version="1.0"> | ||
| 3 | |||
| 4 | <xsl:import href="http://downloads.yoctoproject.org/mirror/docbook-mirror/docbook-xsl-1.76.1/xhtml/docbook.xsl" /> | ||
| 5 | |||
| 6 | <!-- | ||
| 7 | |||
| 8 | <xsl:import href="../template/1.76.1/docbook-xsl-1.76.1/xhtml/docbook.xsl" /> | ||
| 9 | |||
| 10 | <xsl:import href="http://docbook.sourceforge.net/release/xsl/1.76.1/xhtml/docbook.xsl" /> | ||
| 11 | |||
| 12 | --> | ||
| 13 | |||
| 14 | <xsl:include href="../template/permalinks.xsl"/> | ||
| 15 | <xsl:include href="../template/section.title.xsl"/> | ||
| 16 | <xsl:include href="../template/component.title.xsl"/> | ||
| 17 | <xsl:include href="../template/division.title.xsl"/> | ||
| 18 | <xsl:include href="../template/formal.object.heading.xsl"/> | ||
| 19 | |||
| 20 | <xsl:param name="html.stylesheet" select="'getting-started-style.css'" /> | ||
| 21 | <xsl:param name="chapter.autolabel" select="1" /> | ||
| 22 | <xsl:param name="appendix.autolabel" select="A" /> | ||
| 23 | <xsl:param name="section.autolabel" select="1" /> | ||
| 24 | <xsl:param name="section.label.includes.component.label" select="1" /> | ||
| 25 | <xsl:param name="generate.id.attributes" select="1" /> | ||
| 26 | |||
| 27 | </xsl:stylesheet> | ||
diff --git a/documentation/getting-started/getting-started-development-environment.xml b/documentation/getting-started/getting-started-development-environment.xml new file mode 100644 index 0000000000..7d177cecca --- /dev/null +++ b/documentation/getting-started/getting-started-development-environment.xml | |||
| @@ -0,0 +1,2890 @@ | |||
| 1 | <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" | ||
| 2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" | ||
| 3 | [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > | ||
| 4 | |||
| 5 | <chapter id='overview-development-environment'> | ||
| 6 | <title>The Yocto Project Development Environment</title> | ||
| 7 | |||
| 8 | <para> | ||
| 9 | This chapter takes a look at the Yocto Project development | ||
| 10 | environment and also provides a detailed look at what goes on during | ||
| 11 | development in that environment. | ||
| 12 | The chapter provides Yocto Project Development environment concepts that | ||
| 13 | help you understand how work is accomplished in an open source environment, | ||
| 14 | which is very different as compared to work accomplished in a closed, | ||
| 15 | proprietary environment. | ||
| 16 | </para> | ||
| 17 | |||
| 18 | <para> | ||
| 19 | Specifically, this chapter addresses open source philosophy, workflows, | ||
| 20 | Git, source repositories, licensing, recipe syntax, and development | ||
| 21 | syntax. | ||
| 22 | </para> | ||
| 23 | |||
| 24 | <section id='yp-intro'> | ||
| 25 | <title>Introduction</title> | ||
| 26 | |||
| 27 | <para> | ||
| 28 | The Yocto Project is an open-source collaboration project whose | ||
| 29 | focus is for developers of embedded Linux systems. | ||
| 30 | Among other things, the Yocto Project uses an | ||
| 31 | <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink>. | ||
| 32 | The build system, which is based on the OpenEmbedded (OE) project and | ||
| 33 | uses the | ||
| 34 | <ulink url='&YOCTO_DOCS_REF_URL;#bitbake-term'>BitBake</ulink> tool, | ||
| 35 | constructs complete Linux images for architectures based on ARM, MIPS, | ||
| 36 | PowerPC, x86 and x86-64. | ||
| 37 | <note> | ||
| 38 | Historically, the OpenEmbedded build system, which is the | ||
| 39 | combination of BitBake and OE components, formed a reference | ||
| 40 | build host that was known as | ||
| 41 | "<ulink url='&YOCTO_DOCS_REF_URL;#poky'>Poky</ulink>" | ||
| 42 | (<emphasis>Pah</emphasis>-kee). | ||
| 43 | The term "Poky", as used throughout the Yocto Project Documentation | ||
| 44 | set, can have different meanings. | ||
| 45 | </note> | ||
| 46 | The Yocto Project provides various ancillary tools for the embedded | ||
| 47 | developer and also features the Sato reference User Interface, which | ||
| 48 | is optimized for stylus-driven, low-resolution screens. | ||
| 49 | </para> | ||
| 50 | |||
| 51 | <mediaobject> | ||
| 52 | <imageobject> | ||
| 53 | <imagedata fileref="figures/YP-flow-diagram.png" | ||
| 54 | format="PNG" align='center' width="8in"/> | ||
| 55 | </imageobject> | ||
| 56 | </mediaobject> | ||
| 57 | |||
| 58 | <para> | ||
| 59 | Here are some highlights for the Yocto Project: | ||
| 60 | </para> | ||
| 61 | |||
| 62 | <itemizedlist> | ||
| 63 | <listitem><para> | ||
| 64 | Provides a recent Linux kernel along with a set of system | ||
| 65 | commands and libraries suitable for the embedded | ||
| 66 | environment. | ||
| 67 | </para></listitem> | ||
| 68 | <listitem><para> | ||
| 69 | Makes available system components such as X11, GTK+, Qt, | ||
| 70 | Clutter, and SDL (among others) so you can create a rich user | ||
| 71 | experience on devices that have display hardware. | ||
| 72 | For devices that do not have a display or where you wish to | ||
| 73 | use alternative UI frameworks, these components need not be | ||
| 74 | installed. | ||
| 75 | </para></listitem> | ||
| 76 | <listitem><para> | ||
| 77 | Creates a focused and stable core compatible with the | ||
| 78 | OpenEmbedded project with which you can easily and reliably | ||
| 79 | build and develop. | ||
| 80 | </para></listitem> | ||
| 81 | <listitem><para> | ||
| 82 | Fully supports a wide range of hardware and device emulation | ||
| 83 | through the Quick EMUlator (QEMU). | ||
| 84 | </para></listitem> | ||
| 85 | <listitem><para> | ||
| 86 | Provides a layer mechanism that allows you to easily extend | ||
| 87 | the system, make customizations, and keep them organized. | ||
| 88 | </para></listitem> | ||
| 89 | </itemizedlist> | ||
| 90 | |||
| 91 | <para> | ||
| 92 | You can use the Yocto Project to generate images for many kinds | ||
| 93 | of devices. | ||
| 94 | As mentioned earlier, the Yocto Project supports creation of | ||
| 95 | reference images that you can boot within and emulate using QEMU. | ||
| 96 | The standard example machines target QEMU full-system | ||
| 97 | emulation for 32-bit and 64-bit variants of x86, ARM, MIPS, and | ||
| 98 | PowerPC architectures. | ||
| 99 | Beyond emulation, you can use the layer mechanism to extend | ||
| 100 | support to just about any platform that Linux can run on and that | ||
| 101 | a toolchain can target. | ||
| 102 | </para> | ||
| 103 | |||
| 104 | <para> | ||
| 105 | Another Yocto Project feature is the Sato reference User | ||
| 106 | Interface. | ||
| 107 | This optional UI that is based on GTK+ is intended for devices with | ||
| 108 | restricted screen sizes and is included as part of the | ||
| 109 | OpenEmbedded Core layer so that developers can test parts of the | ||
| 110 | software stack. | ||
| 111 | </para> | ||
| 112 | |||
| 113 | <para> | ||
| 114 | While the Yocto Project does not provide a strict testing framework, | ||
| 115 | it does provide or generate for you artifacts that let you perform | ||
| 116 | target-level and emulated testing and debugging. | ||
| 117 | Additionally, if you are an | ||
| 118 | <trademark class='trade'>Eclipse</trademark> IDE user, you can | ||
| 119 | install an Eclipse Yocto Plug-in to allow you to develop within that | ||
| 120 | familiar environment. | ||
| 121 | </para> | ||
| 122 | |||
| 123 | <para> | ||
| 124 | By default, using the Yocto Project to build an image creates a Poky | ||
| 125 | distribution. | ||
| 126 | However, you can create your own distribution by providing key | ||
| 127 | <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink>. | ||
| 128 | A good example is Angstrom, which has had a distribution | ||
| 129 | based on the Yocto Project since its inception. | ||
| 130 | Other examples include commercial distributions like | ||
| 131 | <ulink url='https://www.yoctoproject.org/organization/wind-river-systems'>Wind River Linux</ulink>, | ||
| 132 | <ulink url='https://www.yoctoproject.org/organization/mentor-graphics'>Mentor Embedded Linux</ulink>, | ||
| 133 | <ulink url='https://www.yoctoproject.org/organization/enea-ab'>ENEA Linux</ulink> | ||
| 134 | and <ulink url='https://www.yoctoproject.org/ecosystem/member-organizations'>others</ulink>. | ||
| 135 | See the "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-your-own-distribution'>Creating Your Own Distribution</ulink>" | ||
| 136 | section in the Yocto Project Development Tasks Manual for more | ||
| 137 | information. | ||
| 138 | </para> | ||
| 139 | </section> | ||
| 140 | |||
| 141 | <section id='open-source-philosophy'> | ||
| 142 | <title>Open Source Philosophy</title> | ||
| 143 | |||
| 144 | <para> | ||
| 145 | Open source philosophy is characterized by software development | ||
| 146 | directed by peer production and collaboration through an active | ||
| 147 | community of developers. | ||
| 148 | Contrast this to the more standard centralized development models | ||
| 149 | used by commercial software companies where a finite set of developers | ||
| 150 | produces a product for sale using a defined set of procedures that | ||
| 151 | ultimately result in an end product whose architecture and source | ||
| 152 | material are closed to the public. | ||
| 153 | </para> | ||
| 154 | |||
| 155 | <para> | ||
| 156 | Open source projects conceptually have differing concurrent agendas, | ||
| 157 | approaches, and production. | ||
| 158 | These facets of the development process can come from anyone in the | ||
| 159 | public (community) that has a stake in the software project. | ||
| 160 | The open source environment contains new copyright, licensing, domain, | ||
| 161 | and consumer issues that differ from the more traditional development | ||
| 162 | environment. | ||
| 163 | In an open source environment, the end product, source material, | ||
| 164 | and documentation are all available to the public at no cost. | ||
| 165 | </para> | ||
| 166 | |||
| 167 | <para> | ||
| 168 | A benchmark example of an open source project is the Linux kernel, | ||
| 169 | which was initially conceived and created by Finnish computer science | ||
| 170 | student Linus Torvalds in 1991. | ||
| 171 | Conversely, a good example of a non-open source project is the | ||
| 172 | <trademark class='registered'>Windows</trademark> family of operating | ||
| 173 | systems developed by | ||
| 174 | <trademark class='registered'>Microsoft</trademark> Corporation. | ||
| 175 | </para> | ||
| 176 | |||
| 177 | <para> | ||
| 178 | Wikipedia has a good historical description of the Open Source | ||
| 179 | Philosophy | ||
| 180 | <ulink url='http://en.wikipedia.org/wiki/Open_source'>here</ulink>. | ||
| 181 | You can also find helpful information on how to participate in the | ||
| 182 | Linux Community | ||
| 183 | <ulink url='http://ldn.linuxfoundation.org/book/how-participate-linux-community'>here</ulink>. | ||
| 184 | </para> | ||
| 185 | </section> | ||
| 186 | |||
| 187 | <section id='workflows'> | ||
| 188 | <title>Workflows</title> | ||
| 189 | |||
| 190 | <para> | ||
| 191 | This section provides workflow concepts using the Yocto Project and | ||
| 192 | Git. | ||
| 193 | In particular, the information covers basic practices that describe | ||
| 194 | roles and actions in a collaborative development environment. | ||
| 195 | <note> | ||
| 196 | If you are familiar with this type of development environment, you | ||
| 197 | might not want to read this section. | ||
| 198 | </note> | ||
| 199 | </para> | ||
| 200 | |||
| 201 | <para> | ||
| 202 | The Yocto Project files are maintained using Git in "master" | ||
| 203 | branches whose Git histories track every change and whose structures | ||
| 204 | provides branches for all diverging functionality. | ||
| 205 | Although there is no need to use Git, many open source projects do so. | ||
| 206 | <para> | ||
| 207 | |||
| 208 | </para> | ||
| 209 | For the Yocto Project, a key individual called the "maintainer" is | ||
| 210 | responsible for the "master" branch of a given Git repository. | ||
| 211 | The "master" branch is the “upstream” repository from which final or | ||
| 212 | most recent builds of the project occur. | ||
| 213 | The maintainer is responsible for accepting changes from other | ||
| 214 | developers and for organizing the underlying branch structure to | ||
| 215 | reflect release strategies and so forth. | ||
| 216 | <note>For information on finding out who is responsible for (maintains) | ||
| 217 | a particular area of code, see the | ||
| 218 | "<ulink url='&YOCTO_DOCS_DEV_URL;#how-to-submit-a-change'>Submitting a Change to the Yocto Project</ulink>" | ||
| 219 | section of the Yocto Project Development Tasks Manual. | ||
| 220 | </note> | ||
| 221 | </para> | ||
| 222 | |||
| 223 | <para> | ||
| 224 | The Yocto Project <filename>poky</filename> Git repository also has an | ||
| 225 | upstream contribution Git repository named | ||
| 226 | <filename>poky-contrib</filename>. | ||
| 227 | You can see all the branches in this repository using the web interface | ||
| 228 | of the | ||
| 229 | <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink> organized | ||
| 230 | within the "Poky Support" area. | ||
| 231 | These branches temporarily hold changes to the project that have been | ||
| 232 | submitted or committed by the Yocto Project development team and by | ||
| 233 | community members who contribute to the project. | ||
| 234 | The maintainer determines if the changes are qualified to be moved | ||
| 235 | from the "contrib" branches into the "master" branch of the Git | ||
| 236 | repository. | ||
| 237 | </para> | ||
| 238 | |||
| 239 | <para> | ||
| 240 | Developers (including contributing community members) create and | ||
| 241 | maintain cloned repositories of the upstream "master" branch. | ||
| 242 | The cloned repositories are local to their development platforms and | ||
| 243 | are used to develop changes. | ||
| 244 | When a developer is satisfied with a particular feature or change, | ||
| 245 | they "push" the changes to the appropriate "contrib" repository. | ||
| 246 | </para> | ||
| 247 | |||
| 248 | <para> | ||
| 249 | Developers are responsible for keeping their local repository | ||
| 250 | up-to-date with "master". | ||
| 251 | They are also responsible for straightening out any conflicts that | ||
| 252 | might arise within files that are being worked on simultaneously by | ||
| 253 | more than one person. | ||
| 254 | All this work is done locally on the developer’s machine before | ||
| 255 | anything is pushed to a "contrib" area and examined at the maintainer’s | ||
| 256 | level. | ||
| 257 | </para> | ||
| 258 | |||
| 259 | <para> | ||
| 260 | A somewhat formal method exists by which developers commit changes | ||
| 261 | and push them into the "contrib" area and subsequently request that | ||
| 262 | the maintainer include them into "master". | ||
| 263 | This process is called “submitting a patch” or "submitting a change." | ||
| 264 | For information on submitting patches and changes, see the | ||
| 265 | "<ulink url='&YOCTO_DOCS_DEV_URL;#how-to-submit-a-change'>Submitting a Change to the Yocto Project</ulink>" | ||
| 266 | section in the Yocto Project Development Tasks Manual. | ||
| 267 | </para> | ||
| 268 | |||
| 269 | <para> | ||
| 270 | To summarize the development workflow: a single point of entry | ||
| 271 | exists for changes into the project’s "master" branch of the | ||
| 272 | Git repository, which is controlled by the project’s maintainer. | ||
| 273 | And, a set of developers exist who independently develop, test, and | ||
| 274 | submit changes to "contrib" areas for the maintainer to examine. | ||
| 275 | The maintainer then chooses which changes are going to become a | ||
| 276 | permanent part of the project. | ||
| 277 | </para> | ||
| 278 | |||
| 279 | <para> | ||
| 280 | <imagedata fileref="figures/git-workflow.png" width="6in" depth="3in" align="left" scalefit="1" /> | ||
| 281 | </para> | ||
| 282 | |||
| 283 | <para> | ||
| 284 | While each development environment is unique, there are some best | ||
| 285 | practices or methods that help development run smoothly. | ||
| 286 | The following list describes some of these practices. | ||
| 287 | For more information about Git workflows, see the workflow topics in | ||
| 288 | the | ||
| 289 | <ulink url='http://book.git-scm.com'>Git Community Book</ulink>. | ||
| 290 | <itemizedlist> | ||
| 291 | <listitem><para> | ||
| 292 | <emphasis>Make Small Changes:</emphasis> | ||
| 293 | It is best to keep the changes you commit small as compared to | ||
| 294 | bundling many disparate changes into a single commit. | ||
| 295 | This practice not only keeps things manageable but also allows | ||
| 296 | the maintainer to more easily include or refuse changes.</para> | ||
| 297 | |||
| 298 | <para>It is also good practice to leave the repository in a | ||
| 299 | state that allows you to still successfully build your project. | ||
| 300 | In other words, do not commit half of a feature, | ||
| 301 | then add the other half as a separate, later commit. | ||
| 302 | Each commit should take you from one buildable project state | ||
| 303 | to another buildable state. | ||
| 304 | </para></listitem> | ||
| 305 | <listitem><para> | ||
| 306 | <emphasis>Use Branches Liberally:</emphasis> | ||
| 307 | It is very easy to create, use, and delete local branches in | ||
| 308 | your working Git repository. | ||
| 309 | You can name these branches anything you like. | ||
| 310 | It is helpful to give them names associated with the particular | ||
| 311 | feature or change on which you are working. | ||
| 312 | Once you are done with a feature or change and have merged it | ||
| 313 | into your local master branch, simply discard the temporary | ||
| 314 | branch. | ||
| 315 | </para></listitem> | ||
| 316 | <listitem><para> | ||
| 317 | <emphasis>Merge Changes:</emphasis> | ||
| 318 | The <filename>git merge</filename> command allows you to take | ||
| 319 | the changes from one branch and fold them into another branch. | ||
| 320 | This process is especially helpful when more than a single | ||
| 321 | developer might be working on different parts of the same | ||
| 322 | feature. | ||
| 323 | Merging changes also automatically identifies any collisions | ||
| 324 | or "conflicts" that might happen as a result of the same lines | ||
| 325 | of code being altered by two different developers. | ||
| 326 | </para></listitem> | ||
| 327 | <listitem><para> | ||
| 328 | <emphasis>Manage Branches:</emphasis> | ||
| 329 | Because branches are easy to use, you should use a system | ||
| 330 | where branches indicate varying levels of code readiness. | ||
| 331 | For example, you can have a "work" branch to develop in, a | ||
| 332 | "test" branch where the code or change is tested, a "stage" | ||
| 333 | branch where changes are ready to be committed, and so forth. | ||
| 334 | As your project develops, you can merge code across the | ||
| 335 | branches to reflect ever-increasing stable states of the | ||
| 336 | development. | ||
| 337 | </para></listitem> | ||
| 338 | <listitem><para> | ||
| 339 | <emphasis>Use Push and Pull:</emphasis> | ||
| 340 | The push-pull workflow is based on the concept of developers | ||
| 341 | "pushing" local commits to a remote repository, which is | ||
| 342 | usually a contribution repository. | ||
| 343 | This workflow is also based on developers "pulling" known | ||
| 344 | states of the project down into their local development | ||
| 345 | repositories. | ||
| 346 | The workflow easily allows you to pull changes submitted by | ||
| 347 | other developers from the upstream repository into your | ||
| 348 | work area ensuring that you have the most recent software | ||
| 349 | on which to develop. | ||
| 350 | The Yocto Project has two scripts named | ||
| 351 | <filename>create-pull-request</filename> and | ||
| 352 | <filename>send-pull-request</filename> that ship with the | ||
| 353 | release to facilitate this workflow. | ||
| 354 | You can find these scripts in the <filename>scripts</filename> | ||
| 355 | folder of the | ||
| 356 | <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>. | ||
| 357 | For information on how to use these scripts, see the | ||
| 358 | "<ulink url='&YOCTO_DOCS_DEV_URL;#pushing-a-change-upstream'>Using Scripts to Push a Change Upstream and Request a Pull</ulink>" | ||
| 359 | section in the Yocto Project Development Tasks Manual. | ||
| 360 | </para></listitem> | ||
| 361 | <listitem><para> | ||
| 362 | <emphasis>Patch Workflow:</emphasis> | ||
| 363 | This workflow allows you to notify the maintainer through an | ||
| 364 | email that you have a change (or patch) you would like | ||
| 365 | considered for the "master" branch of the Git repository. | ||
| 366 | To send this type of change, you format the patch and then | ||
| 367 | send the email using the Git commands | ||
| 368 | <filename>git format-patch</filename> and | ||
| 369 | <filename>git send-email</filename>. | ||
| 370 | For information on how to use these scripts, see the | ||
| 371 | "<ulink url='&YOCTO_DOCS_DEV_URL;#how-to-submit-a-change'>Submitting a Change to the Yocto Project</ulink>" | ||
| 372 | section in the Yocto Project Development Tasks Manual. | ||
| 373 | </para></listitem> | ||
| 374 | </itemizedlist> | ||
| 375 | </para> | ||
| 376 | </section> | ||
| 377 | |||
| 378 | <section id='git'> | ||
| 379 | <title>Git</title> | ||
| 380 | |||
| 381 | <para> | ||
| 382 | The Yocto Project makes extensive use of Git, which is a | ||
| 383 | free, open source distributed version control system. | ||
| 384 | Git supports distributed development, non-linear development, | ||
| 385 | and can handle large projects. | ||
| 386 | It is best that you have some fundamental understanding | ||
| 387 | of how Git tracks projects and how to work with Git if | ||
| 388 | you are going to use the Yocto Project for development. | ||
| 389 | This section provides a quick overview of how Git works and | ||
| 390 | provides you with a summary of some essential Git commands. | ||
| 391 | <note><title>Notes</title> | ||
| 392 | <itemizedlist> | ||
| 393 | <listitem><para> | ||
| 394 | For more information on Git, see | ||
| 395 | <ulink url='http://git-scm.com/documentation'></ulink>. | ||
| 396 | </para></listitem> | ||
| 397 | <listitem><para> | ||
| 398 | If you need to download Git, it is recommended that you add | ||
| 399 | Git to your system through your distribution's "software | ||
| 400 | store" (e.g. for Ubuntu, use the Ubuntu Software feature). | ||
| 401 | For the Git download page, see | ||
| 402 | <ulink url='http://git-scm.com/download'></ulink>. | ||
| 403 | </para></listitem> | ||
| 404 | <listitem><para> | ||
| 405 | For examples beyond the limited few in this section on how | ||
| 406 | to use Git with the Yocto Project, see the | ||
| 407 | "<ulink url='&YOCTO_DOCS_DEV_URL;#working-with-yocto-project-source-files'>Working With Yocto Project Source Files</ulink>" | ||
| 408 | section in the Yocto Project Development Tasks Manual. | ||
| 409 | </para></listitem> | ||
| 410 | </itemizedlist> | ||
| 411 | </note> | ||
| 412 | </para> | ||
| 413 | |||
| 414 | <section id='repositories-tags-and-branches'> | ||
| 415 | <title>Repositories, Tags, and Branches</title> | ||
| 416 | |||
| 417 | <para> | ||
| 418 | As mentioned briefly in the previous section and also in the | ||
| 419 | "<link linkend='workflows'>Workflows</link>" section, | ||
| 420 | the Yocto Project maintains source repositories at | ||
| 421 | <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>. | ||
| 422 | If you look at this web-interface of the repositories, each item | ||
| 423 | is a separate Git repository. | ||
| 424 | </para> | ||
| 425 | |||
| 426 | <para> | ||
| 427 | Git repositories use branching techniques that track content | ||
| 428 | change (not files) within a project (e.g. a new feature or updated | ||
| 429 | documentation). | ||
| 430 | Creating a tree-like structure based on project divergence allows | ||
| 431 | for excellent historical information over the life of a project. | ||
| 432 | This methodology also allows for an environment from which you can | ||
| 433 | do lots of local experimentation on projects as you develop | ||
| 434 | changes or new features. | ||
| 435 | </para> | ||
| 436 | |||
| 437 | <para> | ||
| 438 | A Git repository represents all development efforts for a given | ||
| 439 | project. | ||
| 440 | For example, the Git repository <filename>poky</filename> contains | ||
| 441 | all changes and developments for Poky over the course of its | ||
| 442 | entire life. | ||
| 443 | That means that all changes that make up all releases are captured. | ||
| 444 | The repository maintains a complete history of changes. | ||
| 445 | </para> | ||
| 446 | |||
| 447 | <para> | ||
| 448 | You can create a local copy of any repository by "cloning" it | ||
| 449 | with the <filename>git clone</filename> command. | ||
| 450 | When you clone a Git repository, you end up with an identical | ||
| 451 | copy of the repository on your development system. | ||
| 452 | Once you have a local copy of a repository, you can take steps to | ||
| 453 | develop locally. | ||
| 454 | For examples on how to clone Git repositories, see the | ||
| 455 | "<ulink url='&YOCTO_DOCS_DEV_URL;#working-with-yocto-project-source-files'>Working With Yocto Project Source Files</ulink>" | ||
| 456 | section in the Yocto Project Development Tasks Manual. | ||
| 457 | </para> | ||
| 458 | |||
| 459 | <para> | ||
| 460 | It is important to understand that Git tracks content change and | ||
| 461 | not files. | ||
| 462 | Git uses "branches" to organize different development efforts. | ||
| 463 | For example, the <filename>poky</filename> repository has | ||
| 464 | several branches that include the current "&DISTRO_NAME_NO_CAP;" | ||
| 465 | branch, the "master" branch, and many branches for past | ||
| 466 | Yocto Project releases. | ||
| 467 | You can see all the branches by going to | ||
| 468 | <ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/'></ulink> and | ||
| 469 | clicking on the | ||
| 470 | <filename><ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/refs/heads'>[...]</ulink></filename> | ||
| 471 | link beneath the "Branch" heading. | ||
| 472 | </para> | ||
| 473 | |||
| 474 | <para> | ||
| 475 | Each of these branches represents a specific area of development. | ||
| 476 | The "master" branch represents the current or most recent | ||
| 477 | development. | ||
| 478 | All other branches represent offshoots of the "master" branch. | ||
| 479 | </para> | ||
| 480 | |||
| 481 | <para> | ||
| 482 | When you create a local copy of a Git repository, the copy has | ||
| 483 | the same set of branches as the original. | ||
| 484 | This means you can use Git to create a local working area | ||
| 485 | (also called a branch) that tracks a specific development branch | ||
| 486 | from the upstream source Git repository. | ||
| 487 | in other words, you can define your local Git environment to | ||
| 488 | work on any development branch in the repository. | ||
| 489 | To help illustrate, consider the following example Git commands: | ||
| 490 | <literallayout class='monospaced'> | ||
| 491 | $ cd ~ | ||
| 492 | $ git clone git://git.yoctoproject.org/poky | ||
| 493 | $ cd poky | ||
| 494 | $ git checkout -b &DISTRO_NAME_NO_CAP; origin/&DISTRO_NAME_NO_CAP; | ||
| 495 | </literallayout> | ||
| 496 | In the previous example after moving to the home directory, the | ||
| 497 | <filename>git clone</filename> command creates a | ||
| 498 | local copy of the upstream <filename>poky</filename> Git repository. | ||
| 499 | By default, Git checks out the "master" branch for your work. | ||
| 500 | After changing the working directory to the new local repository | ||
| 501 | (i.e. <filename>poky</filename>), the | ||
| 502 | <filename>git checkout</filename> command creates | ||
| 503 | and checks out a local branch named "&DISTRO_NAME_NO_CAP;", which | ||
| 504 | tracks the upstream "origin/&DISTRO_NAME_NO_CAP;" branch. | ||
| 505 | Changes you make while in this branch would ultimately affect | ||
| 506 | the upstream "&DISTRO_NAME_NO_CAP;" branch of the | ||
| 507 | <filename>poky</filename> repository. | ||
| 508 | </para> | ||
| 509 | |||
| 510 | <para> | ||
| 511 | It is important to understand that when you create and checkout a | ||
| 512 | local working branch based on a branch name, | ||
| 513 | your local environment matches the "tip" of that particular | ||
| 514 | development branch at the time you created your local branch, | ||
| 515 | which could be different from the files in the "master" branch | ||
| 516 | of the upstream repository. | ||
| 517 | In other words, creating and checking out a local branch based on | ||
| 518 | the "&DISTRO_NAME_NO_CAP;" branch name is not the same as | ||
| 519 | cloning and checking out the "master" branch if the repository. | ||
| 520 | Keep reading to see how you create a local snapshot of a Yocto | ||
| 521 | Project Release. | ||
| 522 | </para> | ||
| 523 | |||
| 524 | <para> | ||
| 525 | Git uses "tags" to mark specific changes in a repository. | ||
| 526 | Typically, a tag is used to mark a special point such as the final | ||
| 527 | change before a project is released. | ||
| 528 | You can see the tags used with the <filename>poky</filename> Git | ||
| 529 | repository by going to | ||
| 530 | <ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/'></ulink> and | ||
| 531 | clicking on the | ||
| 532 | <filename><ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/refs/tags'>[...]</ulink></filename> | ||
| 533 | link beneath the "Tag" heading. | ||
| 534 | </para> | ||
| 535 | |||
| 536 | <para> | ||
| 537 | Some key tags for the <filename>poky</filename> are | ||
| 538 | <filename>jethro-14.0.3</filename>, | ||
| 539 | <filename>morty-16.0.1</filename>, | ||
| 540 | <filename>pyro-17.0.0</filename>, and | ||
| 541 | <filename>&DISTRO_NAME_NO_CAP;-&POKYVERSION;</filename>. | ||
| 542 | These tags represent Yocto Project releases. | ||
| 543 | </para> | ||
| 544 | |||
| 545 | <para> | ||
| 546 | When you create a local copy of the Git repository, you also | ||
| 547 | have access to all the tags in the upstream repository. | ||
| 548 | Similar to branches, you can create and checkout a local working | ||
| 549 | Git branch based on a tag name. | ||
| 550 | When you do this, you get a snapshot of the Git repository that | ||
| 551 | reflects the state of the files when the change was made associated | ||
| 552 | with that tag. | ||
| 553 | The most common use is to checkout a working branch that matches | ||
| 554 | a specific Yocto Project release. | ||
| 555 | Here is an example: | ||
| 556 | <literallayout class='monospaced'> | ||
| 557 | $ cd ~ | ||
| 558 | $ git clone git://git.yoctoproject.org/poky | ||
| 559 | $ cd poky | ||
| 560 | $ git fetch --all --tags --prune | ||
| 561 | $ git checkout tags/pyro-17.0.0 -b my-pyro-17.0.0 | ||
| 562 | </literallayout> | ||
| 563 | In this example, the name of the top-level directory of your | ||
| 564 | local Yocto Project repository is <filename>poky</filename>. | ||
| 565 | After moving to the <filename>poky</filename> directory, the | ||
| 566 | <filename>git fetch</filename> command makes all the upstream | ||
| 567 | tags available locally in your repository. | ||
| 568 | Finally, the <filename>git checkout</filename> command | ||
| 569 | creates and checks out a branch named "my-pyro-17.0.0" that is | ||
| 570 | based on the specific change upstream in the repository | ||
| 571 | associated with the "pyro-17.0.0" tag. | ||
| 572 | The files in your repository now exactly match that particular | ||
| 573 | Yocto Project release as it is tagged in the upstream Git | ||
| 574 | repository. | ||
| 575 | It is important to understand that when you create and | ||
| 576 | checkout a local working branch based on a tag, your environment | ||
| 577 | matches a specific point in time and not the entire development | ||
| 578 | branch (i.e. the "tip" of the branch). | ||
| 579 | </para> | ||
| 580 | </section> | ||
| 581 | |||
| 582 | <section id='basic-commands'> | ||
| 583 | <title>Basic Commands</title> | ||
| 584 | |||
| 585 | <para> | ||
| 586 | Git has an extensive set of commands that lets you manage changes | ||
| 587 | and perform collaboration over the life of a project. | ||
| 588 | Conveniently though, you can manage with a small set of basic | ||
| 589 | operations and workflows once you understand the basic | ||
| 590 | philosophy behind Git. | ||
| 591 | You do not have to be an expert in Git to be functional. | ||
| 592 | A good place to look for instruction on a minimal set of Git | ||
| 593 | commands is | ||
| 594 | <ulink url='http://git-scm.com/documentation'>here</ulink>. | ||
| 595 | </para> | ||
| 596 | |||
| 597 | <para> | ||
| 598 | If you do not know much about Git, you should educate | ||
| 599 | yourself by visiting the links previously mentioned. | ||
| 600 | </para> | ||
| 601 | |||
| 602 | <para> | ||
| 603 | The following list of Git commands briefly describes some basic | ||
| 604 | Git operations as a way to get started. | ||
| 605 | As with any set of commands, this list (in most cases) simply shows | ||
| 606 | the base command and omits the many arguments they support. | ||
| 607 | See the Git documentation for complete descriptions and strategies | ||
| 608 | on how to use these commands: | ||
| 609 | <itemizedlist> | ||
| 610 | <listitem><para> | ||
| 611 | <emphasis><filename>git init</filename>:</emphasis> | ||
| 612 | Initializes an empty Git repository. | ||
| 613 | You cannot use Git commands unless you have a | ||
| 614 | <filename>.git</filename> repository. | ||
| 615 | </para></listitem> | ||
| 616 | <listitem><para id='git-commands-clone'> | ||
| 617 | <emphasis><filename>git clone</filename>:</emphasis> | ||
| 618 | Creates a local clone of a Git repository that is on | ||
| 619 | equal footing with a fellow developer’s Git repository | ||
| 620 | or an upstream repository. | ||
| 621 | </para></listitem> | ||
| 622 | <listitem><para> | ||
| 623 | <emphasis><filename>git add</filename>:</emphasis> | ||
| 624 | Locally stages updated file contents to the index that | ||
| 625 | Git uses to track changes. | ||
| 626 | You must stage all files that have changed before you | ||
| 627 | can commit them. | ||
| 628 | </para></listitem> | ||
| 629 | <listitem><para> | ||
| 630 | <emphasis><filename>git commit</filename>:</emphasis> | ||
| 631 | Creates a local "commit" that documents the changes you | ||
| 632 | made. | ||
| 633 | Only changes that have been staged can be committed. | ||
| 634 | Commits are used for historical purposes, for determining | ||
| 635 | if a maintainer of a project will allow the change, | ||
| 636 | and for ultimately pushing the change from your local | ||
| 637 | Git repository into the project’s upstream repository. | ||
| 638 | </para></listitem> | ||
| 639 | <listitem><para> | ||
| 640 | <emphasis><filename>git status</filename>:</emphasis> | ||
| 641 | Reports any modified files that possibly need to be | ||
| 642 | staged and gives you a status of where you stand regarding | ||
| 643 | local commits as compared to the upstream repository. | ||
| 644 | </para></listitem> | ||
| 645 | <listitem><para> | ||
| 646 | <emphasis><filename>git checkout</filename> <replaceable>branch-name</replaceable>:</emphasis> | ||
| 647 | Changes your working branch. | ||
| 648 | This command is analogous to "cd". | ||
| 649 | </para></listitem> | ||
| 650 | <listitem><para><emphasis><filename>git checkout –b</filename> <replaceable>working-branch</replaceable>:</emphasis> | ||
| 651 | Creates and checks out a working branch on your local | ||
| 652 | machine that you can use to isolate your work. | ||
| 653 | It is a good idea to use local branches when adding | ||
| 654 | specific features or changes. | ||
| 655 | Using isolated branches facilitates easy removal of | ||
| 656 | changes if they do not work out. | ||
| 657 | </para></listitem> | ||
| 658 | <listitem><para><emphasis><filename>git branch</filename>:</emphasis> | ||
| 659 | Displays the existing local branches associated with your | ||
| 660 | local repository. | ||
| 661 | The branch that you have currently checked out is noted | ||
| 662 | with an asterisk character. | ||
| 663 | </para></listitem> | ||
| 664 | <listitem><para> | ||
| 665 | <emphasis><filename>git branch -D</filename> <replaceable>branch-name</replaceable>:</emphasis> | ||
| 666 | Deletes an existing local branch. | ||
| 667 | You need to be in a local branch other than the one you | ||
| 668 | are deleting in order to delete | ||
| 669 | <replaceable>branch-name</replaceable>. | ||
| 670 | </para></listitem> | ||
| 671 | <listitem><para> | ||
| 672 | <emphasis><filename>git pull</filename>:</emphasis> | ||
| 673 | Retrieves information from an upstream Git repository | ||
| 674 | and places it in your local Git repository. | ||
| 675 | You use this command to make sure you are synchronized with | ||
| 676 | the repository from which you are basing changes | ||
| 677 | (.e.g. the "master" branch). | ||
| 678 | </para></listitem> | ||
| 679 | <listitem><para> | ||
| 680 | <emphasis><filename>git push</filename>:</emphasis> | ||
| 681 | Sends all your committed local changes to the upstream Git | ||
| 682 | repository that your local repository is tracking | ||
| 683 | (e.g. a contribution repository). | ||
| 684 | The maintainer of the project draws from these repositories | ||
| 685 | to merge changes (commits) into the appropriate branch | ||
| 686 | of project's upstream repository. | ||
| 687 | </para></listitem> | ||
| 688 | <listitem><para> | ||
| 689 | <emphasis><filename>git merge</filename>:</emphasis> | ||
| 690 | Combines or adds changes from one | ||
| 691 | local branch of your repository with another branch. | ||
| 692 | When you create a local Git repository, the default branch | ||
| 693 | is named "master". | ||
| 694 | A typical workflow is to create a temporary branch that is | ||
| 695 | based off "master" that you would use for isolated work. | ||
| 696 | You would make your changes in that isolated branch, | ||
| 697 | stage and commit them locally, switch to the "master" | ||
| 698 | branch, and then use the <filename>git merge</filename> | ||
| 699 | command to apply the changes from your isolated branch | ||
| 700 | into the currently checked out branch (e.g. "master"). | ||
| 701 | After the merge is complete and if you are done with | ||
| 702 | working in that isolated branch, you can safely delete | ||
| 703 | the isolated branch. | ||
| 704 | </para></listitem> | ||
| 705 | <listitem><para> | ||
| 706 | <emphasis><filename>git cherry-pick</filename>:</emphasis> | ||
| 707 | Choose and apply specific commits from one branch | ||
| 708 | into another branch. | ||
| 709 | There are times when you might not be able to merge | ||
| 710 | all the changes in one branch with | ||
| 711 | another but need to pick out certain ones. | ||
| 712 | </para></listitem> | ||
| 713 | <listitem><para> | ||
| 714 | <emphasis><filename>gitk</filename>:</emphasis> | ||
| 715 | Provides a GUI view of the branches and changes in your | ||
| 716 | local Git repository. | ||
| 717 | This command is a good way to graphically see where things | ||
| 718 | have diverged in your local repository. | ||
| 719 | <note> | ||
| 720 | You need to install the <filename>gitk</filename> | ||
| 721 | package on your development system to use this | ||
| 722 | command. | ||
| 723 | </note> | ||
| 724 | </para></listitem> | ||
| 725 | <listitem><para> | ||
| 726 | <emphasis><filename>git log</filename>:</emphasis> | ||
| 727 | Reports a history of your commits to the repository. | ||
| 728 | This report lists all commits regardless of whether you | ||
| 729 | have pushed them upstream or not. | ||
| 730 | </para></listitem> | ||
| 731 | <listitem><para> | ||
| 732 | <emphasis><filename>git diff</filename>:</emphasis> | ||
| 733 | Displays line-by-line differences between a local | ||
| 734 | working file and the same file as understood by Git. | ||
| 735 | This command is useful to see what you have changed | ||
| 736 | in any given file. | ||
| 737 | </para></listitem> | ||
| 738 | </itemizedlist> | ||
| 739 | </para> | ||
| 740 | </section> | ||
| 741 | </section> | ||
| 742 | |||
| 743 | <section id='yocto-project-repositories'> | ||
| 744 | <title>Yocto Project Source Repositories</title> | ||
| 745 | |||
| 746 | <para> | ||
| 747 | The Yocto Project team maintains complete source repositories for all | ||
| 748 | Yocto Project files at | ||
| 749 | <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi'></ulink>. | ||
| 750 | This web-based source code browser is organized into categories by | ||
| 751 | function such as IDE Plugins, Matchbox, Poky, Yocto Linux Kernel, and | ||
| 752 | so forth. | ||
| 753 | From the interface, you can click on any particular item in the "Name" | ||
| 754 | column and see the URL at the bottom of the page that you need to clone | ||
| 755 | a Git repository for that particular item. | ||
| 756 | Having a local Git repository of the | ||
| 757 | <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>, | ||
| 758 | which is usually named "poky", allows | ||
| 759 | you to make changes, contribute to the history, and ultimately enhance | ||
| 760 | the Yocto Project's tools, Board Support Packages, and so forth. | ||
| 761 | </para> | ||
| 762 | |||
| 763 | <para> | ||
| 764 | For any supported release of Yocto Project, you can also go to the | ||
| 765 | <ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink> and | ||
| 766 | select the "Downloads" tab and get a released tarball of the | ||
| 767 | <filename>poky</filename> repository or any supported BSP tarballs. | ||
| 768 | Unpacking these tarballs gives you a snapshot of the released | ||
| 769 | files. | ||
| 770 | <note><title>Notes</title> | ||
| 771 | <itemizedlist> | ||
| 772 | <listitem><para> | ||
| 773 | The recommended method for setting up the Yocto Project | ||
| 774 | <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink> | ||
| 775 | and the files for supported BSPs | ||
| 776 | (e.g., <filename>meta-intel</filename>) is to use | ||
| 777 | <link linkend='git'>Git</link> to create a local copy of | ||
| 778 | the upstream repositories. | ||
| 779 | </para></listitem> | ||
| 780 | <listitem><para> | ||
| 781 | Be sure to always work in matching branches for both | ||
| 782 | the selected BSP repository and the | ||
| 783 | <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink> | ||
| 784 | (i.e. <filename>poky</filename>) repository. | ||
| 785 | For example, if you have checked out the "master" branch | ||
| 786 | of <filename>poky</filename> and you are going to use | ||
| 787 | <filename>meta-intel</filename>, be sure to checkout the | ||
| 788 | "master" branch of <filename>meta-intel</filename>. | ||
| 789 | </para></listitem> | ||
| 790 | </itemizedlist> | ||
| 791 | </note> | ||
| 792 | </para> | ||
| 793 | |||
| 794 | <para> | ||
| 795 | In summary, here is where you can get the project files needed for | ||
| 796 | development: | ||
| 797 | <itemizedlist> | ||
| 798 | <listitem><para id='source-repositories'> | ||
| 799 | <emphasis> | ||
| 800 | <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi'>Source Repositories:</ulink> | ||
| 801 | </emphasis> | ||
| 802 | This area contains IDE Plugins, Matchbox, Poky, Poky Support, | ||
| 803 | Tools, Yocto Linux Kernel, and Yocto Metadata Layers. | ||
| 804 | You can create local copies of Git repositories for each of | ||
| 805 | these areas.</para> | ||
| 806 | |||
| 807 | <para> | ||
| 808 | <imagedata fileref="figures/source-repos.png" align="center" width="6in" depth="4in" /> | ||
| 809 | For steps on how to view and access these upstream Git | ||
| 810 | repositories, see the | ||
| 811 | "<ulink url='&YOCTO_DOCS_DEV_URL;#accessing-source-repositories'>Accessing Source Repositories</ulink>" | ||
| 812 | Section in the Yocto Project Development Tasks Manual. | ||
| 813 | </para></listitem> | ||
| 814 | <listitem><para><anchor id='index-downloads' /> | ||
| 815 | <emphasis> | ||
| 816 | <ulink url='&YOCTO_DL_URL;/releases/'>Index of /releases:</ulink> | ||
| 817 | </emphasis> | ||
| 818 | This is an index of releases such as | ||
| 819 | the <trademark class='trade'>Eclipse</trademark> | ||
| 820 | Yocto Plug-in, miscellaneous support, Poky, Pseudo, installers | ||
| 821 | for cross-development toolchains, and all released versions of | ||
| 822 | Yocto Project in the form of images or tarballs. | ||
| 823 | Downloading and extracting these files does not produce a local | ||
| 824 | copy of the Git repository but rather a snapshot of a | ||
| 825 | particular release or image.</para> | ||
| 826 | |||
| 827 | <para> | ||
| 828 | <imagedata fileref="figures/index-downloads.png" align="center" width="6in" depth="3.5in" /> | ||
| 829 | For steps on how to view and access these files, see the | ||
| 830 | "<ulink url='&YOCTO_DOCS_DEV_URL;#accessing-index-of-releases'>Accessing Index of Releases</ulink>" | ||
| 831 | section in the Yocto Project Development Tasks Manual. | ||
| 832 | </para></listitem> | ||
| 833 | <listitem><para id='downloads-page'> | ||
| 834 | <emphasis>"Downloads" page for the | ||
| 835 | <ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink>: | ||
| 836 | </emphasis></para> | ||
| 837 | |||
| 838 | <para role="writernotes">This section will change due to | ||
| 839 | reworking of the YP Website.</para> | ||
| 840 | |||
| 841 | <para>The Yocto Project website includes a "Downloads" tab | ||
| 842 | that allows you to download any Yocto Project | ||
| 843 | release and Board Support Package (BSP) in tarball form. | ||
| 844 | The tarballs are similar to those found in the | ||
| 845 | <ulink url='&YOCTO_DL_URL;/releases/'>Index of /releases:</ulink> area.</para> | ||
| 846 | |||
| 847 | <para> | ||
| 848 | <imagedata fileref="figures/yp-download.png" align="center" width="6in" depth="4in" /> | ||
| 849 | For steps on how to use the "Downloads" page, see the | ||
| 850 | "<ulink url='&YOCTO_DOCS_DEV_URL;#using-the-downloads-page'>Using the Downloads Page</ulink>" | ||
| 851 | section in the Yocto Project Development Tasks Manual. | ||
| 852 | </para></listitem> | ||
| 853 | </itemizedlist> | ||
| 854 | </para> | ||
| 855 | </section> | ||
| 856 | |||
| 857 | <section id='licensing'> | ||
| 858 | <title>Licensing</title> | ||
| 859 | |||
| 860 | <para> | ||
| 861 | Because open source projects are open to the public, they have | ||
| 862 | different licensing structures in place. | ||
| 863 | License evolution for both Open Source and Free Software has an | ||
| 864 | interesting history. | ||
| 865 | If you are interested in this history, you can find basic information | ||
| 866 | here: | ||
| 867 | <itemizedlist> | ||
| 868 | <listitem><para> | ||
| 869 | <ulink url='http://en.wikipedia.org/wiki/Open-source_license'>Open source license history</ulink> | ||
| 870 | </para></listitem> | ||
| 871 | <listitem><para> | ||
| 872 | <ulink url='http://en.wikipedia.org/wiki/Free_software_license'>Free software license history</ulink> | ||
| 873 | </para></listitem> | ||
| 874 | </itemizedlist> | ||
| 875 | </para> | ||
| 876 | |||
| 877 | <para> | ||
| 878 | In general, the Yocto Project is broadly licensed under the | ||
| 879 | Massachusetts Institute of Technology (MIT) License. | ||
| 880 | MIT licensing permits the reuse of software within proprietary | ||
| 881 | software as long as the license is distributed with that software. | ||
| 882 | MIT is also compatible with the GNU General Public License (GPL). | ||
| 883 | Patches to the Yocto Project follow the upstream licensing scheme. | ||
| 884 | You can find information on the MIT license | ||
| 885 | <ulink url='http://www.opensource.org/licenses/mit-license.php'>here</ulink>. | ||
| 886 | You can find information on the GNU GPL | ||
| 887 | <ulink url='http://www.opensource.org/licenses/LGPL-3.0'>here</ulink>. | ||
| 888 | </para> | ||
| 889 | |||
| 890 | <para> | ||
| 891 | When you build an image using the Yocto Project, the build process | ||
| 892 | uses a known list of licenses to ensure compliance. | ||
| 893 | You can find this list in the | ||
| 894 | <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink> | ||
| 895 | at <filename>meta/files/common-licenses</filename>. | ||
| 896 | Once the build completes, the list of all licenses found and used | ||
| 897 | during that build are kept in the | ||
| 898 | <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink> | ||
| 899 | at <filename>tmp/deploy/licenses</filename>. | ||
| 900 | </para> | ||
| 901 | |||
| 902 | <para> | ||
| 903 | If a module requires a license that is not in the base list, the | ||
| 904 | build process generates a warning during the build. | ||
| 905 | These tools make it easier for a developer to be certain of the | ||
| 906 | licenses with which their shipped products must comply. | ||
| 907 | However, even with these tools it is still up to the developer to | ||
| 908 | resolve potential licensing issues. | ||
| 909 | </para> | ||
| 910 | |||
| 911 | <para> | ||
| 912 | The base list of licenses used by the build process is a combination | ||
| 913 | of the Software Package Data Exchange (SPDX) list and the Open | ||
| 914 | Source Initiative (OSI) projects. | ||
| 915 | <ulink url='http://spdx.org'>SPDX Group</ulink> is a working group of | ||
| 916 | the Linux Foundation that maintains a specification for a standard | ||
| 917 | format for communicating the components, licenses, and copyrights | ||
| 918 | associated with a software package. | ||
| 919 | <ulink url='http://opensource.org'>OSI</ulink> is a corporation | ||
| 920 | dedicated to the Open Source Definition and the effort for reviewing | ||
| 921 | and approving licenses that conform to the Open Source Definition | ||
| 922 | (OSD). | ||
| 923 | </para> | ||
| 924 | |||
| 925 | <para> | ||
| 926 | You can find a list of the combined SPDX and OSI licenses that the | ||
| 927 | Yocto Project uses in the | ||
| 928 | <filename>meta/files/common-licenses</filename> directory in your | ||
| 929 | <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>. | ||
| 930 | </para> | ||
| 931 | |||
| 932 | <para> | ||
| 933 | For information that can help you maintain compliance with various | ||
| 934 | open source licensing during the lifecycle of a product created using | ||
| 935 | the Yocto Project, see the | ||
| 936 | "<ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-open-source-license-compliance-during-your-products-lifecycle'>Maintaining Open Source License Compliance During Your Product's Lifecycle</ulink>" | ||
| 937 | section in the Yocto Project Development Tasks Manual. | ||
| 938 | </para> | ||
| 939 | </section> | ||
| 940 | |||
| 941 | <section id='recipe-syntax'> | ||
| 942 | <title>Recipe Syntax</title> | ||
| 943 | |||
| 944 | <para> | ||
| 945 | Understanding recipe file syntax is important for | ||
| 946 | writing recipes. | ||
| 947 | The following list overviews the basic items that make up a | ||
| 948 | BitBake recipe file. | ||
| 949 | For more complete BitBake syntax descriptions, see the | ||
| 950 | "<ulink url='&YOCTO_DOCS_BB_URL;#bitbake-user-manual-metadata'>Syntax and Operators</ulink>" | ||
| 951 | chapter of the BitBake User Manual. | ||
| 952 | <itemizedlist> | ||
| 953 | <listitem><para><emphasis>Variable Assignments and Manipulations:</emphasis> | ||
| 954 | Variable assignments allow a value to be assigned to a | ||
| 955 | variable. | ||
| 956 | The assignment can be static text or might include | ||
| 957 | the contents of other variables. | ||
| 958 | In addition to the assignment, appending and prepending | ||
| 959 | operations are also supported.</para> | ||
| 960 | <para>The following example shows some of the ways | ||
| 961 | you can use variables in recipes: | ||
| 962 | <literallayout class='monospaced'> | ||
| 963 | S = "${WORKDIR}/postfix-${PV}" | ||
| 964 | CFLAGS += "-DNO_ASM" | ||
| 965 | SRC_URI_append = " file://fixup.patch" | ||
| 966 | </literallayout> | ||
| 967 | </para></listitem> | ||
| 968 | <listitem><para><emphasis>Functions:</emphasis> | ||
| 969 | Functions provide a series of actions to be performed. | ||
| 970 | You usually use functions to override the default | ||
| 971 | implementation of a task function or to complement | ||
| 972 | a default function (i.e. append or prepend to an | ||
| 973 | existing function). | ||
| 974 | Standard functions use <filename>sh</filename> shell | ||
| 975 | syntax, although access to OpenEmbedded variables and | ||
| 976 | internal methods are also available.</para> | ||
| 977 | <para>The following is an example function from the | ||
| 978 | <filename>sed</filename> recipe: | ||
| 979 | <literallayout class='monospaced'> | ||
| 980 | do_install () { | ||
| 981 | autotools_do_install | ||
| 982 | install -d ${D}${base_bindir} | ||
| 983 | mv ${D}${bindir}/sed ${D}${base_bindir}/sed | ||
| 984 | rmdir ${D}${bindir}/ | ||
| 985 | } | ||
| 986 | </literallayout> | ||
| 987 | It is also possible to implement new functions that | ||
| 988 | are called between existing tasks as long as the | ||
| 989 | new functions are not replacing or complementing the | ||
| 990 | default functions. | ||
| 991 | You can implement functions in Python | ||
| 992 | instead of shell. | ||
| 993 | Both of these options are not seen in the majority of | ||
| 994 | recipes.</para></listitem> | ||
| 995 | <listitem><para><emphasis>Keywords:</emphasis> | ||
| 996 | BitBake recipes use only a few keywords. | ||
| 997 | You use keywords to include common | ||
| 998 | functions (<filename>inherit</filename>), load parts | ||
| 999 | of a recipe from other files | ||
| 1000 | (<filename>include</filename> and | ||
| 1001 | <filename>require</filename>) and export variables | ||
| 1002 | to the environment (<filename>export</filename>).</para> | ||
| 1003 | <para>The following example shows the use of some of | ||
| 1004 | these keywords: | ||
| 1005 | <literallayout class='monospaced'> | ||
| 1006 | export POSTCONF = "${STAGING_BINDIR}/postconf" | ||
| 1007 | inherit autoconf | ||
| 1008 | require otherfile.inc | ||
| 1009 | </literallayout> | ||
| 1010 | </para></listitem> | ||
| 1011 | <listitem><para><emphasis>Comments:</emphasis> | ||
| 1012 | Any lines that begin with the hash character | ||
| 1013 | (<filename>#</filename>) are treated as comment lines | ||
| 1014 | and are ignored: | ||
| 1015 | <literallayout class='monospaced'> | ||
| 1016 | # This is a comment | ||
| 1017 | </literallayout> | ||
| 1018 | </para></listitem> | ||
| 1019 | </itemizedlist> | ||
| 1020 | </para> | ||
| 1021 | |||
| 1022 | <para> | ||
| 1023 | This next list summarizes the most important and most commonly | ||
| 1024 | used parts of the recipe syntax. | ||
| 1025 | For more information on these parts of the syntax, you can | ||
| 1026 | reference the | ||
| 1027 | <ulink url='&YOCTO_DOCS_BB_URL;#bitbake-user-manual-metadata'>Syntax and Operators</ulink> | ||
| 1028 | chapter in the BitBake User Manual. | ||
| 1029 | <itemizedlist> | ||
| 1030 | <listitem><para><emphasis>Line Continuation: <filename>\</filename></emphasis> - | ||
| 1031 | Use the backward slash (<filename>\</filename>) | ||
| 1032 | character to split a statement over multiple lines. | ||
| 1033 | Place the slash character at the end of the line that | ||
| 1034 | is to be continued on the next line: | ||
| 1035 | <literallayout class='monospaced'> | ||
| 1036 | VAR = "A really long \ | ||
| 1037 | line" | ||
| 1038 | </literallayout> | ||
| 1039 | <note> | ||
| 1040 | You cannot have any characters including spaces | ||
| 1041 | or tabs after the slash character. | ||
| 1042 | </note> | ||
| 1043 | </para></listitem> | ||
| 1044 | <listitem><para> | ||
| 1045 | <emphasis>Using Variables: <filename>${...}</filename></emphasis> - | ||
| 1046 | Use the <filename>${<replaceable>VARNAME</replaceable>}</filename> syntax to | ||
| 1047 | access the contents of a variable: | ||
| 1048 | <literallayout class='monospaced'> | ||
| 1049 | SRC_URI = "${SOURCEFORGE_MIRROR}/libpng/zlib-${PV}.tar.gz" | ||
| 1050 | </literallayout> | ||
| 1051 | <note> | ||
| 1052 | It is important to understand that the value of a | ||
| 1053 | variable expressed in this form does not get | ||
| 1054 | substituted automatically. | ||
| 1055 | The expansion of these expressions happens | ||
| 1056 | on-demand later (e.g. usually when a function that | ||
| 1057 | makes reference to the variable executes). | ||
| 1058 | This behavior ensures that the values are most | ||
| 1059 | appropriate for the context in which they are | ||
| 1060 | finally used. | ||
| 1061 | On the rare occasion that you do need the variable | ||
| 1062 | expression to be expanded immediately, you can use | ||
| 1063 | the <filename>:=</filename> operator instead of | ||
| 1064 | <filename>=</filename> when you make the | ||
| 1065 | assignment, but this is not generally needed. | ||
| 1066 | </note> | ||
| 1067 | </para></listitem> | ||
| 1068 | <listitem><para><emphasis>Quote All Assignments: <filename>"<replaceable>value</replaceable>"</filename></emphasis> - | ||
| 1069 | Use double quotes around the value in all variable | ||
| 1070 | assignments. | ||
| 1071 | <literallayout class='monospaced'> | ||
| 1072 | VAR1 = "${OTHERVAR}" | ||
| 1073 | VAR2 = "The version is ${PV}" | ||
| 1074 | </literallayout> | ||
| 1075 | </para></listitem> | ||
| 1076 | <listitem><para><emphasis>Conditional Assignment: <filename>?=</filename></emphasis> - | ||
| 1077 | Conditional assignment is used to assign a value to | ||
| 1078 | a variable, but only when the variable is currently | ||
| 1079 | unset. | ||
| 1080 | Use the question mark followed by the equal sign | ||
| 1081 | (<filename>?=</filename>) to make a "soft" assignment | ||
| 1082 | used for conditional assignment. | ||
| 1083 | Typically, "soft" assignments are used in the | ||
| 1084 | <filename>local.conf</filename> file for variables | ||
| 1085 | that are allowed to come through from the external | ||
| 1086 | environment. | ||
| 1087 | </para> | ||
| 1088 | <para>Here is an example where | ||
| 1089 | <filename>VAR1</filename> is set to "New value" if | ||
| 1090 | it is currently empty. | ||
| 1091 | However, if <filename>VAR1</filename> has already been | ||
| 1092 | set, it remains unchanged: | ||
| 1093 | <literallayout class='monospaced'> | ||
| 1094 | VAR1 ?= "New value" | ||
| 1095 | </literallayout> | ||
| 1096 | In this next example, <filename>VAR1</filename> | ||
| 1097 | is left with the value "Original value": | ||
| 1098 | <literallayout class='monospaced'> | ||
| 1099 | VAR1 = "Original value" | ||
| 1100 | VAR1 ?= "New value" | ||
| 1101 | </literallayout> | ||
| 1102 | </para></listitem> | ||
| 1103 | <listitem><para><emphasis>Appending: <filename>+=</filename></emphasis> - | ||
| 1104 | Use the plus character followed by the equals sign | ||
| 1105 | (<filename>+=</filename>) to append values to existing | ||
| 1106 | variables. | ||
| 1107 | <note> | ||
| 1108 | This operator adds a space between the existing | ||
| 1109 | content of the variable and the new content. | ||
| 1110 | </note></para> | ||
| 1111 | <para>Here is an example: | ||
| 1112 | <literallayout class='monospaced'> | ||
| 1113 | SRC_URI += "file://fix-makefile.patch" | ||
| 1114 | </literallayout> | ||
| 1115 | </para></listitem> | ||
| 1116 | <listitem><para><emphasis>Prepending: <filename>=+</filename></emphasis> - | ||
| 1117 | Use the equals sign followed by the plus character | ||
| 1118 | (<filename>=+</filename>) to prepend values to existing | ||
| 1119 | variables. | ||
| 1120 | <note> | ||
| 1121 | This operator adds a space between the new content | ||
| 1122 | and the existing content of the variable. | ||
| 1123 | </note></para> | ||
| 1124 | <para>Here is an example: | ||
| 1125 | <literallayout class='monospaced'> | ||
| 1126 | VAR =+ "Starts" | ||
| 1127 | </literallayout> | ||
| 1128 | </para></listitem> | ||
| 1129 | <listitem><para><emphasis>Appending: <filename>_append</filename></emphasis> - | ||
| 1130 | Use the <filename>_append</filename> operator to | ||
| 1131 | append values to existing variables. | ||
| 1132 | This operator does not add any additional space. | ||
| 1133 | Also, the operator is applied after all the | ||
| 1134 | <filename>+=</filename>, and | ||
| 1135 | <filename>=+</filename> operators have been applied and | ||
| 1136 | after all <filename>=</filename> assignments have | ||
| 1137 | occurred. | ||
| 1138 | </para> | ||
| 1139 | <para>The following example shows the space being | ||
| 1140 | explicitly added to the start to ensure the appended | ||
| 1141 | value is not merged with the existing value: | ||
| 1142 | <literallayout class='monospaced'> | ||
| 1143 | SRC_URI_append = " file://fix-makefile.patch" | ||
| 1144 | </literallayout> | ||
| 1145 | You can also use the <filename>_append</filename> | ||
| 1146 | operator with overrides, which results in the actions | ||
| 1147 | only being performed for the specified target or | ||
| 1148 | machine: | ||
| 1149 | <literallayout class='monospaced'> | ||
| 1150 | SRC_URI_append_sh4 = " file://fix-makefile.patch" | ||
| 1151 | </literallayout> | ||
| 1152 | </para></listitem> | ||
| 1153 | <listitem><para><emphasis>Prepending: <filename>_prepend</filename></emphasis> - | ||
| 1154 | Use the <filename>_prepend</filename> operator to | ||
| 1155 | prepend values to existing variables. | ||
| 1156 | This operator does not add any additional space. | ||
| 1157 | Also, the operator is applied after all the | ||
| 1158 | <filename>+=</filename>, and | ||
| 1159 | <filename>=+</filename> operators have been applied and | ||
| 1160 | after all <filename>=</filename> assignments have | ||
| 1161 | occurred. | ||
| 1162 | </para> | ||
| 1163 | <para>The following example shows the space being | ||
| 1164 | explicitly added to the end to ensure the prepended | ||
| 1165 | value is not merged with the existing value: | ||
| 1166 | <literallayout class='monospaced'> | ||
| 1167 | CFLAGS_prepend = "-I${S}/myincludes " | ||
| 1168 | </literallayout> | ||
| 1169 | You can also use the <filename>_prepend</filename> | ||
| 1170 | operator with overrides, which results in the actions | ||
| 1171 | only being performed for the specified target or | ||
| 1172 | machine: | ||
| 1173 | <literallayout class='monospaced'> | ||
| 1174 | CFLAGS_prepend_sh4 = "-I${S}/myincludes " | ||
| 1175 | </literallayout> | ||
| 1176 | </para></listitem> | ||
| 1177 | <listitem><para><emphasis>Overrides:</emphasis> - | ||
| 1178 | You can use overrides to set a value conditionally, | ||
| 1179 | typically based on how the recipe is being built. | ||
| 1180 | For example, to set the | ||
| 1181 | <ulink url='&YOCTO_DOCS_REF_URL;#var-KBRANCH'><filename>KBRANCH</filename></ulink> | ||
| 1182 | variable's value to "standard/base" for any target | ||
| 1183 | <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>, | ||
| 1184 | except for qemuarm where it should be set to | ||
| 1185 | "standard/arm-versatile-926ejs", you would do the | ||
| 1186 | following: | ||
| 1187 | <literallayout class='monospaced'> | ||
| 1188 | KBRANCH = "standard/base" | ||
| 1189 | KBRANCH_qemuarm = "standard/arm-versatile-926ejs" | ||
| 1190 | </literallayout> | ||
| 1191 | Overrides are also used to separate alternate values | ||
| 1192 | of a variable in other situations. | ||
| 1193 | For example, when setting variables such as | ||
| 1194 | <ulink url='&YOCTO_DOCS_REF_URL;#var-FILES'><filename>FILES</filename></ulink> | ||
| 1195 | and | ||
| 1196 | <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink> | ||
| 1197 | that are specific to individual packages produced by | ||
| 1198 | a recipe, you should always use an override that | ||
| 1199 | specifies the name of the package. | ||
| 1200 | </para></listitem> | ||
| 1201 | <listitem><para><emphasis>Indentation:</emphasis> | ||
| 1202 | Use spaces for indentation rather than than tabs. | ||
| 1203 | For shell functions, both currently work. | ||
| 1204 | However, it is a policy decision of the Yocto Project | ||
| 1205 | to use tabs in shell functions. | ||
| 1206 | Realize that some layers have a policy to use spaces | ||
| 1207 | for all indentation. | ||
| 1208 | </para></listitem> | ||
| 1209 | <listitem><para><emphasis>Using Python for Complex Operations: <filename>${@<replaceable>python_code</replaceable>}</filename></emphasis> - | ||
| 1210 | For more advanced processing, it is possible to use | ||
| 1211 | Python code during variable assignments (e.g. | ||
| 1212 | search and replacement on a variable).</para> | ||
| 1213 | <para>You indicate Python code using the | ||
| 1214 | <filename>${@<replaceable>python_code</replaceable>}</filename> | ||
| 1215 | syntax for the variable assignment: | ||
| 1216 | <literallayout class='monospaced'> | ||
| 1217 | SRC_URI = "ftp://ftp.info-zip.org/pub/infozip/src/zip${@d.getVar('PV',1).replace('.', '')}.tgz | ||
| 1218 | </literallayout> | ||
| 1219 | </para></listitem> | ||
| 1220 | <listitem><para><emphasis>Shell Function Syntax:</emphasis> | ||
| 1221 | Write shell functions as if you were writing a shell | ||
| 1222 | script when you describe a list of actions to take. | ||
| 1223 | You should ensure that your script works with a generic | ||
| 1224 | <filename>sh</filename> and that it does not require | ||
| 1225 | any <filename>bash</filename> or other shell-specific | ||
| 1226 | functionality. | ||
| 1227 | The same considerations apply to various system | ||
| 1228 | utilities (e.g. <filename>sed</filename>, | ||
| 1229 | <filename>grep</filename>, <filename>awk</filename>, | ||
| 1230 | and so forth) that you might wish to use. | ||
| 1231 | If in doubt, you should check with multiple | ||
| 1232 | implementations - including those from BusyBox. | ||
| 1233 | </para></listitem> | ||
| 1234 | </itemizedlist> | ||
| 1235 | </para> | ||
| 1236 | </section> | ||
| 1237 | |||
| 1238 | <section id="development-concepts"> | ||
| 1239 | <title>Development Concepts</title> | ||
| 1240 | |||
| 1241 | <para> | ||
| 1242 | This section takes a more detailed look inside the development | ||
| 1243 | process. | ||
| 1244 | The following diagram represents development at a high level. | ||
| 1245 | The remainder of this chapter expands on the fundamental input, output, | ||
| 1246 | process, and | ||
| 1247 | <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink>) blocks | ||
| 1248 | that make up development in the Yocto Project environment. | ||
| 1249 | </para> | ||
| 1250 | |||
| 1251 | <para id='general-yocto-environment-figure'> | ||
| 1252 | <imagedata fileref="figures/yocto-environment-ref.png" align="center" width="8in" depth="4.25in" /> | ||
| 1253 | </para> | ||
| 1254 | |||
| 1255 | <para> | ||
| 1256 | In general, development consists of several functional areas: | ||
| 1257 | <itemizedlist> | ||
| 1258 | <listitem><para><emphasis>User Configuration:</emphasis> | ||
| 1259 | Metadata you can use to control the build process. | ||
| 1260 | </para></listitem> | ||
| 1261 | <listitem><para><emphasis>Metadata Layers:</emphasis> | ||
| 1262 | Various layers that provide software, machine, and | ||
| 1263 | distro Metadata.</para></listitem> | ||
| 1264 | <listitem><para><emphasis>Source Files:</emphasis> | ||
| 1265 | Upstream releases, local projects, and SCMs.</para></listitem> | ||
| 1266 | <listitem><para><emphasis>Build System:</emphasis> | ||
| 1267 | Processes under the control of | ||
| 1268 | <ulink url='&YOCTO_DOCS_REF_URL;#bitbake-term'>BitBake</ulink>. | ||
| 1269 | This block expands on how BitBake fetches source, applies | ||
| 1270 | patches, completes compilation, analyzes output for package | ||
| 1271 | generation, creates and tests packages, generates images, and | ||
| 1272 | generates cross-development tools.</para></listitem> | ||
| 1273 | <listitem><para><emphasis>Package Feeds:</emphasis> | ||
| 1274 | Directories containing output packages (RPM, DEB or IPK), | ||
| 1275 | which are subsequently used in the construction of an image or | ||
| 1276 | SDK, produced by the build system. | ||
| 1277 | These feeds can also be copied and shared using a web server or | ||
| 1278 | other means to facilitate extending or updating existing | ||
| 1279 | images on devices at runtime if runtime package management is | ||
| 1280 | enabled.</para></listitem> | ||
| 1281 | <listitem><para><emphasis>Images:</emphasis> | ||
| 1282 | Images produced by the development process. | ||
| 1283 | </para></listitem> | ||
| 1284 | <listitem><para><emphasis>Application Development SDK:</emphasis> | ||
| 1285 | Cross-development tools that are produced along with an image | ||
| 1286 | or separately with BitBake.</para></listitem> | ||
| 1287 | </itemizedlist> | ||
| 1288 | </para> | ||
| 1289 | |||
| 1290 | <section id="user-configuration"> | ||
| 1291 | <title>User Configuration</title> | ||
| 1292 | |||
| 1293 | <para> | ||
| 1294 | User configuration helps define the build. | ||
| 1295 | Through user configuration, you can tell BitBake the | ||
| 1296 | target architecture for which you are building the image, | ||
| 1297 | where to store downloaded source, and other build properties. | ||
| 1298 | </para> | ||
| 1299 | |||
| 1300 | <para> | ||
| 1301 | The following figure shows an expanded representation of the | ||
| 1302 | "User Configuration" box of the | ||
| 1303 | <link linkend='general-yocto-environment-figure'>general Yocto Project Development Environment figure</link>: | ||
| 1304 | </para> | ||
| 1305 | |||
| 1306 | <para> | ||
| 1307 | <imagedata fileref="figures/user-configuration.png" align="center" width="8in" depth="4.5in" /> | ||
| 1308 | </para> | ||
| 1309 | |||
| 1310 | <para> | ||
| 1311 | BitBake needs some basic configuration files in order to complete | ||
| 1312 | a build. | ||
| 1313 | These files are <filename>*.conf</filename> files. | ||
| 1314 | The minimally necessary ones reside as example files in the | ||
| 1315 | <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>. | ||
| 1316 | For simplicity, this section refers to the Source Directory as | ||
| 1317 | the "Poky Directory." | ||
| 1318 | </para> | ||
| 1319 | |||
| 1320 | <para> | ||
| 1321 | When you clone the <filename>poky</filename> Git repository or you | ||
| 1322 | download and unpack a Yocto Project release, you can set up the | ||
| 1323 | Source Directory to be named anything you want. | ||
| 1324 | For this discussion, the cloned repository uses the default | ||
| 1325 | name <filename>poky</filename>. | ||
| 1326 | <note> | ||
| 1327 | The Poky repository is primarily an aggregation of existing | ||
| 1328 | repositories. | ||
| 1329 | It is not a canonical upstream source. | ||
| 1330 | </note> | ||
| 1331 | </para> | ||
| 1332 | |||
| 1333 | <para> | ||
| 1334 | The <filename>meta-poky</filename> layer inside Poky contains | ||
| 1335 | a <filename>conf</filename> directory that has example | ||
| 1336 | configuration files. | ||
| 1337 | These example files are used as a basis for creating actual | ||
| 1338 | configuration files when you source the build environment | ||
| 1339 | script | ||
| 1340 | (i.e. | ||
| 1341 | <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>). | ||
| 1342 | </para> | ||
| 1343 | |||
| 1344 | <para> | ||
| 1345 | Sourcing the build environment script creates a | ||
| 1346 | <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink> | ||
| 1347 | if one does not already exist. | ||
| 1348 | BitBake uses the Build Directory for all its work during builds. | ||
| 1349 | The Build Directory has a <filename>conf</filename> directory that | ||
| 1350 | contains default versions of your <filename>local.conf</filename> | ||
| 1351 | and <filename>bblayers.conf</filename> configuration files. | ||
| 1352 | These default configuration files are created only if versions | ||
| 1353 | do not already exist in the Build Directory at the time you | ||
| 1354 | source the build environment setup script. | ||
| 1355 | </para> | ||
| 1356 | |||
| 1357 | <para> | ||
| 1358 | Because the Poky repository is fundamentally an aggregation of | ||
| 1359 | existing repositories, some users might be familiar with running | ||
| 1360 | the <filename>&OE_INIT_FILE;</filename> script in the context | ||
| 1361 | of separate OpenEmbedded-Core and BitBake repositories rather than a | ||
| 1362 | single Poky repository. | ||
| 1363 | This discussion assumes the script is executed from within a cloned | ||
| 1364 | or unpacked version of Poky. | ||
| 1365 | </para> | ||
| 1366 | |||
| 1367 | <para> | ||
| 1368 | Depending on where the script is sourced, different sub-scripts | ||
| 1369 | are called to set up the Build Directory (Yocto or OpenEmbedded). | ||
| 1370 | Specifically, the script | ||
| 1371 | <filename>scripts/oe-setup-builddir</filename> inside the | ||
| 1372 | poky directory sets up the Build Directory and seeds the directory | ||
| 1373 | (if necessary) with configuration files appropriate for the | ||
| 1374 | Yocto Project development environment. | ||
| 1375 | <note> | ||
| 1376 | The <filename>scripts/oe-setup-builddir</filename> script | ||
| 1377 | uses the <filename>$TEMPLATECONF</filename> variable to | ||
| 1378 | determine which sample configuration files to locate. | ||
| 1379 | </note> | ||
| 1380 | </para> | ||
| 1381 | |||
| 1382 | <para> | ||
| 1383 | The <filename>local.conf</filename> file provides many | ||
| 1384 | basic variables that define a build environment. | ||
| 1385 | Here is a list of a few. | ||
| 1386 | To see the default configurations in a <filename>local.conf</filename> | ||
| 1387 | file created by the build environment script, see the | ||
| 1388 | <filename>local.conf.sample</filename> in the | ||
| 1389 | <filename>meta-poky</filename> layer: | ||
| 1390 | <itemizedlist> | ||
| 1391 | <listitem><para><emphasis>Parallelism Options:</emphasis> | ||
| 1392 | Controlled by the | ||
| 1393 | <ulink url='&YOCTO_DOCS_REF_URL;#var-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename></ulink>, | ||
| 1394 | <ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></ulink>, | ||
| 1395 | and | ||
| 1396 | <ulink url='&YOCTO_DOCS_BB_URL;#var-BB_NUMBER_PARSE_THREADS'><filename>BB_NUMBER_PARSE_THREADS</filename></ulink> | ||
| 1397 | variables.</para></listitem> | ||
| 1398 | <listitem><para><emphasis>Target Machine Selection:</emphasis> | ||
| 1399 | Controlled by the | ||
| 1400 | <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> | ||
| 1401 | variable.</para></listitem> | ||
| 1402 | <listitem><para><emphasis>Download Directory:</emphasis> | ||
| 1403 | Controlled by the | ||
| 1404 | <ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'><filename>DL_DIR</filename></ulink> | ||
| 1405 | variable.</para></listitem> | ||
| 1406 | <listitem><para><emphasis>Shared State Directory:</emphasis> | ||
| 1407 | Controlled by the | ||
| 1408 | <ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_DIR'><filename>SSTATE_DIR</filename></ulink> | ||
| 1409 | variable.</para></listitem> | ||
| 1410 | <listitem><para><emphasis>Build Output:</emphasis> | ||
| 1411 | Controlled by the | ||
| 1412 | <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink> | ||
| 1413 | variable.</para></listitem> | ||
| 1414 | </itemizedlist> | ||
| 1415 | <note> | ||
| 1416 | Configurations set in the <filename>conf/local.conf</filename> | ||
| 1417 | file can also be set in the | ||
| 1418 | <filename>conf/site.conf</filename> and | ||
| 1419 | <filename>conf/auto.conf</filename> configuration files. | ||
| 1420 | </note> | ||
| 1421 | </para> | ||
| 1422 | |||
| 1423 | <para> | ||
| 1424 | The <filename>bblayers.conf</filename> file tells BitBake what | ||
| 1425 | layers you want considered during the build. | ||
| 1426 | By default, the layers listed in this file include layers | ||
| 1427 | minimally needed by the build system. | ||
| 1428 | However, you must manually add any custom layers you have created. | ||
| 1429 | You can find more information on working with the | ||
| 1430 | <filename>bblayers.conf</filename> file in the | ||
| 1431 | "<ulink url='&YOCTO_DOCS_DEV_URL;#enabling-your-layer'>Enabling Your Layer</ulink>" | ||
| 1432 | section in the Yocto Project Development Tasks Manual. | ||
| 1433 | </para> | ||
| 1434 | |||
| 1435 | <para> | ||
| 1436 | The files <filename>site.conf</filename> and | ||
| 1437 | <filename>auto.conf</filename> are not created by the environment | ||
| 1438 | initialization script. | ||
| 1439 | If you want the <filename>site.conf</filename> file, you need to | ||
| 1440 | create that yourself. | ||
| 1441 | The <filename>auto.conf</filename> file is typically created by | ||
| 1442 | an autobuilder: | ||
| 1443 | <itemizedlist> | ||
| 1444 | <listitem><para><emphasis><filename>site.conf</filename>:</emphasis> | ||
| 1445 | You can use the <filename>conf/site.conf</filename> | ||
| 1446 | configuration file to configure multiple build directories. | ||
| 1447 | For example, suppose you had several build environments and | ||
| 1448 | they shared some common features. | ||
| 1449 | You can set these default build properties here. | ||
| 1450 | A good example is perhaps the packaging format to use | ||
| 1451 | through the | ||
| 1452 | <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></ulink> | ||
| 1453 | variable.</para> | ||
| 1454 | <para>One useful scenario for using the | ||
| 1455 | <filename>conf/site.conf</filename> file is to extend your | ||
| 1456 | <ulink url='&YOCTO_DOCS_REF_URL;#var-BBPATH'><filename>BBPATH</filename></ulink> | ||
| 1457 | variable to include the path to a | ||
| 1458 | <filename>conf/site.conf</filename>. | ||
| 1459 | Then, when BitBake looks for Metadata using | ||
| 1460 | <filename>BBPATH</filename>, it finds the | ||
| 1461 | <filename>conf/site.conf</filename> file and applies your | ||
| 1462 | common configurations found in the file. | ||
| 1463 | To override configurations in a particular build directory, | ||
| 1464 | alter the similar configurations within that build | ||
| 1465 | directory's <filename>conf/local.conf</filename> file. | ||
| 1466 | </para></listitem> | ||
| 1467 | <listitem><para><emphasis><filename>auto.conf</filename>:</emphasis> | ||
| 1468 | The file is usually created and written to by | ||
| 1469 | an autobuilder. | ||
| 1470 | The settings put into the file are typically the same as | ||
| 1471 | you would find in the <filename>conf/local.conf</filename> | ||
| 1472 | or the <filename>conf/site.conf</filename> files. | ||
| 1473 | </para></listitem> | ||
| 1474 | </itemizedlist> | ||
| 1475 | </para> | ||
| 1476 | |||
| 1477 | <para> | ||
| 1478 | You can edit all configuration files to further define | ||
| 1479 | any particular build environment. | ||
| 1480 | This process is represented by the "User Configuration Edits" | ||
| 1481 | box in the figure. | ||
| 1482 | </para> | ||
| 1483 | |||
| 1484 | <para> | ||
| 1485 | When you launch your build with the | ||
| 1486 | <filename>bitbake <replaceable>target</replaceable></filename> | ||
| 1487 | command, BitBake sorts out the configurations to ultimately | ||
| 1488 | define your build environment. | ||
| 1489 | It is important to understand that the OpenEmbedded build system | ||
| 1490 | reads the configuration files in a specific order: | ||
| 1491 | <filename>site.conf</filename>, <filename>auto.conf</filename>, | ||
| 1492 | and <filename>local.conf</filename>. | ||
| 1493 | And, the build system applies the normal assignment statement | ||
| 1494 | rules. | ||
| 1495 | Because the files are parsed in a specific order, variable | ||
| 1496 | assignments for the same variable could be affected. | ||
| 1497 | For example, if the <filename>auto.conf</filename> file and | ||
| 1498 | the <filename>local.conf</filename> set | ||
| 1499 | <replaceable>variable1</replaceable> to different values, because | ||
| 1500 | the build system parses <filename>local.conf</filename> after | ||
| 1501 | <filename>auto.conf</filename>, | ||
| 1502 | <replaceable>variable1</replaceable> is assigned the value from | ||
| 1503 | the <filename>local.conf</filename> file. | ||
| 1504 | </para> | ||
| 1505 | </section> | ||
| 1506 | |||
| 1507 | <section id="metadata-machine-configuration-and-policy-configuration"> | ||
| 1508 | <title>Metadata, Machine Configuration, and Policy Configuration</title> | ||
| 1509 | |||
| 1510 | <para> | ||
| 1511 | The previous section described the user configurations that | ||
| 1512 | define BitBake's global behavior. | ||
| 1513 | This section takes a closer look at the layers the build system | ||
| 1514 | uses to further control the build. | ||
| 1515 | These layers provide Metadata for the software, machine, and | ||
| 1516 | policy. | ||
| 1517 | </para> | ||
| 1518 | |||
| 1519 | <para> | ||
| 1520 | In general, three types of layer input exist: | ||
| 1521 | <itemizedlist> | ||
| 1522 | <listitem><para><emphasis>Policy Configuration:</emphasis> | ||
| 1523 | Distribution Layers provide top-level or general | ||
| 1524 | policies for the image or SDK being built. | ||
| 1525 | For example, this layer would dictate whether BitBake | ||
| 1526 | produces RPM or IPK packages.</para></listitem> | ||
| 1527 | <listitem><para><emphasis>Machine Configuration:</emphasis> | ||
| 1528 | Board Support Package (BSP) layers provide machine | ||
| 1529 | configurations. | ||
| 1530 | This type of information is specific to a particular | ||
| 1531 | target architecture.</para></listitem> | ||
| 1532 | <listitem><para><emphasis>Metadata:</emphasis> | ||
| 1533 | Software layers contain user-supplied recipe files, | ||
| 1534 | patches, and append files. | ||
| 1535 | </para></listitem> | ||
| 1536 | </itemizedlist> | ||
| 1537 | </para> | ||
| 1538 | |||
| 1539 | <para> | ||
| 1540 | The following figure shows an expanded representation of the | ||
| 1541 | Metadata, Machine Configuration, and Policy Configuration input | ||
| 1542 | (layers) boxes of the | ||
| 1543 | <link linkend='general-yocto-environment-figure'>general Yocto Project Development Environment figure</link>: | ||
| 1544 | </para> | ||
| 1545 | |||
| 1546 | <para> | ||
| 1547 | <imagedata fileref="figures/layer-input.png" align="center" width="8in" depth="7.5in" /> | ||
| 1548 | </para> | ||
| 1549 | |||
| 1550 | <para> | ||
| 1551 | In general, all layers have a similar structure. | ||
| 1552 | They all contain a licensing file | ||
| 1553 | (e.g. <filename>COPYING</filename>) if the layer is to be | ||
| 1554 | distributed, a <filename>README</filename> file as good practice | ||
| 1555 | and especially if the layer is to be distributed, a | ||
| 1556 | configuration directory, and recipe directories. | ||
| 1557 | </para> | ||
| 1558 | |||
| 1559 | <para> | ||
| 1560 | The Yocto Project has many layers that can be used. | ||
| 1561 | You can see a web-interface listing of them on the | ||
| 1562 | <ulink url="http://git.yoctoproject.org/">Source Repositories</ulink> | ||
| 1563 | page. | ||
| 1564 | The layers are shown at the bottom categorized under | ||
| 1565 | "Yocto Metadata Layers." | ||
| 1566 | These layers are fundamentally a subset of the | ||
| 1567 | <ulink url="http://layers.openembedded.org/layerindex/layers/">OpenEmbedded Metadata Index</ulink>, | ||
| 1568 | which lists all layers provided by the OpenEmbedded community. | ||
| 1569 | <note> | ||
| 1570 | Layers exist in the Yocto Project Source Repositories that | ||
| 1571 | cannot be found in the OpenEmbedded Metadata Index. | ||
| 1572 | These layers are either deprecated or experimental in nature. | ||
| 1573 | </note> | ||
| 1574 | </para> | ||
| 1575 | |||
| 1576 | <para> | ||
| 1577 | BitBake uses the <filename>conf/bblayers.conf</filename> file, | ||
| 1578 | which is part of the user configuration, to find what layers it | ||
| 1579 | should be using as part of the build. | ||
| 1580 | </para> | ||
| 1581 | |||
| 1582 | <para> | ||
| 1583 | For more information on layers, see the | ||
| 1584 | "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>" | ||
| 1585 | section in the Yocto Project Development Tasks Manual. | ||
| 1586 | </para> | ||
| 1587 | |||
| 1588 | <section id="distro-layer"> | ||
| 1589 | <title>Distro Layer</title> | ||
| 1590 | |||
| 1591 | <para> | ||
| 1592 | The distribution layer provides policy configurations for your | ||
| 1593 | distribution. | ||
| 1594 | Best practices dictate that you isolate these types of | ||
| 1595 | configurations into their own layer. | ||
| 1596 | Settings you provide in | ||
| 1597 | <filename>conf/distro/<replaceable>distro</replaceable>.conf</filename> override | ||
| 1598 | similar | ||
| 1599 | settings that BitBake finds in your | ||
| 1600 | <filename>conf/local.conf</filename> file in the Build | ||
| 1601 | Directory. | ||
| 1602 | </para> | ||
| 1603 | |||
| 1604 | <para> | ||
| 1605 | The following list provides some explanation and references | ||
| 1606 | for what you typically find in the distribution layer: | ||
| 1607 | <itemizedlist> | ||
| 1608 | <listitem><para><emphasis>classes:</emphasis> | ||
| 1609 | Class files (<filename>.bbclass</filename>) hold | ||
| 1610 | common functionality that can be shared among | ||
| 1611 | recipes in the distribution. | ||
| 1612 | When your recipes inherit a class, they take on the | ||
| 1613 | settings and functions for that class. | ||
| 1614 | You can read more about class files in the | ||
| 1615 | "<ulink url='&YOCTO_DOCS_REF_URL;#ref-classes'>Classes</ulink>" | ||
| 1616 | section of the Yocto Reference Manual. | ||
| 1617 | </para></listitem> | ||
| 1618 | <listitem><para><emphasis>conf:</emphasis> | ||
| 1619 | This area holds configuration files for the | ||
| 1620 | layer (<filename>conf/layer.conf</filename>), | ||
| 1621 | the distribution | ||
| 1622 | (<filename>conf/distro/<replaceable>distro</replaceable>.conf</filename>), | ||
| 1623 | and any distribution-wide include files. | ||
| 1624 | </para></listitem> | ||
| 1625 | <listitem><para><emphasis>recipes-*:</emphasis> | ||
| 1626 | Recipes and append files that affect common | ||
| 1627 | functionality across the distribution. | ||
| 1628 | This area could include recipes and append files | ||
| 1629 | to add distribution-specific configuration, | ||
| 1630 | initialization scripts, custom image recipes, | ||
| 1631 | and so forth.</para></listitem> | ||
| 1632 | </itemizedlist> | ||
| 1633 | </para> | ||
| 1634 | </section> | ||
| 1635 | |||
| 1636 | <section id="bsp-layer"> | ||
| 1637 | <title>BSP Layer</title> | ||
| 1638 | |||
| 1639 | <para> | ||
| 1640 | The BSP Layer provides machine configurations. | ||
| 1641 | Everything in this layer is specific to the machine for which | ||
| 1642 | you are building the image or the SDK. | ||
| 1643 | A common structure or form is defined for BSP layers. | ||
| 1644 | You can learn more about this structure in the | ||
| 1645 | <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>. | ||
| 1646 | <note> | ||
| 1647 | In order for a BSP layer to be considered compliant with the | ||
| 1648 | Yocto Project, it must meet some structural requirements. | ||
| 1649 | </note> | ||
| 1650 | </para> | ||
| 1651 | |||
| 1652 | <para> | ||
| 1653 | The BSP Layer's configuration directory contains | ||
| 1654 | configuration files for the machine | ||
| 1655 | (<filename>conf/machine/<replaceable>machine</replaceable>.conf</filename>) and, | ||
| 1656 | of course, the layer (<filename>conf/layer.conf</filename>). | ||
| 1657 | </para> | ||
| 1658 | |||
| 1659 | <para> | ||
| 1660 | The remainder of the layer is dedicated to specific recipes | ||
| 1661 | by function: <filename>recipes-bsp</filename>, | ||
| 1662 | <filename>recipes-core</filename>, | ||
| 1663 | <filename>recipes-graphics</filename>, and | ||
| 1664 | <filename>recipes-kernel</filename>. | ||
| 1665 | Metadata can exist for multiple formfactors, graphics | ||
| 1666 | support systems, and so forth. | ||
| 1667 | <note> | ||
| 1668 | While the figure shows several <filename>recipes-*</filename> | ||
| 1669 | directories, not all these directories appear in all | ||
| 1670 | BSP layers. | ||
| 1671 | </note> | ||
| 1672 | </para> | ||
| 1673 | </section> | ||
| 1674 | |||
| 1675 | <section id="software-layer"> | ||
| 1676 | <title>Software Layer</title> | ||
| 1677 | |||
| 1678 | <para> | ||
| 1679 | The software layer provides the Metadata for additional | ||
| 1680 | software packages used during the build. | ||
| 1681 | This layer does not include Metadata that is specific to the | ||
| 1682 | distribution or the machine, which are found in their | ||
| 1683 | respective layers. | ||
| 1684 | </para> | ||
| 1685 | |||
| 1686 | <para> | ||
| 1687 | This layer contains any new recipes that your project needs | ||
| 1688 | in the form of recipe files. | ||
| 1689 | </para> | ||
| 1690 | </section> | ||
| 1691 | </section> | ||
| 1692 | |||
| 1693 | <section id="sources-dev-environment"> | ||
| 1694 | <title>Sources</title> | ||
| 1695 | |||
| 1696 | <para> | ||
| 1697 | In order for the OpenEmbedded build system to create an image or | ||
| 1698 | any target, it must be able to access source files. | ||
| 1699 | The | ||
| 1700 | <link linkend='general-yocto-environment-figure'>general Yocto Project Development Environment figure</link> | ||
| 1701 | represents source files using the "Upstream Project Releases", | ||
| 1702 | "Local Projects", and "SCMs (optional)" boxes. | ||
| 1703 | The figure represents mirrors, which also play a role in locating | ||
| 1704 | source files, with the "Source Mirror(s)" box. | ||
| 1705 | </para> | ||
| 1706 | |||
| 1707 | <para> | ||
| 1708 | The method by which source files are ultimately organized is | ||
| 1709 | a function of the project. | ||
| 1710 | For example, for released software, projects tend to use tarballs | ||
| 1711 | or other archived files that can capture the state of a release | ||
| 1712 | guaranteeing that it is statically represented. | ||
| 1713 | On the other hand, for a project that is more dynamic or | ||
| 1714 | experimental in nature, a project might keep source files in a | ||
| 1715 | repository controlled by a Source Control Manager (SCM) such as | ||
| 1716 | Git. | ||
| 1717 | Pulling source from a repository allows you to control | ||
| 1718 | the point in the repository (the revision) from which you want to | ||
| 1719 | build software. | ||
| 1720 | Finally, a combination of the two might exist, which would give the | ||
| 1721 | consumer a choice when deciding where to get source files. | ||
| 1722 | </para> | ||
| 1723 | |||
| 1724 | <para> | ||
| 1725 | BitBake uses the | ||
| 1726 | <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> | ||
| 1727 | variable to point to source files regardless of their location. | ||
| 1728 | Each recipe must have a <filename>SRC_URI</filename> variable | ||
| 1729 | that points to the source. | ||
| 1730 | </para> | ||
| 1731 | |||
| 1732 | <para> | ||
| 1733 | Another area that plays a significant role in where source files | ||
| 1734 | come from is pointed to by the | ||
| 1735 | <ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'><filename>DL_DIR</filename></ulink> | ||
| 1736 | variable. | ||
| 1737 | This area is a cache that can hold previously downloaded source. | ||
| 1738 | You can also instruct the OpenEmbedded build system to create | ||
| 1739 | tarballs from Git repositories, which is not the default behavior, | ||
| 1740 | and store them in the <filename>DL_DIR</filename> by using the | ||
| 1741 | <ulink url='&YOCTO_DOCS_REF_URL;#var-BB_GENERATE_MIRROR_TARBALLS'><filename>BB_GENERATE_MIRROR_TARBALLS</filename></ulink> | ||
| 1742 | variable. | ||
| 1743 | </para> | ||
| 1744 | |||
| 1745 | <para> | ||
| 1746 | Judicious use of a <filename>DL_DIR</filename> directory can | ||
| 1747 | save the build system a trip across the Internet when looking | ||
| 1748 | for files. | ||
| 1749 | A good method for using a download directory is to have | ||
| 1750 | <filename>DL_DIR</filename> point to an area outside of your | ||
| 1751 | Build Directory. | ||
| 1752 | Doing so allows you to safely delete the Build Directory | ||
| 1753 | if needed without fear of removing any downloaded source file. | ||
| 1754 | </para> | ||
| 1755 | |||
| 1756 | <para> | ||
| 1757 | The remainder of this section provides a deeper look into the | ||
| 1758 | source files and the mirrors. | ||
| 1759 | Here is a more detailed look at the source file area of the | ||
| 1760 | base figure: | ||
| 1761 | <imagedata fileref="figures/source-input.png" align="center" width="7in" depth="7.5in" /> | ||
| 1762 | </para> | ||
| 1763 | |||
| 1764 | <section id='upstream-project-releases'> | ||
| 1765 | <title>Upstream Project Releases</title> | ||
| 1766 | |||
| 1767 | <para> | ||
| 1768 | Upstream project releases exist anywhere in the form of an | ||
| 1769 | archived file (e.g. tarball or zip file). | ||
| 1770 | These files correspond to individual recipes. | ||
| 1771 | For example, the figure uses specific releases each for | ||
| 1772 | BusyBox, Qt, and Dbus. | ||
| 1773 | An archive file can be for any released product that can be | ||
| 1774 | built using a recipe. | ||
| 1775 | </para> | ||
| 1776 | </section> | ||
| 1777 | |||
| 1778 | <section id='local-projects'> | ||
| 1779 | <title>Local Projects</title> | ||
| 1780 | |||
| 1781 | <para> | ||
| 1782 | Local projects are custom bits of software the user provides. | ||
| 1783 | These bits reside somewhere local to a project - perhaps | ||
| 1784 | a directory into which the user checks in items (e.g. | ||
| 1785 | a local directory containing a development source tree | ||
| 1786 | used by the group). | ||
| 1787 | </para> | ||
| 1788 | |||
| 1789 | <para> | ||
| 1790 | The canonical method through which to include a local project | ||
| 1791 | is to use the | ||
| 1792 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-externalsrc'><filename>externalsrc</filename></ulink> | ||
| 1793 | class to include that local project. | ||
| 1794 | You use either the <filename>local.conf</filename> or a | ||
| 1795 | recipe's append file to override or set the | ||
| 1796 | recipe to point to the local directory on your disk to pull | ||
| 1797 | in the whole source tree. | ||
| 1798 | </para> | ||
| 1799 | |||
| 1800 | <para> | ||
| 1801 | For information on how to use the | ||
| 1802 | <filename>externalsrc</filename> class, see the | ||
| 1803 | "<ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-externalsrc'><filename>externalsrc.bbclass</filename></ulink>" | ||
| 1804 | section. | ||
| 1805 | </para> | ||
| 1806 | </section> | ||
| 1807 | |||
| 1808 | <section id='scms'> | ||
| 1809 | <title>Source Control Managers (Optional)</title> | ||
| 1810 | |||
| 1811 | <para> | ||
| 1812 | Another place the build system can get source files from is | ||
| 1813 | through an SCM such as Git or Subversion. | ||
| 1814 | In this case, a repository is cloned or checked out. | ||
| 1815 | The | ||
| 1816 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-fetch'><filename>do_fetch</filename></ulink> | ||
| 1817 | task inside BitBake uses | ||
| 1818 | the <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> | ||
| 1819 | variable and the argument's prefix to determine the correct | ||
| 1820 | fetcher module. | ||
| 1821 | </para> | ||
| 1822 | |||
| 1823 | <note> | ||
| 1824 | For information on how to have the OpenEmbedded build system | ||
| 1825 | generate tarballs for Git repositories and place them in the | ||
| 1826 | <ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'><filename>DL_DIR</filename></ulink> | ||
| 1827 | directory, see the | ||
| 1828 | <ulink url='&YOCTO_DOCS_REF_URL;#var-BB_GENERATE_MIRROR_TARBALLS'><filename>BB_GENERATE_MIRROR_TARBALLS</filename></ulink> | ||
| 1829 | variable. | ||
| 1830 | </note> | ||
| 1831 | |||
| 1832 | <para> | ||
| 1833 | When fetching a repository, BitBake uses the | ||
| 1834 | <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink> | ||
| 1835 | variable to determine the specific revision from which to | ||
| 1836 | build. | ||
| 1837 | </para> | ||
| 1838 | </section> | ||
| 1839 | |||
| 1840 | <section id='source-mirrors'> | ||
| 1841 | <title>Source Mirror(s)</title> | ||
| 1842 | |||
| 1843 | <para> | ||
| 1844 | Two kinds of mirrors exist: pre-mirrors and regular mirrors. | ||
| 1845 | The | ||
| 1846 | <ulink url='&YOCTO_DOCS_REF_URL;#var-PREMIRRORS'><filename>PREMIRRORS</filename></ulink> | ||
| 1847 | and | ||
| 1848 | <ulink url='&YOCTO_DOCS_REF_URL;#var-MIRRORS'><filename>MIRRORS</filename></ulink> | ||
| 1849 | variables point to these, respectively. | ||
| 1850 | BitBake checks pre-mirrors before looking upstream for any | ||
| 1851 | source files. | ||
| 1852 | Pre-mirrors are appropriate when you have a shared directory | ||
| 1853 | that is not a directory defined by the | ||
| 1854 | <ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'><filename>DL_DIR</filename></ulink> | ||
| 1855 | variable. | ||
| 1856 | A Pre-mirror typically points to a shared directory that is | ||
| 1857 | local to your organization. | ||
| 1858 | </para> | ||
| 1859 | |||
| 1860 | <para> | ||
| 1861 | Regular mirrors can be any site across the Internet that is | ||
| 1862 | used as an alternative location for source code should the | ||
| 1863 | primary site not be functioning for some reason or another. | ||
| 1864 | </para> | ||
| 1865 | </section> | ||
| 1866 | </section> | ||
| 1867 | |||
| 1868 | <section id="package-feeds-dev-environment"> | ||
| 1869 | <title>Package Feeds</title> | ||
| 1870 | |||
| 1871 | <para> | ||
| 1872 | When the OpenEmbedded build system generates an image or an SDK, | ||
| 1873 | it gets the packages from a package feed area located in the | ||
| 1874 | <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>. | ||
| 1875 | The | ||
| 1876 | <link linkend='general-yocto-environment-figure'>general Yocto Project Development Environment figure</link> | ||
| 1877 | shows this package feeds area in the upper-right corner. | ||
| 1878 | </para> | ||
| 1879 | |||
| 1880 | <para> | ||
| 1881 | This section looks a little closer into the package feeds area used | ||
| 1882 | by the build system. | ||
| 1883 | Here is a more detailed look at the area: | ||
| 1884 | <imagedata fileref="figures/package-feeds.png" align="center" width="7in" depth="6in" /> | ||
| 1885 | </para> | ||
| 1886 | |||
| 1887 | <para> | ||
| 1888 | Package feeds are an intermediary step in the build process. | ||
| 1889 | The OpenEmbedded build system provides classes to generate | ||
| 1890 | different package types, and you specify which classes to enable | ||
| 1891 | through the | ||
| 1892 | <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></ulink> | ||
| 1893 | variable. | ||
| 1894 | Before placing the packages into package feeds, | ||
| 1895 | the build process validates them with generated output quality | ||
| 1896 | assurance checks through the | ||
| 1897 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-insane'><filename>insane</filename></ulink> | ||
| 1898 | class. | ||
| 1899 | </para> | ||
| 1900 | |||
| 1901 | <para> | ||
| 1902 | The package feed area resides in the Build Directory. | ||
| 1903 | The directory the build system uses to temporarily store packages | ||
| 1904 | is determined by a combination of variables and the particular | ||
| 1905 | package manager in use. | ||
| 1906 | See the "Package Feeds" box in the illustration and note the | ||
| 1907 | information to the right of that area. | ||
| 1908 | In particular, the following defines where package files are | ||
| 1909 | kept: | ||
| 1910 | <itemizedlist> | ||
| 1911 | <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></ulink>: | ||
| 1912 | Defined as <filename>tmp/deploy</filename> in the Build | ||
| 1913 | Directory. | ||
| 1914 | </para></listitem> | ||
| 1915 | <listitem><para><filename>DEPLOY_DIR_*</filename>: | ||
| 1916 | Depending on the package manager used, the package type | ||
| 1917 | sub-folder. | ||
| 1918 | Given RPM, IPK, or DEB packaging and tarball creation, the | ||
| 1919 | <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPLOY_DIR_RPM'><filename>DEPLOY_DIR_RPM</filename></ulink>, | ||
| 1920 | <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPLOY_DIR_IPK'><filename>DEPLOY_DIR_IPK</filename></ulink>, | ||
| 1921 | <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPLOY_DIR_DEB'><filename>DEPLOY_DIR_DEB</filename></ulink>, | ||
| 1922 | or | ||
| 1923 | <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPLOY_DIR_TAR'><filename>DEPLOY_DIR_TAR</filename></ulink>, | ||
| 1924 | variables are used, respectively. | ||
| 1925 | </para></listitem> | ||
| 1926 | <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></ulink>: | ||
| 1927 | Defines architecture-specific sub-folders. | ||
| 1928 | For example, packages could exist for the i586 or qemux86 | ||
| 1929 | architectures. | ||
| 1930 | </para></listitem> | ||
| 1931 | </itemizedlist> | ||
| 1932 | </para> | ||
| 1933 | |||
| 1934 | <para> | ||
| 1935 | BitBake uses the <filename>do_package_write_*</filename> tasks to | ||
| 1936 | generate packages and place them into the package holding area (e.g. | ||
| 1937 | <filename>do_package_write_ipk</filename> for IPK packages). | ||
| 1938 | See the | ||
| 1939 | "<ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package_write_deb'><filename>do_package_write_deb</filename></ulink>", | ||
| 1940 | "<ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package_write_ipk'><filename>do_package_write_ipk</filename></ulink>", | ||
| 1941 | "<ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package_write_rpm'><filename>do_package_write_rpm</filename></ulink>", | ||
| 1942 | and | ||
| 1943 | "<ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package_write_tar'><filename>do_package_write_tar</filename></ulink>" | ||
| 1944 | sections for additional information. | ||
| 1945 | As an example, consider a scenario where an IPK packaging manager | ||
| 1946 | is being used and package architecture support for both i586 | ||
| 1947 | and qemux86 exist. | ||
| 1948 | Packages for the i586 architecture are placed in | ||
| 1949 | <filename>build/tmp/deploy/ipk/i586</filename>, while packages for | ||
| 1950 | the qemux86 architecture are placed in | ||
| 1951 | <filename>build/tmp/deploy/ipk/qemux86</filename>. | ||
| 1952 | </para> | ||
| 1953 | </section> | ||
| 1954 | |||
| 1955 | <section id='bitbake-dev-environment'> | ||
| 1956 | <title>BitBake</title> | ||
| 1957 | |||
| 1958 | <para> | ||
| 1959 | The OpenEmbedded build system uses | ||
| 1960 | <ulink url='&YOCTO_DOCS_REF_URL;#bitbake-term'>BitBake</ulink> | ||
| 1961 | to produce images. | ||
| 1962 | You can see from the | ||
| 1963 | <link linkend='general-yocto-environment-figure'>general Yocto Project Development Environment figure</link>, | ||
| 1964 | the BitBake area consists of several functional areas. | ||
| 1965 | This section takes a closer look at each of those areas. | ||
| 1966 | </para> | ||
| 1967 | |||
| 1968 | <para> | ||
| 1969 | Separate documentation exists for the BitBake tool. | ||
| 1970 | See the | ||
| 1971 | <ulink url='&YOCTO_DOCS_BB_URL;#bitbake-user-manual'>BitBake User Manual</ulink> | ||
| 1972 | for reference material on BitBake. | ||
| 1973 | </para> | ||
| 1974 | |||
| 1975 | <section id='source-fetching-dev-environment'> | ||
| 1976 | <title>Source Fetching</title> | ||
| 1977 | |||
| 1978 | <para> | ||
| 1979 | The first stages of building a recipe are to fetch and unpack | ||
| 1980 | the source code: | ||
| 1981 | <imagedata fileref="figures/source-fetching.png" align="center" width="6.5in" depth="5in" /> | ||
| 1982 | </para> | ||
| 1983 | |||
| 1984 | <para> | ||
| 1985 | The | ||
| 1986 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-fetch'><filename>do_fetch</filename></ulink> | ||
| 1987 | and | ||
| 1988 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-unpack'><filename>do_unpack</filename></ulink> | ||
| 1989 | tasks fetch the source files and unpack them into the work | ||
| 1990 | directory. | ||
| 1991 | <note> | ||
| 1992 | For every local file (e.g. <filename>file://</filename>) | ||
| 1993 | that is part of a recipe's | ||
| 1994 | <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> | ||
| 1995 | statement, the OpenEmbedded build system takes a checksum | ||
| 1996 | of the file for the recipe and inserts the checksum into | ||
| 1997 | the signature for the <filename>do_fetch</filename>. | ||
| 1998 | If any local file has been modified, the | ||
| 1999 | <filename>do_fetch</filename> task and all tasks that | ||
| 2000 | depend on it are re-executed. | ||
| 2001 | </note> | ||
| 2002 | By default, everything is accomplished in the | ||
| 2003 | <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>, | ||
| 2004 | which has a defined structure. | ||
| 2005 | For additional general information on the Build Directory, | ||
| 2006 | see the | ||
| 2007 | "<ulink url='&YOCTO_DOCS_REF_URL;#structure-core-build'><filename>build/</filename></ulink>" | ||
| 2008 | section in the Yocto Project Reference Manual. | ||
| 2009 | </para> | ||
| 2010 | |||
| 2011 | <para> | ||
| 2012 | Unpacked source files are pointed to by the | ||
| 2013 | <ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink> | ||
| 2014 | variable. | ||
| 2015 | Each recipe has an area in the Build Directory where the | ||
| 2016 | unpacked source code resides. | ||
| 2017 | The name of that directory for any given recipe is defined from | ||
| 2018 | several different variables. | ||
| 2019 | You can see the variables that define these directories | ||
| 2020 | by looking at the figure: | ||
| 2021 | <itemizedlist> | ||
| 2022 | <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink> - | ||
| 2023 | The base directory where the OpenEmbedded build system | ||
| 2024 | performs all its work during the build. | ||
| 2025 | </para></listitem> | ||
| 2026 | <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></ulink> - | ||
| 2027 | The architecture of the built package or packages. | ||
| 2028 | </para></listitem> | ||
| 2029 | <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-TARGET_OS'><filename>TARGET_OS</filename></ulink> - | ||
| 2030 | The operating system of the target device. | ||
| 2031 | </para></listitem> | ||
| 2032 | <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink> - | ||
| 2033 | The name of the built package. | ||
| 2034 | </para></listitem> | ||
| 2035 | <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink> - | ||
| 2036 | The version of the recipe used to build the package. | ||
| 2037 | </para></listitem> | ||
| 2038 | <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink> - | ||
| 2039 | The revision of the recipe used to build the package. | ||
| 2040 | </para></listitem> | ||
| 2041 | <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink> - | ||
| 2042 | The location within <filename>TMPDIR</filename> where | ||
| 2043 | a specific package is built. | ||
| 2044 | </para></listitem> | ||
| 2045 | <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink> - | ||
| 2046 | Contains the unpacked source files for a given recipe. | ||
| 2047 | </para></listitem> | ||
| 2048 | </itemizedlist> | ||
| 2049 | </para> | ||
| 2050 | </section> | ||
| 2051 | |||
| 2052 | <section id='patching-dev-environment'> | ||
| 2053 | <title>Patching</title> | ||
| 2054 | |||
| 2055 | <para> | ||
| 2056 | Once source code is fetched and unpacked, BitBake locates | ||
| 2057 | patch files and applies them to the source files: | ||
| 2058 | <imagedata fileref="figures/patching.png" align="center" width="6in" depth="5in" /> | ||
| 2059 | </para> | ||
| 2060 | |||
| 2061 | <para> | ||
| 2062 | The | ||
| 2063 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-patch'><filename>do_patch</filename></ulink> | ||
| 2064 | task processes recipes by | ||
| 2065 | using the | ||
| 2066 | <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> | ||
| 2067 | variable to locate applicable patch files, which by default | ||
| 2068 | are <filename>*.patch</filename> or | ||
| 2069 | <filename>*.diff</filename> files, or any file if | ||
| 2070 | "apply=yes" is specified for the file in | ||
| 2071 | <filename>SRC_URI</filename>. | ||
| 2072 | </para> | ||
| 2073 | |||
| 2074 | <para> | ||
| 2075 | BitBake finds and applies multiple patches for a single recipe | ||
| 2076 | in the order in which it finds the patches. | ||
| 2077 | Patches are applied to the recipe's source files located in the | ||
| 2078 | <ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink> | ||
| 2079 | directory. | ||
| 2080 | </para> | ||
| 2081 | |||
| 2082 | <para> | ||
| 2083 | For more information on how the source directories are | ||
| 2084 | created, see the | ||
| 2085 | "<link linkend='source-fetching-dev-environment'>Source Fetching</link>" | ||
| 2086 | section. | ||
| 2087 | </para> | ||
| 2088 | </section> | ||
| 2089 | |||
| 2090 | <section id='configuration-and-compilation-dev-environment'> | ||
| 2091 | <title>Configuration and Compilation</title> | ||
| 2092 | |||
| 2093 | <para> | ||
| 2094 | After source code is patched, BitBake executes tasks that | ||
| 2095 | configure and compile the source code: | ||
| 2096 | <imagedata fileref="figures/configuration-compile-autoreconf.png" align="center" width="7in" depth="5in" /> | ||
| 2097 | </para> | ||
| 2098 | |||
| 2099 | <para> | ||
| 2100 | This step in the build process consists of three tasks: | ||
| 2101 | <itemizedlist> | ||
| 2102 | <listitem><para> | ||
| 2103 | <emphasis><ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-prepare_recipe_sysroot'><filename>do_prepare_recipe_sysroot</filename></ulink>:</emphasis> | ||
| 2104 | This task sets up the two sysroots in | ||
| 2105 | <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}</filename> | ||
| 2106 | (i.e. <filename>recipe-sysroot</filename> and | ||
| 2107 | <filename>recipe-sysroot-native</filename>) so that | ||
| 2108 | the sysroots contain the contents of the | ||
| 2109 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></ulink> | ||
| 2110 | tasks of the recipes on which the recipe | ||
| 2111 | containing the tasks depends. | ||
| 2112 | A sysroot exists for both the target and for the native | ||
| 2113 | binaries, which run on the host system. | ||
| 2114 | </para></listitem> | ||
| 2115 | <listitem><para><emphasis><filename>do_configure</filename>:</emphasis> | ||
| 2116 | This task configures the source by enabling and | ||
| 2117 | disabling any build-time and configuration options for | ||
| 2118 | the software being built. | ||
| 2119 | Configurations can come from the recipe itself as well | ||
| 2120 | as from an inherited class. | ||
| 2121 | Additionally, the software itself might configure itself | ||
| 2122 | depending on the target for which it is being built. | ||
| 2123 | </para> | ||
| 2124 | |||
| 2125 | <para>The configurations handled by the | ||
| 2126 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-configure'><filename>do_configure</filename></ulink> | ||
| 2127 | task are specific | ||
| 2128 | to source code configuration for the source code | ||
| 2129 | being built by the recipe.</para> | ||
| 2130 | |||
| 2131 | <para>If you are using the | ||
| 2132 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-autotools'><filename>autotools</filename></ulink> | ||
| 2133 | class, | ||
| 2134 | you can add additional configuration options by using | ||
| 2135 | the | ||
| 2136 | <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></ulink> | ||
| 2137 | or | ||
| 2138 | <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></ulink> | ||
| 2139 | variables. | ||
| 2140 | For information on how this variable works within | ||
| 2141 | that class, see the | ||
| 2142 | <filename>meta/classes/autotools.bbclass</filename> file. | ||
| 2143 | </para></listitem> | ||
| 2144 | <listitem><para><emphasis><filename>do_compile</filename>:</emphasis> | ||
| 2145 | Once a configuration task has been satisfied, BitBake | ||
| 2146 | compiles the source using the | ||
| 2147 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-compile'><filename>do_compile</filename></ulink> | ||
| 2148 | task. | ||
| 2149 | Compilation occurs in the directory pointed to by the | ||
| 2150 | <ulink url='&YOCTO_DOCS_REF_URL;#var-B'><filename>B</filename></ulink> | ||
| 2151 | variable. | ||
| 2152 | Realize that the <filename>B</filename> directory is, by | ||
| 2153 | default, the same as the | ||
| 2154 | <ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink> | ||
| 2155 | directory.</para></listitem> | ||
| 2156 | <listitem><para><emphasis><filename>do_install</filename>:</emphasis> | ||
| 2157 | Once compilation is done, BitBake executes the | ||
| 2158 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink> | ||
| 2159 | task. | ||
| 2160 | This task copies files from the <filename>B</filename> | ||
| 2161 | directory and places them in a holding area pointed to | ||
| 2162 | by the | ||
| 2163 | <ulink url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink> | ||
| 2164 | variable.</para></listitem> | ||
| 2165 | </itemizedlist> | ||
| 2166 | </para> | ||
| 2167 | </section> | ||
| 2168 | |||
| 2169 | <section id='package-splitting-dev-environment'> | ||
| 2170 | <title>Package Splitting</title> | ||
| 2171 | |||
| 2172 | <para> | ||
| 2173 | After source code is configured and compiled, the | ||
| 2174 | OpenEmbedded build system analyzes | ||
| 2175 | the results and splits the output into packages: | ||
| 2176 | <imagedata fileref="figures/analysis-for-package-splitting.png" align="center" width="7in" depth="7in" /> | ||
| 2177 | </para> | ||
| 2178 | |||
| 2179 | <para> | ||
| 2180 | The | ||
| 2181 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package'><filename>do_package</filename></ulink> | ||
| 2182 | and | ||
| 2183 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-packagedata'><filename>do_packagedata</filename></ulink> | ||
| 2184 | tasks combine to analyze | ||
| 2185 | the files found in the | ||
| 2186 | <ulink url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink> directory | ||
| 2187 | and split them into subsets based on available packages and | ||
| 2188 | files. | ||
| 2189 | The analyzing process involves the following as well as other | ||
| 2190 | items: splitting out debugging symbols, | ||
| 2191 | looking at shared library dependencies between packages, | ||
| 2192 | and looking at package relationships. | ||
| 2193 | The <filename>do_packagedata</filename> task creates package | ||
| 2194 | metadata based on the analysis such that the | ||
| 2195 | OpenEmbedded build system can generate the final packages. | ||
| 2196 | Working, staged, and intermediate results of the analysis | ||
| 2197 | and package splitting process use these areas: | ||
| 2198 | <itemizedlist> | ||
| 2199 | <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PKGD'><filename>PKGD</filename></ulink> - | ||
| 2200 | The destination directory for packages before they are | ||
| 2201 | split. | ||
| 2202 | </para></listitem> | ||
| 2203 | <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></ulink> - | ||
| 2204 | A shared, global-state directory that holds data | ||
| 2205 | generated during the packaging process. | ||
| 2206 | </para></listitem> | ||
| 2207 | <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PKGDESTWORK'><filename>PKGDESTWORK</filename></ulink> - | ||
| 2208 | A temporary work area used by the | ||
| 2209 | <filename>do_package</filename> task. | ||
| 2210 | </para></listitem> | ||
| 2211 | <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PKGDEST'><filename>PKGDEST</filename></ulink> - | ||
| 2212 | The parent directory for packages after they have | ||
| 2213 | been split. | ||
| 2214 | </para></listitem> | ||
| 2215 | </itemizedlist> | ||
| 2216 | The <ulink url='&YOCTO_DOCS_REF_URL;#var-FILES'><filename>FILES</filename></ulink> | ||
| 2217 | variable defines the files that go into each package in | ||
| 2218 | <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'><filename>PACKAGES</filename></ulink>. | ||
| 2219 | If you want details on how this is accomplished, you can | ||
| 2220 | look at the | ||
| 2221 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-package'><filename>package</filename></ulink> | ||
| 2222 | class. | ||
| 2223 | </para> | ||
| 2224 | |||
| 2225 | <para> | ||
| 2226 | Depending on the type of packages being created (RPM, DEB, or | ||
| 2227 | IPK), the <filename>do_package_write_*</filename> task | ||
| 2228 | creates the actual packages and places them in the | ||
| 2229 | Package Feed area, which is | ||
| 2230 | <filename>${TMPDIR}/deploy</filename>. | ||
| 2231 | You can see the | ||
| 2232 | "<link linkend='package-feeds-dev-environment'>Package Feeds</link>" | ||
| 2233 | section for more detail on that part of the build process. | ||
| 2234 | <note> | ||
| 2235 | Support for creating feeds directly from the | ||
| 2236 | <filename>deploy/*</filename> directories does not exist. | ||
| 2237 | Creating such feeds usually requires some kind of feed | ||
| 2238 | maintenance mechanism that would upload the new packages | ||
| 2239 | into an official package feed (e.g. the | ||
| 2240 | Ångström distribution). | ||
| 2241 | This functionality is highly distribution-specific | ||
| 2242 | and thus is not provided out of the box. | ||
| 2243 | </note> | ||
| 2244 | </para> | ||
| 2245 | </section> | ||
| 2246 | |||
| 2247 | <section id='image-generation-dev-environment'> | ||
| 2248 | <title>Image Generation</title> | ||
| 2249 | |||
| 2250 | <para> | ||
| 2251 | Once packages are split and stored in the Package Feeds area, | ||
| 2252 | the OpenEmbedded build system uses BitBake to generate the | ||
| 2253 | root filesystem image: | ||
| 2254 | <imagedata fileref="figures/image-generation.png" align="center" width="6in" depth="7in" /> | ||
| 2255 | </para> | ||
| 2256 | |||
| 2257 | <para> | ||
| 2258 | The image generation process consists of several stages and | ||
| 2259 | depends on several tasks and variables. | ||
| 2260 | The | ||
| 2261 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-rootfs'><filename>do_rootfs</filename></ulink> | ||
| 2262 | task creates the root filesystem (file and directory structure) | ||
| 2263 | for an image. | ||
| 2264 | This task uses several key variables to help create the list | ||
| 2265 | of packages to actually install: | ||
| 2266 | <itemizedlist> | ||
| 2267 | <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></ulink>: | ||
| 2268 | Lists out the base set of packages to install from | ||
| 2269 | the Package Feeds area.</para></listitem> | ||
| 2270 | <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_EXCLUDE'><filename>PACKAGE_EXCLUDE</filename></ulink>: | ||
| 2271 | Specifies packages that should not be installed. | ||
| 2272 | </para></listitem> | ||
| 2273 | <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink>: | ||
| 2274 | Specifies features to include in the image. | ||
| 2275 | Most of these features map to additional packages for | ||
| 2276 | installation.</para></listitem> | ||
| 2277 | <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></ulink>: | ||
| 2278 | Specifies the package backend to use and consequently | ||
| 2279 | helps determine where to locate packages within the | ||
| 2280 | Package Feeds area.</para></listitem> | ||
| 2281 | <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_LINGUAS'><filename>IMAGE_LINGUAS</filename></ulink>: | ||
| 2282 | Determines the language(s) for which additional | ||
| 2283 | language support packages are installed. | ||
| 2284 | </para></listitem> | ||
| 2285 | <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_INSTALL'><filename>PACKAGE_INSTALL</filename></ulink>: | ||
| 2286 | The final list of packages passed to the package manager | ||
| 2287 | for installation into the image. | ||
| 2288 | </para></listitem> | ||
| 2289 | </itemizedlist> | ||
| 2290 | </para> | ||
| 2291 | |||
| 2292 | <para> | ||
| 2293 | With | ||
| 2294 | <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_ROOTFS'><filename>IMAGE_ROOTFS</filename></ulink> | ||
| 2295 | pointing to the location of the filesystem under construction and | ||
| 2296 | the <filename>PACKAGE_INSTALL</filename> variable providing the | ||
| 2297 | final list of packages to install, the root file system is | ||
| 2298 | created. | ||
| 2299 | </para> | ||
| 2300 | |||
| 2301 | <para> | ||
| 2302 | Package installation is under control of the package manager | ||
| 2303 | (e.g. dnf/rpm, opkg, or apt/dpkg) regardless of whether or | ||
| 2304 | not package management is enabled for the target. | ||
| 2305 | At the end of the process, if package management is not | ||
| 2306 | enabled for the target, the package manager's data files | ||
| 2307 | are deleted from the root filesystem. | ||
| 2308 | As part of the final stage of package installation, postinstall | ||
| 2309 | scripts that are part of the packages are run. | ||
| 2310 | Any scripts that fail to run | ||
| 2311 | on the build host are run on the target when the target system | ||
| 2312 | is first booted. | ||
| 2313 | If you are using a | ||
| 2314 | <ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-read-only-root-filesystem'>read-only root filesystem</ulink>, | ||
| 2315 | all the post installation scripts must succeed during the | ||
| 2316 | package installation phase since the root filesystem is | ||
| 2317 | read-only. | ||
| 2318 | </para> | ||
| 2319 | |||
| 2320 | <para> | ||
| 2321 | The final stages of the <filename>do_rootfs</filename> task | ||
| 2322 | handle post processing. | ||
| 2323 | Post processing includes creation of a manifest file and | ||
| 2324 | optimizations. | ||
| 2325 | </para> | ||
| 2326 | |||
| 2327 | <para> | ||
| 2328 | The manifest file (<filename>.manifest</filename>) resides | ||
| 2329 | in the same directory as the root filesystem image. | ||
| 2330 | This file lists out, line-by-line, the installed packages. | ||
| 2331 | The manifest file is useful for the | ||
| 2332 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-testimage*'><filename>testimage</filename></ulink> | ||
| 2333 | class, for example, to determine whether or not to run | ||
| 2334 | specific tests. | ||
| 2335 | See the | ||
| 2336 | <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_MANIFEST'><filename>IMAGE_MANIFEST</filename></ulink> | ||
| 2337 | variable for additional information. | ||
| 2338 | </para> | ||
| 2339 | |||
| 2340 | <para> | ||
| 2341 | Optimizing processes run across the image include | ||
| 2342 | <filename>mklibs</filename>, <filename>prelink</filename>, | ||
| 2343 | and any other post-processing commands as defined by the | ||
| 2344 | <ulink url='&YOCTO_DOCS_REF_URL;#var-ROOTFS_POSTPROCESS_COMMAND'><filename>ROOTFS_POSTPROCESS_COMMAND</filename></ulink> | ||
| 2345 | variable. | ||
| 2346 | The <filename>mklibs</filename> process optimizes the size | ||
| 2347 | of the libraries, while the | ||
| 2348 | <filename>prelink</filename> process optimizes the dynamic | ||
| 2349 | linking of shared libraries to reduce start up time of | ||
| 2350 | executables. | ||
| 2351 | </para> | ||
| 2352 | |||
| 2353 | <para> | ||
| 2354 | After the root filesystem is built, processing begins on | ||
| 2355 | the image through the | ||
| 2356 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-image'><filename>do_image</filename></ulink> | ||
| 2357 | task. | ||
| 2358 | The build system runs any pre-processing commands as defined | ||
| 2359 | by the | ||
| 2360 | <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_PREPROCESS_COMMAND'><filename>IMAGE_PREPROCESS_COMMAND</filename></ulink> | ||
| 2361 | variable. | ||
| 2362 | This variable specifies a list of functions to call before | ||
| 2363 | the OpenEmbedded build system creates the final image output | ||
| 2364 | files. | ||
| 2365 | </para> | ||
| 2366 | |||
| 2367 | <para> | ||
| 2368 | The OpenEmbedded build system dynamically creates | ||
| 2369 | <filename>do_image_*</filename> tasks as needed, based | ||
| 2370 | on the image types specified in the | ||
| 2371 | <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></ulink> | ||
| 2372 | variable. | ||
| 2373 | The process turns everything into an image file or a set of | ||
| 2374 | image files and compresses the root filesystem image to reduce | ||
| 2375 | the overall size of the image. | ||
| 2376 | The formats used for the root filesystem depend on the | ||
| 2377 | <filename>IMAGE_FSTYPES</filename> variable. | ||
| 2378 | </para> | ||
| 2379 | |||
| 2380 | <para> | ||
| 2381 | As an example, a dynamically created task when creating a | ||
| 2382 | particular image <replaceable>type</replaceable> would take the | ||
| 2383 | following form: | ||
| 2384 | <literallayout class='monospaced'> | ||
| 2385 | do_image_<replaceable>type</replaceable>[depends] | ||
| 2386 | </literallayout> | ||
| 2387 | So, if the <replaceable>type</replaceable> as specified by the | ||
| 2388 | <filename>IMAGE_FSTYPES</filename> were | ||
| 2389 | <filename>ext4</filename>, the dynamically generated task | ||
| 2390 | would be as follows: | ||
| 2391 | <literallayout class='monospaced'> | ||
| 2392 | do_image_ext4[depends] | ||
| 2393 | </literallayout> | ||
| 2394 | </para> | ||
| 2395 | |||
| 2396 | <para> | ||
| 2397 | The final task involved in image creation is the | ||
| 2398 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-image-complete'><filename>do_image_complete</filename></ulink> | ||
| 2399 | task. | ||
| 2400 | This task completes the image by applying any image | ||
| 2401 | post processing as defined through the | ||
| 2402 | <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_POSTPROCESS_COMMAND'><filename>IMAGE_POSTPROCESS_COMMAND</filename></ulink> | ||
| 2403 | variable. | ||
| 2404 | The variable specifies a list of functions to call once the | ||
| 2405 | OpenEmbedded build system has created the final image output | ||
| 2406 | files. | ||
| 2407 | </para> | ||
| 2408 | |||
| 2409 | <note> | ||
| 2410 | The entire image generation process is run under Pseudo. | ||
| 2411 | Running under Pseudo ensures that the files in the root | ||
| 2412 | filesystem have correct ownership. | ||
| 2413 | </note> | ||
| 2414 | </section> | ||
| 2415 | |||
| 2416 | <section id='sdk-generation-dev-environment'> | ||
| 2417 | <title>SDK Generation</title> | ||
| 2418 | |||
| 2419 | <para> | ||
| 2420 | The OpenEmbedded build system uses BitBake to generate the | ||
| 2421 | Software Development Kit (SDK) installer script for both the | ||
| 2422 | standard and extensible SDKs: | ||
| 2423 | <imagedata fileref="figures/sdk-generation.png" align="center" /> | ||
| 2424 | </para> | ||
| 2425 | |||
| 2426 | <note> | ||
| 2427 | For more information on the cross-development toolchain | ||
| 2428 | generation, see the | ||
| 2429 | "<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>" | ||
| 2430 | section. | ||
| 2431 | For information on advantages gained when building a | ||
| 2432 | cross-development toolchain using the | ||
| 2433 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-populate_sdk'><filename>do_populate_sdk</filename></ulink> | ||
| 2434 | task, see the | ||
| 2435 | "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-building-an-sdk-installer'>Building an SDK Installer</ulink>" | ||
| 2436 | section in the Yocto Project Application Development and the | ||
| 2437 | Extensible Software Development Kit (SDK) manual. | ||
| 2438 | </note> | ||
| 2439 | |||
| 2440 | <para> | ||
| 2441 | Like image generation, the SDK script process consists of | ||
| 2442 | several stages and depends on many variables. | ||
| 2443 | The <filename>do_populate_sdk</filename> and | ||
| 2444 | <filename>do_populate_sdk_ext</filename> tasks use these | ||
| 2445 | key variables to help create the list of packages to actually | ||
| 2446 | install. | ||
| 2447 | For information on the variables listed in the figure, see the | ||
| 2448 | "<link linkend='sdk-dev-environment'>Application Development SDK</link>" | ||
| 2449 | section. | ||
| 2450 | </para> | ||
| 2451 | |||
| 2452 | <para> | ||
| 2453 | The <filename>do_populate_sdk</filename> task helps create | ||
| 2454 | the standard SDK and handles two parts: a target part and a | ||
| 2455 | host part. | ||
| 2456 | The target part is the part built for the target hardware and | ||
| 2457 | includes libraries and headers. | ||
| 2458 | The host part is the part of the SDK that runs on the | ||
| 2459 | <ulink url='&YOCTO_DOCS_REF_URL;#var-SDKMACHINE'><filename>SDKMACHINE</filename></ulink>. | ||
| 2460 | </para> | ||
| 2461 | |||
| 2462 | <para> | ||
| 2463 | The <filename>do_populate_sdk_ext</filename> task helps create | ||
| 2464 | the extensible SDK and handles host and target parts | ||
| 2465 | differently than its counter part does for the standard SDK. | ||
| 2466 | For the extensible SDK, the task encapsulates the build system, | ||
| 2467 | which includes everything needed (host and target) for the SDK. | ||
| 2468 | </para> | ||
| 2469 | |||
| 2470 | <para> | ||
| 2471 | Regardless of the type of SDK being constructed, the | ||
| 2472 | tasks perform some cleanup after which a cross-development | ||
| 2473 | environment setup script and any needed configuration files | ||
| 2474 | are created. | ||
| 2475 | The final output is the Cross-development | ||
| 2476 | toolchain installation script (<filename>.sh</filename> file), | ||
| 2477 | which includes the environment setup script. | ||
| 2478 | </para> | ||
| 2479 | </section> | ||
| 2480 | |||
| 2481 | <section id='stamp-files-and-the-rerunning-of-tasks'> | ||
| 2482 | <title>Stamp Files and the Rerunning of Tasks</title> | ||
| 2483 | |||
| 2484 | <para> | ||
| 2485 | For each task that completes successfully, BitBake writes a | ||
| 2486 | stamp file into the | ||
| 2487 | <ulink url='&YOCTO_DOCS_REF_URL;#var-STAMPS_DIR'><filename>STAMPS_DIR</filename></ulink> | ||
| 2488 | directory. | ||
| 2489 | The beginning of the stamp file's filename is determined by the | ||
| 2490 | <ulink url='&YOCTO_DOCS_REF_URL;#var-STAMP'><filename>STAMP</filename></ulink> | ||
| 2491 | variable, and the end of the name consists of the task's name | ||
| 2492 | and current | ||
| 2493 | <link linkend='overview-checksums'>input checksum</link>. | ||
| 2494 | <note> | ||
| 2495 | This naming scheme assumes that | ||
| 2496 | <ulink url='&YOCTO_DOCS_BB_URL;#var-BB_SIGNATURE_HANDLER'><filename>BB_SIGNATURE_HANDLER</filename></ulink> | ||
| 2497 | is "OEBasicHash", which is almost always the case in | ||
| 2498 | current OpenEmbedded. | ||
| 2499 | </note> | ||
| 2500 | To determine if a task needs to be rerun, BitBake checks if a | ||
| 2501 | stamp file with a matching input checksum exists for the task. | ||
| 2502 | If such a stamp file exists, the task's output is assumed to | ||
| 2503 | exist and still be valid. | ||
| 2504 | If the file does not exist, the task is rerun. | ||
| 2505 | <note> | ||
| 2506 | <para>The stamp mechanism is more general than the shared | ||
| 2507 | state (sstate) cache mechanism described in the | ||
| 2508 | "<link linkend='setscene-tasks-and-shared-state'>Setscene Tasks and Shared State</link>" | ||
| 2509 | section. | ||
| 2510 | BitBake avoids rerunning any task that has a valid | ||
| 2511 | stamp file, not just tasks that can be accelerated through | ||
| 2512 | the sstate cache.</para> | ||
| 2513 | <para>However, you should realize that stamp files only | ||
| 2514 | serve as a marker that some work has been done and that | ||
| 2515 | these files do not record task output. | ||
| 2516 | The actual task output would usually be somewhere in | ||
| 2517 | <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink> | ||
| 2518 | (e.g. in some recipe's | ||
| 2519 | <ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>.) | ||
| 2520 | What the sstate cache mechanism adds is a way to cache task | ||
| 2521 | output that can then be shared between build machines. | ||
| 2522 | </para> | ||
| 2523 | </note> | ||
| 2524 | Since <filename>STAMPS_DIR</filename> is usually a subdirectory | ||
| 2525 | of <filename>TMPDIR</filename>, removing | ||
| 2526 | <filename>TMPDIR</filename> will also remove | ||
| 2527 | <filename>STAMPS_DIR</filename>, which means tasks will | ||
| 2528 | properly be rerun to repopulate <filename>TMPDIR</filename>. | ||
| 2529 | </para> | ||
| 2530 | |||
| 2531 | <para> | ||
| 2532 | If you want some task to always be considered "out of date", | ||
| 2533 | you can mark it with the | ||
| 2534 | <ulink url='&YOCTO_DOCS_BB_URL;#variable-flags'><filename>nostamp</filename></ulink> | ||
| 2535 | varflag. | ||
| 2536 | If some other task depends on such a task, then that task will | ||
| 2537 | also always be considered out of date, which might not be what | ||
| 2538 | you want. | ||
| 2539 | </para> | ||
| 2540 | |||
| 2541 | <para> | ||
| 2542 | For details on how to view information about a task's | ||
| 2543 | signature, see the | ||
| 2544 | "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-viewing-task-variable-dependencies'>Viewing Task Variable Dependencies</ulink>" | ||
| 2545 | section in the Yocto Project Development Tasks Manual. | ||
| 2546 | </para> | ||
| 2547 | </section> | ||
| 2548 | |||
| 2549 | <section id='setscene-tasks-and-shared-state'> | ||
| 2550 | <title>Setscene Tasks and Shared State</title> | ||
| 2551 | |||
| 2552 | <para> | ||
| 2553 | The description of tasks so far assumes that BitBake needs to | ||
| 2554 | build everything and there are no prebuilt objects available. | ||
| 2555 | BitBake does support skipping tasks if prebuilt objects are | ||
| 2556 | available. | ||
| 2557 | These objects are usually made available in the form of a | ||
| 2558 | shared state (sstate) cache. | ||
| 2559 | <note> | ||
| 2560 | For information on variables affecting sstate, see the | ||
| 2561 | <ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_DIR'><filename>SSTATE_DIR</filename></ulink> | ||
| 2562 | and | ||
| 2563 | <ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></ulink> | ||
| 2564 | variables. | ||
| 2565 | </note> | ||
| 2566 | </para> | ||
| 2567 | |||
| 2568 | <para> | ||
| 2569 | The idea of a setscene task (i.e | ||
| 2570 | <filename>do_</filename><replaceable>taskname</replaceable><filename>_setscene</filename>) | ||
| 2571 | is a version of the task where | ||
| 2572 | instead of building something, BitBake can skip to the end | ||
| 2573 | result and simply place a set of files into specific locations | ||
| 2574 | as needed. | ||
| 2575 | In some cases, it makes sense to have a setscene task variant | ||
| 2576 | (e.g. generating package files in the | ||
| 2577 | <filename>do_package_write_*</filename> task). | ||
| 2578 | In other cases, it does not make sense, (e.g. a | ||
| 2579 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-patch'><filename>do_patch</filename></ulink> | ||
| 2580 | task or | ||
| 2581 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-unpack'><filename>do_unpack</filename></ulink> | ||
| 2582 | task) since the work involved would be equal to or greater than | ||
| 2583 | the underlying task. | ||
| 2584 | </para> | ||
| 2585 | |||
| 2586 | <para> | ||
| 2587 | In the OpenEmbedded build system, the common tasks that have | ||
| 2588 | setscene variants are | ||
| 2589 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package'><filename>do_package</filename></ulink>, | ||
| 2590 | <filename>do_package_write_*</filename>, | ||
| 2591 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-deploy'><filename>do_deploy</filename></ulink>, | ||
| 2592 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-packagedata'><filename>do_packagedata</filename></ulink>, | ||
| 2593 | and | ||
| 2594 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></ulink>. | ||
| 2595 | Notice that these are most of the tasks whose output is an | ||
| 2596 | end result. | ||
| 2597 | </para> | ||
| 2598 | |||
| 2599 | <para> | ||
| 2600 | The OpenEmbedded build system has knowledge of the relationship | ||
| 2601 | between these tasks and other tasks that precede them. | ||
| 2602 | For example, if BitBake runs | ||
| 2603 | <filename>do_populate_sysroot_setscene</filename> for | ||
| 2604 | something, there is little point in running any of the | ||
| 2605 | <filename>do_fetch</filename>, <filename>do_unpack</filename>, | ||
| 2606 | <filename>do_patch</filename>, | ||
| 2607 | <filename>do_configure</filename>, | ||
| 2608 | <filename>do_compile</filename>, and | ||
| 2609 | <filename>do_install</filename> tasks. | ||
| 2610 | However, if <filename>do_package</filename> needs to be run, | ||
| 2611 | BitBake would need to run those other tasks. | ||
| 2612 | </para> | ||
| 2613 | |||
| 2614 | <para> | ||
| 2615 | It becomes more complicated if everything can come from an | ||
| 2616 | sstate cache because some objects are simply not required at | ||
| 2617 | all. | ||
| 2618 | For example, you do not need a compiler or native tools, such | ||
| 2619 | as quilt, if there is nothing to compile or patch. | ||
| 2620 | If the <filename>do_package_write_*</filename> packages are | ||
| 2621 | available from sstate, BitBake does not need the | ||
| 2622 | <filename>do_package</filename> task data. | ||
| 2623 | </para> | ||
| 2624 | |||
| 2625 | <para> | ||
| 2626 | To handle all these complexities, BitBake runs in two phases. | ||
| 2627 | The first is the "setscene" stage. | ||
| 2628 | During this stage, BitBake first checks the sstate cache for | ||
| 2629 | any targets it is planning to build. | ||
| 2630 | BitBake does a fast check to see if the object exists rather | ||
| 2631 | than a complete download. | ||
| 2632 | If nothing exists, the second phase, which is the setscene | ||
| 2633 | stage, completes and the main build proceeds. | ||
| 2634 | </para> | ||
| 2635 | |||
| 2636 | <para> | ||
| 2637 | If objects are found in the sstate cache, the OpenEmbedded | ||
| 2638 | build system works backwards from the end targets specified | ||
| 2639 | by the user. | ||
| 2640 | For example, if an image is being built, the OpenEmbedded build | ||
| 2641 | system first looks for the packages needed for that image and | ||
| 2642 | the tools needed to construct an image. | ||
| 2643 | If those are available, the compiler is not needed. | ||
| 2644 | Thus, the compiler is not even downloaded. | ||
| 2645 | If something was found to be unavailable, or the download or | ||
| 2646 | setscene task fails, the OpenEmbedded build system then tries | ||
| 2647 | to install dependencies, such as the compiler, from the cache. | ||
| 2648 | </para> | ||
| 2649 | |||
| 2650 | <para> | ||
| 2651 | The availability of objects in the sstate cache is handled by | ||
| 2652 | the function specified by the | ||
| 2653 | <ulink url='&YOCTO_DOCS_BB_URL;#var-BB_HASHCHECK_FUNCTION'><filename>BB_HASHCHECK_FUNCTION</filename></ulink> | ||
| 2654 | variable and returns a list of the objects that are available. | ||
| 2655 | The function specified by the | ||
| 2656 | <ulink url='&YOCTO_DOCS_BB_URL;#var-BB_SETSCENE_DEPVALID'><filename>BB_SETSCENE_DEPVALID</filename></ulink> | ||
| 2657 | variable is the function that determines whether a given | ||
| 2658 | dependency needs to be followed, and whether for any given | ||
| 2659 | relationship the function needs to be passed. | ||
| 2660 | The function returns a True or False value. | ||
| 2661 | </para> | ||
| 2662 | </section> | ||
| 2663 | </section> | ||
| 2664 | |||
| 2665 | <section id='images-dev-environment'> | ||
| 2666 | <title>Images</title> | ||
| 2667 | |||
| 2668 | <para> | ||
| 2669 | The images produced by the OpenEmbedded build system | ||
| 2670 | are compressed forms of the | ||
| 2671 | root filesystem that are ready to boot on a target device. | ||
| 2672 | You can see from the | ||
| 2673 | <link linkend='general-yocto-environment-figure'>general Yocto Project Development Environment figure</link> | ||
| 2674 | that BitBake output, in part, consists of images. | ||
| 2675 | This section is going to look more closely at this output: | ||
| 2676 | <imagedata fileref="figures/images.png" align="center" width="5.5in" depth="5.5in" /> | ||
| 2677 | </para> | ||
| 2678 | |||
| 2679 | <para> | ||
| 2680 | For a list of example images that the Yocto Project provides, | ||
| 2681 | see the | ||
| 2682 | "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" | ||
| 2683 | chapter in the Yocto Project Reference Manual. | ||
| 2684 | </para> | ||
| 2685 | |||
| 2686 | <para> | ||
| 2687 | Images are written out to the | ||
| 2688 | <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink> | ||
| 2689 | inside the | ||
| 2690 | <filename>tmp/deploy/images/<replaceable>machine</replaceable>/</filename> | ||
| 2691 | folder as shown in the figure. | ||
| 2692 | This folder contains any files expected to be loaded on the | ||
| 2693 | target device. | ||
| 2694 | The | ||
| 2695 | <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></ulink> | ||
| 2696 | variable points to the <filename>deploy</filename> directory, | ||
| 2697 | while the | ||
| 2698 | <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPLOY_DIR_IMAGE'><filename>DEPLOY_DIR_IMAGE</filename></ulink> | ||
| 2699 | variable points to the appropriate directory containing images for | ||
| 2700 | the current configuration. | ||
| 2701 | <itemizedlist> | ||
| 2702 | <listitem><para><filename><replaceable>kernel-image</replaceable></filename>: | ||
| 2703 | A kernel binary file. | ||
| 2704 | The | ||
| 2705 | <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_IMAGETYPE'><filename>KERNEL_IMAGETYPE</filename></ulink> | ||
| 2706 | variable setting determines the naming scheme for the | ||
| 2707 | kernel image file. | ||
| 2708 | Depending on that variable, the file could begin with | ||
| 2709 | a variety of naming strings. | ||
| 2710 | The <filename>deploy/images/<replaceable>machine</replaceable></filename> | ||
| 2711 | directory can contain multiple image files for the | ||
| 2712 | machine.</para></listitem> | ||
| 2713 | <listitem><para><filename><replaceable>root-filesystem-image</replaceable></filename>: | ||
| 2714 | Root filesystems for the target device (e.g. | ||
| 2715 | <filename>*.ext3</filename> or <filename>*.bz2</filename> | ||
| 2716 | files). | ||
| 2717 | The | ||
| 2718 | <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></ulink> | ||
| 2719 | variable setting determines the root filesystem image | ||
| 2720 | type. | ||
| 2721 | The <filename>deploy/images/<replaceable>machine</replaceable></filename> | ||
| 2722 | directory can contain multiple root filesystems for the | ||
| 2723 | machine.</para></listitem> | ||
| 2724 | <listitem><para><filename><replaceable>kernel-modules</replaceable></filename>: | ||
| 2725 | Tarballs that contain all the modules built for the kernel. | ||
| 2726 | Kernel module tarballs exist for legacy purposes and | ||
| 2727 | can be suppressed by setting the | ||
| 2728 | <ulink url='&YOCTO_DOCS_REF_URL;#var-MODULE_TARBALL_DEPLOY'><filename>MODULE_TARBALL_DEPLOY</filename></ulink> | ||
| 2729 | variable to "0". | ||
| 2730 | The <filename>deploy/images/<replaceable>machine</replaceable></filename> | ||
| 2731 | directory can contain multiple kernel module tarballs | ||
| 2732 | for the machine.</para></listitem> | ||
| 2733 | <listitem><para><filename><replaceable>bootloaders</replaceable></filename>: | ||
| 2734 | Bootloaders supporting the image, if applicable to the | ||
| 2735 | target machine. | ||
| 2736 | The <filename>deploy/images/<replaceable>machine</replaceable></filename> | ||
| 2737 | directory can contain multiple bootloaders for the | ||
| 2738 | machine.</para></listitem> | ||
| 2739 | <listitem><para><filename><replaceable>symlinks</replaceable></filename>: | ||
| 2740 | The <filename>deploy/images/<replaceable>machine</replaceable></filename> | ||
| 2741 | folder contains | ||
| 2742 | a symbolic link that points to the most recently built file | ||
| 2743 | for each machine. | ||
| 2744 | These links might be useful for external scripts that | ||
| 2745 | need to obtain the latest version of each file. | ||
| 2746 | </para></listitem> | ||
| 2747 | </itemizedlist> | ||
| 2748 | </para> | ||
| 2749 | </section> | ||
| 2750 | |||
| 2751 | <section id='sdk-dev-environment'> | ||
| 2752 | <title>Application Development SDK</title> | ||
| 2753 | |||
| 2754 | <para> | ||
| 2755 | In the | ||
| 2756 | <link linkend='general-yocto-environment-figure'>general Yocto Project Development Environment figure</link>, | ||
| 2757 | the output labeled "Application Development SDK" represents an | ||
| 2758 | SDK. | ||
| 2759 | The SDK generation process differs depending on whether you build | ||
| 2760 | a standard SDK | ||
| 2761 | (e.g. <filename>bitbake -c populate_sdk</filename> <replaceable>imagename</replaceable>) | ||
| 2762 | or an extensible SDK | ||
| 2763 | (e.g. <filename>bitbake -c populate_sdk_ext</filename> <replaceable>imagename</replaceable>). | ||
| 2764 | This section is going to take a closer look at this output: | ||
| 2765 | <imagedata fileref="figures/sdk.png" align="center" width="9in" depth="7.25in" /> | ||
| 2766 | </para> | ||
| 2767 | |||
| 2768 | <para> | ||
| 2769 | The specific form of this output is a self-extracting | ||
| 2770 | SDK installer (<filename>*.sh</filename>) that, when run, | ||
| 2771 | installs the SDK, which consists of a cross-development | ||
| 2772 | toolchain, a set of libraries and headers, and an SDK | ||
| 2773 | environment setup script. | ||
| 2774 | Running this installer essentially sets up your | ||
| 2775 | cross-development environment. | ||
| 2776 | You can think of the cross-toolchain as the "host" | ||
| 2777 | part because it runs on the SDK machine. | ||
| 2778 | You can think of the libraries and headers as the "target" | ||
| 2779 | part because they are built for the target hardware. | ||
| 2780 | The environment setup script is added so that you can initialize | ||
| 2781 | the environment before using the tools. | ||
| 2782 | </para> | ||
| 2783 | |||
| 2784 | <note><title>Notes</title> | ||
| 2785 | <itemizedlist> | ||
| 2786 | <listitem><para> | ||
| 2787 | The Yocto Project supports several methods by which you can | ||
| 2788 | set up this cross-development environment. | ||
| 2789 | These methods include downloading pre-built SDK installers | ||
| 2790 | or building and installing your own SDK installer. | ||
| 2791 | </para></listitem> | ||
| 2792 | <listitem><para> | ||
| 2793 | For background information on cross-development toolchains | ||
| 2794 | in the Yocto Project development environment, see the | ||
| 2795 | "<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>" | ||
| 2796 | section. | ||
| 2797 | </para></listitem> | ||
| 2798 | <listitem><para> | ||
| 2799 | For information on setting up a cross-development | ||
| 2800 | environment, see the | ||
| 2801 | <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink> | ||
| 2802 | manual. | ||
| 2803 | </para></listitem> | ||
| 2804 | </itemizedlist> | ||
| 2805 | </note> | ||
| 2806 | |||
| 2807 | <para> | ||
| 2808 | Once built, the SDK installers are written out to the | ||
| 2809 | <filename>deploy/sdk</filename> folder inside the | ||
| 2810 | <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink> | ||
| 2811 | as shown in the figure at the beginning of this section. | ||
| 2812 | Depending on the type of SDK, several variables exist that help | ||
| 2813 | configure these files. | ||
| 2814 | The following list shows the variables associated with a standard | ||
| 2815 | SDK: | ||
| 2816 | <itemizedlist> | ||
| 2817 | <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></ulink>: | ||
| 2818 | Points to the <filename>deploy</filename> | ||
| 2819 | directory.</para></listitem> | ||
| 2820 | <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-SDKMACHINE'><filename>SDKMACHINE</filename></ulink>: | ||
| 2821 | Specifies the architecture of the machine | ||
| 2822 | on which the cross-development tools are run to | ||
| 2823 | create packages for the target hardware. | ||
| 2824 | </para></listitem> | ||
| 2825 | <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-SDKIMAGE_FEATURES'><filename>SDKIMAGE_FEATURES</filename></ulink>: | ||
| 2826 | Lists the features to include in the "target" part | ||
| 2827 | of the SDK. | ||
| 2828 | </para></listitem> | ||
| 2829 | <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-TOOLCHAIN_HOST_TASK'><filename>TOOLCHAIN_HOST_TASK</filename></ulink>: | ||
| 2830 | Lists packages that make up the host | ||
| 2831 | part of the SDK (i.e. the part that runs on | ||
| 2832 | the <filename>SDKMACHINE</filename>). | ||
| 2833 | When you use | ||
| 2834 | <filename>bitbake -c populate_sdk <replaceable>imagename</replaceable></filename> | ||
| 2835 | to create the SDK, a set of default packages | ||
| 2836 | apply. | ||
| 2837 | This variable allows you to add more packages. | ||
| 2838 | </para></listitem> | ||
| 2839 | <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-TOOLCHAIN_TARGET_TASK'><filename>TOOLCHAIN_TARGET_TASK</filename></ulink>: | ||
| 2840 | Lists packages that make up the target part | ||
| 2841 | of the SDK (i.e. the part built for the | ||
| 2842 | target hardware). | ||
| 2843 | </para></listitem> | ||
| 2844 | <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-SDKPATH'><filename>SDKPATH</filename></ulink>: | ||
| 2845 | Defines the default SDK installation path offered by the | ||
| 2846 | installation script. | ||
| 2847 | </para></listitem> | ||
| 2848 | </itemizedlist> | ||
| 2849 | This next list, shows the variables associated with an extensible | ||
| 2850 | SDK: | ||
| 2851 | <itemizedlist> | ||
| 2852 | <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></ulink>: | ||
| 2853 | Points to the <filename>deploy</filename> directory. | ||
| 2854 | </para></listitem> | ||
| 2855 | <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_EXT_TYPE'><filename>SDK_EXT_TYPE</filename></ulink>: | ||
| 2856 | Controls whether or not shared state artifacts are copied | ||
| 2857 | into the extensible SDK. | ||
| 2858 | By default, all required shared state artifacts are copied | ||
| 2859 | into the SDK. | ||
| 2860 | </para></listitem> | ||
| 2861 | <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_INCLUDE_PKGDATA'><filename>SDK_INCLUDE_PKGDATA</filename></ulink>: | ||
| 2862 | Specifies whether or not packagedata will be included in | ||
| 2863 | the extensible SDK for all recipes in the "world" target. | ||
| 2864 | </para></listitem> | ||
| 2865 | <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_INCLUDE_TOOLCHAIN'><filename>SDK_INCLUDE_TOOLCHAIN</filename></ulink>: | ||
| 2866 | Specifies whether or not the toolchain will be included | ||
| 2867 | when building the extensible SDK. | ||
| 2868 | </para></listitem> | ||
| 2869 | <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_LOCAL_CONF_WHITELIST'><filename>SDK_LOCAL_CONF_WHITELIST</filename></ulink>: | ||
| 2870 | A list of variables allowed through from the build system | ||
| 2871 | configuration into the extensible SDK configuration. | ||
| 2872 | </para></listitem> | ||
| 2873 | <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_LOCAL_CONF_BLACKLIST'><filename>SDK_LOCAL_CONF_BLACKLIST</filename></ulink>: | ||
| 2874 | A list of variables not allowed through from the build | ||
| 2875 | system configuration into the extensible SDK configuration. | ||
| 2876 | </para></listitem> | ||
| 2877 | <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_INHERIT_BLACKLIST'><filename>SDK_INHERIT_BLACKLIST</filename></ulink>: | ||
| 2878 | A list of classes to remove from the | ||
| 2879 | <ulink url='&YOCTO_DOCS_REF_URL;#var-INHERIT'><filename>INHERIT</filename></ulink> | ||
| 2880 | value globally within the extensible SDK configuration. | ||
| 2881 | </para></listitem> | ||
| 2882 | </itemizedlist> | ||
| 2883 | </para> | ||
| 2884 | </section> | ||
| 2885 | </section> | ||
| 2886 | |||
| 2887 | </chapter> | ||
| 2888 | <!-- | ||
| 2889 | vim: expandtab tw=80 ts=4 | ||
| 2890 | --> | ||
diff --git a/documentation/getting-started/getting-started-eclipse-customization.xsl b/documentation/getting-started/getting-started-eclipse-customization.xsl new file mode 100644 index 0000000000..17fff727f9 --- /dev/null +++ b/documentation/getting-started/getting-started-eclipse-customization.xsl | |||
| @@ -0,0 +1,35 @@ | |||
| 1 | <?xml version='1.0'?> | ||
| 2 | <xsl:stylesheet | ||
| 3 | xmlns:xsl="http://www.w3.org/1999/XSL/Transform" | ||
| 4 | xmlns="http://www.w3.org/1999/xhtml" | ||
| 5 | xmlns:fo="http://www.w3.org/1999/XSL/Format" | ||
| 6 | version="1.0"> | ||
| 7 | |||
| 8 | <xsl:import href="http://downloads.yoctoproject.org/mirror/docbook-mirror/docbook-xsl-1.76.1/eclipse/eclipse3.xsl" /> | ||
| 9 | |||
| 10 | <!-- | ||
| 11 | |||
| 12 | <xsl:import href="../template/1.76.1/docbook-xsl-1.76.1/eclipse/eclipse3.xsl" /> | ||
| 13 | |||
| 14 | <xsl:import | ||
| 15 | href="http://docbook.sourceforge.net/release/xsl/1.76.1/eclipse/eclipse3.xsl" /> | ||
| 16 | |||
| 17 | --> | ||
| 18 | |||
| 19 | <xsl:param name="chunker.output.indent" select="'yes'"/> | ||
| 20 | <xsl:param name="chunk.quietly" select="1"/> | ||
| 21 | <xsl:param name="chunk.first.sections" select="1"/> | ||
| 22 | <xsl:param name="chunk.section.depth" select="10"/> | ||
| 23 | <xsl:param name="use.id.as.filename" select="1"/> | ||
| 24 | <xsl:param name="ulink.target" select="'_self'" /> | ||
| 25 | <xsl:param name="base.dir" select="'html/getting-started/'"/> | ||
| 26 | <xsl:param name="html.stylesheet" select="'../book.css'"/> | ||
| 27 | <xsl:param name="eclipse.manifest" select="0"/> | ||
| 28 | <xsl:param name="create.plugin.xml" select="0"/> | ||
| 29 | <xsl:param name="suppress.navigation" select="1"/> | ||
| 30 | <xsl:param name="generate.index" select="0"/> | ||
| 31 | <xsl:param name="chapter.autolabel" select="1" /> | ||
| 32 | <xsl:param name="appendix.autolabel" select="1" /> | ||
| 33 | <xsl:param name="section.autolabel" select="1" /> | ||
| 34 | <xsl:param name="section.label.includes.component.label" select="1" /> | ||
| 35 | </xsl:stylesheet> | ||
diff --git a/documentation/getting-started/getting-started-intro.xml b/documentation/getting-started/getting-started-intro.xml new file mode 100644 index 0000000000..51a21b6e23 --- /dev/null +++ b/documentation/getting-started/getting-started-intro.xml | |||
| @@ -0,0 +1,103 @@ | |||
| 1 | <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" | ||
| 2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" | ||
| 3 | [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > | ||
| 4 | |||
| 5 | <chapter id='overview-manual-intro'> | ||
| 6 | |||
| 7 | <title>The Yocto Project Overview Manual</title> | ||
| 8 | <section id='overview-welcome'> | ||
| 9 | <title>Welcome</title> | ||
| 10 | |||
| 11 | <para> | ||
| 12 | Welcome to the Yocto Project Overview Manual! | ||
| 13 | This manual introduces the Yocto Project by providing concepts, | ||
| 14 | software overviews, best-known-methods (BKMs), and any other | ||
| 15 | high-level introductory information suitable for a new Yocto | ||
| 16 | Project user. | ||
| 17 | </para> | ||
| 18 | |||
| 19 | <para> | ||
| 20 | The following list describes what you can get from this manual: | ||
| 21 | <itemizedlist> | ||
| 22 | <listitem><para> | ||
| 23 | <emphasis>Major Topic:</emphasis> | ||
| 24 | Provide a high-level description of this major topic. | ||
| 25 | </para></listitem> | ||
| 26 | <listitem><para> | ||
| 27 | <emphasis>Major Topic:</emphasis> | ||
| 28 | Provide a high-level description of this major topic. | ||
| 29 | </para></listitem> | ||
| 30 | <listitem><para> | ||
| 31 | <emphasis>Major Topic:</emphasis> | ||
| 32 | Provide a high-level description of this major topic. | ||
| 33 | </para></listitem> | ||
| 34 | <listitem><para> | ||
| 35 | <emphasis>Major Topic:</emphasis> | ||
| 36 | Provide a high-level description of this major topic. | ||
| 37 | </para></listitem> | ||
| 38 | </itemizedlist> | ||
| 39 | </para> | ||
| 40 | |||
| 41 | <para> | ||
| 42 | This manual does not give you the following: | ||
| 43 | <itemizedlist> | ||
| 44 | <listitem><para> | ||
| 45 | <emphasis>Step-by-step Instructions for Development Tasks:</emphasis> | ||
| 46 | Instructional procedures reside in other manuals within | ||
| 47 | the Yocto Project documentation set. | ||
| 48 | For example, the | ||
| 49 | <ulink url='&YOCTO_DOCS_DEV_URL;'>Yocto Project Development Tasks Manual</ulink> | ||
| 50 | provides examples on how to perform various development | ||
| 51 | tasks. | ||
| 52 | As another example, the | ||
| 53 | <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink> | ||
| 54 | manual contains detailed instructions on how to install an | ||
| 55 | SDK, which is used to develop applications for target | ||
| 56 | hardware. | ||
| 57 | </para></listitem> | ||
| 58 | <listitem><para> | ||
| 59 | <emphasis>Reference Material:</emphasis> | ||
| 60 | This type of material resides in an appropriate reference | ||
| 61 | manual. | ||
| 62 | For example, system variables are documented in the | ||
| 63 | <ulink url='&YOCTO_DOCS_REF_URL;'>Yocto Project Reference Manual</ulink>. | ||
| 64 | As another example, the | ||
| 65 | <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink> | ||
| 66 | contains reference information on BSPs. | ||
| 67 | </para></listitem> | ||
| 68 | <listitem><para> | ||
| 69 | <emphasis>Detailed Public Information Not Specific to the | ||
| 70 | Yocto Project:</emphasis> | ||
| 71 | For example, exhaustive information on how to use the | ||
| 72 | Source Control Manager Git is better covered with Internet | ||
| 73 | searches and official Git Documentation than through the | ||
| 74 | Yocto Project documentation. | ||
| 75 | </para></listitem> | ||
| 76 | </itemizedlist> | ||
| 77 | </para> | ||
| 78 | </section> | ||
| 79 | |||
| 80 | <section id='overview-other-information'> | ||
| 81 | <title>Other Information</title> | ||
| 82 | |||
| 83 | <para> | ||
| 84 | Because this manual presents information for many different | ||
| 85 | topics, supplemental information is recommended for full | ||
| 86 | comprehension. | ||
| 87 | For additional introductory information on the Yocto Project, see | ||
| 88 | the <ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink>. | ||
| 89 | You can find an introductory to using the Yocto Project by working | ||
| 90 | through the | ||
| 91 | <ulink url='&YOCTO_DOCS_QS_URL;'>Yocto Project Quick Start</ulink>. | ||
| 92 | </para> | ||
| 93 | |||
| 94 | <para> | ||
| 95 | For a comprehensive list of links and other documentation, see the | ||
| 96 | "<ulink url='&YOCTO_DOCS_REF_URL;#resources-links-and-related-documentation'>Links and Related Documentation</ulink>" | ||
| 97 | section in the Yocto Project Reference Manual. | ||
| 98 | </para> | ||
| 99 | </section> | ||
| 100 | </chapter> | ||
| 101 | <!-- | ||
| 102 | vim: expandtab tw=80 ts=4 | ||
| 103 | --> | ||
diff --git a/documentation/getting-started/getting-started-style.css b/documentation/getting-started/getting-started-style.css new file mode 100644 index 0000000000..a03f7dc0c1 --- /dev/null +++ b/documentation/getting-started/getting-started-style.css | |||
| @@ -0,0 +1,988 @@ | |||
| 1 | /* | ||
| 2 | Generic XHTML / DocBook XHTML CSS Stylesheet. | ||
| 3 | |||
| 4 | Browser wrangling and typographic design by | ||
| 5 | Oyvind Kolas / pippin@gimp.org | ||
| 6 | |||
| 7 | Customised for Poky by | ||
| 8 | Matthew Allum / mallum@o-hand.com | ||
| 9 | |||
| 10 | Thanks to: | ||
| 11 | Liam R. E. Quin | ||
| 12 | William Skaggs | ||
| 13 | Jakub Steiner | ||
| 14 | |||
| 15 | Structure | ||
| 16 | --------- | ||
| 17 | |||
| 18 | The stylesheet is divided into the following sections: | ||
| 19 | |||
| 20 | Positioning | ||
| 21 | Margins, paddings, width, font-size, clearing. | ||
| 22 | Decorations | ||
| 23 | Borders, style | ||
| 24 | Colors | ||
| 25 | Colors | ||
| 26 | Graphics | ||
| 27 | Graphical backgrounds | ||
| 28 | Nasty IE tweaks | ||
| 29 | Workarounds needed to make it work in internet explorer, | ||
| 30 | currently makes the stylesheet non validating, but up until | ||
| 31 | this point it is validating. | ||
| 32 | Mozilla extensions | ||
| 33 | Transparency for footer | ||
| 34 | Rounded corners on boxes | ||
| 35 | |||
| 36 | */ | ||
| 37 | |||
| 38 | |||
| 39 | /*************** / | ||
| 40 | / Positioning / | ||
| 41 | / ***************/ | ||
| 42 | |||
| 43 | body { | ||
| 44 | font-family: Verdana, Sans, sans-serif; | ||
| 45 | |||
| 46 | min-width: 640px; | ||
| 47 | width: 80%; | ||
| 48 | margin: 0em auto; | ||
| 49 | padding: 2em 5em 5em 5em; | ||
| 50 | color: #333; | ||
| 51 | } | ||
| 52 | |||
| 53 | h1,h2,h3,h4,h5,h6,h7 { | ||
| 54 | font-family: Arial, Sans; | ||
| 55 | color: #00557D; | ||
| 56 | clear: both; | ||
| 57 | } | ||
| 58 | |||
| 59 | h1 { | ||
| 60 | font-size: 2em; | ||
| 61 | text-align: left; | ||
| 62 | padding: 0em 0em 0em 0em; | ||
| 63 | margin: 2em 0em 0em 0em; | ||
| 64 | } | ||
| 65 | |||
| 66 | h2.subtitle { | ||
| 67 | margin: 0.10em 0em 3.0em 0em; | ||
| 68 | padding: 0em 0em 0em 0em; | ||
| 69 | font-size: 1.8em; | ||
| 70 | padding-left: 20%; | ||
| 71 | font-weight: normal; | ||
| 72 | font-style: italic; | ||
| 73 | } | ||
| 74 | |||
| 75 | h2 { | ||
| 76 | margin: 2em 0em 0.66em 0em; | ||
| 77 | padding: 0.5em 0em 0em 0em; | ||
| 78 | font-size: 1.5em; | ||
| 79 | font-weight: bold; | ||
| 80 | } | ||
| 81 | |||
| 82 | h3.subtitle { | ||
| 83 | margin: 0em 0em 1em 0em; | ||
| 84 | padding: 0em 0em 0em 0em; | ||
| 85 | font-size: 142.14%; | ||
| 86 | text-align: right; | ||
| 87 | } | ||
| 88 | |||
| 89 | h3 { | ||
| 90 | margin: 1em 0em 0.5em 0em; | ||
| 91 | padding: 1em 0em 0em 0em; | ||
| 92 | font-size: 140%; | ||
| 93 | font-weight: bold; | ||
| 94 | } | ||
| 95 | |||
| 96 | h4 { | ||
| 97 | margin: 1em 0em 0.5em 0em; | ||
| 98 | padding: 1em 0em 0em 0em; | ||
| 99 | font-size: 120%; | ||
| 100 | font-weight: bold; | ||
| 101 | } | ||
| 102 | |||
| 103 | h5 { | ||
| 104 | margin: 1em 0em 0.5em 0em; | ||
| 105 | padding: 1em 0em 0em 0em; | ||
| 106 | font-size: 110%; | ||
| 107 | font-weight: bold; | ||
| 108 | } | ||
| 109 | |||
| 110 | h6 { | ||
| 111 | margin: 1em 0em 0em 0em; | ||
| 112 | padding: 1em 0em 0em 0em; | ||
| 113 | font-size: 110%; | ||
| 114 | font-weight: bold; | ||
| 115 | } | ||
| 116 | |||
| 117 | .authorgroup { | ||
| 118 | background-color: transparent; | ||
| 119 | background-repeat: no-repeat; | ||
| 120 | padding-top: 256px; | ||
| 121 | background-image: url("figures/getting-started-title.png"); | ||
| 122 | background-position: left top; | ||
| 123 | margin-top: -256px; | ||
| 124 | padding-right: 50px; | ||
| 125 | margin-left: 0px; | ||
| 126 | text-align: right; | ||
| 127 | width: 740px; | ||
| 128 | } | ||
| 129 | |||
| 130 | h3.author { | ||
| 131 | margin: 0em 0me 0em 0em; | ||
| 132 | padding: 0em 0em 0em 0em; | ||
| 133 | font-weight: normal; | ||
| 134 | font-size: 100%; | ||
| 135 | color: #333; | ||
| 136 | clear: both; | ||
| 137 | } | ||
| 138 | |||
| 139 | .author tt.email { | ||
| 140 | font-size: 66%; | ||
| 141 | } | ||
| 142 | |||
| 143 | .titlepage hr { | ||
| 144 | width: 0em; | ||
| 145 | clear: both; | ||
| 146 | } | ||
| 147 | |||
| 148 | .revhistory { | ||
| 149 | padding-top: 2em; | ||
| 150 | clear: both; | ||
| 151 | } | ||
| 152 | |||
| 153 | .toc, | ||
| 154 | .list-of-tables, | ||
| 155 | .list-of-examples, | ||
| 156 | .list-of-figures { | ||
| 157 | padding: 1.33em 0em 2.5em 0em; | ||
| 158 | color: #00557D; | ||
| 159 | } | ||
| 160 | |||
| 161 | .toc p, | ||
| 162 | .list-of-tables p, | ||
| 163 | .list-of-figures p, | ||
| 164 | .list-of-examples p { | ||
| 165 | padding: 0em 0em 0em 0em; | ||
| 166 | padding: 0em 0em 0.3em; | ||
| 167 | margin: 1.5em 0em 0em 0em; | ||
| 168 | } | ||
| 169 | |||
| 170 | .toc p b, | ||
| 171 | .list-of-tables p b, | ||
| 172 | .list-of-figures p b, | ||
| 173 | .list-of-examples p b{ | ||
| 174 | font-size: 100.0%; | ||
| 175 | font-weight: bold; | ||
| 176 | } | ||
| 177 | |||
| 178 | .toc dl, | ||
| 179 | .list-of-tables dl, | ||
| 180 | .list-of-figures dl, | ||
| 181 | .list-of-examples dl { | ||
| 182 | margin: 0em 0em 0.5em 0em; | ||
| 183 | padding: 0em 0em 0em 0em; | ||
| 184 | } | ||
| 185 | |||
| 186 | .toc dt { | ||
| 187 | margin: 0em 0em 0em 0em; | ||
| 188 | padding: 0em 0em 0em 0em; | ||
| 189 | } | ||
| 190 | |||
| 191 | .toc dd { | ||
| 192 | margin: 0em 0em 0em 2.6em; | ||
| 193 | padding: 0em 0em 0em 0em; | ||
| 194 | } | ||
| 195 | |||
| 196 | div.glossary dl, | ||
| 197 | div.variablelist dl { | ||
| 198 | } | ||
| 199 | |||
| 200 | .glossary dl dt, | ||
| 201 | .variablelist dl dt, | ||
| 202 | .variablelist dl dt span.term { | ||
| 203 | font-weight: normal; | ||
| 204 | width: 20em; | ||
| 205 | text-align: right; | ||
| 206 | } | ||
| 207 | |||
| 208 | .variablelist dl dt { | ||
| 209 | margin-top: 0.5em; | ||
| 210 | } | ||
| 211 | |||
| 212 | .glossary dl dd, | ||
| 213 | .variablelist dl dd { | ||
| 214 | margin-top: -1em; | ||
| 215 | margin-left: 25.5em; | ||
| 216 | } | ||
| 217 | |||
| 218 | .glossary dd p, | ||
| 219 | .variablelist dd p { | ||
| 220 | margin-top: 0em; | ||
| 221 | margin-bottom: 1em; | ||
| 222 | } | ||
| 223 | |||
| 224 | |||
| 225 | div.calloutlist table td { | ||
| 226 | padding: 0em 0em 0em 0em; | ||
| 227 | margin: 0em 0em 0em 0em; | ||
| 228 | } | ||
| 229 | |||
| 230 | div.calloutlist table td p { | ||
| 231 | margin-top: 0em; | ||
| 232 | margin-bottom: 1em; | ||
| 233 | } | ||
| 234 | |||
| 235 | div p.copyright { | ||
| 236 | text-align: left; | ||
| 237 | } | ||
| 238 | |||
| 239 | div.legalnotice p.legalnotice-title { | ||
| 240 | margin-bottom: 0em; | ||
| 241 | } | ||
| 242 | |||
| 243 | p { | ||
| 244 | line-height: 1.5em; | ||
| 245 | margin-top: 0em; | ||
| 246 | |||
| 247 | } | ||
| 248 | |||
| 249 | dl { | ||
| 250 | padding-top: 0em; | ||
| 251 | } | ||
| 252 | |||
| 253 | hr { | ||
| 254 | border: solid 1px; | ||
| 255 | } | ||
| 256 | |||
| 257 | |||
| 258 | .mediaobject, | ||
| 259 | .mediaobjectco { | ||
| 260 | text-align: center; | ||
| 261 | } | ||
| 262 | |||
| 263 | img { | ||
| 264 | border: none; | ||
| 265 | } | ||
| 266 | |||
| 267 | ul { | ||
| 268 | padding: 0em 0em 0em 1.5em; | ||
| 269 | } | ||
| 270 | |||
| 271 | ul li { | ||
| 272 | padding: 0em 0em 0em 0em; | ||
| 273 | } | ||
| 274 | |||
| 275 | ul li p { | ||
| 276 | text-align: left; | ||
| 277 | } | ||
| 278 | |||
| 279 | table { | ||
| 280 | width :100%; | ||
| 281 | } | ||
| 282 | |||
| 283 | th { | ||
| 284 | padding: 0.25em; | ||
| 285 | text-align: left; | ||
| 286 | font-weight: normal; | ||
| 287 | vertical-align: top; | ||
| 288 | } | ||
| 289 | |||
| 290 | td { | ||
| 291 | padding: 0.25em; | ||
| 292 | vertical-align: top; | ||
| 293 | } | ||
| 294 | |||
| 295 | p a[id] { | ||
| 296 | margin: 0px; | ||
| 297 | padding: 0px; | ||
| 298 | display: inline; | ||
| 299 | background-image: none; | ||
| 300 | } | ||
| 301 | |||
| 302 | a { | ||
| 303 | text-decoration: underline; | ||
| 304 | color: #444; | ||
| 305 | } | ||
| 306 | |||
| 307 | pre { | ||
| 308 | overflow: auto; | ||
| 309 | } | ||
| 310 | |||
| 311 | a:hover { | ||
| 312 | text-decoration: underline; | ||
| 313 | /*font-weight: bold;*/ | ||
| 314 | } | ||
| 315 | |||
| 316 | /* This style defines how the permalink character | ||
| 317 | appears by itself and when hovered over with | ||
| 318 | the mouse. */ | ||
| 319 | |||
| 320 | [alt='Permalink'] { color: #eee; } | ||
| 321 | [alt='Permalink']:hover { color: black; } | ||
| 322 | |||
| 323 | |||
| 324 | div.informalfigure, | ||
| 325 | div.informalexample, | ||
| 326 | div.informaltable, | ||
| 327 | div.figure, | ||
| 328 | div.table, | ||
| 329 | div.example { | ||
| 330 | margin: 1em 0em; | ||
| 331 | padding: 1em; | ||
| 332 | page-break-inside: avoid; | ||
| 333 | } | ||
| 334 | |||
| 335 | |||
| 336 | div.informalfigure p.title b, | ||
| 337 | div.informalexample p.title b, | ||
| 338 | div.informaltable p.title b, | ||
| 339 | div.figure p.title b, | ||
| 340 | div.example p.title b, | ||
| 341 | div.table p.title b{ | ||
| 342 | padding-top: 0em; | ||
| 343 | margin-top: 0em; | ||
| 344 | font-size: 100%; | ||
| 345 | font-weight: normal; | ||
| 346 | } | ||
| 347 | |||
| 348 | .mediaobject .caption, | ||
| 349 | .mediaobject .caption p { | ||
| 350 | text-align: center; | ||
| 351 | font-size: 80%; | ||
| 352 | padding-top: 0.5em; | ||
| 353 | padding-bottom: 0.5em; | ||
| 354 | } | ||
| 355 | |||
| 356 | .epigraph { | ||
| 357 | padding-left: 55%; | ||
| 358 | margin-bottom: 1em; | ||
| 359 | } | ||
| 360 | |||
| 361 | .epigraph p { | ||
| 362 | text-align: left; | ||
| 363 | } | ||
| 364 | |||
| 365 | .epigraph .quote { | ||
| 366 | font-style: italic; | ||
| 367 | } | ||
| 368 | .epigraph .attribution { | ||
| 369 | font-style: normal; | ||
| 370 | text-align: right; | ||
| 371 | } | ||
| 372 | |||
| 373 | span.application { | ||
| 374 | font-style: italic; | ||
| 375 | } | ||
| 376 | |||
| 377 | .programlisting { | ||
| 378 | font-family: monospace; | ||
| 379 | font-size: 80%; | ||
| 380 | white-space: pre; | ||
| 381 | margin: 1.33em 0em; | ||
| 382 | padding: 1.33em; | ||
| 383 | } | ||
| 384 | |||
| 385 | .tip, | ||
| 386 | .warning, | ||
| 387 | .caution, | ||
| 388 | .note { | ||
| 389 | margin-top: 1em; | ||
| 390 | margin-bottom: 1em; | ||
| 391 | |||
| 392 | } | ||
| 393 | |||
| 394 | /* force full width of table within div */ | ||
| 395 | .tip table, | ||
| 396 | .warning table, | ||
| 397 | .caution table, | ||
| 398 | .note table { | ||
| 399 | border: none; | ||
| 400 | width: 100%; | ||
| 401 | } | ||
| 402 | |||
| 403 | |||
| 404 | .tip table th, | ||
| 405 | .warning table th, | ||
| 406 | .caution table th, | ||
| 407 | .note table th { | ||
| 408 | padding: 0.8em 0.0em 0.0em 0.0em; | ||
| 409 | margin : 0em 0em 0em 0em; | ||
| 410 | } | ||
| 411 | |||
| 412 | .tip p, | ||
| 413 | .warning p, | ||
| 414 | .caution p, | ||
| 415 | .note p { | ||
| 416 | margin-top: 0.5em; | ||
| 417 | margin-bottom: 0.5em; | ||
| 418 | padding-right: 1em; | ||
| 419 | text-align: left; | ||
| 420 | } | ||
| 421 | |||
| 422 | .acronym { | ||
| 423 | text-transform: uppercase; | ||
| 424 | } | ||
| 425 | |||
| 426 | b.keycap, | ||
| 427 | .keycap { | ||
| 428 | padding: 0.09em 0.3em; | ||
| 429 | margin: 0em; | ||
| 430 | } | ||
| 431 | |||
| 432 | .itemizedlist li { | ||
| 433 | clear: none; | ||
| 434 | } | ||
| 435 | |||
| 436 | .filename { | ||
| 437 | font-size: medium; | ||
| 438 | font-family: Courier, monospace; | ||
| 439 | } | ||
| 440 | |||
| 441 | |||
| 442 | div.navheader, div.heading{ | ||
| 443 | position: absolute; | ||
| 444 | left: 0em; | ||
| 445 | top: 0em; | ||
| 446 | width: 100%; | ||
| 447 | background-color: #cdf; | ||
| 448 | width: 100%; | ||
| 449 | } | ||
| 450 | |||
| 451 | div.navfooter, div.footing{ | ||
| 452 | position: fixed; | ||
| 453 | left: 0em; | ||
| 454 | bottom: 0em; | ||
| 455 | background-color: #eee; | ||
| 456 | width: 100%; | ||
| 457 | } | ||
| 458 | |||
| 459 | |||
| 460 | div.navheader td, | ||
| 461 | div.navfooter td { | ||
| 462 | font-size: 66%; | ||
| 463 | } | ||
| 464 | |||
| 465 | div.navheader table th { | ||
| 466 | /*font-family: Georgia, Times, serif;*/ | ||
| 467 | /*font-size: x-large;*/ | ||
| 468 | font-size: 80%; | ||
| 469 | } | ||
| 470 | |||
| 471 | div.navheader table { | ||
| 472 | border-left: 0em; | ||
| 473 | border-right: 0em; | ||
| 474 | border-top: 0em; | ||
| 475 | width: 100%; | ||
| 476 | } | ||
| 477 | |||
| 478 | div.navfooter table { | ||
| 479 | border-left: 0em; | ||
| 480 | border-right: 0em; | ||
| 481 | border-bottom: 0em; | ||
| 482 | width: 100%; | ||
| 483 | } | ||
| 484 | |||
| 485 | div.navheader table td a, | ||
| 486 | div.navfooter table td a { | ||
| 487 | color: #777; | ||
| 488 | text-decoration: none; | ||
| 489 | } | ||
| 490 | |||
| 491 | /* normal text in the footer */ | ||
| 492 | div.navfooter table td { | ||
| 493 | color: black; | ||
| 494 | } | ||
| 495 | |||
| 496 | div.navheader table td a:visited, | ||
| 497 | div.navfooter table td a:visited { | ||
| 498 | color: #444; | ||
| 499 | } | ||
| 500 | |||
| 501 | |||
| 502 | /* links in header and footer */ | ||
| 503 | div.navheader table td a:hover, | ||
| 504 | div.navfooter table td a:hover { | ||
| 505 | text-decoration: underline; | ||
| 506 | background-color: transparent; | ||
| 507 | color: #33a; | ||
| 508 | } | ||
| 509 | |||
| 510 | div.navheader hr, | ||
| 511 | div.navfooter hr { | ||
| 512 | display: none; | ||
| 513 | } | ||
| 514 | |||
| 515 | |||
| 516 | .qandaset tr.question td p { | ||
| 517 | margin: 0em 0em 1em 0em; | ||
| 518 | padding: 0em 0em 0em 0em; | ||
| 519 | } | ||
| 520 | |||
| 521 | .qandaset tr.answer td p { | ||
| 522 | margin: 0em 0em 1em 0em; | ||
| 523 | padding: 0em 0em 0em 0em; | ||
| 524 | } | ||
| 525 | .answer td { | ||
| 526 | padding-bottom: 1.5em; | ||
| 527 | } | ||
| 528 | |||
| 529 | .emphasis { | ||
| 530 | font-weight: bold; | ||
| 531 | } | ||
| 532 | |||
| 533 | |||
| 534 | /************* / | ||
| 535 | / decorations / | ||
| 536 | / *************/ | ||
| 537 | |||
| 538 | .titlepage { | ||
| 539 | } | ||
| 540 | |||
| 541 | .part .title { | ||
| 542 | } | ||
| 543 | |||
| 544 | .subtitle { | ||
| 545 | border: none; | ||
| 546 | } | ||
| 547 | |||
| 548 | /* | ||
| 549 | h1 { | ||
| 550 | border: none; | ||
| 551 | } | ||
| 552 | |||
| 553 | h2 { | ||
| 554 | border-top: solid 0.2em; | ||
| 555 | border-bottom: solid 0.06em; | ||
| 556 | } | ||
| 557 | |||
| 558 | h3 { | ||
| 559 | border-top: 0em; | ||
| 560 | border-bottom: solid 0.06em; | ||
| 561 | } | ||
| 562 | |||
| 563 | h4 { | ||
| 564 | border: 0em; | ||
| 565 | border-bottom: solid 0.06em; | ||
| 566 | } | ||
| 567 | |||
| 568 | h5 { | ||
| 569 | border: 0em; | ||
| 570 | } | ||
| 571 | */ | ||
| 572 | |||
| 573 | .programlisting { | ||
| 574 | border: solid 1px; | ||
| 575 | } | ||
| 576 | |||
| 577 | div.figure, | ||
| 578 | div.table, | ||
| 579 | div.informalfigure, | ||
| 580 | div.informaltable, | ||
| 581 | div.informalexample, | ||
| 582 | div.example { | ||
| 583 | border: 1px solid; | ||
| 584 | } | ||
| 585 | |||
| 586 | |||
| 587 | |||
| 588 | .tip, | ||
| 589 | .warning, | ||
| 590 | .caution, | ||
| 591 | .note { | ||
| 592 | border: 1px solid; | ||
| 593 | } | ||
| 594 | |||
| 595 | .tip table th, | ||
| 596 | .warning table th, | ||
| 597 | .caution table th, | ||
| 598 | .note table th { | ||
| 599 | border-bottom: 1px solid; | ||
| 600 | } | ||
| 601 | |||
| 602 | .question td { | ||
| 603 | border-top: 1px solid black; | ||
| 604 | } | ||
| 605 | |||
| 606 | .answer { | ||
| 607 | } | ||
| 608 | |||
| 609 | |||
| 610 | b.keycap, | ||
| 611 | .keycap { | ||
| 612 | border: 1px solid; | ||
| 613 | } | ||
| 614 | |||
| 615 | |||
| 616 | div.navheader, div.heading{ | ||
| 617 | border-bottom: 1px solid; | ||
| 618 | } | ||
| 619 | |||
| 620 | |||
| 621 | div.navfooter, div.footing{ | ||
| 622 | border-top: 1px solid; | ||
| 623 | } | ||
| 624 | |||
| 625 | /********* / | ||
| 626 | / colors / | ||
| 627 | / *********/ | ||
| 628 | |||
| 629 | body { | ||
| 630 | color: #333; | ||
| 631 | background: white; | ||
| 632 | } | ||
| 633 | |||
| 634 | a { | ||
| 635 | background: transparent; | ||
| 636 | } | ||
| 637 | |||
| 638 | a:hover { | ||
| 639 | background-color: #dedede; | ||
| 640 | } | ||
| 641 | |||
| 642 | |||
| 643 | h1, | ||
| 644 | h2, | ||
| 645 | h3, | ||
| 646 | h4, | ||
| 647 | h5, | ||
| 648 | h6, | ||
| 649 | h7, | ||
| 650 | h8 { | ||
| 651 | background-color: transparent; | ||
| 652 | } | ||
| 653 | |||
| 654 | hr { | ||
| 655 | border-color: #aaa; | ||
| 656 | } | ||
| 657 | |||
| 658 | |||
| 659 | .tip, .warning, .caution, .note { | ||
| 660 | border-color: #fff; | ||
| 661 | } | ||
| 662 | |||
| 663 | |||
| 664 | .tip table th, | ||
| 665 | .warning table th, | ||
| 666 | .caution table th, | ||
| 667 | .note table th { | ||
| 668 | border-bottom-color: #fff; | ||
| 669 | } | ||
| 670 | |||
| 671 | |||
| 672 | .warning { | ||
| 673 | background-color: #f0f0f2; | ||
| 674 | } | ||
| 675 | |||
| 676 | .caution { | ||
| 677 | background-color: #f0f0f2; | ||
| 678 | } | ||
| 679 | |||
| 680 | .tip { | ||
| 681 | background-color: #f0f0f2; | ||
| 682 | } | ||
| 683 | |||
| 684 | .note { | ||
| 685 | background-color: #f0f0f2; | ||
| 686 | } | ||
| 687 | |||
| 688 | .glossary dl dt, | ||
| 689 | .variablelist dl dt, | ||
| 690 | .variablelist dl dt span.term { | ||
| 691 | color: #044; | ||
| 692 | } | ||
| 693 | |||
| 694 | div.figure, | ||
| 695 | div.table, | ||
| 696 | div.example, | ||
| 697 | div.informalfigure, | ||
| 698 | div.informaltable, | ||
| 699 | div.informalexample { | ||
| 700 | border-color: #aaa; | ||
| 701 | } | ||
| 702 | |||
| 703 | pre.programlisting { | ||
| 704 | color: black; | ||
| 705 | background-color: #fff; | ||
| 706 | border-color: #aaa; | ||
| 707 | border-width: 2px; | ||
| 708 | } | ||
| 709 | |||
| 710 | .guimenu, | ||
| 711 | .guilabel, | ||
| 712 | .guimenuitem { | ||
| 713 | background-color: #eee; | ||
| 714 | } | ||
| 715 | |||
| 716 | |||
| 717 | b.keycap, | ||
| 718 | .keycap { | ||
| 719 | background-color: #eee; | ||
| 720 | border-color: #999; | ||
| 721 | } | ||
| 722 | |||
| 723 | |||
| 724 | div.navheader { | ||
| 725 | border-color: black; | ||
| 726 | } | ||
| 727 | |||
| 728 | |||
| 729 | div.navfooter { | ||
| 730 | border-color: black; | ||
| 731 | } | ||
| 732 | |||
| 733 | .writernotes { | ||
| 734 | color: red; | ||
| 735 | } | ||
| 736 | |||
| 737 | |||
| 738 | /*********** / | ||
| 739 | / graphics / | ||
| 740 | / ***********/ | ||
| 741 | |||
| 742 | /* | ||
| 743 | body { | ||
| 744 | background-image: url("images/body_bg.jpg"); | ||
| 745 | background-attachment: fixed; | ||
| 746 | } | ||
| 747 | |||
| 748 | .navheader, | ||
| 749 | .note, | ||
| 750 | .tip { | ||
| 751 | background-image: url("images/note_bg.jpg"); | ||
| 752 | background-attachment: fixed; | ||
| 753 | } | ||
| 754 | |||
| 755 | .warning, | ||
| 756 | .caution { | ||
| 757 | background-image: url("images/warning_bg.jpg"); | ||
| 758 | background-attachment: fixed; | ||
| 759 | } | ||
| 760 | |||
| 761 | .figure, | ||
| 762 | .informalfigure, | ||
| 763 | .example, | ||
| 764 | .informalexample, | ||
| 765 | .table, | ||
| 766 | .informaltable { | ||
| 767 | background-image: url("images/figure_bg.jpg"); | ||
| 768 | background-attachment: fixed; | ||
| 769 | } | ||
| 770 | |||
| 771 | */ | ||
| 772 | h1, | ||
| 773 | h2, | ||
| 774 | h3, | ||
| 775 | h4, | ||
| 776 | h5, | ||
| 777 | h6, | ||
| 778 | h7{ | ||
| 779 | } | ||
| 780 | |||
| 781 | /* | ||
| 782 | Example of how to stick an image as part of the title. | ||
| 783 | |||
| 784 | div.article .titlepage .title | ||
| 785 | { | ||
| 786 | background-image: url("figures/white-on-black.png"); | ||
| 787 | background-position: center; | ||
| 788 | background-repeat: repeat-x; | ||
| 789 | } | ||
| 790 | */ | ||
| 791 | |||
| 792 | div.preface .titlepage .title, | ||
| 793 | div.colophon .title, | ||
| 794 | div.chapter .titlepage .title, | ||
| 795 | div.article .titlepage .title | ||
| 796 | { | ||
| 797 | } | ||
| 798 | |||
| 799 | div.section div.section .titlepage .title, | ||
| 800 | div.sect2 .titlepage .title { | ||
| 801 | background: none; | ||
| 802 | } | ||
| 803 | |||
| 804 | |||
| 805 | h1.title { | ||
| 806 | background-color: transparent; | ||
| 807 | background-repeat: no-repeat; | ||
| 808 | height: 256px; | ||
| 809 | text-indent: -9000px; | ||
| 810 | overflow:hidden; | ||
| 811 | } | ||
| 812 | |||
| 813 | h2.subtitle { | ||
| 814 | background-color: transparent; | ||
| 815 | text-indent: -9000px; | ||
| 816 | overflow:hidden; | ||
| 817 | width: 0px; | ||
| 818 | display: none; | ||
| 819 | } | ||
| 820 | |||
| 821 | /*************************************** / | ||
| 822 | / pippin.gimp.org specific alterations / | ||
| 823 | / ***************************************/ | ||
| 824 | |||
| 825 | /* | ||
| 826 | div.heading, div.navheader { | ||
| 827 | color: #777; | ||
| 828 | font-size: 80%; | ||
| 829 | padding: 0; | ||
| 830 | margin: 0; | ||
| 831 | text-align: left; | ||
| 832 | position: absolute; | ||
| 833 | top: 0px; | ||
| 834 | left: 0px; | ||
| 835 | width: 100%; | ||
| 836 | height: 50px; | ||
| 837 | background: url('/gfx/heading_bg.png') transparent; | ||
| 838 | background-repeat: repeat-x; | ||
| 839 | background-attachment: fixed; | ||
| 840 | border: none; | ||
| 841 | } | ||
| 842 | |||
| 843 | div.heading a { | ||
| 844 | color: #444; | ||
| 845 | } | ||
| 846 | |||
| 847 | div.footing, div.navfooter { | ||
| 848 | border: none; | ||
| 849 | color: #ddd; | ||
| 850 | font-size: 80%; | ||
| 851 | text-align:right; | ||
| 852 | |||
| 853 | width: 100%; | ||
| 854 | padding-top: 10px; | ||
| 855 | position: absolute; | ||
| 856 | bottom: 0px; | ||
| 857 | left: 0px; | ||
| 858 | |||
| 859 | background: url('/gfx/footing_bg.png') transparent; | ||
| 860 | } | ||
| 861 | */ | ||
| 862 | |||
| 863 | |||
| 864 | |||
| 865 | /****************** / | ||
| 866 | / nasty ie tweaks / | ||
| 867 | / ******************/ | ||
| 868 | |||
| 869 | /* | ||
| 870 | div.heading, div.navheader { | ||
| 871 | width:expression(document.body.clientWidth + "px"); | ||
| 872 | } | ||
| 873 | |||
| 874 | div.footing, div.navfooter { | ||
| 875 | width:expression(document.body.clientWidth + "px"); | ||
| 876 | margin-left:expression("-5em"); | ||
| 877 | } | ||
| 878 | body { | ||
| 879 | padding:expression("4em 5em 0em 5em"); | ||
| 880 | } | ||
| 881 | */ | ||
| 882 | |||
| 883 | /**************************************** / | ||
| 884 | / mozilla vendor specific css extensions / | ||
| 885 | / ****************************************/ | ||
| 886 | /* | ||
| 887 | div.navfooter, div.footing{ | ||
| 888 | -moz-opacity: 0.8em; | ||
| 889 | } | ||
| 890 | |||
| 891 | div.figure, | ||
| 892 | div.table, | ||
| 893 | div.informalfigure, | ||
| 894 | div.informaltable, | ||
| 895 | div.informalexample, | ||
| 896 | div.example, | ||
| 897 | .tip, | ||
| 898 | .warning, | ||
| 899 | .caution, | ||
| 900 | .note { | ||
| 901 | -moz-border-radius: 0.5em; | ||
| 902 | } | ||
| 903 | |||
| 904 | b.keycap, | ||
| 905 | .keycap { | ||
| 906 | -moz-border-radius: 0.3em; | ||
| 907 | } | ||
| 908 | */ | ||
| 909 | |||
| 910 | table tr td table tr td { | ||
| 911 | display: none; | ||
| 912 | } | ||
| 913 | |||
| 914 | |||
| 915 | hr { | ||
| 916 | display: none; | ||
| 917 | } | ||
| 918 | |||
| 919 | table { | ||
| 920 | border: 0em; | ||
| 921 | } | ||
| 922 | |||
| 923 | .photo { | ||
| 924 | float: right; | ||
| 925 | margin-left: 1.5em; | ||
| 926 | margin-bottom: 1.5em; | ||
| 927 | margin-top: 0em; | ||
| 928 | max-width: 17em; | ||
| 929 | border: 1px solid gray; | ||
| 930 | padding: 3px; | ||
| 931 | background: white; | ||
| 932 | } | ||
| 933 | .seperator { | ||
| 934 | padding-top: 2em; | ||
| 935 | clear: both; | ||
| 936 | } | ||
| 937 | |||
| 938 | #validators { | ||
| 939 | margin-top: 5em; | ||
| 940 | text-align: right; | ||
| 941 | color: #777; | ||
| 942 | } | ||
| 943 | @media print { | ||
| 944 | body { | ||
| 945 | font-size: 8pt; | ||
| 946 | } | ||
| 947 | .noprint { | ||
| 948 | display: none; | ||
| 949 | } | ||
| 950 | } | ||
| 951 | |||
| 952 | |||
| 953 | .tip, | ||
| 954 | .note { | ||
| 955 | background: #f0f0f2; | ||
| 956 | color: #333; | ||
| 957 | padding: 20px; | ||
| 958 | margin: 20px; | ||
| 959 | } | ||
| 960 | |||
| 961 | .tip h3, | ||
| 962 | .note h3 { | ||
| 963 | padding: 0em; | ||
| 964 | margin: 0em; | ||
| 965 | font-size: 2em; | ||
| 966 | font-weight: bold; | ||
| 967 | color: #333; | ||
| 968 | } | ||
| 969 | |||
| 970 | .tip a, | ||
| 971 | .note a { | ||
| 972 | color: #333; | ||
| 973 | text-decoration: underline; | ||
| 974 | } | ||
| 975 | |||
| 976 | .footnote { | ||
| 977 | font-size: small; | ||
| 978 | color: #333; | ||
| 979 | } | ||
| 980 | |||
| 981 | /* Changes the announcement text */ | ||
| 982 | .tip h3, | ||
| 983 | .warning h3, | ||
| 984 | .caution h3, | ||
| 985 | .note h3 { | ||
| 986 | font-size:large; | ||
| 987 | color: #00557D; | ||
| 988 | } | ||
diff --git a/documentation/getting-started/getting-started.html b/documentation/getting-started/getting-started.html new file mode 100644 index 0000000000..19c1384f8e --- /dev/null +++ b/documentation/getting-started/getting-started.html | |||
| @@ -0,0 +1,3900 @@ | |||
| 1 | <?xml version="1.0" encoding="UTF-8"?> | ||
| 2 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Getting Started With Yocto Project</title><link rel="stylesheet" type="text/css" href="getting-started-style.css" /><meta name="generator" content="DocBook XSL Stylesheets V1.76.1" /></head><body><div xml:lang="en" class="book" title="Getting Started With Yocto Project" id="getting-started-manual" lang="en"><div class="titlepage"><div><div><h1 class="title"> | ||
| 3 | Getting Started With Yocto Project | ||
| 4 | </h1></div><div><div class="authorgroup"> | ||
| 5 | <div class="author"><h3 class="author"><span class="firstname">Scott</span> <span class="surname">Rifenbark</span></h3><div class="affiliation"> | ||
| 6 | <span class="orgname">Scotty's Documentation Services, INC<br /></span> | ||
| 7 | </div><code class="email"><<a class="email" href="mailto:srifenbark@gmail.com">srifenbark@gmail.com</a>></code></div> | ||
| 8 | </div></div><div><p class="copyright">Copyright © 2010-2018 Linux Foundation</p></div><div><div class="legalnotice" title="Legal Notice"><a id="idm45705112624512"></a> | ||
| 9 | <p> | ||
| 10 | Permission is granted to copy, distribute and/or modify this document under | ||
| 11 | the terms of the <a class="ulink" href="http://creativecommons.org/licenses/by-sa/2.0/uk/" target="_top"> | ||
| 12 | Creative Commons Attribution-Share Alike 2.0 UK: England & Wales</a> as published by | ||
| 13 | Creative Commons. | ||
| 14 | </p> | ||
| 15 | <div class="note" title="Manual Notes" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Manual Notes</h3> | ||
| 16 | <div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> | ||
| 17 | This version of the | ||
| 18 | <span class="emphasis"><em>Yocto Project Overview Manual</em></span> | ||
| 19 | is for the 2.5 release of the | ||
| 20 | Yocto Project. | ||
| 21 | To be sure you have the latest version of the manual | ||
| 22 | for this release, use the manual from the | ||
| 23 | <a class="ulink" href="http://www.yoctoproject.org/documentation" target="_top">Yocto Project documentation page</a>. | ||
| 24 | </p></li><li class="listitem"><p> | ||
| 25 | For manuals associated with other releases of the Yocto | ||
| 26 | Project, go to the | ||
| 27 | <a class="ulink" href="http://www.yoctoproject.org/documentation" target="_top">Yocto Project documentation page</a> | ||
| 28 | and use the drop-down "Active Releases" button | ||
| 29 | and choose the manual associated with the desired | ||
| 30 | Yocto Project. | ||
| 31 | </p></li><li class="listitem"><p> | ||
| 32 | To report any inaccuracies or problems with this | ||
| 33 | manual, send an email to the Yocto Project | ||
| 34 | discussion group at | ||
| 35 | <code class="filename">yocto@yoctoproject.com</code> or log into | ||
| 36 | the freenode <code class="filename">#yocto</code> channel. | ||
| 37 | </p></li></ul></div> | ||
| 38 | </div> | ||
| 39 | </div></div><div><div class="revhistory"><table border="1" width="100%" summary="Revision history"><tr><th align="left" valign="top" colspan="2"><strong>Revision History</strong></th></tr> | ||
| 40 | <tr><td align="left">Revision 2.5</td><td align="left">April 2018</td></tr><tr><td align="left" colspan="2">The initial document released with the Yocto Project 2.5 Release.</td></tr> | ||
| 41 | </table></div></div></div><hr /></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="chapter"><a href="#overview-manual-intro">1. The Yocto Project Overview Manual</a></span></dt><dd><dl><dt><span class="section"><a href="#overview-welcome">1.1. Welcome</a></span></dt><dt><span class="section"><a href="#overview-other-information">1.2. Other Information</a></span></dt></dl></dd><dt><span class="chapter"><a href="#overview-development-environment">2. The Yocto Project Development Environment</a></span></dt><dd><dl><dt><span class="section"><a href="#yp-intro">2.1. Introduction</a></span></dt><dt><span class="section"><a href="#open-source-philosophy">2.2. Open Source Philosophy</a></span></dt><dt><span class="section"><a href="#workflows">2.3. Workflows</a></span></dt><dt><span class="section"><a href="#git">2.4. Git</a></span></dt><dd><dl><dt><span class="section"><a href="#repositories-tags-and-branches">2.4.1. Repositories, Tags, and Branches</a></span></dt><dt><span class="section"><a href="#basic-commands">2.4.2. Basic Commands</a></span></dt></dl></dd><dt><span class="section"><a href="#yocto-project-repositories">2.5. Yocto Project Source Repositories</a></span></dt><dt><span class="section"><a href="#licensing">2.6. Licensing</a></span></dt><dt><span class="section"><a href="#recipe-syntax">2.7. Recipe Syntax</a></span></dt><dt><span class="section"><a href="#development-concepts">2.8. Development Concepts</a></span></dt><dd><dl><dt><span class="section"><a href="#user-configuration">2.8.1. User Configuration</a></span></dt><dt><span class="section"><a href="#metadata-machine-configuration-and-policy-configuration">2.8.2. Metadata, Machine Configuration, and Policy Configuration</a></span></dt><dt><span class="section"><a href="#sources-dev-environment">2.8.3. Sources</a></span></dt><dt><span class="section"><a href="#package-feeds-dev-environment">2.8.4. Package Feeds</a></span></dt><dt><span class="section"><a href="#bitbake-dev-environment">2.8.5. BitBake</a></span></dt><dt><span class="section"><a href="#images-dev-environment">2.8.6. Images</a></span></dt><dt><span class="section"><a href="#sdk-dev-environment">2.8.7. Application Development SDK</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#overview-concepts">3. Yocto Project Concepts</a></span></dt><dd><dl><dt><span class="section"><a href="#yocto-project-components">3.1. Yocto Project Components</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-components-bitbake">3.1.1. BitBake</a></span></dt><dt><span class="section"><a href="#usingpoky-components-metadata">3.1.2. Metadata (Recipes)</a></span></dt><dt><span class="section"><a href="#metadata-virtual-providers">3.1.3. Metadata (Virtual Providers)</a></span></dt><dt><span class="section"><a href="#usingpoky-components-classes">3.1.4. Classes</a></span></dt><dt><span class="section"><a href="#usingpoky-components-configuration">3.1.5. Configuration</a></span></dt></dl></dd><dt><span class="section"><a href="#cross-development-toolchain-generation">3.2. Cross-Development Toolchain Generation</a></span></dt><dt><span class="section"><a href="#shared-state-cache">3.3. Shared State Cache</a></span></dt><dd><dl><dt><span class="section"><a href="#overall-architecture">3.3.1. Overall Architecture</a></span></dt><dt><span class="section"><a href="#overview-checksums">3.3.2. Checksums (Signatures)</a></span></dt><dt><span class="section"><a href="#shared-state">3.3.3. Shared State</a></span></dt><dt><span class="section"><a href="#tips-and-tricks">3.3.4. Tips and Tricks</a></span></dt></dl></dd><dt><span class="section"><a href="#automatically-added-runtime-dependencies">3.4. Automatically Added Runtime Dependencies</a></span></dt><dt><span class="section"><a href="#fakeroot-and-pseudo">3.5. Fakeroot and Pseudo</a></span></dt><dt><span class="section"><a href="#wayland">3.6. Wayland</a></span></dt><dd><dl><dt><span class="section"><a href="#wayland-support">3.6.1. Support</a></span></dt><dt><span class="section"><a href="#enabling-wayland-in-an-image">3.6.2. Enabling Wayland in an Image</a></span></dt><dt><span class="section"><a href="#running-weston">3.6.3. Running Weston</a></span></dt></dl></dd><dt><span class="section"><a href="#overview-licenses">3.7. Licenses</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-configuring-LIC_FILES_CHKSUM">3.7.1. Tracking License Changes</a></span></dt><dt><span class="section"><a href="#enabling-commercially-licensed-recipes">3.7.2. Enabling Commercially Licensed Recipes</a></span></dt></dl></dd><dt><span class="section"><a href="#x32">3.8. x32 psABI</a></span></dt></dl></dd></dl></div> | ||
| 42 | |||
| 43 | |||
| 44 | <div class="chapter" title="Chapter 1. The Yocto Project Overview Manual" id="overview-manual-intro"><div class="titlepage"><div><div><h2 class="title">Chapter 1. The Yocto Project Overview Manual<span class="permalink"><a alt="Permalink" title="Permalink" href="#overview-manual-intro">¶</a></span></h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="section"><a href="#overview-welcome">1.1. Welcome</a></span></dt><dt><span class="section"><a href="#overview-other-information">1.2. Other Information</a></span></dt></dl></div><div class="section" title="1.1. Welcome"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="overview-welcome">1.1. Welcome<span class="permalink"><a alt="Permalink" title="Permalink" href="#overview-welcome">¶</a></span></h2></div></div></div><p> | ||
| 45 | Welcome to the Yocto Project Overview Manual! | ||
| 46 | This manual introduces the Yocto Project by providing concepts, | ||
| 47 | software overviews, best-known-methods (BKMs), and any other | ||
| 48 | high-level introductory information suitable for a new Yocto | ||
| 49 | Project user. | ||
| 50 | </p><p> | ||
| 51 | The following list describes what you can get from this manual: | ||
| 52 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> | ||
| 53 | <span class="emphasis"><em>Major Topic:</em></span> | ||
| 54 | Provide a high-level description of this major topic. | ||
| 55 | </p></li><li class="listitem"><p> | ||
| 56 | <span class="emphasis"><em>Major Topic:</em></span> | ||
| 57 | Provide a high-level description of this major topic. | ||
| 58 | </p></li><li class="listitem"><p> | ||
| 59 | <span class="emphasis"><em>Major Topic:</em></span> | ||
| 60 | Provide a high-level description of this major topic. | ||
| 61 | </p></li><li class="listitem"><p> | ||
| 62 | <span class="emphasis"><em>Major Topic:</em></span> | ||
| 63 | Provide a high-level description of this major topic. | ||
| 64 | </p></li></ul></div><p> | ||
| 65 | </p><p> | ||
| 66 | This manual does not give you the following: | ||
| 67 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> | ||
| 68 | <span class="emphasis"><em>Step-by-step Instructions for Development Tasks:</em></span> | ||
| 69 | Instructional procedures reside in other manuals within | ||
| 70 | the Yocto Project documentation set. | ||
| 71 | For example, the | ||
| 72 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/dev-manual/dev-manual.html" target="_top">Yocto Project Development Tasks Manual</a> | ||
| 73 | provides examples on how to perform various development | ||
| 74 | tasks. | ||
| 75 | As another example, the | ||
| 76 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/sdk-manual/sdk-manual.html" target="_top">Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</a> | ||
| 77 | manual contains detailed instructions on how to install an | ||
| 78 | SDK, which is used to develop applications for target | ||
| 79 | hardware. | ||
| 80 | </p></li><li class="listitem"><p> | ||
| 81 | <span class="emphasis"><em>Reference Material:</em></span> | ||
| 82 | This type of material resides in an appropriate reference | ||
| 83 | manual. | ||
| 84 | For example, system variables are documented in the | ||
| 85 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html" target="_top">Yocto Project Reference Manual</a>. | ||
| 86 | As another example, the | ||
| 87 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/bsp-guide/bsp-guide.html" target="_top">Yocto Project Board Support Package (BSP) Developer's Guide</a> | ||
| 88 | contains reference information on BSPs. | ||
| 89 | </p></li><li class="listitem"><p> | ||
| 90 | <span class="emphasis"><em>Detailed Public Information Not Specific to the | ||
| 91 | Yocto Project:</em></span> | ||
| 92 | For example, exhaustive information on how to use the | ||
| 93 | Source Control Manager Git is better covered with Internet | ||
| 94 | searches and official Git Documentation than through the | ||
| 95 | Yocto Project documentation. | ||
| 96 | </p></li></ul></div><p> | ||
| 97 | </p></div><div class="section" title="1.2. Other Information"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="overview-other-information">1.2. Other Information<span class="permalink"><a alt="Permalink" title="Permalink" href="#overview-other-information">¶</a></span></h2></div></div></div><p> | ||
| 98 | Because this manual presents information for many different | ||
| 99 | topics, supplemental information is recommended for full | ||
| 100 | comprehension. | ||
| 101 | For additional introductory information on the Yocto Project, see | ||
| 102 | the <a class="ulink" href="http://www.yoctoproject.org" target="_top">Yocto Project Website</a>. | ||
| 103 | You can find an introductory to using the Yocto Project by working | ||
| 104 | through the | ||
| 105 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/yocto-project-qs/yocto-project-qs.html" target="_top">Yocto Project Quick Start</a>. | ||
| 106 | </p><p> | ||
| 107 | For a comprehensive list of links and other documentation, see the | ||
| 108 | "<a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#resources-links-and-related-documentation" target="_top">Links and Related Documentation</a>" | ||
| 109 | section in the Yocto Project Reference Manual. | ||
| 110 | </p></div></div> | ||
| 111 | |||
| 112 | <div class="chapter" title="Chapter 2. The Yocto Project Development Environment" id="overview-development-environment"><div class="titlepage"><div><div><h2 class="title">Chapter 2. The Yocto Project Development Environment<span class="permalink"><a alt="Permalink" title="Permalink" href="#overview-development-environment">¶</a></span></h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="section"><a href="#yp-intro">2.1. Introduction</a></span></dt><dt><span class="section"><a href="#open-source-philosophy">2.2. Open Source Philosophy</a></span></dt><dt><span class="section"><a href="#workflows">2.3. Workflows</a></span></dt><dt><span class="section"><a href="#git">2.4. Git</a></span></dt><dd><dl><dt><span class="section"><a href="#repositories-tags-and-branches">2.4.1. Repositories, Tags, and Branches</a></span></dt><dt><span class="section"><a href="#basic-commands">2.4.2. Basic Commands</a></span></dt></dl></dd><dt><span class="section"><a href="#yocto-project-repositories">2.5. Yocto Project Source Repositories</a></span></dt><dt><span class="section"><a href="#licensing">2.6. Licensing</a></span></dt><dt><span class="section"><a href="#recipe-syntax">2.7. Recipe Syntax</a></span></dt><dt><span class="section"><a href="#development-concepts">2.8. Development Concepts</a></span></dt><dd><dl><dt><span class="section"><a href="#user-configuration">2.8.1. User Configuration</a></span></dt><dt><span class="section"><a href="#metadata-machine-configuration-and-policy-configuration">2.8.2. Metadata, Machine Configuration, and Policy Configuration</a></span></dt><dt><span class="section"><a href="#sources-dev-environment">2.8.3. Sources</a></span></dt><dt><span class="section"><a href="#package-feeds-dev-environment">2.8.4. Package Feeds</a></span></dt><dt><span class="section"><a href="#bitbake-dev-environment">2.8.5. BitBake</a></span></dt><dt><span class="section"><a href="#images-dev-environment">2.8.6. Images</a></span></dt><dt><span class="section"><a href="#sdk-dev-environment">2.8.7. Application Development SDK</a></span></dt></dl></dd></dl></div><p> | ||
| 113 | This chapter takes a look at the Yocto Project development | ||
| 114 | environment and also provides a detailed look at what goes on during | ||
| 115 | development in that environment. | ||
| 116 | The chapter provides Yocto Project Development environment concepts that | ||
| 117 | help you understand how work is accomplished in an open source environment, | ||
| 118 | which is very different as compared to work accomplished in a closed, | ||
| 119 | proprietary environment. | ||
| 120 | </p><p> | ||
| 121 | Specifically, this chapter addresses open source philosophy, workflows, | ||
| 122 | Git, source repositories, licensing, recipe syntax, and development | ||
| 123 | syntax. | ||
| 124 | </p><div class="section" title="2.1. Introduction"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="yp-intro">2.1. Introduction<span class="permalink"><a alt="Permalink" title="Permalink" href="#yp-intro">¶</a></span></h2></div></div></div><p> | ||
| 125 | The Yocto Project is an open-source collaboration project whose | ||
| 126 | focus is for developers of embedded Linux systems. | ||
| 127 | Among other things, the Yocto Project uses an | ||
| 128 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#build-system-term" target="_top">OpenEmbedded build system</a>. | ||
| 129 | The build system, which is based on the OpenEmbedded (OE) project and | ||
| 130 | uses the | ||
| 131 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#bitbake-term" target="_top">BitBake</a> tool, | ||
| 132 | constructs complete Linux images for architectures based on ARM, MIPS, | ||
| 133 | PowerPC, x86 and x86-64. | ||
| 134 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> | ||
| 135 | Historically, the OpenEmbedded build system, which is the | ||
| 136 | combination of BitBake and OE components, formed a reference | ||
| 137 | build host that was known as | ||
| 138 | "<a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#poky" target="_top">Poky</a>" | ||
| 139 | (<span class="emphasis"><em>Pah</em></span>-kee). | ||
| 140 | The term "Poky", as used throughout the Yocto Project Documentation | ||
| 141 | set, can have different meanings. | ||
| 142 | </div><p> | ||
| 143 | The Yocto Project provides various ancillary tools for the embedded | ||
| 144 | developer and also features the Sato reference User Interface, which | ||
| 145 | is optimized for stylus-driven, low-resolution screens. | ||
| 146 | </p><div class="mediaobject" align="center"><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="720"><tr><td align="center"><img src="figures/YP-flow-diagram.png" align="middle" width="720" /></td></tr></table></div><p> | ||
| 147 | Here are some highlights for the Yocto Project: | ||
| 148 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> | ||
| 149 | Provides a recent Linux kernel along with a set of system | ||
| 150 | commands and libraries suitable for the embedded | ||
| 151 | environment. | ||
| 152 | </p></li><li class="listitem"><p> | ||
| 153 | Makes available system components such as X11, GTK+, Qt, | ||
| 154 | Clutter, and SDL (among others) so you can create a rich user | ||
| 155 | experience on devices that have display hardware. | ||
| 156 | For devices that do not have a display or where you wish to | ||
| 157 | use alternative UI frameworks, these components need not be | ||
| 158 | installed. | ||
| 159 | </p></li><li class="listitem"><p> | ||
| 160 | Creates a focused and stable core compatible with the | ||
| 161 | OpenEmbedded project with which you can easily and reliably | ||
| 162 | build and develop. | ||
| 163 | </p></li><li class="listitem"><p> | ||
| 164 | Fully supports a wide range of hardware and device emulation | ||
| 165 | through the Quick EMUlator (QEMU). | ||
| 166 | </p></li><li class="listitem"><p> | ||
| 167 | Provides a layer mechanism that allows you to easily extend | ||
| 168 | the system, make customizations, and keep them organized. | ||
| 169 | </p></li></ul></div><p> | ||
| 170 | You can use the Yocto Project to generate images for many kinds | ||
| 171 | of devices. | ||
| 172 | As mentioned earlier, the Yocto Project supports creation of | ||
| 173 | reference images that you can boot within and emulate using QEMU. | ||
| 174 | The standard example machines target QEMU full-system | ||
| 175 | emulation for 32-bit and 64-bit variants of x86, ARM, MIPS, and | ||
| 176 | PowerPC architectures. | ||
| 177 | Beyond emulation, you can use the layer mechanism to extend | ||
| 178 | support to just about any platform that Linux can run on and that | ||
| 179 | a toolchain can target. | ||
| 180 | </p><p> | ||
| 181 | Another Yocto Project feature is the Sato reference User | ||
| 182 | Interface. | ||
| 183 | This optional UI that is based on GTK+ is intended for devices with | ||
| 184 | restricted screen sizes and is included as part of the | ||
| 185 | OpenEmbedded Core layer so that developers can test parts of the | ||
| 186 | software stack. | ||
| 187 | </p><p> | ||
| 188 | While the Yocto Project does not provide a strict testing framework, | ||
| 189 | it does provide or generate for you artifacts that let you perform | ||
| 190 | target-level and emulated testing and debugging. | ||
| 191 | Additionally, if you are an | ||
| 192 | <span class="trademark">Eclipse</span>™ IDE user, you can | ||
| 193 | install an Eclipse Yocto Plug-in to allow you to develop within that | ||
| 194 | familiar environment. | ||
| 195 | </p><p> | ||
| 196 | By default, using the Yocto Project to build an image creates a Poky | ||
| 197 | distribution. | ||
| 198 | However, you can create your own distribution by providing key | ||
| 199 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#metadata" target="_top">Metadata</a>. | ||
| 200 | A good example is Angstrom, which has had a distribution | ||
| 201 | based on the Yocto Project since its inception. | ||
| 202 | Other examples include commercial distributions like | ||
| 203 | <a class="ulink" href="https://www.yoctoproject.org/organization/wind-river-systems" target="_top">Wind River Linux</a>, | ||
| 204 | <a class="ulink" href="https://www.yoctoproject.org/organization/mentor-graphics" target="_top">Mentor Embedded Linux</a>, | ||
| 205 | <a class="ulink" href="https://www.yoctoproject.org/organization/enea-ab" target="_top">ENEA Linux</a> | ||
| 206 | and <a class="ulink" href="https://www.yoctoproject.org/ecosystem/member-organizations" target="_top">others</a>. | ||
| 207 | See the "<a class="ulink" href="http://www.yoctoproject.org/docs/2.5/dev-manual/dev-manual.html#creating-your-own-distribution" target="_top">Creating Your Own Distribution</a>" | ||
| 208 | section in the Yocto Project Development Tasks Manual for more | ||
| 209 | information. | ||
| 210 | </p></div><div class="section" title="2.2. Open Source Philosophy"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="open-source-philosophy">2.2. Open Source Philosophy<span class="permalink"><a alt="Permalink" title="Permalink" href="#open-source-philosophy">¶</a></span></h2></div></div></div><p> | ||
| 211 | Open source philosophy is characterized by software development | ||
| 212 | directed by peer production and collaboration through an active | ||
| 213 | community of developers. | ||
| 214 | Contrast this to the more standard centralized development models | ||
| 215 | used by commercial software companies where a finite set of developers | ||
| 216 | produces a product for sale using a defined set of procedures that | ||
| 217 | ultimately result in an end product whose architecture and source | ||
| 218 | material are closed to the public. | ||
| 219 | </p><p> | ||
| 220 | Open source projects conceptually have differing concurrent agendas, | ||
| 221 | approaches, and production. | ||
| 222 | These facets of the development process can come from anyone in the | ||
| 223 | public (community) that has a stake in the software project. | ||
| 224 | The open source environment contains new copyright, licensing, domain, | ||
| 225 | and consumer issues that differ from the more traditional development | ||
| 226 | environment. | ||
| 227 | In an open source environment, the end product, source material, | ||
| 228 | and documentation are all available to the public at no cost. | ||
| 229 | </p><p> | ||
| 230 | A benchmark example of an open source project is the Linux kernel, | ||
| 231 | which was initially conceived and created by Finnish computer science | ||
| 232 | student Linus Torvalds in 1991. | ||
| 233 | Conversely, a good example of a non-open source project is the | ||
| 234 | <span class="trademark">Windows</span>® family of operating | ||
| 235 | systems developed by | ||
| 236 | <span class="trademark">Microsoft</span>® Corporation. | ||
| 237 | </p><p> | ||
| 238 | Wikipedia has a good historical description of the Open Source | ||
| 239 | Philosophy | ||
| 240 | <a class="ulink" href="http://en.wikipedia.org/wiki/Open_source" target="_top">here</a>. | ||
| 241 | You can also find helpful information on how to participate in the | ||
| 242 | Linux Community | ||
| 243 | <a class="ulink" href="http://ldn.linuxfoundation.org/book/how-participate-linux-community" target="_top">here</a>. | ||
| 244 | </p></div><div class="section" title="2.3. Workflows"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="workflows">2.3. Workflows<span class="permalink"><a alt="Permalink" title="Permalink" href="#workflows">¶</a></span></h2></div></div></div><p> | ||
| 245 | This section provides workflow concepts using the Yocto Project and | ||
| 246 | Git. | ||
| 247 | In particular, the information covers basic practices that describe | ||
| 248 | roles and actions in a collaborative development environment. | ||
| 249 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> | ||
| 250 | If you are familiar with this type of development environment, you | ||
| 251 | might not want to read this section. | ||
| 252 | </div><p> | ||
| 253 | </p><p> | ||
| 254 | The Yocto Project files are maintained using Git in "master" | ||
| 255 | branches whose Git histories track every change and whose structures | ||
| 256 | provides branches for all diverging functionality. | ||
| 257 | Although there is no need to use Git, many open source projects do so. | ||
| 258 | </p><p> | ||
| 259 | |||
| 260 | </p><p> | ||
| 261 | For the Yocto Project, a key individual called the "maintainer" is | ||
| 262 | responsible for the "master" branch of a given Git repository. | ||
| 263 | The "master" branch is the “upstream” repository from which final or | ||
| 264 | most recent builds of the project occur. | ||
| 265 | The maintainer is responsible for accepting changes from other | ||
| 266 | developers and for organizing the underlying branch structure to | ||
| 267 | reflect release strategies and so forth. | ||
| 268 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>For information on finding out who is responsible for (maintains) | ||
| 269 | a particular area of code, see the | ||
| 270 | "<a class="ulink" href="http://www.yoctoproject.org/docs/2.5/dev-manual/dev-manual.html#how-to-submit-a-change" target="_top">Submitting a Change to the Yocto Project</a>" | ||
| 271 | section of the Yocto Project Development Tasks Manual. | ||
| 272 | </div><p> | ||
| 273 | </p><p> | ||
| 274 | The Yocto Project <code class="filename">poky</code> Git repository also has an | ||
| 275 | upstream contribution Git repository named | ||
| 276 | <code class="filename">poky-contrib</code>. | ||
| 277 | You can see all the branches in this repository using the web interface | ||
| 278 | of the | ||
| 279 | <a class="ulink" href="http://git.yoctoproject.org" target="_top">Source Repositories</a> organized | ||
| 280 | within the "Poky Support" area. | ||
| 281 | These branches temporarily hold changes to the project that have been | ||
| 282 | submitted or committed by the Yocto Project development team and by | ||
| 283 | community members who contribute to the project. | ||
| 284 | The maintainer determines if the changes are qualified to be moved | ||
| 285 | from the "contrib" branches into the "master" branch of the Git | ||
| 286 | repository. | ||
| 287 | </p><p> | ||
| 288 | Developers (including contributing community members) create and | ||
| 289 | maintain cloned repositories of the upstream "master" branch. | ||
| 290 | The cloned repositories are local to their development platforms and | ||
| 291 | are used to develop changes. | ||
| 292 | When a developer is satisfied with a particular feature or change, | ||
| 293 | they "push" the changes to the appropriate "contrib" repository. | ||
| 294 | </p><p> | ||
| 295 | Developers are responsible for keeping their local repository | ||
| 296 | up-to-date with "master". | ||
| 297 | They are also responsible for straightening out any conflicts that | ||
| 298 | might arise within files that are being worked on simultaneously by | ||
| 299 | more than one person. | ||
| 300 | All this work is done locally on the developer’s machine before | ||
| 301 | anything is pushed to a "contrib" area and examined at the maintainer’s | ||
| 302 | level. | ||
| 303 | </p><p> | ||
| 304 | A somewhat formal method exists by which developers commit changes | ||
| 305 | and push them into the "contrib" area and subsequently request that | ||
| 306 | the maintainer include them into "master". | ||
| 307 | This process is called “submitting a patch” or "submitting a change." | ||
| 308 | For information on submitting patches and changes, see the | ||
| 309 | "<a class="ulink" href="http://www.yoctoproject.org/docs/2.5/dev-manual/dev-manual.html#how-to-submit-a-change" target="_top">Submitting a Change to the Yocto Project</a>" | ||
| 310 | section in the Yocto Project Development Tasks Manual. | ||
| 311 | </p><p> | ||
| 312 | To summarize the development workflow: a single point of entry | ||
| 313 | exists for changes into the project’s "master" branch of the | ||
| 314 | Git repository, which is controlled by the project’s maintainer. | ||
| 315 | And, a set of developers exist who independently develop, test, and | ||
| 316 | submit changes to "contrib" areas for the maintainer to examine. | ||
| 317 | The maintainer then chooses which changes are going to become a | ||
| 318 | permanent part of the project. | ||
| 319 | </p><p> | ||
| 320 | </p><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="540"><tr style="height: 270px"><td align="left"><img src="figures/git-workflow.png" align="left" height="270" /></td></tr></table><p> | ||
| 321 | </p><p> | ||
| 322 | While each development environment is unique, there are some best | ||
| 323 | practices or methods that help development run smoothly. | ||
| 324 | The following list describes some of these practices. | ||
| 325 | For more information about Git workflows, see the workflow topics in | ||
| 326 | the | ||
| 327 | <a class="ulink" href="http://book.git-scm.com" target="_top">Git Community Book</a>. | ||
| 328 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> | ||
| 329 | <span class="emphasis"><em>Make Small Changes:</em></span> | ||
| 330 | It is best to keep the changes you commit small as compared to | ||
| 331 | bundling many disparate changes into a single commit. | ||
| 332 | This practice not only keeps things manageable but also allows | ||
| 333 | the maintainer to more easily include or refuse changes.</p><p>It is also good practice to leave the repository in a | ||
| 334 | state that allows you to still successfully build your project. | ||
| 335 | In other words, do not commit half of a feature, | ||
| 336 | then add the other half as a separate, later commit. | ||
| 337 | Each commit should take you from one buildable project state | ||
| 338 | to another buildable state. | ||
| 339 | </p></li><li class="listitem"><p> | ||
| 340 | <span class="emphasis"><em>Use Branches Liberally:</em></span> | ||
| 341 | It is very easy to create, use, and delete local branches in | ||
| 342 | your working Git repository. | ||
| 343 | You can name these branches anything you like. | ||
| 344 | It is helpful to give them names associated with the particular | ||
| 345 | feature or change on which you are working. | ||
| 346 | Once you are done with a feature or change and have merged it | ||
| 347 | into your local master branch, simply discard the temporary | ||
| 348 | branch. | ||
| 349 | </p></li><li class="listitem"><p> | ||
| 350 | <span class="emphasis"><em>Merge Changes:</em></span> | ||
| 351 | The <code class="filename">git merge</code> command allows you to take | ||
| 352 | the changes from one branch and fold them into another branch. | ||
| 353 | This process is especially helpful when more than a single | ||
| 354 | developer might be working on different parts of the same | ||
| 355 | feature. | ||
| 356 | Merging changes also automatically identifies any collisions | ||
| 357 | or "conflicts" that might happen as a result of the same lines | ||
| 358 | of code being altered by two different developers. | ||
| 359 | </p></li><li class="listitem"><p> | ||
| 360 | <span class="emphasis"><em>Manage Branches:</em></span> | ||
| 361 | Because branches are easy to use, you should use a system | ||
| 362 | where branches indicate varying levels of code readiness. | ||
| 363 | For example, you can have a "work" branch to develop in, a | ||
| 364 | "test" branch where the code or change is tested, a "stage" | ||
| 365 | branch where changes are ready to be committed, and so forth. | ||
| 366 | As your project develops, you can merge code across the | ||
| 367 | branches to reflect ever-increasing stable states of the | ||
| 368 | development. | ||
| 369 | </p></li><li class="listitem"><p> | ||
| 370 | <span class="emphasis"><em>Use Push and Pull:</em></span> | ||
| 371 | The push-pull workflow is based on the concept of developers | ||
| 372 | "pushing" local commits to a remote repository, which is | ||
| 373 | usually a contribution repository. | ||
| 374 | This workflow is also based on developers "pulling" known | ||
| 375 | states of the project down into their local development | ||
| 376 | repositories. | ||
| 377 | The workflow easily allows you to pull changes submitted by | ||
| 378 | other developers from the upstream repository into your | ||
| 379 | work area ensuring that you have the most recent software | ||
| 380 | on which to develop. | ||
| 381 | The Yocto Project has two scripts named | ||
| 382 | <code class="filename">create-pull-request</code> and | ||
| 383 | <code class="filename">send-pull-request</code> that ship with the | ||
| 384 | release to facilitate this workflow. | ||
| 385 | You can find these scripts in the <code class="filename">scripts</code> | ||
| 386 | folder of the | ||
| 387 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#source-directory" target="_top">Source Directory</a>. | ||
| 388 | For information on how to use these scripts, see the | ||
| 389 | "<a class="ulink" href="http://www.yoctoproject.org/docs/2.5/dev-manual/dev-manual.html#pushing-a-change-upstream" target="_top">Using Scripts to Push a Change Upstream and Request a Pull</a>" | ||
| 390 | section in the Yocto Project Development Tasks Manual. | ||
| 391 | </p></li><li class="listitem"><p> | ||
| 392 | <span class="emphasis"><em>Patch Workflow:</em></span> | ||
| 393 | This workflow allows you to notify the maintainer through an | ||
| 394 | email that you have a change (or patch) you would like | ||
| 395 | considered for the "master" branch of the Git repository. | ||
| 396 | To send this type of change, you format the patch and then | ||
| 397 | send the email using the Git commands | ||
| 398 | <code class="filename">git format-patch</code> and | ||
| 399 | <code class="filename">git send-email</code>. | ||
| 400 | For information on how to use these scripts, see the | ||
| 401 | "<a class="ulink" href="http://www.yoctoproject.org/docs/2.5/dev-manual/dev-manual.html#how-to-submit-a-change" target="_top">Submitting a Change to the Yocto Project</a>" | ||
| 402 | section in the Yocto Project Development Tasks Manual. | ||
| 403 | </p></li></ul></div><p> | ||
| 404 | </p></div><div class="section" title="2.4. Git"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="git">2.4. Git<span class="permalink"><a alt="Permalink" title="Permalink" href="#git">¶</a></span></h2></div></div></div><p> | ||
| 405 | The Yocto Project makes extensive use of Git, which is a | ||
| 406 | free, open source distributed version control system. | ||
| 407 | Git supports distributed development, non-linear development, | ||
| 408 | and can handle large projects. | ||
| 409 | It is best that you have some fundamental understanding | ||
| 410 | of how Git tracks projects and how to work with Git if | ||
| 411 | you are going to use the Yocto Project for development. | ||
| 412 | This section provides a quick overview of how Git works and | ||
| 413 | provides you with a summary of some essential Git commands. | ||
| 414 | </p><div class="note" title="Notes" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Notes</h3><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> | ||
| 415 | For more information on Git, see | ||
| 416 | <a class="ulink" href="http://git-scm.com/documentation" target="_top">http://git-scm.com/documentation</a>. | ||
| 417 | </p></li><li class="listitem"><p> | ||
| 418 | If you need to download Git, it is recommended that you add | ||
| 419 | Git to your system through your distribution's "software | ||
| 420 | store" (e.g. for Ubuntu, use the Ubuntu Software feature). | ||
| 421 | For the Git download page, see | ||
| 422 | <a class="ulink" href="http://git-scm.com/download" target="_top">http://git-scm.com/download</a>. | ||
| 423 | </p></li><li class="listitem"><p> | ||
| 424 | For examples beyond the limited few in this section on how | ||
| 425 | to use Git with the Yocto Project, see the | ||
| 426 | "<a class="ulink" href="http://www.yoctoproject.org/docs/2.5/dev-manual/dev-manual.html#working-with-yocto-project-source-files" target="_top">Working With Yocto Project Source Files</a>" | ||
| 427 | section in the Yocto Project Development Tasks Manual. | ||
| 428 | </p></li></ul></div></div><p> | ||
| 429 | </p><div class="section" title="2.4.1. Repositories, Tags, and Branches"><div class="titlepage"><div><div><h3 class="title" id="repositories-tags-and-branches">2.4.1. Repositories, Tags, and Branches<span class="permalink"><a alt="Permalink" title="Permalink" href="#repositories-tags-and-branches">¶</a></span></h3></div></div></div><p> | ||
| 430 | As mentioned briefly in the previous section and also in the | ||
| 431 | "<a class="link" href="#workflows" title="2.3. Workflows">Workflows</a>" section, | ||
| 432 | the Yocto Project maintains source repositories at | ||
| 433 | <a class="ulink" href="http://git.yoctoproject.org/cgit.cgi" target="_top">http://git.yoctoproject.org/cgit.cgi</a>. | ||
| 434 | If you look at this web-interface of the repositories, each item | ||
| 435 | is a separate Git repository. | ||
| 436 | </p><p> | ||
| 437 | Git repositories use branching techniques that track content | ||
| 438 | change (not files) within a project (e.g. a new feature or updated | ||
| 439 | documentation). | ||
| 440 | Creating a tree-like structure based on project divergence allows | ||
| 441 | for excellent historical information over the life of a project. | ||
| 442 | This methodology also allows for an environment from which you can | ||
| 443 | do lots of local experimentation on projects as you develop | ||
| 444 | changes or new features. | ||
| 445 | </p><p> | ||
| 446 | A Git repository represents all development efforts for a given | ||
| 447 | project. | ||
| 448 | For example, the Git repository <code class="filename">poky</code> contains | ||
| 449 | all changes and developments for Poky over the course of its | ||
| 450 | entire life. | ||
| 451 | That means that all changes that make up all releases are captured. | ||
| 452 | The repository maintains a complete history of changes. | ||
| 453 | </p><p> | ||
| 454 | You can create a local copy of any repository by "cloning" it | ||
| 455 | with the <code class="filename">git clone</code> command. | ||
| 456 | When you clone a Git repository, you end up with an identical | ||
| 457 | copy of the repository on your development system. | ||
| 458 | Once you have a local copy of a repository, you can take steps to | ||
| 459 | develop locally. | ||
| 460 | For examples on how to clone Git repositories, see the | ||
| 461 | "<a class="ulink" href="http://www.yoctoproject.org/docs/2.5/dev-manual/dev-manual.html#working-with-yocto-project-source-files" target="_top">Working With Yocto Project Source Files</a>" | ||
| 462 | section in the Yocto Project Development Tasks Manual. | ||
| 463 | </p><p> | ||
| 464 | It is important to understand that Git tracks content change and | ||
| 465 | not files. | ||
| 466 | Git uses "branches" to organize different development efforts. | ||
| 467 | For example, the <code class="filename">poky</code> repository has | ||
| 468 | several branches that include the current "sumo" | ||
| 469 | branch, the "master" branch, and many branches for past | ||
| 470 | Yocto Project releases. | ||
| 471 | You can see all the branches by going to | ||
| 472 | <a class="ulink" href="http://git.yoctoproject.org/cgit.cgi/poky/" target="_top">http://git.yoctoproject.org/cgit.cgi/poky/</a> and | ||
| 473 | clicking on the | ||
| 474 | <code class="filename"><a class="ulink" href="http://git.yoctoproject.org/cgit.cgi/poky/refs/heads" target="_top">[...]</a></code> | ||
| 475 | link beneath the "Branch" heading. | ||
| 476 | </p><p> | ||
| 477 | Each of these branches represents a specific area of development. | ||
| 478 | The "master" branch represents the current or most recent | ||
| 479 | development. | ||
| 480 | All other branches represent offshoots of the "master" branch. | ||
| 481 | </p><p> | ||
| 482 | When you create a local copy of a Git repository, the copy has | ||
| 483 | the same set of branches as the original. | ||
| 484 | This means you can use Git to create a local working area | ||
| 485 | (also called a branch) that tracks a specific development branch | ||
| 486 | from the upstream source Git repository. | ||
| 487 | in other words, you can define your local Git environment to | ||
| 488 | work on any development branch in the repository. | ||
| 489 | To help illustrate, consider the following example Git commands: | ||
| 490 | </p><pre class="literallayout"> | ||
| 491 | $ cd ~ | ||
| 492 | $ git clone git://git.yoctoproject.org/poky | ||
| 493 | $ cd poky | ||
| 494 | $ git checkout -b sumo origin/sumo | ||
| 495 | </pre><p> | ||
| 496 | In the previous example after moving to the home directory, the | ||
| 497 | <code class="filename">git clone</code> command creates a | ||
| 498 | local copy of the upstream <code class="filename">poky</code> Git repository. | ||
| 499 | By default, Git checks out the "master" branch for your work. | ||
| 500 | After changing the working directory to the new local repository | ||
| 501 | (i.e. <code class="filename">poky</code>), the | ||
| 502 | <code class="filename">git checkout</code> command creates | ||
| 503 | and checks out a local branch named "sumo", which | ||
| 504 | tracks the upstream "origin/sumo" branch. | ||
| 505 | Changes you make while in this branch would ultimately affect | ||
| 506 | the upstream "sumo" branch of the | ||
| 507 | <code class="filename">poky</code> repository. | ||
| 508 | </p><p> | ||
| 509 | It is important to understand that when you create and checkout a | ||
| 510 | local working branch based on a branch name, | ||
| 511 | your local environment matches the "tip" of that particular | ||
| 512 | development branch at the time you created your local branch, | ||
| 513 | which could be different from the files in the "master" branch | ||
| 514 | of the upstream repository. | ||
| 515 | In other words, creating and checking out a local branch based on | ||
| 516 | the "sumo" branch name is not the same as | ||
| 517 | cloning and checking out the "master" branch if the repository. | ||
| 518 | Keep reading to see how you create a local snapshot of a Yocto | ||
| 519 | Project Release. | ||
| 520 | </p><p> | ||
| 521 | Git uses "tags" to mark specific changes in a repository. | ||
| 522 | Typically, a tag is used to mark a special point such as the final | ||
| 523 | change before a project is released. | ||
| 524 | You can see the tags used with the <code class="filename">poky</code> Git | ||
| 525 | repository by going to | ||
| 526 | <a class="ulink" href="http://git.yoctoproject.org/cgit.cgi/poky/" target="_top">http://git.yoctoproject.org/cgit.cgi/poky/</a> and | ||
| 527 | clicking on the | ||
| 528 | <code class="filename"><a class="ulink" href="http://git.yoctoproject.org/cgit.cgi/poky/refs/tags" target="_top">[...]</a></code> | ||
| 529 | link beneath the "Tag" heading. | ||
| 530 | </p><p> | ||
| 531 | Some key tags for the <code class="filename">poky</code> are | ||
| 532 | <code class="filename">jethro-14.0.3</code>, | ||
| 533 | <code class="filename">morty-16.0.1</code>, | ||
| 534 | <code class="filename">pyro-17.0.0</code>, and | ||
| 535 | <code class="filename">sumo-20.0.0</code>. | ||
| 536 | These tags represent Yocto Project releases. | ||
| 537 | </p><p> | ||
| 538 | When you create a local copy of the Git repository, you also | ||
| 539 | have access to all the tags in the upstream repository. | ||
| 540 | Similar to branches, you can create and checkout a local working | ||
| 541 | Git branch based on a tag name. | ||
| 542 | When you do this, you get a snapshot of the Git repository that | ||
| 543 | reflects the state of the files when the change was made associated | ||
| 544 | with that tag. | ||
| 545 | The most common use is to checkout a working branch that matches | ||
| 546 | a specific Yocto Project release. | ||
| 547 | Here is an example: | ||
| 548 | </p><pre class="literallayout"> | ||
| 549 | $ cd ~ | ||
| 550 | $ git clone git://git.yoctoproject.org/poky | ||
| 551 | $ cd poky | ||
| 552 | $ git fetch --all --tags --prune | ||
| 553 | $ git checkout tags/pyro-17.0.0 -b my-pyro-17.0.0 | ||
| 554 | </pre><p> | ||
| 555 | In this example, the name of the top-level directory of your | ||
| 556 | local Yocto Project repository is <code class="filename">poky</code>. | ||
| 557 | After moving to the <code class="filename">poky</code> directory, the | ||
| 558 | <code class="filename">git fetch</code> command makes all the upstream | ||
| 559 | tags available locally in your repository. | ||
| 560 | Finally, the <code class="filename">git checkout</code> command | ||
| 561 | creates and checks out a branch named "my-pyro-17.0.0" that is | ||
| 562 | based on the specific change upstream in the repository | ||
| 563 | associated with the "pyro-17.0.0" tag. | ||
| 564 | The files in your repository now exactly match that particular | ||
| 565 | Yocto Project release as it is tagged in the upstream Git | ||
| 566 | repository. | ||
| 567 | It is important to understand that when you create and | ||
| 568 | checkout a local working branch based on a tag, your environment | ||
| 569 | matches a specific point in time and not the entire development | ||
| 570 | branch (i.e. the "tip" of the branch). | ||
| 571 | </p></div><div class="section" title="2.4.2. Basic Commands"><div class="titlepage"><div><div><h3 class="title" id="basic-commands">2.4.2. Basic Commands<span class="permalink"><a alt="Permalink" title="Permalink" href="#basic-commands">¶</a></span></h3></div></div></div><p> | ||
| 572 | Git has an extensive set of commands that lets you manage changes | ||
| 573 | and perform collaboration over the life of a project. | ||
| 574 | Conveniently though, you can manage with a small set of basic | ||
| 575 | operations and workflows once you understand the basic | ||
| 576 | philosophy behind Git. | ||
| 577 | You do not have to be an expert in Git to be functional. | ||
| 578 | A good place to look for instruction on a minimal set of Git | ||
| 579 | commands is | ||
| 580 | <a class="ulink" href="http://git-scm.com/documentation" target="_top">here</a>. | ||
| 581 | </p><p> | ||
| 582 | If you do not know much about Git, you should educate | ||
| 583 | yourself by visiting the links previously mentioned. | ||
| 584 | </p><p> | ||
| 585 | The following list of Git commands briefly describes some basic | ||
| 586 | Git operations as a way to get started. | ||
| 587 | As with any set of commands, this list (in most cases) simply shows | ||
| 588 | the base command and omits the many arguments they support. | ||
| 589 | See the Git documentation for complete descriptions and strategies | ||
| 590 | on how to use these commands: | ||
| 591 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> | ||
| 592 | <span class="emphasis"><em><code class="filename">git init</code>:</em></span> | ||
| 593 | Initializes an empty Git repository. | ||
| 594 | You cannot use Git commands unless you have a | ||
| 595 | <code class="filename">.git</code> repository. | ||
| 596 | </p></li><li class="listitem"><p><a id="git-commands-clone"></a> | ||
| 597 | <span class="emphasis"><em><code class="filename">git clone</code>:</em></span> | ||
| 598 | Creates a local clone of a Git repository that is on | ||
| 599 | equal footing with a fellow developer’s Git repository | ||
| 600 | or an upstream repository. | ||
| 601 | </p></li><li class="listitem"><p> | ||
| 602 | <span class="emphasis"><em><code class="filename">git add</code>:</em></span> | ||
| 603 | Locally stages updated file contents to the index that | ||
| 604 | Git uses to track changes. | ||
| 605 | You must stage all files that have changed before you | ||
| 606 | can commit them. | ||
| 607 | </p></li><li class="listitem"><p> | ||
| 608 | <span class="emphasis"><em><code class="filename">git commit</code>:</em></span> | ||
| 609 | Creates a local "commit" that documents the changes you | ||
| 610 | made. | ||
| 611 | Only changes that have been staged can be committed. | ||
| 612 | Commits are used for historical purposes, for determining | ||
| 613 | if a maintainer of a project will allow the change, | ||
| 614 | and for ultimately pushing the change from your local | ||
| 615 | Git repository into the project’s upstream repository. | ||
| 616 | </p></li><li class="listitem"><p> | ||
| 617 | <span class="emphasis"><em><code class="filename">git status</code>:</em></span> | ||
| 618 | Reports any modified files that possibly need to be | ||
| 619 | staged and gives you a status of where you stand regarding | ||
| 620 | local commits as compared to the upstream repository. | ||
| 621 | </p></li><li class="listitem"><p> | ||
| 622 | <span class="emphasis"><em><code class="filename">git checkout</code> <em class="replaceable"><code>branch-name</code></em>:</em></span> | ||
| 623 | Changes your working branch. | ||
| 624 | This command is analogous to "cd". | ||
| 625 | </p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">git checkout –b</code> <em class="replaceable"><code>working-branch</code></em>:</em></span> | ||
| 626 | Creates and checks out a working branch on your local | ||
| 627 | machine that you can use to isolate your work. | ||
| 628 | It is a good idea to use local branches when adding | ||
| 629 | specific features or changes. | ||
| 630 | Using isolated branches facilitates easy removal of | ||
| 631 | changes if they do not work out. | ||
| 632 | </p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">git branch</code>:</em></span> | ||
| 633 | Displays the existing local branches associated with your | ||
| 634 | local repository. | ||
| 635 | The branch that you have currently checked out is noted | ||
| 636 | with an asterisk character. | ||
| 637 | </p></li><li class="listitem"><p> | ||
| 638 | <span class="emphasis"><em><code class="filename">git branch -D</code> <em class="replaceable"><code>branch-name</code></em>:</em></span> | ||
| 639 | Deletes an existing local branch. | ||
| 640 | You need to be in a local branch other than the one you | ||
| 641 | are deleting in order to delete | ||
| 642 | <em class="replaceable"><code>branch-name</code></em>. | ||
| 643 | </p></li><li class="listitem"><p> | ||
| 644 | <span class="emphasis"><em><code class="filename">git pull</code>:</em></span> | ||
| 645 | Retrieves information from an upstream Git repository | ||
| 646 | and places it in your local Git repository. | ||
| 647 | You use this command to make sure you are synchronized with | ||
| 648 | the repository from which you are basing changes | ||
| 649 | (.e.g. the "master" branch). | ||
| 650 | </p></li><li class="listitem"><p> | ||
| 651 | <span class="emphasis"><em><code class="filename">git push</code>:</em></span> | ||
| 652 | Sends all your committed local changes to the upstream Git | ||
| 653 | repository that your local repository is tracking | ||
| 654 | (e.g. a contribution repository). | ||
| 655 | The maintainer of the project draws from these repositories | ||
| 656 | to merge changes (commits) into the appropriate branch | ||
| 657 | of project's upstream repository. | ||
| 658 | </p></li><li class="listitem"><p> | ||
| 659 | <span class="emphasis"><em><code class="filename">git merge</code>:</em></span> | ||
| 660 | Combines or adds changes from one | ||
| 661 | local branch of your repository with another branch. | ||
| 662 | When you create a local Git repository, the default branch | ||
| 663 | is named "master". | ||
| 664 | A typical workflow is to create a temporary branch that is | ||
| 665 | based off "master" that you would use for isolated work. | ||
| 666 | You would make your changes in that isolated branch, | ||
| 667 | stage and commit them locally, switch to the "master" | ||
| 668 | branch, and then use the <code class="filename">git merge</code> | ||
| 669 | command to apply the changes from your isolated branch | ||
| 670 | into the currently checked out branch (e.g. "master"). | ||
| 671 | After the merge is complete and if you are done with | ||
| 672 | working in that isolated branch, you can safely delete | ||
| 673 | the isolated branch. | ||
| 674 | </p></li><li class="listitem"><p> | ||
| 675 | <span class="emphasis"><em><code class="filename">git cherry-pick</code>:</em></span> | ||
| 676 | Choose and apply specific commits from one branch | ||
| 677 | into another branch. | ||
| 678 | There are times when you might not be able to merge | ||
| 679 | all the changes in one branch with | ||
| 680 | another but need to pick out certain ones. | ||
| 681 | </p></li><li class="listitem"><p> | ||
| 682 | <span class="emphasis"><em><code class="filename">gitk</code>:</em></span> | ||
| 683 | Provides a GUI view of the branches and changes in your | ||
| 684 | local Git repository. | ||
| 685 | This command is a good way to graphically see where things | ||
| 686 | have diverged in your local repository. | ||
| 687 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> | ||
| 688 | You need to install the <code class="filename">gitk</code> | ||
| 689 | package on your development system to use this | ||
| 690 | command. | ||
| 691 | </div><p> | ||
| 692 | </p></li><li class="listitem"><p> | ||
| 693 | <span class="emphasis"><em><code class="filename">git log</code>:</em></span> | ||
| 694 | Reports a history of your commits to the repository. | ||
| 695 | This report lists all commits regardless of whether you | ||
| 696 | have pushed them upstream or not. | ||
| 697 | </p></li><li class="listitem"><p> | ||
| 698 | <span class="emphasis"><em><code class="filename">git diff</code>:</em></span> | ||
| 699 | Displays line-by-line differences between a local | ||
| 700 | working file and the same file as understood by Git. | ||
| 701 | This command is useful to see what you have changed | ||
| 702 | in any given file. | ||
| 703 | </p></li></ul></div><p> | ||
| 704 | </p></div></div><div class="section" title="2.5. Yocto Project Source Repositories"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="yocto-project-repositories">2.5. Yocto Project Source Repositories<span class="permalink"><a alt="Permalink" title="Permalink" href="#yocto-project-repositories">¶</a></span></h2></div></div></div><p> | ||
| 705 | The Yocto Project team maintains complete source repositories for all | ||
| 706 | Yocto Project files at | ||
| 707 | <a class="ulink" href="http://git.yoctoproject.org/cgit/cgit.cgi" target="_top">http://git.yoctoproject.org/cgit/cgit.cgi</a>. | ||
| 708 | This web-based source code browser is organized into categories by | ||
| 709 | function such as IDE Plugins, Matchbox, Poky, Yocto Linux Kernel, and | ||
| 710 | so forth. | ||
| 711 | From the interface, you can click on any particular item in the "Name" | ||
| 712 | column and see the URL at the bottom of the page that you need to clone | ||
| 713 | a Git repository for that particular item. | ||
| 714 | Having a local Git repository of the | ||
| 715 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#source-directory" target="_top">Source Directory</a>, | ||
| 716 | which is usually named "poky", allows | ||
| 717 | you to make changes, contribute to the history, and ultimately enhance | ||
| 718 | the Yocto Project's tools, Board Support Packages, and so forth. | ||
| 719 | </p><p> | ||
| 720 | For any supported release of Yocto Project, you can also go to the | ||
| 721 | <a class="ulink" href="http://www.yoctoproject.org" target="_top">Yocto Project Website</a> and | ||
| 722 | select the "Downloads" tab and get a released tarball of the | ||
| 723 | <code class="filename">poky</code> repository or any supported BSP tarballs. | ||
| 724 | Unpacking these tarballs gives you a snapshot of the released | ||
| 725 | files. | ||
| 726 | </p><div class="note" title="Notes" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Notes</h3><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> | ||
| 727 | The recommended method for setting up the Yocto Project | ||
| 728 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#source-directory" target="_top">Source Directory</a> | ||
| 729 | and the files for supported BSPs | ||
| 730 | (e.g., <code class="filename">meta-intel</code>) is to use | ||
| 731 | <a class="link" href="#git" title="2.4. Git">Git</a> to create a local copy of | ||
| 732 | the upstream repositories. | ||
| 733 | </p></li><li class="listitem"><p> | ||
| 734 | Be sure to always work in matching branches for both | ||
| 735 | the selected BSP repository and the | ||
| 736 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#source-directory" target="_top">Source Directory</a> | ||
| 737 | (i.e. <code class="filename">poky</code>) repository. | ||
| 738 | For example, if you have checked out the "master" branch | ||
| 739 | of <code class="filename">poky</code> and you are going to use | ||
| 740 | <code class="filename">meta-intel</code>, be sure to checkout the | ||
| 741 | "master" branch of <code class="filename">meta-intel</code>. | ||
| 742 | </p></li></ul></div></div><p> | ||
| 743 | </p><p> | ||
| 744 | In summary, here is where you can get the project files needed for | ||
| 745 | development: | ||
| 746 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><a id="source-repositories"></a> | ||
| 747 | <span class="emphasis"><em> | ||
| 748 | <a class="ulink" href="http://git.yoctoproject.org/cgit/cgit.cgi" target="_top">Source Repositories:</a> | ||
| 749 | </em></span> | ||
| 750 | This area contains IDE Plugins, Matchbox, Poky, Poky Support, | ||
| 751 | Tools, Yocto Linux Kernel, and Yocto Metadata Layers. | ||
| 752 | You can create local copies of Git repositories for each of | ||
| 753 | these areas.</p><p> | ||
| 754 | </p><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="540"><tr style="height: 360px"><td align="center"><img src="figures/source-repos.png" align="middle" width="540" /></td></tr></table><p> | ||
| 755 | For steps on how to view and access these upstream Git | ||
| 756 | repositories, see the | ||
| 757 | "<a class="ulink" href="http://www.yoctoproject.org/docs/2.5/dev-manual/dev-manual.html#accessing-source-repositories" target="_top">Accessing Source Repositories</a>" | ||
| 758 | Section in the Yocto Project Development Tasks Manual. | ||
| 759 | </p></li><li class="listitem"><p><a id="index-downloads"></a> | ||
| 760 | <span class="emphasis"><em> | ||
| 761 | <a class="ulink" href="http://downloads.yoctoproject.org/releases/" target="_top">Index of /releases:</a> | ||
| 762 | </em></span> | ||
| 763 | This is an index of releases such as | ||
| 764 | the <span class="trademark">Eclipse</span>™ | ||
| 765 | Yocto Plug-in, miscellaneous support, Poky, Pseudo, installers | ||
| 766 | for cross-development toolchains, and all released versions of | ||
| 767 | Yocto Project in the form of images or tarballs. | ||
| 768 | Downloading and extracting these files does not produce a local | ||
| 769 | copy of the Git repository but rather a snapshot of a | ||
| 770 | particular release or image.</p><p> | ||
| 771 | </p><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="540"><tr style="height: 315px"><td align="center"><img src="figures/index-downloads.png" align="middle" height="315" /></td></tr></table><p> | ||
| 772 | For steps on how to view and access these files, see the | ||
| 773 | "<a class="ulink" href="http://www.yoctoproject.org/docs/2.5/dev-manual/dev-manual.html#accessing-index-of-releases" target="_top">Accessing Index of Releases</a>" | ||
| 774 | section in the Yocto Project Development Tasks Manual. | ||
| 775 | </p></li><li class="listitem"><p><a id="downloads-page"></a> | ||
| 776 | <span class="emphasis"><em>"Downloads" page for the | ||
| 777 | <a class="ulink" href="http://www.yoctoproject.org" target="_top">Yocto Project Website</a>: | ||
| 778 | </em></span></p><p class="writernotes">This section will change due to | ||
| 779 | reworking of the YP Website.</p><p>The Yocto Project website includes a "Downloads" tab | ||
| 780 | that allows you to download any Yocto Project | ||
| 781 | release and Board Support Package (BSP) in tarball form. | ||
| 782 | The tarballs are similar to those found in the | ||
| 783 | <a class="ulink" href="http://downloads.yoctoproject.org/releases/" target="_top">Index of /releases:</a> area.</p><p> | ||
| 784 | </p><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="540"><tr style="height: 360px"><td align="center"><img src="figures/yp-download.png" align="middle" width="540" /></td></tr></table><p> | ||
| 785 | For steps on how to use the "Downloads" page, see the | ||
| 786 | "<a class="ulink" href="http://www.yoctoproject.org/docs/2.5/dev-manual/dev-manual.html#using-the-downloads-page" target="_top">Using the Downloads Page</a>" | ||
| 787 | section in the Yocto Project Development Tasks Manual. | ||
| 788 | </p></li></ul></div><p> | ||
| 789 | </p></div><div class="section" title="2.6. Licensing"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="licensing">2.6. Licensing<span class="permalink"><a alt="Permalink" title="Permalink" href="#licensing">¶</a></span></h2></div></div></div><p> | ||
| 790 | Because open source projects are open to the public, they have | ||
| 791 | different licensing structures in place. | ||
| 792 | License evolution for both Open Source and Free Software has an | ||
| 793 | interesting history. | ||
| 794 | If you are interested in this history, you can find basic information | ||
| 795 | here: | ||
| 796 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> | ||
| 797 | <a class="ulink" href="http://en.wikipedia.org/wiki/Open-source_license" target="_top">Open source license history</a> | ||
| 798 | </p></li><li class="listitem"><p> | ||
| 799 | <a class="ulink" href="http://en.wikipedia.org/wiki/Free_software_license" target="_top">Free software license history</a> | ||
| 800 | </p></li></ul></div><p> | ||
| 801 | </p><p> | ||
| 802 | In general, the Yocto Project is broadly licensed under the | ||
| 803 | Massachusetts Institute of Technology (MIT) License. | ||
| 804 | MIT licensing permits the reuse of software within proprietary | ||
| 805 | software as long as the license is distributed with that software. | ||
| 806 | MIT is also compatible with the GNU General Public License (GPL). | ||
| 807 | Patches to the Yocto Project follow the upstream licensing scheme. | ||
| 808 | You can find information on the MIT license | ||
| 809 | <a class="ulink" href="http://www.opensource.org/licenses/mit-license.php" target="_top">here</a>. | ||
| 810 | You can find information on the GNU GPL | ||
| 811 | <a class="ulink" href="http://www.opensource.org/licenses/LGPL-3.0" target="_top">here</a>. | ||
| 812 | </p><p> | ||
| 813 | When you build an image using the Yocto Project, the build process | ||
| 814 | uses a known list of licenses to ensure compliance. | ||
| 815 | You can find this list in the | ||
| 816 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#source-directory" target="_top">Source Directory</a> | ||
| 817 | at <code class="filename">meta/files/common-licenses</code>. | ||
| 818 | Once the build completes, the list of all licenses found and used | ||
| 819 | during that build are kept in the | ||
| 820 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#build-directory" target="_top">Build Directory</a> | ||
| 821 | at <code class="filename">tmp/deploy/licenses</code>. | ||
| 822 | </p><p> | ||
| 823 | If a module requires a license that is not in the base list, the | ||
| 824 | build process generates a warning during the build. | ||
| 825 | These tools make it easier for a developer to be certain of the | ||
| 826 | licenses with which their shipped products must comply. | ||
| 827 | However, even with these tools it is still up to the developer to | ||
| 828 | resolve potential licensing issues. | ||
| 829 | </p><p> | ||
| 830 | The base list of licenses used by the build process is a combination | ||
| 831 | of the Software Package Data Exchange (SPDX) list and the Open | ||
| 832 | Source Initiative (OSI) projects. | ||
| 833 | <a class="ulink" href="http://spdx.org" target="_top">SPDX Group</a> is a working group of | ||
| 834 | the Linux Foundation that maintains a specification for a standard | ||
| 835 | format for communicating the components, licenses, and copyrights | ||
| 836 | associated with a software package. | ||
| 837 | <a class="ulink" href="http://opensource.org" target="_top">OSI</a> is a corporation | ||
| 838 | dedicated to the Open Source Definition and the effort for reviewing | ||
| 839 | and approving licenses that conform to the Open Source Definition | ||
| 840 | (OSD). | ||
| 841 | </p><p> | ||
| 842 | You can find a list of the combined SPDX and OSI licenses that the | ||
| 843 | Yocto Project uses in the | ||
| 844 | <code class="filename">meta/files/common-licenses</code> directory in your | ||
| 845 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#source-directory" target="_top">Source Directory</a>. | ||
| 846 | </p><p> | ||
| 847 | For information that can help you maintain compliance with various | ||
| 848 | open source licensing during the lifecycle of a product created using | ||
| 849 | the Yocto Project, see the | ||
| 850 | "<a class="ulink" href="http://www.yoctoproject.org/docs/2.5/dev-manual/dev-manual.html#maintaining-open-source-license-compliance-during-your-products-lifecycle" target="_top">Maintaining Open Source License Compliance During Your Product's Lifecycle</a>" | ||
| 851 | section in the Yocto Project Development Tasks Manual. | ||
| 852 | </p></div><div class="section" title="2.7. Recipe Syntax"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="recipe-syntax">2.7. Recipe Syntax<span class="permalink"><a alt="Permalink" title="Permalink" href="#recipe-syntax">¶</a></span></h2></div></div></div><p> | ||
| 853 | Understanding recipe file syntax is important for | ||
| 854 | writing recipes. | ||
| 855 | The following list overviews the basic items that make up a | ||
| 856 | BitBake recipe file. | ||
| 857 | For more complete BitBake syntax descriptions, see the | ||
| 858 | "<a class="ulink" href="http://www.yoctoproject.org/docs/2.5/bitbake-user-manual/bitbake-user-manual.html#bitbake-user-manual-metadata" target="_top">Syntax and Operators</a>" | ||
| 859 | chapter of the BitBake User Manual. | ||
| 860 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>Variable Assignments and Manipulations:</em></span> | ||
| 861 | Variable assignments allow a value to be assigned to a | ||
| 862 | variable. | ||
| 863 | The assignment can be static text or might include | ||
| 864 | the contents of other variables. | ||
| 865 | In addition to the assignment, appending and prepending | ||
| 866 | operations are also supported.</p><p>The following example shows some of the ways | ||
| 867 | you can use variables in recipes: | ||
| 868 | </p><pre class="literallayout"> | ||
| 869 | S = "${WORKDIR}/postfix-${PV}" | ||
| 870 | CFLAGS += "-DNO_ASM" | ||
| 871 | SRC_URI_append = " file://fixup.patch" | ||
| 872 | </pre><p> | ||
| 873 | </p></li><li class="listitem"><p><span class="emphasis"><em>Functions:</em></span> | ||
| 874 | Functions provide a series of actions to be performed. | ||
| 875 | You usually use functions to override the default | ||
| 876 | implementation of a task function or to complement | ||
| 877 | a default function (i.e. append or prepend to an | ||
| 878 | existing function). | ||
| 879 | Standard functions use <code class="filename">sh</code> shell | ||
| 880 | syntax, although access to OpenEmbedded variables and | ||
| 881 | internal methods are also available.</p><p>The following is an example function from the | ||
| 882 | <code class="filename">sed</code> recipe: | ||
| 883 | </p><pre class="literallayout"> | ||
| 884 | do_install () { | ||
| 885 | autotools_do_install | ||
| 886 | install -d ${D}${base_bindir} | ||
| 887 | mv ${D}${bindir}/sed ${D}${base_bindir}/sed | ||
| 888 | rmdir ${D}${bindir}/ | ||
| 889 | } | ||
| 890 | </pre><p> | ||
| 891 | It is also possible to implement new functions that | ||
| 892 | are called between existing tasks as long as the | ||
| 893 | new functions are not replacing or complementing the | ||
| 894 | default functions. | ||
| 895 | You can implement functions in Python | ||
| 896 | instead of shell. | ||
| 897 | Both of these options are not seen in the majority of | ||
| 898 | recipes.</p></li><li class="listitem"><p><span class="emphasis"><em>Keywords:</em></span> | ||
| 899 | BitBake recipes use only a few keywords. | ||
| 900 | You use keywords to include common | ||
| 901 | functions (<code class="filename">inherit</code>), load parts | ||
| 902 | of a recipe from other files | ||
| 903 | (<code class="filename">include</code> and | ||
| 904 | <code class="filename">require</code>) and export variables | ||
| 905 | to the environment (<code class="filename">export</code>).</p><p>The following example shows the use of some of | ||
| 906 | these keywords: | ||
| 907 | </p><pre class="literallayout"> | ||
| 908 | export POSTCONF = "${STAGING_BINDIR}/postconf" | ||
| 909 | inherit autoconf | ||
| 910 | require otherfile.inc | ||
| 911 | </pre><p> | ||
| 912 | </p></li><li class="listitem"><p><span class="emphasis"><em>Comments:</em></span> | ||
| 913 | Any lines that begin with the hash character | ||
| 914 | (<code class="filename">#</code>) are treated as comment lines | ||
| 915 | and are ignored: | ||
| 916 | </p><pre class="literallayout"> | ||
| 917 | # This is a comment | ||
| 918 | </pre><p> | ||
| 919 | </p></li></ul></div><p> | ||
| 920 | </p><p> | ||
| 921 | This next list summarizes the most important and most commonly | ||
| 922 | used parts of the recipe syntax. | ||
| 923 | For more information on these parts of the syntax, you can | ||
| 924 | reference the | ||
| 925 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/bitbake-user-manual/bitbake-user-manual.html#bitbake-user-manual-metadata" target="_top">Syntax and Operators</a> | ||
| 926 | chapter in the BitBake User Manual. | ||
| 927 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>Line Continuation: <code class="filename">\</code></em></span> - | ||
| 928 | Use the backward slash (<code class="filename">\</code>) | ||
| 929 | character to split a statement over multiple lines. | ||
| 930 | Place the slash character at the end of the line that | ||
| 931 | is to be continued on the next line: | ||
| 932 | </p><pre class="literallayout"> | ||
| 933 | VAR = "A really long \ | ||
| 934 | line" | ||
| 935 | </pre><p> | ||
| 936 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> | ||
| 937 | You cannot have any characters including spaces | ||
| 938 | or tabs after the slash character. | ||
| 939 | </div><p> | ||
| 940 | </p></li><li class="listitem"><p> | ||
| 941 | <span class="emphasis"><em>Using Variables: <code class="filename">${...}</code></em></span> - | ||
| 942 | Use the <code class="filename">${<em class="replaceable"><code>VARNAME</code></em>}</code> syntax to | ||
| 943 | access the contents of a variable: | ||
| 944 | </p><pre class="literallayout"> | ||
| 945 | SRC_URI = "${SOURCEFORGE_MIRROR}/libpng/zlib-${PV}.tar.gz" | ||
| 946 | </pre><p> | ||
| 947 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> | ||
| 948 | It is important to understand that the value of a | ||
| 949 | variable expressed in this form does not get | ||
| 950 | substituted automatically. | ||
| 951 | The expansion of these expressions happens | ||
| 952 | on-demand later (e.g. usually when a function that | ||
| 953 | makes reference to the variable executes). | ||
| 954 | This behavior ensures that the values are most | ||
| 955 | appropriate for the context in which they are | ||
| 956 | finally used. | ||
| 957 | On the rare occasion that you do need the variable | ||
| 958 | expression to be expanded immediately, you can use | ||
| 959 | the <code class="filename">:=</code> operator instead of | ||
| 960 | <code class="filename">=</code> when you make the | ||
| 961 | assignment, but this is not generally needed. | ||
| 962 | </div><p> | ||
| 963 | </p></li><li class="listitem"><p><span class="emphasis"><em>Quote All Assignments: <code class="filename">"<em class="replaceable"><code>value</code></em>"</code></em></span> - | ||
| 964 | Use double quotes around the value in all variable | ||
| 965 | assignments. | ||
| 966 | </p><pre class="literallayout"> | ||
| 967 | VAR1 = "${OTHERVAR}" | ||
| 968 | VAR2 = "The version is ${PV}" | ||
| 969 | </pre><p> | ||
| 970 | </p></li><li class="listitem"><p><span class="emphasis"><em>Conditional Assignment: <code class="filename">?=</code></em></span> - | ||
| 971 | Conditional assignment is used to assign a value to | ||
| 972 | a variable, but only when the variable is currently | ||
| 973 | unset. | ||
| 974 | Use the question mark followed by the equal sign | ||
| 975 | (<code class="filename">?=</code>) to make a "soft" assignment | ||
| 976 | used for conditional assignment. | ||
| 977 | Typically, "soft" assignments are used in the | ||
| 978 | <code class="filename">local.conf</code> file for variables | ||
| 979 | that are allowed to come through from the external | ||
| 980 | environment. | ||
| 981 | </p><p>Here is an example where | ||
| 982 | <code class="filename">VAR1</code> is set to "New value" if | ||
| 983 | it is currently empty. | ||
| 984 | However, if <code class="filename">VAR1</code> has already been | ||
| 985 | set, it remains unchanged: | ||
| 986 | </p><pre class="literallayout"> | ||
| 987 | VAR1 ?= "New value" | ||
| 988 | </pre><p> | ||
| 989 | In this next example, <code class="filename">VAR1</code> | ||
| 990 | is left with the value "Original value": | ||
| 991 | </p><pre class="literallayout"> | ||
| 992 | VAR1 = "Original value" | ||
| 993 | VAR1 ?= "New value" | ||
| 994 | </pre><p> | ||
| 995 | </p></li><li class="listitem"><p><span class="emphasis"><em>Appending: <code class="filename">+=</code></em></span> - | ||
| 996 | Use the plus character followed by the equals sign | ||
| 997 | (<code class="filename">+=</code>) to append values to existing | ||
| 998 | variables. | ||
| 999 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> | ||
| 1000 | This operator adds a space between the existing | ||
| 1001 | content of the variable and the new content. | ||
| 1002 | </div><p>Here is an example: | ||
| 1003 | </p><pre class="literallayout"> | ||
| 1004 | SRC_URI += "file://fix-makefile.patch" | ||
| 1005 | </pre><p> | ||
| 1006 | </p></li><li class="listitem"><p><span class="emphasis"><em>Prepending: <code class="filename">=+</code></em></span> - | ||
| 1007 | Use the equals sign followed by the plus character | ||
| 1008 | (<code class="filename">=+</code>) to prepend values to existing | ||
| 1009 | variables. | ||
| 1010 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> | ||
| 1011 | This operator adds a space between the new content | ||
| 1012 | and the existing content of the variable. | ||
| 1013 | </div><p>Here is an example: | ||
| 1014 | </p><pre class="literallayout"> | ||
| 1015 | VAR =+ "Starts" | ||
| 1016 | </pre><p> | ||
| 1017 | </p></li><li class="listitem"><p><span class="emphasis"><em>Appending: <code class="filename">_append</code></em></span> - | ||
| 1018 | Use the <code class="filename">_append</code> operator to | ||
| 1019 | append values to existing variables. | ||
| 1020 | This operator does not add any additional space. | ||
| 1021 | Also, the operator is applied after all the | ||
| 1022 | <code class="filename">+=</code>, and | ||
| 1023 | <code class="filename">=+</code> operators have been applied and | ||
| 1024 | after all <code class="filename">=</code> assignments have | ||
| 1025 | occurred. | ||
| 1026 | </p><p>The following example shows the space being | ||
| 1027 | explicitly added to the start to ensure the appended | ||
| 1028 | value is not merged with the existing value: | ||
| 1029 | </p><pre class="literallayout"> | ||
| 1030 | SRC_URI_append = " file://fix-makefile.patch" | ||
| 1031 | </pre><p> | ||
| 1032 | You can also use the <code class="filename">_append</code> | ||
| 1033 | operator with overrides, which results in the actions | ||
| 1034 | only being performed for the specified target or | ||
| 1035 | machine: | ||
| 1036 | </p><pre class="literallayout"> | ||
| 1037 | SRC_URI_append_sh4 = " file://fix-makefile.patch" | ||
| 1038 | </pre><p> | ||
| 1039 | </p></li><li class="listitem"><p><span class="emphasis"><em>Prepending: <code class="filename">_prepend</code></em></span> - | ||
| 1040 | Use the <code class="filename">_prepend</code> operator to | ||
| 1041 | prepend values to existing variables. | ||
| 1042 | This operator does not add any additional space. | ||
| 1043 | Also, the operator is applied after all the | ||
| 1044 | <code class="filename">+=</code>, and | ||
| 1045 | <code class="filename">=+</code> operators have been applied and | ||
| 1046 | after all <code class="filename">=</code> assignments have | ||
| 1047 | occurred. | ||
| 1048 | </p><p>The following example shows the space being | ||
| 1049 | explicitly added to the end to ensure the prepended | ||
| 1050 | value is not merged with the existing value: | ||
| 1051 | </p><pre class="literallayout"> | ||
| 1052 | CFLAGS_prepend = "-I${S}/myincludes " | ||
| 1053 | </pre><p> | ||
| 1054 | You can also use the <code class="filename">_prepend</code> | ||
| 1055 | operator with overrides, which results in the actions | ||
| 1056 | only being performed for the specified target or | ||
| 1057 | machine: | ||
| 1058 | </p><pre class="literallayout"> | ||
| 1059 | CFLAGS_prepend_sh4 = "-I${S}/myincludes " | ||
| 1060 | </pre><p> | ||
| 1061 | </p></li><li class="listitem"><p><span class="emphasis"><em>Overrides:</em></span> - | ||
| 1062 | You can use overrides to set a value conditionally, | ||
| 1063 | typically based on how the recipe is being built. | ||
| 1064 | For example, to set the | ||
| 1065 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-KBRANCH" target="_top"><code class="filename">KBRANCH</code></a> | ||
| 1066 | variable's value to "standard/base" for any target | ||
| 1067 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-MACHINE" target="_top"><code class="filename">MACHINE</code></a>, | ||
| 1068 | except for qemuarm where it should be set to | ||
| 1069 | "standard/arm-versatile-926ejs", you would do the | ||
| 1070 | following: | ||
| 1071 | </p><pre class="literallayout"> | ||
| 1072 | KBRANCH = "standard/base" | ||
| 1073 | KBRANCH_qemuarm = "standard/arm-versatile-926ejs" | ||
| 1074 | </pre><p> | ||
| 1075 | Overrides are also used to separate alternate values | ||
| 1076 | of a variable in other situations. | ||
| 1077 | For example, when setting variables such as | ||
| 1078 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-FILES" target="_top"><code class="filename">FILES</code></a> | ||
| 1079 | and | ||
| 1080 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-RDEPENDS" target="_top"><code class="filename">RDEPENDS</code></a> | ||
| 1081 | that are specific to individual packages produced by | ||
| 1082 | a recipe, you should always use an override that | ||
| 1083 | specifies the name of the package. | ||
| 1084 | </p></li><li class="listitem"><p><span class="emphasis"><em>Indentation:</em></span> | ||
| 1085 | Use spaces for indentation rather than than tabs. | ||
| 1086 | For shell functions, both currently work. | ||
| 1087 | However, it is a policy decision of the Yocto Project | ||
| 1088 | to use tabs in shell functions. | ||
| 1089 | Realize that some layers have a policy to use spaces | ||
| 1090 | for all indentation. | ||
| 1091 | </p></li><li class="listitem"><p><span class="emphasis"><em>Using Python for Complex Operations: <code class="filename">${@<em class="replaceable"><code>python_code</code></em>}</code></em></span> - | ||
| 1092 | For more advanced processing, it is possible to use | ||
| 1093 | Python code during variable assignments (e.g. | ||
| 1094 | search and replacement on a variable).</p><p>You indicate Python code using the | ||
| 1095 | <code class="filename">${@<em class="replaceable"><code>python_code</code></em>}</code> | ||
| 1096 | syntax for the variable assignment: | ||
| 1097 | </p><pre class="literallayout"> | ||
| 1098 | SRC_URI = "ftp://ftp.info-zip.org/pub/infozip/src/zip${@d.getVar('PV',1).replace('.', '')}.tgz | ||
| 1099 | </pre><p> | ||
| 1100 | </p></li><li class="listitem"><p><span class="emphasis"><em>Shell Function Syntax:</em></span> | ||
| 1101 | Write shell functions as if you were writing a shell | ||
| 1102 | script when you describe a list of actions to take. | ||
| 1103 | You should ensure that your script works with a generic | ||
| 1104 | <code class="filename">sh</code> and that it does not require | ||
| 1105 | any <code class="filename">bash</code> or other shell-specific | ||
| 1106 | functionality. | ||
| 1107 | The same considerations apply to various system | ||
| 1108 | utilities (e.g. <code class="filename">sed</code>, | ||
| 1109 | <code class="filename">grep</code>, <code class="filename">awk</code>, | ||
| 1110 | and so forth) that you might wish to use. | ||
| 1111 | If in doubt, you should check with multiple | ||
| 1112 | implementations - including those from BusyBox. | ||
| 1113 | </p></li></ul></div><p> | ||
| 1114 | </p></div><div class="section" title="2.8. Development Concepts"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="development-concepts">2.8. Development Concepts<span class="permalink"><a alt="Permalink" title="Permalink" href="#development-concepts">¶</a></span></h2></div></div></div><p> | ||
| 1115 | This section takes a more detailed look inside the development | ||
| 1116 | process. | ||
| 1117 | The following diagram represents development at a high level. | ||
| 1118 | The remainder of this chapter expands on the fundamental input, output, | ||
| 1119 | process, and | ||
| 1120 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#metadata" target="_top">Metadata</a>) blocks | ||
| 1121 | that make up development in the Yocto Project environment. | ||
| 1122 | </p><p><a id="general-yocto-environment-figure"></a> | ||
| 1123 | </p><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="720"><tr style="height: 383px"><td align="center"><img src="figures/yocto-environment-ref.png" align="middle" height="383" /></td></tr></table><p> | ||
| 1124 | </p><p> | ||
| 1125 | In general, development consists of several functional areas: | ||
| 1126 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>User Configuration:</em></span> | ||
| 1127 | Metadata you can use to control the build process. | ||
| 1128 | </p></li><li class="listitem"><p><span class="emphasis"><em>Metadata Layers:</em></span> | ||
| 1129 | Various layers that provide software, machine, and | ||
| 1130 | distro Metadata.</p></li><li class="listitem"><p><span class="emphasis"><em>Source Files:</em></span> | ||
| 1131 | Upstream releases, local projects, and SCMs.</p></li><li class="listitem"><p><span class="emphasis"><em>Build System:</em></span> | ||
| 1132 | Processes under the control of | ||
| 1133 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#bitbake-term" target="_top">BitBake</a>. | ||
| 1134 | This block expands on how BitBake fetches source, applies | ||
| 1135 | patches, completes compilation, analyzes output for package | ||
| 1136 | generation, creates and tests packages, generates images, and | ||
| 1137 | generates cross-development tools.</p></li><li class="listitem"><p><span class="emphasis"><em>Package Feeds:</em></span> | ||
| 1138 | Directories containing output packages (RPM, DEB or IPK), | ||
| 1139 | which are subsequently used in the construction of an image or | ||
| 1140 | SDK, produced by the build system. | ||
| 1141 | These feeds can also be copied and shared using a web server or | ||
| 1142 | other means to facilitate extending or updating existing | ||
| 1143 | images on devices at runtime if runtime package management is | ||
| 1144 | enabled.</p></li><li class="listitem"><p><span class="emphasis"><em>Images:</em></span> | ||
| 1145 | Images produced by the development process. | ||
| 1146 | </p></li><li class="listitem"><p><span class="emphasis"><em>Application Development SDK:</em></span> | ||
| 1147 | Cross-development tools that are produced along with an image | ||
| 1148 | or separately with BitBake.</p></li></ul></div><p> | ||
| 1149 | </p><div class="section" title="2.8.1. User Configuration"><div class="titlepage"><div><div><h3 class="title" id="user-configuration">2.8.1. User Configuration<span class="permalink"><a alt="Permalink" title="Permalink" href="#user-configuration">¶</a></span></h3></div></div></div><p> | ||
| 1150 | User configuration helps define the build. | ||
| 1151 | Through user configuration, you can tell BitBake the | ||
| 1152 | target architecture for which you are building the image, | ||
| 1153 | where to store downloaded source, and other build properties. | ||
| 1154 | </p><p> | ||
| 1155 | The following figure shows an expanded representation of the | ||
| 1156 | "User Configuration" box of the | ||
| 1157 | <a class="link" href="#general-yocto-environment-figure">general Yocto Project Development Environment figure</a>: | ||
| 1158 | </p><p> | ||
| 1159 | </p><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="720"><tr style="height: 405px"><td align="center"><img src="figures/user-configuration.png" align="middle" height="405" /></td></tr></table><p> | ||
| 1160 | </p><p> | ||
| 1161 | BitBake needs some basic configuration files in order to complete | ||
| 1162 | a build. | ||
| 1163 | These files are <code class="filename">*.conf</code> files. | ||
| 1164 | The minimally necessary ones reside as example files in the | ||
| 1165 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#source-directory" target="_top">Source Directory</a>. | ||
| 1166 | For simplicity, this section refers to the Source Directory as | ||
| 1167 | the "Poky Directory." | ||
| 1168 | </p><p> | ||
| 1169 | When you clone the <code class="filename">poky</code> Git repository or you | ||
| 1170 | download and unpack a Yocto Project release, you can set up the | ||
| 1171 | Source Directory to be named anything you want. | ||
| 1172 | For this discussion, the cloned repository uses the default | ||
| 1173 | name <code class="filename">poky</code>. | ||
| 1174 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> | ||
| 1175 | The Poky repository is primarily an aggregation of existing | ||
| 1176 | repositories. | ||
| 1177 | It is not a canonical upstream source. | ||
| 1178 | </div><p> | ||
| 1179 | </p><p> | ||
| 1180 | The <code class="filename">meta-poky</code> layer inside Poky contains | ||
| 1181 | a <code class="filename">conf</code> directory that has example | ||
| 1182 | configuration files. | ||
| 1183 | These example files are used as a basis for creating actual | ||
| 1184 | configuration files when you source the build environment | ||
| 1185 | script | ||
| 1186 | (i.e. | ||
| 1187 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#structure-core-script" target="_top"><code class="filename">oe-init-build-env</code></a>). | ||
| 1188 | </p><p> | ||
| 1189 | Sourcing the build environment script creates a | ||
| 1190 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#build-directory" target="_top">Build Directory</a> | ||
| 1191 | if one does not already exist. | ||
| 1192 | BitBake uses the Build Directory for all its work during builds. | ||
| 1193 | The Build Directory has a <code class="filename">conf</code> directory that | ||
| 1194 | contains default versions of your <code class="filename">local.conf</code> | ||
| 1195 | and <code class="filename">bblayers.conf</code> configuration files. | ||
| 1196 | These default configuration files are created only if versions | ||
| 1197 | do not already exist in the Build Directory at the time you | ||
| 1198 | source the build environment setup script. | ||
| 1199 | </p><p> | ||
| 1200 | Because the Poky repository is fundamentally an aggregation of | ||
| 1201 | existing repositories, some users might be familiar with running | ||
| 1202 | the <code class="filename">oe-init-build-env</code> script in the context | ||
| 1203 | of separate OpenEmbedded-Core and BitBake repositories rather than a | ||
| 1204 | single Poky repository. | ||
| 1205 | This discussion assumes the script is executed from within a cloned | ||
| 1206 | or unpacked version of Poky. | ||
| 1207 | </p><p> | ||
| 1208 | Depending on where the script is sourced, different sub-scripts | ||
| 1209 | are called to set up the Build Directory (Yocto or OpenEmbedded). | ||
| 1210 | Specifically, the script | ||
| 1211 | <code class="filename">scripts/oe-setup-builddir</code> inside the | ||
| 1212 | poky directory sets up the Build Directory and seeds the directory | ||
| 1213 | (if necessary) with configuration files appropriate for the | ||
| 1214 | Yocto Project development environment. | ||
| 1215 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> | ||
| 1216 | The <code class="filename">scripts/oe-setup-builddir</code> script | ||
| 1217 | uses the <code class="filename">$TEMPLATECONF</code> variable to | ||
| 1218 | determine which sample configuration files to locate. | ||
| 1219 | </div><p> | ||
| 1220 | </p><p> | ||
| 1221 | The <code class="filename">local.conf</code> file provides many | ||
| 1222 | basic variables that define a build environment. | ||
| 1223 | Here is a list of a few. | ||
| 1224 | To see the default configurations in a <code class="filename">local.conf</code> | ||
| 1225 | file created by the build environment script, see the | ||
| 1226 | <code class="filename">local.conf.sample</code> in the | ||
| 1227 | <code class="filename">meta-poky</code> layer: | ||
| 1228 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>Parallelism Options:</em></span> | ||
| 1229 | Controlled by the | ||
| 1230 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-BB_NUMBER_THREADS" target="_top"><code class="filename">BB_NUMBER_THREADS</code></a>, | ||
| 1231 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-PARALLEL_MAKE" target="_top"><code class="filename">PARALLEL_MAKE</code></a>, | ||
| 1232 | and | ||
| 1233 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/bitbake-user-manual/bitbake-user-manual.html#var-BB_NUMBER_PARSE_THREADS" target="_top"><code class="filename">BB_NUMBER_PARSE_THREADS</code></a> | ||
| 1234 | variables.</p></li><li class="listitem"><p><span class="emphasis"><em>Target Machine Selection:</em></span> | ||
| 1235 | Controlled by the | ||
| 1236 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-MACHINE" target="_top"><code class="filename">MACHINE</code></a> | ||
| 1237 | variable.</p></li><li class="listitem"><p><span class="emphasis"><em>Download Directory:</em></span> | ||
| 1238 | Controlled by the | ||
| 1239 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-DL_DIR" target="_top"><code class="filename">DL_DIR</code></a> | ||
| 1240 | variable.</p></li><li class="listitem"><p><span class="emphasis"><em>Shared State Directory:</em></span> | ||
| 1241 | Controlled by the | ||
| 1242 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-SSTATE_DIR" target="_top"><code class="filename">SSTATE_DIR</code></a> | ||
| 1243 | variable.</p></li><li class="listitem"><p><span class="emphasis"><em>Build Output:</em></span> | ||
| 1244 | Controlled by the | ||
| 1245 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-TMPDIR" target="_top"><code class="filename">TMPDIR</code></a> | ||
| 1246 | variable.</p></li></ul></div><p> | ||
| 1247 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> | ||
| 1248 | Configurations set in the <code class="filename">conf/local.conf</code> | ||
| 1249 | file can also be set in the | ||
| 1250 | <code class="filename">conf/site.conf</code> and | ||
| 1251 | <code class="filename">conf/auto.conf</code> configuration files. | ||
| 1252 | </div><p> | ||
| 1253 | </p><p> | ||
| 1254 | The <code class="filename">bblayers.conf</code> file tells BitBake what | ||
| 1255 | layers you want considered during the build. | ||
| 1256 | By default, the layers listed in this file include layers | ||
| 1257 | minimally needed by the build system. | ||
| 1258 | However, you must manually add any custom layers you have created. | ||
| 1259 | You can find more information on working with the | ||
| 1260 | <code class="filename">bblayers.conf</code> file in the | ||
| 1261 | "<a class="ulink" href="http://www.yoctoproject.org/docs/2.5/dev-manual/dev-manual.html#enabling-your-layer" target="_top">Enabling Your Layer</a>" | ||
| 1262 | section in the Yocto Project Development Tasks Manual. | ||
| 1263 | </p><p> | ||
| 1264 | The files <code class="filename">site.conf</code> and | ||
| 1265 | <code class="filename">auto.conf</code> are not created by the environment | ||
| 1266 | initialization script. | ||
| 1267 | If you want the <code class="filename">site.conf</code> file, you need to | ||
| 1268 | create that yourself. | ||
| 1269 | The <code class="filename">auto.conf</code> file is typically created by | ||
| 1270 | an autobuilder: | ||
| 1271 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em><code class="filename">site.conf</code>:</em></span> | ||
| 1272 | You can use the <code class="filename">conf/site.conf</code> | ||
| 1273 | configuration file to configure multiple build directories. | ||
| 1274 | For example, suppose you had several build environments and | ||
| 1275 | they shared some common features. | ||
| 1276 | You can set these default build properties here. | ||
| 1277 | A good example is perhaps the packaging format to use | ||
| 1278 | through the | ||
| 1279 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-PACKAGE_CLASSES" target="_top"><code class="filename">PACKAGE_CLASSES</code></a> | ||
| 1280 | variable.</p><p>One useful scenario for using the | ||
| 1281 | <code class="filename">conf/site.conf</code> file is to extend your | ||
| 1282 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-BBPATH" target="_top"><code class="filename">BBPATH</code></a> | ||
| 1283 | variable to include the path to a | ||
| 1284 | <code class="filename">conf/site.conf</code>. | ||
| 1285 | Then, when BitBake looks for Metadata using | ||
| 1286 | <code class="filename">BBPATH</code>, it finds the | ||
| 1287 | <code class="filename">conf/site.conf</code> file and applies your | ||
| 1288 | common configurations found in the file. | ||
| 1289 | To override configurations in a particular build directory, | ||
| 1290 | alter the similar configurations within that build | ||
| 1291 | directory's <code class="filename">conf/local.conf</code> file. | ||
| 1292 | </p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">auto.conf</code>:</em></span> | ||
| 1293 | The file is usually created and written to by | ||
| 1294 | an autobuilder. | ||
| 1295 | The settings put into the file are typically the same as | ||
| 1296 | you would find in the <code class="filename">conf/local.conf</code> | ||
| 1297 | or the <code class="filename">conf/site.conf</code> files. | ||
| 1298 | </p></li></ul></div><p> | ||
| 1299 | </p><p> | ||
| 1300 | You can edit all configuration files to further define | ||
| 1301 | any particular build environment. | ||
| 1302 | This process is represented by the "User Configuration Edits" | ||
| 1303 | box in the figure. | ||
| 1304 | </p><p> | ||
| 1305 | When you launch your build with the | ||
| 1306 | <code class="filename">bitbake <em class="replaceable"><code>target</code></em></code> | ||
| 1307 | command, BitBake sorts out the configurations to ultimately | ||
| 1308 | define your build environment. | ||
| 1309 | It is important to understand that the OpenEmbedded build system | ||
| 1310 | reads the configuration files in a specific order: | ||
| 1311 | <code class="filename">site.conf</code>, <code class="filename">auto.conf</code>, | ||
| 1312 | and <code class="filename">local.conf</code>. | ||
| 1313 | And, the build system applies the normal assignment statement | ||
| 1314 | rules. | ||
| 1315 | Because the files are parsed in a specific order, variable | ||
| 1316 | assignments for the same variable could be affected. | ||
| 1317 | For example, if the <code class="filename">auto.conf</code> file and | ||
| 1318 | the <code class="filename">local.conf</code> set | ||
| 1319 | <em class="replaceable"><code>variable1</code></em> to different values, because | ||
| 1320 | the build system parses <code class="filename">local.conf</code> after | ||
| 1321 | <code class="filename">auto.conf</code>, | ||
| 1322 | <em class="replaceable"><code>variable1</code></em> is assigned the value from | ||
| 1323 | the <code class="filename">local.conf</code> file. | ||
| 1324 | </p></div><div class="section" title="2.8.2. Metadata, Machine Configuration, and Policy Configuration"><div class="titlepage"><div><div><h3 class="title" id="metadata-machine-configuration-and-policy-configuration">2.8.2. Metadata, Machine Configuration, and Policy Configuration<span class="permalink"><a alt="Permalink" title="Permalink" href="#metadata-machine-configuration-and-policy-configuration">¶</a></span></h3></div></div></div><p> | ||
| 1325 | The previous section described the user configurations that | ||
| 1326 | define BitBake's global behavior. | ||
| 1327 | This section takes a closer look at the layers the build system | ||
| 1328 | uses to further control the build. | ||
| 1329 | These layers provide Metadata for the software, machine, and | ||
| 1330 | policy. | ||
| 1331 | </p><p> | ||
| 1332 | In general, three types of layer input exist: | ||
| 1333 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>Policy Configuration:</em></span> | ||
| 1334 | Distribution Layers provide top-level or general | ||
| 1335 | policies for the image or SDK being built. | ||
| 1336 | For example, this layer would dictate whether BitBake | ||
| 1337 | produces RPM or IPK packages.</p></li><li class="listitem"><p><span class="emphasis"><em>Machine Configuration:</em></span> | ||
| 1338 | Board Support Package (BSP) layers provide machine | ||
| 1339 | configurations. | ||
| 1340 | This type of information is specific to a particular | ||
| 1341 | target architecture.</p></li><li class="listitem"><p><span class="emphasis"><em>Metadata:</em></span> | ||
| 1342 | Software layers contain user-supplied recipe files, | ||
| 1343 | patches, and append files. | ||
| 1344 | </p></li></ul></div><p> | ||
| 1345 | </p><p> | ||
| 1346 | The following figure shows an expanded representation of the | ||
| 1347 | Metadata, Machine Configuration, and Policy Configuration input | ||
| 1348 | (layers) boxes of the | ||
| 1349 | <a class="link" href="#general-yocto-environment-figure">general Yocto Project Development Environment figure</a>: | ||
| 1350 | </p><p> | ||
| 1351 | </p><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="720"><tr style="height: 675px"><td align="center"><img src="figures/layer-input.png" align="middle" width="720" /></td></tr></table><p> | ||
| 1352 | </p><p> | ||
| 1353 | In general, all layers have a similar structure. | ||
| 1354 | They all contain a licensing file | ||
| 1355 | (e.g. <code class="filename">COPYING</code>) if the layer is to be | ||
| 1356 | distributed, a <code class="filename">README</code> file as good practice | ||
| 1357 | and especially if the layer is to be distributed, a | ||
| 1358 | configuration directory, and recipe directories. | ||
| 1359 | </p><p> | ||
| 1360 | The Yocto Project has many layers that can be used. | ||
| 1361 | You can see a web-interface listing of them on the | ||
| 1362 | <a class="ulink" href="http://git.yoctoproject.org/" target="_top">Source Repositories</a> | ||
| 1363 | page. | ||
| 1364 | The layers are shown at the bottom categorized under | ||
| 1365 | "Yocto Metadata Layers." | ||
| 1366 | These layers are fundamentally a subset of the | ||
| 1367 | <a class="ulink" href="http://layers.openembedded.org/layerindex/layers/" target="_top">OpenEmbedded Metadata Index</a>, | ||
| 1368 | which lists all layers provided by the OpenEmbedded community. | ||
| 1369 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> | ||
| 1370 | Layers exist in the Yocto Project Source Repositories that | ||
| 1371 | cannot be found in the OpenEmbedded Metadata Index. | ||
| 1372 | These layers are either deprecated or experimental in nature. | ||
| 1373 | </div><p> | ||
| 1374 | </p><p> | ||
| 1375 | BitBake uses the <code class="filename">conf/bblayers.conf</code> file, | ||
| 1376 | which is part of the user configuration, to find what layers it | ||
| 1377 | should be using as part of the build. | ||
| 1378 | </p><p> | ||
| 1379 | For more information on layers, see the | ||
| 1380 | "<a class="ulink" href="http://www.yoctoproject.org/docs/2.5/dev-manual/dev-manual.html#understanding-and-creating-layers" target="_top">Understanding and Creating Layers</a>" | ||
| 1381 | section in the Yocto Project Development Tasks Manual. | ||
| 1382 | </p><div class="section" title="2.8.2.1. Distro Layer"><div class="titlepage"><div><div><h4 class="title" id="distro-layer">2.8.2.1. Distro Layer<span class="permalink"><a alt="Permalink" title="Permalink" href="#distro-layer">¶</a></span></h4></div></div></div><p> | ||
| 1383 | The distribution layer provides policy configurations for your | ||
| 1384 | distribution. | ||
| 1385 | Best practices dictate that you isolate these types of | ||
| 1386 | configurations into their own layer. | ||
| 1387 | Settings you provide in | ||
| 1388 | <code class="filename">conf/distro/<em class="replaceable"><code>distro</code></em>.conf</code> override | ||
| 1389 | similar | ||
| 1390 | settings that BitBake finds in your | ||
| 1391 | <code class="filename">conf/local.conf</code> file in the Build | ||
| 1392 | Directory. | ||
| 1393 | </p><p> | ||
| 1394 | The following list provides some explanation and references | ||
| 1395 | for what you typically find in the distribution layer: | ||
| 1396 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>classes:</em></span> | ||
| 1397 | Class files (<code class="filename">.bbclass</code>) hold | ||
| 1398 | common functionality that can be shared among | ||
| 1399 | recipes in the distribution. | ||
| 1400 | When your recipes inherit a class, they take on the | ||
| 1401 | settings and functions for that class. | ||
| 1402 | You can read more about class files in the | ||
| 1403 | "<a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-classes" target="_top">Classes</a>" | ||
| 1404 | section of the Yocto Reference Manual. | ||
| 1405 | </p></li><li class="listitem"><p><span class="emphasis"><em>conf:</em></span> | ||
| 1406 | This area holds configuration files for the | ||
| 1407 | layer (<code class="filename">conf/layer.conf</code>), | ||
| 1408 | the distribution | ||
| 1409 | (<code class="filename">conf/distro/<em class="replaceable"><code>distro</code></em>.conf</code>), | ||
| 1410 | and any distribution-wide include files. | ||
| 1411 | </p></li><li class="listitem"><p><span class="emphasis"><em>recipes-*:</em></span> | ||
| 1412 | Recipes and append files that affect common | ||
| 1413 | functionality across the distribution. | ||
| 1414 | This area could include recipes and append files | ||
| 1415 | to add distribution-specific configuration, | ||
| 1416 | initialization scripts, custom image recipes, | ||
| 1417 | and so forth.</p></li></ul></div><p> | ||
| 1418 | </p></div><div class="section" title="2.8.2.2. BSP Layer"><div class="titlepage"><div><div><h4 class="title" id="bsp-layer">2.8.2.2. BSP Layer<span class="permalink"><a alt="Permalink" title="Permalink" href="#bsp-layer">¶</a></span></h4></div></div></div><p> | ||
| 1419 | The BSP Layer provides machine configurations. | ||
| 1420 | Everything in this layer is specific to the machine for which | ||
| 1421 | you are building the image or the SDK. | ||
| 1422 | A common structure or form is defined for BSP layers. | ||
| 1423 | You can learn more about this structure in the | ||
| 1424 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/bsp-guide/bsp-guide.html" target="_top">Yocto Project Board Support Package (BSP) Developer's Guide</a>. | ||
| 1425 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> | ||
| 1426 | In order for a BSP layer to be considered compliant with the | ||
| 1427 | Yocto Project, it must meet some structural requirements. | ||
| 1428 | </div><p> | ||
| 1429 | </p><p> | ||
| 1430 | The BSP Layer's configuration directory contains | ||
| 1431 | configuration files for the machine | ||
| 1432 | (<code class="filename">conf/machine/<em class="replaceable"><code>machine</code></em>.conf</code>) and, | ||
| 1433 | of course, the layer (<code class="filename">conf/layer.conf</code>). | ||
| 1434 | </p><p> | ||
| 1435 | The remainder of the layer is dedicated to specific recipes | ||
| 1436 | by function: <code class="filename">recipes-bsp</code>, | ||
| 1437 | <code class="filename">recipes-core</code>, | ||
| 1438 | <code class="filename">recipes-graphics</code>, and | ||
| 1439 | <code class="filename">recipes-kernel</code>. | ||
| 1440 | Metadata can exist for multiple formfactors, graphics | ||
| 1441 | support systems, and so forth. | ||
| 1442 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> | ||
| 1443 | While the figure shows several <code class="filename">recipes-*</code> | ||
| 1444 | directories, not all these directories appear in all | ||
| 1445 | BSP layers. | ||
| 1446 | </div><p> | ||
| 1447 | </p></div><div class="section" title="2.8.2.3. Software Layer"><div class="titlepage"><div><div><h4 class="title" id="software-layer">2.8.2.3. Software Layer<span class="permalink"><a alt="Permalink" title="Permalink" href="#software-layer">¶</a></span></h4></div></div></div><p> | ||
| 1448 | The software layer provides the Metadata for additional | ||
| 1449 | software packages used during the build. | ||
| 1450 | This layer does not include Metadata that is specific to the | ||
| 1451 | distribution or the machine, which are found in their | ||
| 1452 | respective layers. | ||
| 1453 | </p><p> | ||
| 1454 | This layer contains any new recipes that your project needs | ||
| 1455 | in the form of recipe files. | ||
| 1456 | </p></div></div><div class="section" title="2.8.3. Sources"><div class="titlepage"><div><div><h3 class="title" id="sources-dev-environment">2.8.3. Sources<span class="permalink"><a alt="Permalink" title="Permalink" href="#sources-dev-environment">¶</a></span></h3></div></div></div><p> | ||
| 1457 | In order for the OpenEmbedded build system to create an image or | ||
| 1458 | any target, it must be able to access source files. | ||
| 1459 | The | ||
| 1460 | <a class="link" href="#general-yocto-environment-figure">general Yocto Project Development Environment figure</a> | ||
| 1461 | represents source files using the "Upstream Project Releases", | ||
| 1462 | "Local Projects", and "SCMs (optional)" boxes. | ||
| 1463 | The figure represents mirrors, which also play a role in locating | ||
| 1464 | source files, with the "Source Mirror(s)" box. | ||
| 1465 | </p><p> | ||
| 1466 | The method by which source files are ultimately organized is | ||
| 1467 | a function of the project. | ||
| 1468 | For example, for released software, projects tend to use tarballs | ||
| 1469 | or other archived files that can capture the state of a release | ||
| 1470 | guaranteeing that it is statically represented. | ||
| 1471 | On the other hand, for a project that is more dynamic or | ||
| 1472 | experimental in nature, a project might keep source files in a | ||
| 1473 | repository controlled by a Source Control Manager (SCM) such as | ||
| 1474 | Git. | ||
| 1475 | Pulling source from a repository allows you to control | ||
| 1476 | the point in the repository (the revision) from which you want to | ||
| 1477 | build software. | ||
| 1478 | Finally, a combination of the two might exist, which would give the | ||
| 1479 | consumer a choice when deciding where to get source files. | ||
| 1480 | </p><p> | ||
| 1481 | BitBake uses the | ||
| 1482 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-SRC_URI" target="_top"><code class="filename">SRC_URI</code></a> | ||
| 1483 | variable to point to source files regardless of their location. | ||
| 1484 | Each recipe must have a <code class="filename">SRC_URI</code> variable | ||
| 1485 | that points to the source. | ||
| 1486 | </p><p> | ||
| 1487 | Another area that plays a significant role in where source files | ||
| 1488 | come from is pointed to by the | ||
| 1489 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-DL_DIR" target="_top"><code class="filename">DL_DIR</code></a> | ||
| 1490 | variable. | ||
| 1491 | This area is a cache that can hold previously downloaded source. | ||
| 1492 | You can also instruct the OpenEmbedded build system to create | ||
| 1493 | tarballs from Git repositories, which is not the default behavior, | ||
| 1494 | and store them in the <code class="filename">DL_DIR</code> by using the | ||
| 1495 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-BB_GENERATE_MIRROR_TARBALLS" target="_top"><code class="filename">BB_GENERATE_MIRROR_TARBALLS</code></a> | ||
| 1496 | variable. | ||
| 1497 | </p><p> | ||
| 1498 | Judicious use of a <code class="filename">DL_DIR</code> directory can | ||
| 1499 | save the build system a trip across the Internet when looking | ||
| 1500 | for files. | ||
| 1501 | A good method for using a download directory is to have | ||
| 1502 | <code class="filename">DL_DIR</code> point to an area outside of your | ||
| 1503 | Build Directory. | ||
| 1504 | Doing so allows you to safely delete the Build Directory | ||
| 1505 | if needed without fear of removing any downloaded source file. | ||
| 1506 | </p><p> | ||
| 1507 | The remainder of this section provides a deeper look into the | ||
| 1508 | source files and the mirrors. | ||
| 1509 | Here is a more detailed look at the source file area of the | ||
| 1510 | base figure: | ||
| 1511 | </p><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="630"><tr style="height: 675px"><td align="center"><img src="figures/source-input.png" align="middle" width="630" /></td></tr></table><p> | ||
| 1512 | </p><div class="section" title="2.8.3.1. Upstream Project Releases"><div class="titlepage"><div><div><h4 class="title" id="upstream-project-releases">2.8.3.1. Upstream Project Releases<span class="permalink"><a alt="Permalink" title="Permalink" href="#upstream-project-releases">¶</a></span></h4></div></div></div><p> | ||
| 1513 | Upstream project releases exist anywhere in the form of an | ||
| 1514 | archived file (e.g. tarball or zip file). | ||
| 1515 | These files correspond to individual recipes. | ||
| 1516 | For example, the figure uses specific releases each for | ||
| 1517 | BusyBox, Qt, and Dbus. | ||
| 1518 | An archive file can be for any released product that can be | ||
| 1519 | built using a recipe. | ||
| 1520 | </p></div><div class="section" title="2.8.3.2. Local Projects"><div class="titlepage"><div><div><h4 class="title" id="local-projects">2.8.3.2. Local Projects<span class="permalink"><a alt="Permalink" title="Permalink" href="#local-projects">¶</a></span></h4></div></div></div><p> | ||
| 1521 | Local projects are custom bits of software the user provides. | ||
| 1522 | These bits reside somewhere local to a project - perhaps | ||
| 1523 | a directory into which the user checks in items (e.g. | ||
| 1524 | a local directory containing a development source tree | ||
| 1525 | used by the group). | ||
| 1526 | </p><p> | ||
| 1527 | The canonical method through which to include a local project | ||
| 1528 | is to use the | ||
| 1529 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-classes-externalsrc" target="_top"><code class="filename">externalsrc</code></a> | ||
| 1530 | class to include that local project. | ||
| 1531 | You use either the <code class="filename">local.conf</code> or a | ||
| 1532 | recipe's append file to override or set the | ||
| 1533 | recipe to point to the local directory on your disk to pull | ||
| 1534 | in the whole source tree. | ||
| 1535 | </p><p> | ||
| 1536 | For information on how to use the | ||
| 1537 | <code class="filename">externalsrc</code> class, see the | ||
| 1538 | "<a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-classes-externalsrc" target="_top"><code class="filename">externalsrc.bbclass</code></a>" | ||
| 1539 | section. | ||
| 1540 | </p></div><div class="section" title="2.8.3.3. Source Control Managers (Optional)"><div class="titlepage"><div><div><h4 class="title" id="scms">2.8.3.3. Source Control Managers (Optional)<span class="permalink"><a alt="Permalink" title="Permalink" href="#scms">¶</a></span></h4></div></div></div><p> | ||
| 1541 | Another place the build system can get source files from is | ||
| 1542 | through an SCM such as Git or Subversion. | ||
| 1543 | In this case, a repository is cloned or checked out. | ||
| 1544 | The | ||
| 1545 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-tasks-fetch" target="_top"><code class="filename">do_fetch</code></a> | ||
| 1546 | task inside BitBake uses | ||
| 1547 | the <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-SRC_URI" target="_top"><code class="filename">SRC_URI</code></a> | ||
| 1548 | variable and the argument's prefix to determine the correct | ||
| 1549 | fetcher module. | ||
| 1550 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> | ||
| 1551 | For information on how to have the OpenEmbedded build system | ||
| 1552 | generate tarballs for Git repositories and place them in the | ||
| 1553 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-DL_DIR" target="_top"><code class="filename">DL_DIR</code></a> | ||
| 1554 | directory, see the | ||
| 1555 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-BB_GENERATE_MIRROR_TARBALLS" target="_top"><code class="filename">BB_GENERATE_MIRROR_TARBALLS</code></a> | ||
| 1556 | variable. | ||
| 1557 | </div><p> | ||
| 1558 | When fetching a repository, BitBake uses the | ||
| 1559 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-SRCREV" target="_top"><code class="filename">SRCREV</code></a> | ||
| 1560 | variable to determine the specific revision from which to | ||
| 1561 | build. | ||
| 1562 | </p></div><div class="section" title="2.8.3.4. Source Mirror(s)"><div class="titlepage"><div><div><h4 class="title" id="source-mirrors">2.8.3.4. Source Mirror(s)<span class="permalink"><a alt="Permalink" title="Permalink" href="#source-mirrors">¶</a></span></h4></div></div></div><p> | ||
| 1563 | Two kinds of mirrors exist: pre-mirrors and regular mirrors. | ||
| 1564 | The | ||
| 1565 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-PREMIRRORS" target="_top"><code class="filename">PREMIRRORS</code></a> | ||
| 1566 | and | ||
| 1567 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-MIRRORS" target="_top"><code class="filename">MIRRORS</code></a> | ||
| 1568 | variables point to these, respectively. | ||
| 1569 | BitBake checks pre-mirrors before looking upstream for any | ||
| 1570 | source files. | ||
| 1571 | Pre-mirrors are appropriate when you have a shared directory | ||
| 1572 | that is not a directory defined by the | ||
| 1573 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-DL_DIR" target="_top"><code class="filename">DL_DIR</code></a> | ||
| 1574 | variable. | ||
| 1575 | A Pre-mirror typically points to a shared directory that is | ||
| 1576 | local to your organization. | ||
| 1577 | </p><p> | ||
| 1578 | Regular mirrors can be any site across the Internet that is | ||
| 1579 | used as an alternative location for source code should the | ||
| 1580 | primary site not be functioning for some reason or another. | ||
| 1581 | </p></div></div><div class="section" title="2.8.4. Package Feeds"><div class="titlepage"><div><div><h3 class="title" id="package-feeds-dev-environment">2.8.4. Package Feeds<span class="permalink"><a alt="Permalink" title="Permalink" href="#package-feeds-dev-environment">¶</a></span></h3></div></div></div><p> | ||
| 1582 | When the OpenEmbedded build system generates an image or an SDK, | ||
| 1583 | it gets the packages from a package feed area located in the | ||
| 1584 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#build-directory" target="_top">Build Directory</a>. | ||
| 1585 | The | ||
| 1586 | <a class="link" href="#general-yocto-environment-figure">general Yocto Project Development Environment figure</a> | ||
| 1587 | shows this package feeds area in the upper-right corner. | ||
| 1588 | </p><p> | ||
| 1589 | This section looks a little closer into the package feeds area used | ||
| 1590 | by the build system. | ||
| 1591 | Here is a more detailed look at the area: | ||
| 1592 | </p><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="630"><tr style="height: 540px"><td align="center"><img src="figures/package-feeds.png" align="middle" width="630" /></td></tr></table><p> | ||
| 1593 | </p><p> | ||
| 1594 | Package feeds are an intermediary step in the build process. | ||
| 1595 | The OpenEmbedded build system provides classes to generate | ||
| 1596 | different package types, and you specify which classes to enable | ||
| 1597 | through the | ||
| 1598 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-PACKAGE_CLASSES" target="_top"><code class="filename">PACKAGE_CLASSES</code></a> | ||
| 1599 | variable. | ||
| 1600 | Before placing the packages into package feeds, | ||
| 1601 | the build process validates them with generated output quality | ||
| 1602 | assurance checks through the | ||
| 1603 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-classes-insane" target="_top"><code class="filename">insane</code></a> | ||
| 1604 | class. | ||
| 1605 | </p><p> | ||
| 1606 | The package feed area resides in the Build Directory. | ||
| 1607 | The directory the build system uses to temporarily store packages | ||
| 1608 | is determined by a combination of variables and the particular | ||
| 1609 | package manager in use. | ||
| 1610 | See the "Package Feeds" box in the illustration and note the | ||
| 1611 | information to the right of that area. | ||
| 1612 | In particular, the following defines where package files are | ||
| 1613 | kept: | ||
| 1614 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-DEPLOY_DIR" target="_top"><code class="filename">DEPLOY_DIR</code></a>: | ||
| 1615 | Defined as <code class="filename">tmp/deploy</code> in the Build | ||
| 1616 | Directory. | ||
| 1617 | </p></li><li class="listitem"><p><code class="filename">DEPLOY_DIR_*</code>: | ||
| 1618 | Depending on the package manager used, the package type | ||
| 1619 | sub-folder. | ||
| 1620 | Given RPM, IPK, or DEB packaging and tarball creation, the | ||
| 1621 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-DEPLOY_DIR_RPM" target="_top"><code class="filename">DEPLOY_DIR_RPM</code></a>, | ||
| 1622 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-DEPLOY_DIR_IPK" target="_top"><code class="filename">DEPLOY_DIR_IPK</code></a>, | ||
| 1623 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-DEPLOY_DIR_DEB" target="_top"><code class="filename">DEPLOY_DIR_DEB</code></a>, | ||
| 1624 | or | ||
| 1625 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-DEPLOY_DIR_TAR" target="_top"><code class="filename">DEPLOY_DIR_TAR</code></a>, | ||
| 1626 | variables are used, respectively. | ||
| 1627 | </p></li><li class="listitem"><p><a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-PACKAGE_ARCH" target="_top"><code class="filename">PACKAGE_ARCH</code></a>: | ||
| 1628 | Defines architecture-specific sub-folders. | ||
| 1629 | For example, packages could exist for the i586 or qemux86 | ||
| 1630 | architectures. | ||
| 1631 | </p></li></ul></div><p> | ||
| 1632 | </p><p> | ||
| 1633 | BitBake uses the <code class="filename">do_package_write_*</code> tasks to | ||
| 1634 | generate packages and place them into the package holding area (e.g. | ||
| 1635 | <code class="filename">do_package_write_ipk</code> for IPK packages). | ||
| 1636 | See the | ||
| 1637 | "<a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-tasks-package_write_deb" target="_top"><code class="filename">do_package_write_deb</code></a>", | ||
| 1638 | "<a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-tasks-package_write_ipk" target="_top"><code class="filename">do_package_write_ipk</code></a>", | ||
| 1639 | "<a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-tasks-package_write_rpm" target="_top"><code class="filename">do_package_write_rpm</code></a>", | ||
| 1640 | and | ||
| 1641 | "<a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-tasks-package_write_tar" target="_top"><code class="filename">do_package_write_tar</code></a>" | ||
| 1642 | sections for additional information. | ||
| 1643 | As an example, consider a scenario where an IPK packaging manager | ||
| 1644 | is being used and package architecture support for both i586 | ||
| 1645 | and qemux86 exist. | ||
| 1646 | Packages for the i586 architecture are placed in | ||
| 1647 | <code class="filename">build/tmp/deploy/ipk/i586</code>, while packages for | ||
| 1648 | the qemux86 architecture are placed in | ||
| 1649 | <code class="filename">build/tmp/deploy/ipk/qemux86</code>. | ||
| 1650 | </p></div><div class="section" title="2.8.5. BitBake"><div class="titlepage"><div><div><h3 class="title" id="bitbake-dev-environment">2.8.5. BitBake<span class="permalink"><a alt="Permalink" title="Permalink" href="#bitbake-dev-environment">¶</a></span></h3></div></div></div><p> | ||
| 1651 | The OpenEmbedded build system uses | ||
| 1652 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#bitbake-term" target="_top">BitBake</a> | ||
| 1653 | to produce images. | ||
| 1654 | You can see from the | ||
| 1655 | <a class="link" href="#general-yocto-environment-figure">general Yocto Project Development Environment figure</a>, | ||
| 1656 | the BitBake area consists of several functional areas. | ||
| 1657 | This section takes a closer look at each of those areas. | ||
| 1658 | </p><p> | ||
| 1659 | Separate documentation exists for the BitBake tool. | ||
| 1660 | See the | ||
| 1661 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/bitbake-user-manual/bitbake-user-manual.html#bitbake-user-manual" target="_top">BitBake User Manual</a> | ||
| 1662 | for reference material on BitBake. | ||
| 1663 | </p><div class="section" title="2.8.5.1. Source Fetching"><div class="titlepage"><div><div><h4 class="title" id="source-fetching-dev-environment">2.8.5.1. Source Fetching<span class="permalink"><a alt="Permalink" title="Permalink" href="#source-fetching-dev-environment">¶</a></span></h4></div></div></div><p> | ||
| 1664 | The first stages of building a recipe are to fetch and unpack | ||
| 1665 | the source code: | ||
| 1666 | </p><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="585"><tr style="height: 450px"><td align="center"><img src="figures/source-fetching.png" align="middle" width="585" /></td></tr></table><p> | ||
| 1667 | </p><p> | ||
| 1668 | The | ||
| 1669 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-tasks-fetch" target="_top"><code class="filename">do_fetch</code></a> | ||
| 1670 | and | ||
| 1671 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-tasks-unpack" target="_top"><code class="filename">do_unpack</code></a> | ||
| 1672 | tasks fetch the source files and unpack them into the work | ||
| 1673 | directory. | ||
| 1674 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> | ||
| 1675 | For every local file (e.g. <code class="filename">file://</code>) | ||
| 1676 | that is part of a recipe's | ||
| 1677 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-SRC_URI" target="_top"><code class="filename">SRC_URI</code></a> | ||
| 1678 | statement, the OpenEmbedded build system takes a checksum | ||
| 1679 | of the file for the recipe and inserts the checksum into | ||
| 1680 | the signature for the <code class="filename">do_fetch</code>. | ||
| 1681 | If any local file has been modified, the | ||
| 1682 | <code class="filename">do_fetch</code> task and all tasks that | ||
| 1683 | depend on it are re-executed. | ||
| 1684 | </div><p> | ||
| 1685 | By default, everything is accomplished in the | ||
| 1686 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#build-directory" target="_top">Build Directory</a>, | ||
| 1687 | which has a defined structure. | ||
| 1688 | For additional general information on the Build Directory, | ||
| 1689 | see the | ||
| 1690 | "<a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#structure-core-build" target="_top"><code class="filename">build/</code></a>" | ||
| 1691 | section in the Yocto Project Reference Manual. | ||
| 1692 | </p><p> | ||
| 1693 | Unpacked source files are pointed to by the | ||
| 1694 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-S" target="_top"><code class="filename">S</code></a> | ||
| 1695 | variable. | ||
| 1696 | Each recipe has an area in the Build Directory where the | ||
| 1697 | unpacked source code resides. | ||
| 1698 | The name of that directory for any given recipe is defined from | ||
| 1699 | several different variables. | ||
| 1700 | You can see the variables that define these directories | ||
| 1701 | by looking at the figure: | ||
| 1702 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-TMPDIR" target="_top"><code class="filename">TMPDIR</code></a> - | ||
| 1703 | The base directory where the OpenEmbedded build system | ||
| 1704 | performs all its work during the build. | ||
| 1705 | </p></li><li class="listitem"><p><a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-PACKAGE_ARCH" target="_top"><code class="filename">PACKAGE_ARCH</code></a> - | ||
| 1706 | The architecture of the built package or packages. | ||
| 1707 | </p></li><li class="listitem"><p><a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-TARGET_OS" target="_top"><code class="filename">TARGET_OS</code></a> - | ||
| 1708 | The operating system of the target device. | ||
| 1709 | </p></li><li class="listitem"><p><a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-PN" target="_top"><code class="filename">PN</code></a> - | ||
| 1710 | The name of the built package. | ||
| 1711 | </p></li><li class="listitem"><p><a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-PV" target="_top"><code class="filename">PV</code></a> - | ||
| 1712 | The version of the recipe used to build the package. | ||
| 1713 | </p></li><li class="listitem"><p><a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-PR" target="_top"><code class="filename">PR</code></a> - | ||
| 1714 | The revision of the recipe used to build the package. | ||
| 1715 | </p></li><li class="listitem"><p><a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-WORKDIR" target="_top"><code class="filename">WORKDIR</code></a> - | ||
| 1716 | The location within <code class="filename">TMPDIR</code> where | ||
| 1717 | a specific package is built. | ||
| 1718 | </p></li><li class="listitem"><p><a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-S" target="_top"><code class="filename">S</code></a> - | ||
| 1719 | Contains the unpacked source files for a given recipe. | ||
| 1720 | </p></li></ul></div><p> | ||
| 1721 | </p></div><div class="section" title="2.8.5.2. Patching"><div class="titlepage"><div><div><h4 class="title" id="patching-dev-environment">2.8.5.2. Patching<span class="permalink"><a alt="Permalink" title="Permalink" href="#patching-dev-environment">¶</a></span></h4></div></div></div><p> | ||
| 1722 | Once source code is fetched and unpacked, BitBake locates | ||
| 1723 | patch files and applies them to the source files: | ||
| 1724 | </p><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="540"><tr style="height: 450px"><td align="center"><img src="figures/patching.png" align="middle" width="540" /></td></tr></table><p> | ||
| 1725 | </p><p> | ||
| 1726 | The | ||
| 1727 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-tasks-patch" target="_top"><code class="filename">do_patch</code></a> | ||
| 1728 | task processes recipes by | ||
| 1729 | using the | ||
| 1730 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-SRC_URI" target="_top"><code class="filename">SRC_URI</code></a> | ||
| 1731 | variable to locate applicable patch files, which by default | ||
| 1732 | are <code class="filename">*.patch</code> or | ||
| 1733 | <code class="filename">*.diff</code> files, or any file if | ||
| 1734 | "apply=yes" is specified for the file in | ||
| 1735 | <code class="filename">SRC_URI</code>. | ||
| 1736 | </p><p> | ||
| 1737 | BitBake finds and applies multiple patches for a single recipe | ||
| 1738 | in the order in which it finds the patches. | ||
| 1739 | Patches are applied to the recipe's source files located in the | ||
| 1740 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-S" target="_top"><code class="filename">S</code></a> | ||
| 1741 | directory. | ||
| 1742 | </p><p> | ||
| 1743 | For more information on how the source directories are | ||
| 1744 | created, see the | ||
| 1745 | "<a class="link" href="#source-fetching-dev-environment" title="2.8.5.1. Source Fetching">Source Fetching</a>" | ||
| 1746 | section. | ||
| 1747 | </p></div><div class="section" title="2.8.5.3. Configuration and Compilation"><div class="titlepage"><div><div><h4 class="title" id="configuration-and-compilation-dev-environment">2.8.5.3. Configuration and Compilation<span class="permalink"><a alt="Permalink" title="Permalink" href="#configuration-and-compilation-dev-environment">¶</a></span></h4></div></div></div><p> | ||
| 1748 | After source code is patched, BitBake executes tasks that | ||
| 1749 | configure and compile the source code: | ||
| 1750 | </p><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="630"><tr style="height: 450px"><td align="center"><img src="figures/configuration-compile-autoreconf.png" align="middle" width="630" /></td></tr></table><p> | ||
| 1751 | </p><p> | ||
| 1752 | This step in the build process consists of three tasks: | ||
| 1753 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> | ||
| 1754 | <span class="emphasis"><em><a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-tasks-prepare_recipe_sysroot" target="_top"><code class="filename">do_prepare_recipe_sysroot</code></a>:</em></span> | ||
| 1755 | This task sets up the two sysroots in | ||
| 1756 | <code class="filename">${</code><a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-WORKDIR" target="_top"><code class="filename">WORKDIR</code></a><code class="filename">}</code> | ||
| 1757 | (i.e. <code class="filename">recipe-sysroot</code> and | ||
| 1758 | <code class="filename">recipe-sysroot-native</code>) so that | ||
| 1759 | the sysroots contain the contents of the | ||
| 1760 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-tasks-populate_sysroot" target="_top"><code class="filename">do_populate_sysroot</code></a> | ||
| 1761 | tasks of the recipes on which the recipe | ||
| 1762 | containing the tasks depends. | ||
| 1763 | A sysroot exists for both the target and for the native | ||
| 1764 | binaries, which run on the host system. | ||
| 1765 | </p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">do_configure</code>:</em></span> | ||
| 1766 | This task configures the source by enabling and | ||
| 1767 | disabling any build-time and configuration options for | ||
| 1768 | the software being built. | ||
| 1769 | Configurations can come from the recipe itself as well | ||
| 1770 | as from an inherited class. | ||
| 1771 | Additionally, the software itself might configure itself | ||
| 1772 | depending on the target for which it is being built. | ||
| 1773 | </p><p>The configurations handled by the | ||
| 1774 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-tasks-configure" target="_top"><code class="filename">do_configure</code></a> | ||
| 1775 | task are specific | ||
| 1776 | to source code configuration for the source code | ||
| 1777 | being built by the recipe.</p><p>If you are using the | ||
| 1778 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-classes-autotools" target="_top"><code class="filename">autotools</code></a> | ||
| 1779 | class, | ||
| 1780 | you can add additional configuration options by using | ||
| 1781 | the | ||
| 1782 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-EXTRA_OECONF" target="_top"><code class="filename">EXTRA_OECONF</code></a> | ||
| 1783 | or | ||
| 1784 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-PACKAGECONFIG_CONFARGS" target="_top"><code class="filename">PACKAGECONFIG_CONFARGS</code></a> | ||
| 1785 | variables. | ||
| 1786 | For information on how this variable works within | ||
| 1787 | that class, see the | ||
| 1788 | <code class="filename">meta/classes/autotools.bbclass</code> file. | ||
| 1789 | </p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">do_compile</code>:</em></span> | ||
| 1790 | Once a configuration task has been satisfied, BitBake | ||
| 1791 | compiles the source using the | ||
| 1792 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-tasks-compile" target="_top"><code class="filename">do_compile</code></a> | ||
| 1793 | task. | ||
| 1794 | Compilation occurs in the directory pointed to by the | ||
| 1795 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-B" target="_top"><code class="filename">B</code></a> | ||
| 1796 | variable. | ||
| 1797 | Realize that the <code class="filename">B</code> directory is, by | ||
| 1798 | default, the same as the | ||
| 1799 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-S" target="_top"><code class="filename">S</code></a> | ||
| 1800 | directory.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">do_install</code>:</em></span> | ||
| 1801 | Once compilation is done, BitBake executes the | ||
| 1802 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-tasks-install" target="_top"><code class="filename">do_install</code></a> | ||
| 1803 | task. | ||
| 1804 | This task copies files from the <code class="filename">B</code> | ||
| 1805 | directory and places them in a holding area pointed to | ||
| 1806 | by the | ||
| 1807 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-D" target="_top"><code class="filename">D</code></a> | ||
| 1808 | variable.</p></li></ul></div><p> | ||
| 1809 | </p></div><div class="section" title="2.8.5.4. Package Splitting"><div class="titlepage"><div><div><h4 class="title" id="package-splitting-dev-environment">2.8.5.4. Package Splitting<span class="permalink"><a alt="Permalink" title="Permalink" href="#package-splitting-dev-environment">¶</a></span></h4></div></div></div><p> | ||
| 1810 | After source code is configured and compiled, the | ||
| 1811 | OpenEmbedded build system analyzes | ||
| 1812 | the results and splits the output into packages: | ||
| 1813 | </p><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="630"><tr style="height: 630px"><td align="center"><img src="figures/analysis-for-package-splitting.png" align="middle" width="630" /></td></tr></table><p> | ||
| 1814 | </p><p> | ||
| 1815 | The | ||
| 1816 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-tasks-package" target="_top"><code class="filename">do_package</code></a> | ||
| 1817 | and | ||
| 1818 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-tasks-packagedata" target="_top"><code class="filename">do_packagedata</code></a> | ||
| 1819 | tasks combine to analyze | ||
| 1820 | the files found in the | ||
| 1821 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-D" target="_top"><code class="filename">D</code></a> directory | ||
| 1822 | and split them into subsets based on available packages and | ||
| 1823 | files. | ||
| 1824 | The analyzing process involves the following as well as other | ||
| 1825 | items: splitting out debugging symbols, | ||
| 1826 | looking at shared library dependencies between packages, | ||
| 1827 | and looking at package relationships. | ||
| 1828 | The <code class="filename">do_packagedata</code> task creates package | ||
| 1829 | metadata based on the analysis such that the | ||
| 1830 | OpenEmbedded build system can generate the final packages. | ||
| 1831 | Working, staged, and intermediate results of the analysis | ||
| 1832 | and package splitting process use these areas: | ||
| 1833 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-PKGD" target="_top"><code class="filename">PKGD</code></a> - | ||
| 1834 | The destination directory for packages before they are | ||
| 1835 | split. | ||
| 1836 | </p></li><li class="listitem"><p><a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-PKGDATA_DIR" target="_top"><code class="filename">PKGDATA_DIR</code></a> - | ||
| 1837 | A shared, global-state directory that holds data | ||
| 1838 | generated during the packaging process. | ||
| 1839 | </p></li><li class="listitem"><p><a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-PKGDESTWORK" target="_top"><code class="filename">PKGDESTWORK</code></a> - | ||
| 1840 | A temporary work area used by the | ||
| 1841 | <code class="filename">do_package</code> task. | ||
| 1842 | </p></li><li class="listitem"><p><a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-PKGDEST" target="_top"><code class="filename">PKGDEST</code></a> - | ||
| 1843 | The parent directory for packages after they have | ||
| 1844 | been split. | ||
| 1845 | </p></li></ul></div><p> | ||
| 1846 | The <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-FILES" target="_top"><code class="filename">FILES</code></a> | ||
| 1847 | variable defines the files that go into each package in | ||
| 1848 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-PACKAGES" target="_top"><code class="filename">PACKAGES</code></a>. | ||
| 1849 | If you want details on how this is accomplished, you can | ||
| 1850 | look at the | ||
| 1851 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-classes-package" target="_top"><code class="filename">package</code></a> | ||
| 1852 | class. | ||
| 1853 | </p><p> | ||
| 1854 | Depending on the type of packages being created (RPM, DEB, or | ||
| 1855 | IPK), the <code class="filename">do_package_write_*</code> task | ||
| 1856 | creates the actual packages and places them in the | ||
| 1857 | Package Feed area, which is | ||
| 1858 | <code class="filename">${TMPDIR}/deploy</code>. | ||
| 1859 | You can see the | ||
| 1860 | "<a class="link" href="#package-feeds-dev-environment" title="2.8.4. Package Feeds">Package Feeds</a>" | ||
| 1861 | section for more detail on that part of the build process. | ||
| 1862 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> | ||
| 1863 | Support for creating feeds directly from the | ||
| 1864 | <code class="filename">deploy/*</code> directories does not exist. | ||
| 1865 | Creating such feeds usually requires some kind of feed | ||
| 1866 | maintenance mechanism that would upload the new packages | ||
| 1867 | into an official package feed (e.g. the | ||
| 1868 | Ångström distribution). | ||
| 1869 | This functionality is highly distribution-specific | ||
| 1870 | and thus is not provided out of the box. | ||
| 1871 | </div><p> | ||
| 1872 | </p></div><div class="section" title="2.8.5.5. Image Generation"><div class="titlepage"><div><div><h4 class="title" id="image-generation-dev-environment">2.8.5.5. Image Generation<span class="permalink"><a alt="Permalink" title="Permalink" href="#image-generation-dev-environment">¶</a></span></h4></div></div></div><p> | ||
| 1873 | Once packages are split and stored in the Package Feeds area, | ||
| 1874 | the OpenEmbedded build system uses BitBake to generate the | ||
| 1875 | root filesystem image: | ||
| 1876 | </p><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="540"><tr style="height: 630px"><td align="center"><img src="figures/image-generation.png" align="middle" width="540" /></td></tr></table><p> | ||
| 1877 | </p><p> | ||
| 1878 | The image generation process consists of several stages and | ||
| 1879 | depends on several tasks and variables. | ||
| 1880 | The | ||
| 1881 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-tasks-rootfs" target="_top"><code class="filename">do_rootfs</code></a> | ||
| 1882 | task creates the root filesystem (file and directory structure) | ||
| 1883 | for an image. | ||
| 1884 | This task uses several key variables to help create the list | ||
| 1885 | of packages to actually install: | ||
| 1886 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-IMAGE_INSTALL" target="_top"><code class="filename">IMAGE_INSTALL</code></a>: | ||
| 1887 | Lists out the base set of packages to install from | ||
| 1888 | the Package Feeds area.</p></li><li class="listitem"><p><a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-PACKAGE_EXCLUDE" target="_top"><code class="filename">PACKAGE_EXCLUDE</code></a>: | ||
| 1889 | Specifies packages that should not be installed. | ||
| 1890 | </p></li><li class="listitem"><p><a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-IMAGE_FEATURES" target="_top"><code class="filename">IMAGE_FEATURES</code></a>: | ||
| 1891 | Specifies features to include in the image. | ||
| 1892 | Most of these features map to additional packages for | ||
| 1893 | installation.</p></li><li class="listitem"><p><a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-PACKAGE_CLASSES" target="_top"><code class="filename">PACKAGE_CLASSES</code></a>: | ||
| 1894 | Specifies the package backend to use and consequently | ||
| 1895 | helps determine where to locate packages within the | ||
| 1896 | Package Feeds area.</p></li><li class="listitem"><p><a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-IMAGE_LINGUAS" target="_top"><code class="filename">IMAGE_LINGUAS</code></a>: | ||
| 1897 | Determines the language(s) for which additional | ||
| 1898 | language support packages are installed. | ||
| 1899 | </p></li><li class="listitem"><p><a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-PACKAGE_INSTALL" target="_top"><code class="filename">PACKAGE_INSTALL</code></a>: | ||
| 1900 | The final list of packages passed to the package manager | ||
| 1901 | for installation into the image. | ||
| 1902 | </p></li></ul></div><p> | ||
| 1903 | </p><p> | ||
| 1904 | With | ||
| 1905 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-IMAGE_ROOTFS" target="_top"><code class="filename">IMAGE_ROOTFS</code></a> | ||
| 1906 | pointing to the location of the filesystem under construction and | ||
| 1907 | the <code class="filename">PACKAGE_INSTALL</code> variable providing the | ||
| 1908 | final list of packages to install, the root file system is | ||
| 1909 | created. | ||
| 1910 | </p><p> | ||
| 1911 | Package installation is under control of the package manager | ||
| 1912 | (e.g. dnf/rpm, opkg, or apt/dpkg) regardless of whether or | ||
| 1913 | not package management is enabled for the target. | ||
| 1914 | At the end of the process, if package management is not | ||
| 1915 | enabled for the target, the package manager's data files | ||
| 1916 | are deleted from the root filesystem. | ||
| 1917 | As part of the final stage of package installation, postinstall | ||
| 1918 | scripts that are part of the packages are run. | ||
| 1919 | Any scripts that fail to run | ||
| 1920 | on the build host are run on the target when the target system | ||
| 1921 | is first booted. | ||
| 1922 | If you are using a | ||
| 1923 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/dev-manual/dev-manual.html#creating-a-read-only-root-filesystem" target="_top">read-only root filesystem</a>, | ||
| 1924 | all the post installation scripts must succeed during the | ||
| 1925 | package installation phase since the root filesystem is | ||
| 1926 | read-only. | ||
| 1927 | </p><p> | ||
| 1928 | The final stages of the <code class="filename">do_rootfs</code> task | ||
| 1929 | handle post processing. | ||
| 1930 | Post processing includes creation of a manifest file and | ||
| 1931 | optimizations. | ||
| 1932 | </p><p> | ||
| 1933 | The manifest file (<code class="filename">.manifest</code>) resides | ||
| 1934 | in the same directory as the root filesystem image. | ||
| 1935 | This file lists out, line-by-line, the installed packages. | ||
| 1936 | The manifest file is useful for the | ||
| 1937 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-classes-testimage*" target="_top"><code class="filename">testimage</code></a> | ||
| 1938 | class, for example, to determine whether or not to run | ||
| 1939 | specific tests. | ||
| 1940 | See the | ||
| 1941 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-IMAGE_MANIFEST" target="_top"><code class="filename">IMAGE_MANIFEST</code></a> | ||
| 1942 | variable for additional information. | ||
| 1943 | </p><p> | ||
| 1944 | Optimizing processes run across the image include | ||
| 1945 | <code class="filename">mklibs</code>, <code class="filename">prelink</code>, | ||
| 1946 | and any other post-processing commands as defined by the | ||
| 1947 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-ROOTFS_POSTPROCESS_COMMAND" target="_top"><code class="filename">ROOTFS_POSTPROCESS_COMMAND</code></a> | ||
| 1948 | variable. | ||
| 1949 | The <code class="filename">mklibs</code> process optimizes the size | ||
| 1950 | of the libraries, while the | ||
| 1951 | <code class="filename">prelink</code> process optimizes the dynamic | ||
| 1952 | linking of shared libraries to reduce start up time of | ||
| 1953 | executables. | ||
| 1954 | </p><p> | ||
| 1955 | After the root filesystem is built, processing begins on | ||
| 1956 | the image through the | ||
| 1957 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-tasks-image" target="_top"><code class="filename">do_image</code></a> | ||
| 1958 | task. | ||
| 1959 | The build system runs any pre-processing commands as defined | ||
| 1960 | by the | ||
| 1961 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-IMAGE_PREPROCESS_COMMAND" target="_top"><code class="filename">IMAGE_PREPROCESS_COMMAND</code></a> | ||
| 1962 | variable. | ||
| 1963 | This variable specifies a list of functions to call before | ||
| 1964 | the OpenEmbedded build system creates the final image output | ||
| 1965 | files. | ||
| 1966 | </p><p> | ||
| 1967 | The OpenEmbedded build system dynamically creates | ||
| 1968 | <code class="filename">do_image_*</code> tasks as needed, based | ||
| 1969 | on the image types specified in the | ||
| 1970 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-IMAGE_FSTYPES" target="_top"><code class="filename">IMAGE_FSTYPES</code></a> | ||
| 1971 | variable. | ||
| 1972 | The process turns everything into an image file or a set of | ||
| 1973 | image files and compresses the root filesystem image to reduce | ||
| 1974 | the overall size of the image. | ||
| 1975 | The formats used for the root filesystem depend on the | ||
| 1976 | <code class="filename">IMAGE_FSTYPES</code> variable. | ||
| 1977 | </p><p> | ||
| 1978 | As an example, a dynamically created task when creating a | ||
| 1979 | particular image <em class="replaceable"><code>type</code></em> would take the | ||
| 1980 | following form: | ||
| 1981 | </p><pre class="literallayout"> | ||
| 1982 | do_image_<em class="replaceable"><code>type</code></em>[depends] | ||
| 1983 | </pre><p> | ||
| 1984 | So, if the <em class="replaceable"><code>type</code></em> as specified by the | ||
| 1985 | <code class="filename">IMAGE_FSTYPES</code> were | ||
| 1986 | <code class="filename">ext4</code>, the dynamically generated task | ||
| 1987 | would be as follows: | ||
| 1988 | </p><pre class="literallayout"> | ||
| 1989 | do_image_ext4[depends] | ||
| 1990 | </pre><p> | ||
| 1991 | </p><p> | ||
| 1992 | The final task involved in image creation is the | ||
| 1993 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-tasks-image-complete" target="_top"><code class="filename">do_image_complete</code></a> | ||
| 1994 | task. | ||
| 1995 | This task completes the image by applying any image | ||
| 1996 | post processing as defined through the | ||
| 1997 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-IMAGE_POSTPROCESS_COMMAND" target="_top"><code class="filename">IMAGE_POSTPROCESS_COMMAND</code></a> | ||
| 1998 | variable. | ||
| 1999 | The variable specifies a list of functions to call once the | ||
| 2000 | OpenEmbedded build system has created the final image output | ||
| 2001 | files. | ||
| 2002 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> | ||
| 2003 | The entire image generation process is run under Pseudo. | ||
| 2004 | Running under Pseudo ensures that the files in the root | ||
| 2005 | filesystem have correct ownership. | ||
| 2006 | </div></div><div class="section" title="2.8.5.6. SDK Generation"><div class="titlepage"><div><div><h4 class="title" id="sdk-generation-dev-environment">2.8.5.6. SDK Generation<span class="permalink"><a alt="Permalink" title="Permalink" href="#sdk-generation-dev-environment">¶</a></span></h4></div></div></div><p> | ||
| 2007 | The OpenEmbedded build system uses BitBake to generate the | ||
| 2008 | Software Development Kit (SDK) installer script for both the | ||
| 2009 | standard and extensible SDKs: | ||
| 2010 | <img src="figures/sdk-generation.png" align="middle" /> | ||
| 2011 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> | ||
| 2012 | For more information on the cross-development toolchain | ||
| 2013 | generation, see the | ||
| 2014 | "<a class="link" href="#cross-development-toolchain-generation" title="3.2. Cross-Development Toolchain Generation">Cross-Development Toolchain Generation</a>" | ||
| 2015 | section. | ||
| 2016 | For information on advantages gained when building a | ||
| 2017 | cross-development toolchain using the | ||
| 2018 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-tasks-populate_sdk" target="_top"><code class="filename">do_populate_sdk</code></a> | ||
| 2019 | task, see the | ||
| 2020 | "<a class="ulink" href="http://www.yoctoproject.org/docs/2.5/sdk-manual/sdk-manual.html#sdk-building-an-sdk-installer" target="_top">Building an SDK Installer</a>" | ||
| 2021 | section in the Yocto Project Application Development and the | ||
| 2022 | Extensible Software Development Kit (SDK) manual. | ||
| 2023 | </div><p> | ||
| 2024 | Like image generation, the SDK script process consists of | ||
| 2025 | several stages and depends on many variables. | ||
| 2026 | The <code class="filename">do_populate_sdk</code> and | ||
| 2027 | <code class="filename">do_populate_sdk_ext</code> tasks use these | ||
| 2028 | key variables to help create the list of packages to actually | ||
| 2029 | install. | ||
| 2030 | For information on the variables listed in the figure, see the | ||
| 2031 | "<a class="link" href="#sdk-dev-environment" title="2.8.7. Application Development SDK">Application Development SDK</a>" | ||
| 2032 | section. | ||
| 2033 | </p><p> | ||
| 2034 | The <code class="filename">do_populate_sdk</code> task helps create | ||
| 2035 | the standard SDK and handles two parts: a target part and a | ||
| 2036 | host part. | ||
| 2037 | The target part is the part built for the target hardware and | ||
| 2038 | includes libraries and headers. | ||
| 2039 | The host part is the part of the SDK that runs on the | ||
| 2040 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-SDKMACHINE" target="_top"><code class="filename">SDKMACHINE</code></a>. | ||
| 2041 | </p><p> | ||
| 2042 | The <code class="filename">do_populate_sdk_ext</code> task helps create | ||
| 2043 | the extensible SDK and handles host and target parts | ||
| 2044 | differently than its counter part does for the standard SDK. | ||
| 2045 | For the extensible SDK, the task encapsulates the build system, | ||
| 2046 | which includes everything needed (host and target) for the SDK. | ||
| 2047 | </p><p> | ||
| 2048 | Regardless of the type of SDK being constructed, the | ||
| 2049 | tasks perform some cleanup after which a cross-development | ||
| 2050 | environment setup script and any needed configuration files | ||
| 2051 | are created. | ||
| 2052 | The final output is the Cross-development | ||
| 2053 | toolchain installation script (<code class="filename">.sh</code> file), | ||
| 2054 | which includes the environment setup script. | ||
| 2055 | </p></div><div class="section" title="2.8.5.7. Stamp Files and the Rerunning of Tasks"><div class="titlepage"><div><div><h4 class="title" id="stamp-files-and-the-rerunning-of-tasks">2.8.5.7. Stamp Files and the Rerunning of Tasks<span class="permalink"><a alt="Permalink" title="Permalink" href="#stamp-files-and-the-rerunning-of-tasks">¶</a></span></h4></div></div></div><p> | ||
| 2056 | For each task that completes successfully, BitBake writes a | ||
| 2057 | stamp file into the | ||
| 2058 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-STAMPS_DIR" target="_top"><code class="filename">STAMPS_DIR</code></a> | ||
| 2059 | directory. | ||
| 2060 | The beginning of the stamp file's filename is determined by the | ||
| 2061 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-STAMP" target="_top"><code class="filename">STAMP</code></a> | ||
| 2062 | variable, and the end of the name consists of the task's name | ||
| 2063 | and current | ||
| 2064 | <a class="link" href="#overview-checksums" title="3.3.2. Checksums (Signatures)">input checksum</a>. | ||
| 2065 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> | ||
| 2066 | This naming scheme assumes that | ||
| 2067 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/bitbake-user-manual/bitbake-user-manual.html#var-BB_SIGNATURE_HANDLER" target="_top"><code class="filename">BB_SIGNATURE_HANDLER</code></a> | ||
| 2068 | is "OEBasicHash", which is almost always the case in | ||
| 2069 | current OpenEmbedded. | ||
| 2070 | </div><p> | ||
| 2071 | To determine if a task needs to be rerun, BitBake checks if a | ||
| 2072 | stamp file with a matching input checksum exists for the task. | ||
| 2073 | If such a stamp file exists, the task's output is assumed to | ||
| 2074 | exist and still be valid. | ||
| 2075 | If the file does not exist, the task is rerun. | ||
| 2076 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>The stamp mechanism is more general than the shared | ||
| 2077 | state (sstate) cache mechanism described in the | ||
| 2078 | "<a class="link" href="#setscene-tasks-and-shared-state" title="2.8.5.8. Setscene Tasks and Shared State">Setscene Tasks and Shared State</a>" | ||
| 2079 | section. | ||
| 2080 | BitBake avoids rerunning any task that has a valid | ||
| 2081 | stamp file, not just tasks that can be accelerated through | ||
| 2082 | the sstate cache.</p><p>However, you should realize that stamp files only | ||
| 2083 | serve as a marker that some work has been done and that | ||
| 2084 | these files do not record task output. | ||
| 2085 | The actual task output would usually be somewhere in | ||
| 2086 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-TMPDIR" target="_top"><code class="filename">TMPDIR</code></a> | ||
| 2087 | (e.g. in some recipe's | ||
| 2088 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-WORKDIR" target="_top"><code class="filename">WORKDIR</code></a>.) | ||
| 2089 | What the sstate cache mechanism adds is a way to cache task | ||
| 2090 | output that can then be shared between build machines. | ||
| 2091 | </p></div><p> | ||
| 2092 | Since <code class="filename">STAMPS_DIR</code> is usually a subdirectory | ||
| 2093 | of <code class="filename">TMPDIR</code>, removing | ||
| 2094 | <code class="filename">TMPDIR</code> will also remove | ||
| 2095 | <code class="filename">STAMPS_DIR</code>, which means tasks will | ||
| 2096 | properly be rerun to repopulate <code class="filename">TMPDIR</code>. | ||
| 2097 | </p><p> | ||
| 2098 | If you want some task to always be considered "out of date", | ||
| 2099 | you can mark it with the | ||
| 2100 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/bitbake-user-manual/bitbake-user-manual.html#variable-flags" target="_top"><code class="filename">nostamp</code></a> | ||
| 2101 | varflag. | ||
| 2102 | If some other task depends on such a task, then that task will | ||
| 2103 | also always be considered out of date, which might not be what | ||
| 2104 | you want. | ||
| 2105 | </p><p> | ||
| 2106 | For details on how to view information about a task's | ||
| 2107 | signature, see the | ||
| 2108 | "<a class="ulink" href="http://www.yoctoproject.org/docs/2.5/dev-manual/dev-manual.html#dev-viewing-task-variable-dependencies" target="_top">Viewing Task Variable Dependencies</a>" | ||
| 2109 | section in the Yocto Project Development Tasks Manual. | ||
| 2110 | </p></div><div class="section" title="2.8.5.8. Setscene Tasks and Shared State"><div class="titlepage"><div><div><h4 class="title" id="setscene-tasks-and-shared-state">2.8.5.8. Setscene Tasks and Shared State<span class="permalink"><a alt="Permalink" title="Permalink" href="#setscene-tasks-and-shared-state">¶</a></span></h4></div></div></div><p> | ||
| 2111 | The description of tasks so far assumes that BitBake needs to | ||
| 2112 | build everything and there are no prebuilt objects available. | ||
| 2113 | BitBake does support skipping tasks if prebuilt objects are | ||
| 2114 | available. | ||
| 2115 | These objects are usually made available in the form of a | ||
| 2116 | shared state (sstate) cache. | ||
| 2117 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> | ||
| 2118 | For information on variables affecting sstate, see the | ||
| 2119 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-SSTATE_DIR" target="_top"><code class="filename">SSTATE_DIR</code></a> | ||
| 2120 | and | ||
| 2121 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-SSTATE_MIRRORS" target="_top"><code class="filename">SSTATE_MIRRORS</code></a> | ||
| 2122 | variables. | ||
| 2123 | </div><p> | ||
| 2124 | </p><p> | ||
| 2125 | The idea of a setscene task (i.e | ||
| 2126 | <code class="filename">do_</code><em class="replaceable"><code>taskname</code></em><code class="filename">_setscene</code>) | ||
| 2127 | is a version of the task where | ||
| 2128 | instead of building something, BitBake can skip to the end | ||
| 2129 | result and simply place a set of files into specific locations | ||
| 2130 | as needed. | ||
| 2131 | In some cases, it makes sense to have a setscene task variant | ||
| 2132 | (e.g. generating package files in the | ||
| 2133 | <code class="filename">do_package_write_*</code> task). | ||
| 2134 | In other cases, it does not make sense, (e.g. a | ||
| 2135 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-tasks-patch" target="_top"><code class="filename">do_patch</code></a> | ||
| 2136 | task or | ||
| 2137 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-tasks-unpack" target="_top"><code class="filename">do_unpack</code></a> | ||
| 2138 | task) since the work involved would be equal to or greater than | ||
| 2139 | the underlying task. | ||
| 2140 | </p><p> | ||
| 2141 | In the OpenEmbedded build system, the common tasks that have | ||
| 2142 | setscene variants are | ||
| 2143 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-tasks-package" target="_top"><code class="filename">do_package</code></a>, | ||
| 2144 | <code class="filename">do_package_write_*</code>, | ||
| 2145 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-tasks-deploy" target="_top"><code class="filename">do_deploy</code></a>, | ||
| 2146 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-tasks-packagedata" target="_top"><code class="filename">do_packagedata</code></a>, | ||
| 2147 | and | ||
| 2148 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-tasks-populate_sysroot" target="_top"><code class="filename">do_populate_sysroot</code></a>. | ||
| 2149 | Notice that these are most of the tasks whose output is an | ||
| 2150 | end result. | ||
| 2151 | </p><p> | ||
| 2152 | The OpenEmbedded build system has knowledge of the relationship | ||
| 2153 | between these tasks and other tasks that precede them. | ||
| 2154 | For example, if BitBake runs | ||
| 2155 | <code class="filename">do_populate_sysroot_setscene</code> for | ||
| 2156 | something, there is little point in running any of the | ||
| 2157 | <code class="filename">do_fetch</code>, <code class="filename">do_unpack</code>, | ||
| 2158 | <code class="filename">do_patch</code>, | ||
| 2159 | <code class="filename">do_configure</code>, | ||
| 2160 | <code class="filename">do_compile</code>, and | ||
| 2161 | <code class="filename">do_install</code> tasks. | ||
| 2162 | However, if <code class="filename">do_package</code> needs to be run, | ||
| 2163 | BitBake would need to run those other tasks. | ||
| 2164 | </p><p> | ||
| 2165 | It becomes more complicated if everything can come from an | ||
| 2166 | sstate cache because some objects are simply not required at | ||
| 2167 | all. | ||
| 2168 | For example, you do not need a compiler or native tools, such | ||
| 2169 | as quilt, if there is nothing to compile or patch. | ||
| 2170 | If the <code class="filename">do_package_write_*</code> packages are | ||
| 2171 | available from sstate, BitBake does not need the | ||
| 2172 | <code class="filename">do_package</code> task data. | ||
| 2173 | </p><p> | ||
| 2174 | To handle all these complexities, BitBake runs in two phases. | ||
| 2175 | The first is the "setscene" stage. | ||
| 2176 | During this stage, BitBake first checks the sstate cache for | ||
| 2177 | any targets it is planning to build. | ||
| 2178 | BitBake does a fast check to see if the object exists rather | ||
| 2179 | than a complete download. | ||
| 2180 | If nothing exists, the second phase, which is the setscene | ||
| 2181 | stage, completes and the main build proceeds. | ||
| 2182 | </p><p> | ||
| 2183 | If objects are found in the sstate cache, the OpenEmbedded | ||
| 2184 | build system works backwards from the end targets specified | ||
| 2185 | by the user. | ||
| 2186 | For example, if an image is being built, the OpenEmbedded build | ||
| 2187 | system first looks for the packages needed for that image and | ||
| 2188 | the tools needed to construct an image. | ||
| 2189 | If those are available, the compiler is not needed. | ||
| 2190 | Thus, the compiler is not even downloaded. | ||
| 2191 | If something was found to be unavailable, or the download or | ||
| 2192 | setscene task fails, the OpenEmbedded build system then tries | ||
| 2193 | to install dependencies, such as the compiler, from the cache. | ||
| 2194 | </p><p> | ||
| 2195 | The availability of objects in the sstate cache is handled by | ||
| 2196 | the function specified by the | ||
| 2197 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/bitbake-user-manual/bitbake-user-manual.html#var-BB_HASHCHECK_FUNCTION" target="_top"><code class="filename">BB_HASHCHECK_FUNCTION</code></a> | ||
| 2198 | variable and returns a list of the objects that are available. | ||
| 2199 | The function specified by the | ||
| 2200 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/bitbake-user-manual/bitbake-user-manual.html#var-BB_SETSCENE_DEPVALID" target="_top"><code class="filename">BB_SETSCENE_DEPVALID</code></a> | ||
| 2201 | variable is the function that determines whether a given | ||
| 2202 | dependency needs to be followed, and whether for any given | ||
| 2203 | relationship the function needs to be passed. | ||
| 2204 | The function returns a True or False value. | ||
| 2205 | </p></div></div><div class="section" title="2.8.6. Images"><div class="titlepage"><div><div><h3 class="title" id="images-dev-environment">2.8.6. Images<span class="permalink"><a alt="Permalink" title="Permalink" href="#images-dev-environment">¶</a></span></h3></div></div></div><p> | ||
| 2206 | The images produced by the OpenEmbedded build system | ||
| 2207 | are compressed forms of the | ||
| 2208 | root filesystem that are ready to boot on a target device. | ||
| 2209 | You can see from the | ||
| 2210 | <a class="link" href="#general-yocto-environment-figure">general Yocto Project Development Environment figure</a> | ||
| 2211 | that BitBake output, in part, consists of images. | ||
| 2212 | This section is going to look more closely at this output: | ||
| 2213 | </p><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="495"><tr style="height: 495px"><td align="center"><img src="figures/images.png" align="middle" width="495" /></td></tr></table><p> | ||
| 2214 | </p><p> | ||
| 2215 | For a list of example images that the Yocto Project provides, | ||
| 2216 | see the | ||
| 2217 | "<a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-images" target="_top">Images</a>" | ||
| 2218 | chapter in the Yocto Project Reference Manual. | ||
| 2219 | </p><p> | ||
| 2220 | Images are written out to the | ||
| 2221 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#build-directory" target="_top">Build Directory</a> | ||
| 2222 | inside the | ||
| 2223 | <code class="filename">tmp/deploy/images/<em class="replaceable"><code>machine</code></em>/</code> | ||
| 2224 | folder as shown in the figure. | ||
| 2225 | This folder contains any files expected to be loaded on the | ||
| 2226 | target device. | ||
| 2227 | The | ||
| 2228 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-DEPLOY_DIR" target="_top"><code class="filename">DEPLOY_DIR</code></a> | ||
| 2229 | variable points to the <code class="filename">deploy</code> directory, | ||
| 2230 | while the | ||
| 2231 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-DEPLOY_DIR_IMAGE" target="_top"><code class="filename">DEPLOY_DIR_IMAGE</code></a> | ||
| 2232 | variable points to the appropriate directory containing images for | ||
| 2233 | the current configuration. | ||
| 2234 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="filename"><em class="replaceable"><code>kernel-image</code></em></code>: | ||
| 2235 | A kernel binary file. | ||
| 2236 | The | ||
| 2237 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-KERNEL_IMAGETYPE" target="_top"><code class="filename">KERNEL_IMAGETYPE</code></a> | ||
| 2238 | variable setting determines the naming scheme for the | ||
| 2239 | kernel image file. | ||
| 2240 | Depending on that variable, the file could begin with | ||
| 2241 | a variety of naming strings. | ||
| 2242 | The <code class="filename">deploy/images/<em class="replaceable"><code>machine</code></em></code> | ||
| 2243 | directory can contain multiple image files for the | ||
| 2244 | machine.</p></li><li class="listitem"><p><code class="filename"><em class="replaceable"><code>root-filesystem-image</code></em></code>: | ||
| 2245 | Root filesystems for the target device (e.g. | ||
| 2246 | <code class="filename">*.ext3</code> or <code class="filename">*.bz2</code> | ||
| 2247 | files). | ||
| 2248 | The | ||
| 2249 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-IMAGE_FSTYPES" target="_top"><code class="filename">IMAGE_FSTYPES</code></a> | ||
| 2250 | variable setting determines the root filesystem image | ||
| 2251 | type. | ||
| 2252 | The <code class="filename">deploy/images/<em class="replaceable"><code>machine</code></em></code> | ||
| 2253 | directory can contain multiple root filesystems for the | ||
| 2254 | machine.</p></li><li class="listitem"><p><code class="filename"><em class="replaceable"><code>kernel-modules</code></em></code>: | ||
| 2255 | Tarballs that contain all the modules built for the kernel. | ||
| 2256 | Kernel module tarballs exist for legacy purposes and | ||
| 2257 | can be suppressed by setting the | ||
| 2258 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-MODULE_TARBALL_DEPLOY" target="_top"><code class="filename">MODULE_TARBALL_DEPLOY</code></a> | ||
| 2259 | variable to "0". | ||
| 2260 | The <code class="filename">deploy/images/<em class="replaceable"><code>machine</code></em></code> | ||
| 2261 | directory can contain multiple kernel module tarballs | ||
| 2262 | for the machine.</p></li><li class="listitem"><p><code class="filename"><em class="replaceable"><code>bootloaders</code></em></code>: | ||
| 2263 | Bootloaders supporting the image, if applicable to the | ||
| 2264 | target machine. | ||
| 2265 | The <code class="filename">deploy/images/<em class="replaceable"><code>machine</code></em></code> | ||
| 2266 | directory can contain multiple bootloaders for the | ||
| 2267 | machine.</p></li><li class="listitem"><p><code class="filename"><em class="replaceable"><code>symlinks</code></em></code>: | ||
| 2268 | The <code class="filename">deploy/images/<em class="replaceable"><code>machine</code></em></code> | ||
| 2269 | folder contains | ||
| 2270 | a symbolic link that points to the most recently built file | ||
| 2271 | for each machine. | ||
| 2272 | These links might be useful for external scripts that | ||
| 2273 | need to obtain the latest version of each file. | ||
| 2274 | </p></li></ul></div><p> | ||
| 2275 | </p></div><div class="section" title="2.8.7. Application Development SDK"><div class="titlepage"><div><div><h3 class="title" id="sdk-dev-environment">2.8.7. Application Development SDK<span class="permalink"><a alt="Permalink" title="Permalink" href="#sdk-dev-environment">¶</a></span></h3></div></div></div><p> | ||
| 2276 | In the | ||
| 2277 | <a class="link" href="#general-yocto-environment-figure">general Yocto Project Development Environment figure</a>, | ||
| 2278 | the output labeled "Application Development SDK" represents an | ||
| 2279 | SDK. | ||
| 2280 | The SDK generation process differs depending on whether you build | ||
| 2281 | a standard SDK | ||
| 2282 | (e.g. <code class="filename">bitbake -c populate_sdk</code> <em class="replaceable"><code>imagename</code></em>) | ||
| 2283 | or an extensible SDK | ||
| 2284 | (e.g. <code class="filename">bitbake -c populate_sdk_ext</code> <em class="replaceable"><code>imagename</code></em>). | ||
| 2285 | This section is going to take a closer look at this output: | ||
| 2286 | </p><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="810"><tr style="height: 653px"><td align="center"><img src="figures/sdk.png" align="middle" width="810" /></td></tr></table><p> | ||
| 2287 | </p><p> | ||
| 2288 | The specific form of this output is a self-extracting | ||
| 2289 | SDK installer (<code class="filename">*.sh</code>) that, when run, | ||
| 2290 | installs the SDK, which consists of a cross-development | ||
| 2291 | toolchain, a set of libraries and headers, and an SDK | ||
| 2292 | environment setup script. | ||
| 2293 | Running this installer essentially sets up your | ||
| 2294 | cross-development environment. | ||
| 2295 | You can think of the cross-toolchain as the "host" | ||
| 2296 | part because it runs on the SDK machine. | ||
| 2297 | You can think of the libraries and headers as the "target" | ||
| 2298 | part because they are built for the target hardware. | ||
| 2299 | The environment setup script is added so that you can initialize | ||
| 2300 | the environment before using the tools. | ||
| 2301 | </p><div class="note" title="Notes" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Notes</h3><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> | ||
| 2302 | The Yocto Project supports several methods by which you can | ||
| 2303 | set up this cross-development environment. | ||
| 2304 | These methods include downloading pre-built SDK installers | ||
| 2305 | or building and installing your own SDK installer. | ||
| 2306 | </p></li><li class="listitem"><p> | ||
| 2307 | For background information on cross-development toolchains | ||
| 2308 | in the Yocto Project development environment, see the | ||
| 2309 | "<a class="link" href="#cross-development-toolchain-generation" title="3.2. Cross-Development Toolchain Generation">Cross-Development Toolchain Generation</a>" | ||
| 2310 | section. | ||
| 2311 | </p></li><li class="listitem"><p> | ||
| 2312 | For information on setting up a cross-development | ||
| 2313 | environment, see the | ||
| 2314 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/sdk-manual/sdk-manual.html" target="_top">Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</a> | ||
| 2315 | manual. | ||
| 2316 | </p></li></ul></div></div><p> | ||
| 2317 | Once built, the SDK installers are written out to the | ||
| 2318 | <code class="filename">deploy/sdk</code> folder inside the | ||
| 2319 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#build-directory" target="_top">Build Directory</a> | ||
| 2320 | as shown in the figure at the beginning of this section. | ||
| 2321 | Depending on the type of SDK, several variables exist that help | ||
| 2322 | configure these files. | ||
| 2323 | The following list shows the variables associated with a standard | ||
| 2324 | SDK: | ||
| 2325 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-DEPLOY_DIR" target="_top"><code class="filename">DEPLOY_DIR</code></a>: | ||
| 2326 | Points to the <code class="filename">deploy</code> | ||
| 2327 | directory.</p></li><li class="listitem"><p><a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-SDKMACHINE" target="_top"><code class="filename">SDKMACHINE</code></a>: | ||
| 2328 | Specifies the architecture of the machine | ||
| 2329 | on which the cross-development tools are run to | ||
| 2330 | create packages for the target hardware. | ||
| 2331 | </p></li><li class="listitem"><p><a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-SDKIMAGE_FEATURES" target="_top"><code class="filename">SDKIMAGE_FEATURES</code></a>: | ||
| 2332 | Lists the features to include in the "target" part | ||
| 2333 | of the SDK. | ||
| 2334 | </p></li><li class="listitem"><p><a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-TOOLCHAIN_HOST_TASK" target="_top"><code class="filename">TOOLCHAIN_HOST_TASK</code></a>: | ||
| 2335 | Lists packages that make up the host | ||
| 2336 | part of the SDK (i.e. the part that runs on | ||
| 2337 | the <code class="filename">SDKMACHINE</code>). | ||
| 2338 | When you use | ||
| 2339 | <code class="filename">bitbake -c populate_sdk <em class="replaceable"><code>imagename</code></em></code> | ||
| 2340 | to create the SDK, a set of default packages | ||
| 2341 | apply. | ||
| 2342 | This variable allows you to add more packages. | ||
| 2343 | </p></li><li class="listitem"><p><a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-TOOLCHAIN_TARGET_TASK" target="_top"><code class="filename">TOOLCHAIN_TARGET_TASK</code></a>: | ||
| 2344 | Lists packages that make up the target part | ||
| 2345 | of the SDK (i.e. the part built for the | ||
| 2346 | target hardware). | ||
| 2347 | </p></li><li class="listitem"><p><a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-SDKPATH" target="_top"><code class="filename">SDKPATH</code></a>: | ||
| 2348 | Defines the default SDK installation path offered by the | ||
| 2349 | installation script. | ||
| 2350 | </p></li></ul></div><p> | ||
| 2351 | This next list, shows the variables associated with an extensible | ||
| 2352 | SDK: | ||
| 2353 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-DEPLOY_DIR" target="_top"><code class="filename">DEPLOY_DIR</code></a>: | ||
| 2354 | Points to the <code class="filename">deploy</code> directory. | ||
| 2355 | </p></li><li class="listitem"><p><a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-SDK_EXT_TYPE" target="_top"><code class="filename">SDK_EXT_TYPE</code></a>: | ||
| 2356 | Controls whether or not shared state artifacts are copied | ||
| 2357 | into the extensible SDK. | ||
| 2358 | By default, all required shared state artifacts are copied | ||
| 2359 | into the SDK. | ||
| 2360 | </p></li><li class="listitem"><p><a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-SDK_INCLUDE_PKGDATA" target="_top"><code class="filename">SDK_INCLUDE_PKGDATA</code></a>: | ||
| 2361 | Specifies whether or not packagedata will be included in | ||
| 2362 | the extensible SDK for all recipes in the "world" target. | ||
| 2363 | </p></li><li class="listitem"><p><a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-SDK_INCLUDE_TOOLCHAIN" target="_top"><code class="filename">SDK_INCLUDE_TOOLCHAIN</code></a>: | ||
| 2364 | Specifies whether or not the toolchain will be included | ||
| 2365 | when building the extensible SDK. | ||
| 2366 | </p></li><li class="listitem"><p><a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-SDK_LOCAL_CONF_WHITELIST" target="_top"><code class="filename">SDK_LOCAL_CONF_WHITELIST</code></a>: | ||
| 2367 | A list of variables allowed through from the build system | ||
| 2368 | configuration into the extensible SDK configuration. | ||
| 2369 | </p></li><li class="listitem"><p><a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-SDK_LOCAL_CONF_BLACKLIST" target="_top"><code class="filename">SDK_LOCAL_CONF_BLACKLIST</code></a>: | ||
| 2370 | A list of variables not allowed through from the build | ||
| 2371 | system configuration into the extensible SDK configuration. | ||
| 2372 | </p></li><li class="listitem"><p><a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-SDK_INHERIT_BLACKLIST" target="_top"><code class="filename">SDK_INHERIT_BLACKLIST</code></a>: | ||
| 2373 | A list of classes to remove from the | ||
| 2374 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-INHERIT" target="_top"><code class="filename">INHERIT</code></a> | ||
| 2375 | value globally within the extensible SDK configuration. | ||
| 2376 | </p></li></ul></div><p> | ||
| 2377 | </p></div></div></div> | ||
| 2378 | |||
| 2379 | <div class="chapter" title="Chapter 3. Yocto Project Concepts" id="overview-concepts"><div class="titlepage"><div><div><h2 class="title">Chapter 3. Yocto Project Concepts<span class="permalink"><a alt="Permalink" title="Permalink" href="#overview-concepts">¶</a></span></h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="section"><a href="#yocto-project-components">3.1. Yocto Project Components</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-components-bitbake">3.1.1. BitBake</a></span></dt><dt><span class="section"><a href="#usingpoky-components-metadata">3.1.2. Metadata (Recipes)</a></span></dt><dt><span class="section"><a href="#metadata-virtual-providers">3.1.3. Metadata (Virtual Providers)</a></span></dt><dt><span class="section"><a href="#usingpoky-components-classes">3.1.4. Classes</a></span></dt><dt><span class="section"><a href="#usingpoky-components-configuration">3.1.5. Configuration</a></span></dt></dl></dd><dt><span class="section"><a href="#cross-development-toolchain-generation">3.2. Cross-Development Toolchain Generation</a></span></dt><dt><span class="section"><a href="#shared-state-cache">3.3. Shared State Cache</a></span></dt><dd><dl><dt><span class="section"><a href="#overall-architecture">3.3.1. Overall Architecture</a></span></dt><dt><span class="section"><a href="#overview-checksums">3.3.2. Checksums (Signatures)</a></span></dt><dt><span class="section"><a href="#shared-state">3.3.3. Shared State</a></span></dt><dt><span class="section"><a href="#tips-and-tricks">3.3.4. Tips and Tricks</a></span></dt></dl></dd><dt><span class="section"><a href="#automatically-added-runtime-dependencies">3.4. Automatically Added Runtime Dependencies</a></span></dt><dt><span class="section"><a href="#fakeroot-and-pseudo">3.5. Fakeroot and Pseudo</a></span></dt><dt><span class="section"><a href="#wayland">3.6. Wayland</a></span></dt><dd><dl><dt><span class="section"><a href="#wayland-support">3.6.1. Support</a></span></dt><dt><span class="section"><a href="#enabling-wayland-in-an-image">3.6.2. Enabling Wayland in an Image</a></span></dt><dt><span class="section"><a href="#running-weston">3.6.3. Running Weston</a></span></dt></dl></dd><dt><span class="section"><a href="#overview-licenses">3.7. Licenses</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-configuring-LIC_FILES_CHKSUM">3.7.1. Tracking License Changes</a></span></dt><dt><span class="section"><a href="#enabling-commercially-licensed-recipes">3.7.2. Enabling Commercially Licensed Recipes</a></span></dt></dl></dd><dt><span class="section"><a href="#x32">3.8. x32 psABI</a></span></dt></dl></div><p> | ||
| 2380 | This chapter describes concepts for various areas of the Yocto Project. | ||
| 2381 | Currently, topics include Yocto Project components, cross-development | ||
| 2382 | generation, shared state (sstate) cache, runtime dependencies, | ||
| 2383 | Pseudo and Fakeroot, x32 psABI, Wayland support, and Licenses. | ||
| 2384 | </p><div class="section" title="3.1. Yocto Project Components"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="yocto-project-components">3.1. Yocto Project Components<span class="permalink"><a alt="Permalink" title="Permalink" href="#yocto-project-components">¶</a></span></h2></div></div></div><p> | ||
| 2385 | The | ||
| 2386 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#bitbake-term" target="_top">BitBake</a> | ||
| 2387 | task executor together with various types of configuration files | ||
| 2388 | form the OpenEmbedded Core. | ||
| 2389 | This section overviews these components by describing their use and | ||
| 2390 | how they interact. | ||
| 2391 | </p><p> | ||
| 2392 | BitBake handles the parsing and execution of the data files. | ||
| 2393 | The data itself is of various types: | ||
| 2394 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> | ||
| 2395 | <span class="emphasis"><em>Recipes:</em></span> | ||
| 2396 | Provides details about particular pieces of software. | ||
| 2397 | </p></li><li class="listitem"><p> | ||
| 2398 | <span class="emphasis"><em>Class Data:</em></span> | ||
| 2399 | Abstracts common build information (e.g. how to build a | ||
| 2400 | Linux kernel). | ||
| 2401 | </p></li><li class="listitem"><p> | ||
| 2402 | <span class="emphasis"><em>Configuration Data:</em></span> | ||
| 2403 | Defines machine-specific settings, policy decisions, and | ||
| 2404 | so forth. | ||
| 2405 | Configuration data acts as the glue to bind everything | ||
| 2406 | together. | ||
| 2407 | </p></li></ul></div><p> | ||
| 2408 | </p><p> | ||
| 2409 | BitBake knows how to combine multiple data sources together and | ||
| 2410 | refers to each data source as a layer. | ||
| 2411 | For information on layers, see the | ||
| 2412 | "<a class="ulink" href="http://www.yoctoproject.org/docs/2.5/dev-manual/dev-manual.html#understanding-and-creating-layers" target="_top">Understanding and Creating Layers</a>" | ||
| 2413 | section of the Yocto Project Development Tasks Manual. | ||
| 2414 | </p><p> | ||
| 2415 | Following are some brief details on these core components. | ||
| 2416 | For additional information on how these components interact during | ||
| 2417 | a build, see the | ||
| 2418 | "<a class="link" href="#development-concepts" title="2.8. Development Concepts">Development Concepts</a>" | ||
| 2419 | section. | ||
| 2420 | </p><div class="section" title="3.1.1. BitBake"><div class="titlepage"><div><div><h3 class="title" id="usingpoky-components-bitbake">3.1.1. BitBake<span class="permalink"><a alt="Permalink" title="Permalink" href="#usingpoky-components-bitbake">¶</a></span></h3></div></div></div><p> | ||
| 2421 | BitBake is the tool at the heart of the OpenEmbedded build | ||
| 2422 | system and is responsible for parsing the | ||
| 2423 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#metadata" target="_top">Metadata</a>, | ||
| 2424 | generating a list of tasks from it, and then executing those | ||
| 2425 | tasks. | ||
| 2426 | </p><p> | ||
| 2427 | This section briefly introduces BitBake. | ||
| 2428 | If you want more information on BitBake, see the | ||
| 2429 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/bitbake-user-manual/bitbake-user-manual.html#bitbake-user-manual" target="_top">BitBake User Manual</a>. | ||
| 2430 | </p><p> | ||
| 2431 | To see a list of the options BitBake supports, use either of | ||
| 2432 | the following commands: | ||
| 2433 | </p><pre class="literallayout"> | ||
| 2434 | $ bitbake -h | ||
| 2435 | $ bitbake --help | ||
| 2436 | </pre><p> | ||
| 2437 | </p><p> | ||
| 2438 | The most common usage for BitBake is | ||
| 2439 | <code class="filename">bitbake <em class="replaceable"><code>packagename</code></em></code>, | ||
| 2440 | where <code class="filename">packagename</code> is the name of the | ||
| 2441 | package you want to build (referred to as the "target" in this | ||
| 2442 | manual). | ||
| 2443 | The target often equates to the first part of a recipe's | ||
| 2444 | filename (e.g. "foo" for a recipe named | ||
| 2445 | <code class="filename">foo_1.3.0-r0.bb</code>). | ||
| 2446 | So, to process the | ||
| 2447 | <code class="filename">matchbox-desktop_1.2.3.bb</code> recipe file, you | ||
| 2448 | might type the following: | ||
| 2449 | </p><pre class="literallayout"> | ||
| 2450 | $ bitbake matchbox-desktop | ||
| 2451 | </pre><p> | ||
| 2452 | Several different versions of | ||
| 2453 | <code class="filename">matchbox-desktop</code> might exist. | ||
| 2454 | BitBake chooses the one selected by the distribution | ||
| 2455 | configuration. | ||
| 2456 | You can get more details about how BitBake chooses between | ||
| 2457 | different target versions and providers in the | ||
| 2458 | "<a class="ulink" href="http://www.yoctoproject.org/docs/2.5/bitbake-user-manual/bitbake-user-manual.html#bb-bitbake-preferences" target="_top">Preferences</a>" | ||
| 2459 | section of the BitBake User Manual. | ||
| 2460 | </p><p> | ||
| 2461 | BitBake also tries to execute any dependent tasks first. | ||
| 2462 | So for example, before building | ||
| 2463 | <code class="filename">matchbox-desktop</code>, BitBake would build a | ||
| 2464 | cross compiler and <code class="filename">glibc</code> if they had not | ||
| 2465 | already been built. | ||
| 2466 | </p><p> | ||
| 2467 | A useful BitBake option to consider is the | ||
| 2468 | <code class="filename">-k</code> or <code class="filename">--continue</code> | ||
| 2469 | option. | ||
| 2470 | This option instructs BitBake to try and continue processing | ||
| 2471 | the job as long as possible even after encountering an error. | ||
| 2472 | When an error occurs, the target that failed and those that | ||
| 2473 | depend on it cannot be remade. | ||
| 2474 | However, when you use this option other dependencies can | ||
| 2475 | still be processed. | ||
| 2476 | </p></div><div class="section" title="3.1.2. Metadata (Recipes)"><div class="titlepage"><div><div><h3 class="title" id="usingpoky-components-metadata">3.1.2. Metadata (Recipes)<span class="permalink"><a alt="Permalink" title="Permalink" href="#usingpoky-components-metadata">¶</a></span></h3></div></div></div><p> | ||
| 2477 | Files that have the <code class="filename">.bb</code> suffix are | ||
| 2478 | "recipes" files. | ||
| 2479 | In general, a recipe contains information about a single piece | ||
| 2480 | of software. | ||
| 2481 | This information includes the location from which to download | ||
| 2482 | the unaltered source, any source patches to be applied to that | ||
| 2483 | source (if needed), which special configuration options to | ||
| 2484 | apply, how to compile the source files, and how to package the | ||
| 2485 | compiled output. | ||
| 2486 | </p><p> | ||
| 2487 | The term "package" is sometimes used to refer to recipes. | ||
| 2488 | However, since the word "package" is used for the packaged | ||
| 2489 | output from the OpenEmbedded build system (i.e. | ||
| 2490 | <code class="filename">.ipk</code> or <code class="filename">.deb</code> files), | ||
| 2491 | this document avoids using the term "package" when referring | ||
| 2492 | to recipes. | ||
| 2493 | </p></div><div class="section" title="3.1.3. Metadata (Virtual Providers)"><div class="titlepage"><div><div><h3 class="title" id="metadata-virtual-providers">3.1.3. Metadata (Virtual Providers)<span class="permalink"><a alt="Permalink" title="Permalink" href="#metadata-virtual-providers">¶</a></span></h3></div></div></div><p> | ||
| 2494 | Prior to the build, if you know that several different recipes | ||
| 2495 | provide the same functionality, you can use a virtual provider | ||
| 2496 | (i.e. <code class="filename">virtual/*</code>) as a placeholder for the | ||
| 2497 | actual provider. | ||
| 2498 | The actual provider would be determined at build time. | ||
| 2499 | In this case, you should add <code class="filename">virtual/*</code> | ||
| 2500 | to | ||
| 2501 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-DEPENDS" target="_top"><code class="filename">DEPENDS</code></a>, | ||
| 2502 | rather than listing the specified provider. | ||
| 2503 | You would select the actual provider by setting the | ||
| 2504 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-PREFERRED_PROVIDER" target="_top"><code class="filename">PREFERRED_PROVIDER</code></a> | ||
| 2505 | variable (i.e. | ||
| 2506 | <code class="filename">PREFERRED_PROVIDER_virtual/*</code>) | ||
| 2507 | in the build's configuration file (e.g. | ||
| 2508 | <code class="filename">poky/build/conf/local.conf</code>). | ||
| 2509 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> | ||
| 2510 | Any recipe that PROVIDES a <code class="filename">virtual/*</code> | ||
| 2511 | item that is ultimately not selected through | ||
| 2512 | <code class="filename">PREFERRED_PROVIDER</code> does not get built. | ||
| 2513 | Preventing these recipes from building is usually the | ||
| 2514 | desired behavior since this mechanism's purpose is to | ||
| 2515 | select between mutually exclusive alternative providers. | ||
| 2516 | </div><p> | ||
| 2517 | </p><p> | ||
| 2518 | The following lists specific examples of virtual providers: | ||
| 2519 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> | ||
| 2520 | <code class="filename">virtual/mesa</code>: | ||
| 2521 | Provides <code class="filename">gbm.pc</code>. | ||
| 2522 | </p></li><li class="listitem"><p> | ||
| 2523 | <code class="filename">virtual/egl</code>: | ||
| 2524 | Provides <code class="filename">egl.pc</code> and possibly | ||
| 2525 | <code class="filename">wayland-egl.pc</code>. | ||
| 2526 | </p></li><li class="listitem"><p> | ||
| 2527 | <code class="filename">virtual/libgl</code>: | ||
| 2528 | Provides <code class="filename">gl.pc</code> (i.e. libGL). | ||
| 2529 | </p></li><li class="listitem"><p> | ||
| 2530 | <code class="filename">virtual/libgles1</code>: | ||
| 2531 | Provides <code class="filename">glesv1_cm.pc</code> | ||
| 2532 | (i.e. libGLESv1_CM). | ||
| 2533 | </p></li><li class="listitem"><p> | ||
| 2534 | <code class="filename">virtual/libgles2</code>: | ||
| 2535 | Provides <code class="filename">glesv2.pc</code> | ||
| 2536 | (i.e. libGLESv2). | ||
| 2537 | </p></li></ul></div><p> | ||
| 2538 | </p></div><div class="section" title="3.1.4. Classes"><div class="titlepage"><div><div><h3 class="title" id="usingpoky-components-classes">3.1.4. Classes<span class="permalink"><a alt="Permalink" title="Permalink" href="#usingpoky-components-classes">¶</a></span></h3></div></div></div><p> | ||
| 2539 | Class files (<code class="filename">.bbclass</code>) contain information | ||
| 2540 | that is useful to share between | ||
| 2541 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#metadata" target="_top">Metadata</a> | ||
| 2542 | files. | ||
| 2543 | An example is the | ||
| 2544 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-classes-autotools" target="_top"><code class="filename">autotools</code></a> | ||
| 2545 | class, which contains common settings for any application that | ||
| 2546 | Autotools uses. | ||
| 2547 | The | ||
| 2548 | "<a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-classes" target="_top">Classes</a>" | ||
| 2549 | chapter in the Yocto Project Reference Manual provides | ||
| 2550 | details about classes and how to use them. | ||
| 2551 | </p></div><div class="section" title="3.1.5. Configuration"><div class="titlepage"><div><div><h3 class="title" id="usingpoky-components-configuration">3.1.5. Configuration<span class="permalink"><a alt="Permalink" title="Permalink" href="#usingpoky-components-configuration">¶</a></span></h3></div></div></div><p> | ||
| 2552 | The configuration files (<code class="filename">.conf</code>) define | ||
| 2553 | various configuration variables that govern the OpenEmbedded | ||
| 2554 | build process. | ||
| 2555 | These files fall into several areas that define machine | ||
| 2556 | configuration options, distribution configuration options, | ||
| 2557 | compiler tuning options, general common configuration options, | ||
| 2558 | and user configuration options in | ||
| 2559 | <code class="filename">local.conf</code>, which is found in the | ||
| 2560 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#build-directory" target="_top">Build Directory</a>. | ||
| 2561 | </p></div></div><div class="section" title="3.2. Cross-Development Toolchain Generation"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="cross-development-toolchain-generation">3.2. Cross-Development Toolchain Generation<span class="permalink"><a alt="Permalink" title="Permalink" href="#cross-development-toolchain-generation">¶</a></span></h2></div></div></div><p> | ||
| 2562 | The Yocto Project does most of the work for you when it comes to | ||
| 2563 | creating | ||
| 2564 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#cross-development-toolchain" target="_top">cross-development toolchains</a>. | ||
| 2565 | This section provides some technical background on how | ||
| 2566 | cross-development toolchains are created and used. | ||
| 2567 | For more information on toolchains, you can also see the | ||
| 2568 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/sdk-manual/sdk-manual.html" target="_top">Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</a> | ||
| 2569 | manual. | ||
| 2570 | </p><p> | ||
| 2571 | In the Yocto Project development environment, cross-development | ||
| 2572 | toolchains are used to build the image and applications that run | ||
| 2573 | on the target hardware. | ||
| 2574 | With just a few commands, the OpenEmbedded build system creates | ||
| 2575 | these necessary toolchains for you. | ||
| 2576 | </p><p> | ||
| 2577 | The following figure shows a high-level build environment regarding | ||
| 2578 | toolchain construction and use. | ||
| 2579 | </p><p> | ||
| 2580 | </p><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="720"><tr style="height: 540px"><td align="center"><img src="figures/cross-development-toolchains.png" align="middle" width="720" /></td></tr></table><p> | ||
| 2581 | </p><p> | ||
| 2582 | Most of the work occurs on the Build Host. | ||
| 2583 | This is the machine used to build images and generally work within the | ||
| 2584 | the Yocto Project environment. | ||
| 2585 | When you run BitBake to create an image, the OpenEmbedded build system | ||
| 2586 | uses the host <code class="filename">gcc</code> compiler to bootstrap a | ||
| 2587 | cross-compiler named <code class="filename">gcc-cross</code>. | ||
| 2588 | The <code class="filename">gcc-cross</code> compiler is what BitBake uses to | ||
| 2589 | compile source files when creating the target image. | ||
| 2590 | You can think of <code class="filename">gcc-cross</code> simply as an | ||
| 2591 | automatically generated cross-compiler that is used internally within | ||
| 2592 | BitBake only. | ||
| 2593 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> | ||
| 2594 | The extensible SDK does not use | ||
| 2595 | <code class="filename">gcc-cross-canadian</code> since this SDK | ||
| 2596 | ships a copy of the OpenEmbedded build system and the sysroot | ||
| 2597 | within it contains <code class="filename">gcc-cross</code>. | ||
| 2598 | </div><p> | ||
| 2599 | </p><p> | ||
| 2600 | The chain of events that occurs when <code class="filename">gcc-cross</code> is | ||
| 2601 | bootstrapped is as follows: | ||
| 2602 | </p><pre class="literallayout"> | ||
| 2603 | gcc -> binutils-cross -> gcc-cross-initial -> linux-libc-headers -> glibc-initial -> glibc -> gcc-cross -> gcc-runtime | ||
| 2604 | </pre><p> | ||
| 2605 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> | ||
| 2606 | <code class="filename">gcc</code>: | ||
| 2607 | The build host's GNU Compiler Collection (GCC). | ||
| 2608 | </p></li><li class="listitem"><p> | ||
| 2609 | <code class="filename">binutils-cross</code>: | ||
| 2610 | The bare minimum binary utilities needed in order to run | ||
| 2611 | the <code class="filename">gcc-cross-initial</code> phase of the | ||
| 2612 | bootstrap operation. | ||
| 2613 | </p></li><li class="listitem"><p> | ||
| 2614 | <code class="filename">gcc-cross-initial</code>: | ||
| 2615 | An early stage of the bootstrap process for creating | ||
| 2616 | the cross-compiler. | ||
| 2617 | This stage builds enough of the <code class="filename">gcc-cross</code>, | ||
| 2618 | the C library, and other pieces needed to finish building the | ||
| 2619 | final cross-compiler in later stages. | ||
| 2620 | This tool is a "native" package (i.e. it is designed to run on | ||
| 2621 | the build host). | ||
| 2622 | </p></li><li class="listitem"><p> | ||
| 2623 | <code class="filename">linux-libc-headers</code>: | ||
| 2624 | Headers needed for the cross-compiler. | ||
| 2625 | </p></li><li class="listitem"><p> | ||
| 2626 | <code class="filename">glibc-initial</code>: | ||
| 2627 | An initial version of the Embedded GLIBC needed to bootstrap | ||
| 2628 | <code class="filename">glibc</code>. | ||
| 2629 | </p></li><li class="listitem"><p> | ||
| 2630 | <code class="filename">gcc-cross</code>: | ||
| 2631 | The final stage of the bootstrap process for the | ||
| 2632 | cross-compiler. | ||
| 2633 | This stage results in the actual cross-compiler that | ||
| 2634 | BitBake uses when it builds an image for a targeted | ||
| 2635 | device. | ||
| 2636 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> | ||
| 2637 | If you are replacing this cross compiler toolchain | ||
| 2638 | with a custom version, you must replace | ||
| 2639 | <code class="filename">gcc-cross</code>. | ||
| 2640 | </div><p> | ||
| 2641 | This tool is also a "native" package (i.e. it is | ||
| 2642 | designed to run on the build host). | ||
| 2643 | </p></li><li class="listitem"><p> | ||
| 2644 | <code class="filename">gcc-runtime</code>: | ||
| 2645 | Runtime libraries resulting from the toolchain bootstrapping | ||
| 2646 | process. | ||
| 2647 | This tool produces a binary that consists of the | ||
| 2648 | runtime libraries need for the targeted device. | ||
| 2649 | </p></li></ul></div><p> | ||
| 2650 | </p><p> | ||
| 2651 | You can use the OpenEmbedded build system to build an installer for | ||
| 2652 | the relocatable SDK used to develop applications. | ||
| 2653 | When you run the installer, it installs the toolchain, which contains | ||
| 2654 | the development tools (e.g., the | ||
| 2655 | <code class="filename">gcc-cross-canadian</code>), | ||
| 2656 | <code class="filename">binutils-cross-canadian</code>, and other | ||
| 2657 | <code class="filename">nativesdk-*</code> tools, | ||
| 2658 | which are tools native to the SDK (i.e. native to | ||
| 2659 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-SDK_ARCH" target="_top"><code class="filename">SDK_ARCH</code></a>), | ||
| 2660 | you need to cross-compile and test your software. | ||
| 2661 | The figure shows the commands you use to easily build out this | ||
| 2662 | toolchain. | ||
| 2663 | This cross-development toolchain is built to execute on the | ||
| 2664 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-SDKMACHINE" target="_top"><code class="filename">SDKMACHINE</code></a>, | ||
| 2665 | which might or might not be the same | ||
| 2666 | machine as the Build Host. | ||
| 2667 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> | ||
| 2668 | If your target architecture is supported by the Yocto Project, | ||
| 2669 | you can take advantage of pre-built images that ship with the | ||
| 2670 | Yocto Project and already contain cross-development toolchain | ||
| 2671 | installers. | ||
| 2672 | </div><p> | ||
| 2673 | </p><p> | ||
| 2674 | Here is the bootstrap process for the relocatable toolchain: | ||
| 2675 | </p><pre class="literallayout"> | ||
| 2676 | gcc -> binutils-crosssdk -> gcc-crosssdk-initial -> linux-libc-headers -> | ||
| 2677 | glibc-initial -> nativesdk-glibc -> gcc-crosssdk -> gcc-cross-canadian | ||
| 2678 | </pre><p> | ||
| 2679 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> | ||
| 2680 | <code class="filename">gcc</code>: | ||
| 2681 | The build host's GNU Compiler Collection (GCC). | ||
| 2682 | </p></li><li class="listitem"><p> | ||
| 2683 | <code class="filename">binutils-crosssdk</code>: | ||
| 2684 | The bare minimum binary utilities needed in order to run | ||
| 2685 | the <code class="filename">gcc-crosssdk-initial</code> phase of the | ||
| 2686 | bootstrap operation. | ||
| 2687 | </p></li><li class="listitem"><p> | ||
| 2688 | <code class="filename">gcc-crosssdk-initial</code>: | ||
| 2689 | An early stage of the bootstrap process for creating | ||
| 2690 | the cross-compiler. | ||
| 2691 | This stage builds enough of the | ||
| 2692 | <code class="filename">gcc-crosssdk</code> and supporting pieces so that | ||
| 2693 | the final stage of the bootstrap process can produce the | ||
| 2694 | finished cross-compiler. | ||
| 2695 | This tool is a "native" binary that runs on the build host. | ||
| 2696 | </p></li><li class="listitem"><p> | ||
| 2697 | <code class="filename">linux-libc-headers</code>: | ||
| 2698 | Headers needed for the cross-compiler. | ||
| 2699 | </p></li><li class="listitem"><p> | ||
| 2700 | <code class="filename">glibc-initial</code>: | ||
| 2701 | An initial version of the Embedded GLIBC needed to bootstrap | ||
| 2702 | <code class="filename">nativesdk-glibc</code>. | ||
| 2703 | </p></li><li class="listitem"><p> | ||
| 2704 | <code class="filename">nativesdk-glibc</code>: | ||
| 2705 | The Embedded GLIBC needed to bootstrap the | ||
| 2706 | <code class="filename">gcc-crosssdk</code>. | ||
| 2707 | </p></li><li class="listitem"><p> | ||
| 2708 | <code class="filename">gcc-crosssdk</code>: | ||
| 2709 | The final stage of the bootstrap process for the | ||
| 2710 | relocatable cross-compiler. | ||
| 2711 | The <code class="filename">gcc-crosssdk</code> is a transitory compiler | ||
| 2712 | and never leaves the build host. | ||
| 2713 | Its purpose is to help in the bootstrap process to create the | ||
| 2714 | eventual relocatable <code class="filename">gcc-cross-canadian</code> | ||
| 2715 | compiler, which is relocatable. | ||
| 2716 | This tool is also a "native" package (i.e. it is | ||
| 2717 | designed to run on the build host). | ||
| 2718 | </p></li><li class="listitem"><p> | ||
| 2719 | <code class="filename">gcc-cross-canadian</code>: | ||
| 2720 | The final relocatable cross-compiler. | ||
| 2721 | When run on the | ||
| 2722 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-SDKMACHINE" target="_top"><code class="filename">SDKMACHINE</code></a>, | ||
| 2723 | this tool | ||
| 2724 | produces executable code that runs on the target device. | ||
| 2725 | Only one cross-canadian compiler is produced per architecture | ||
| 2726 | since they can be targeted at different processor optimizations | ||
| 2727 | using configurations passed to the compiler through the | ||
| 2728 | compile commands. | ||
| 2729 | This circumvents the need for multiple compilers and thus | ||
| 2730 | reduces the size of the toolchains. | ||
| 2731 | </p></li></ul></div><p> | ||
| 2732 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> | ||
| 2733 | For information on advantages gained when building a | ||
| 2734 | cross-development toolchain installer, see the | ||
| 2735 | "<a class="ulink" href="http://www.yoctoproject.org/docs/2.5/sdk-manual/sdk-manual.html#sdk-building-an-sdk-installer" target="_top">Building an SDK Installer</a>" | ||
| 2736 | section in the Yocto Project Application Development and the | ||
| 2737 | Extensible Software Development Kit (eSDK) manual. | ||
| 2738 | </div></div><div class="section" title="3.3. Shared State Cache"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="shared-state-cache">3.3. Shared State Cache<span class="permalink"><a alt="Permalink" title="Permalink" href="#shared-state-cache">¶</a></span></h2></div></div></div><p> | ||
| 2739 | By design, the OpenEmbedded build system builds everything from | ||
| 2740 | scratch unless BitBake can determine that parts do not need to be | ||
| 2741 | rebuilt. | ||
| 2742 | Fundamentally, building from scratch is attractive as it means all | ||
| 2743 | parts are built fresh and there is no possibility of stale data | ||
| 2744 | causing problems. | ||
| 2745 | When developers hit problems, they typically default back to | ||
| 2746 | building from scratch so they know the state of things from the | ||
| 2747 | start. | ||
| 2748 | </p><p> | ||
| 2749 | Building an image from scratch is both an advantage and a | ||
| 2750 | disadvantage to the process. | ||
| 2751 | As mentioned in the previous paragraph, building from scratch | ||
| 2752 | ensures that everything is current and starts from a known state. | ||
| 2753 | However, building from scratch also takes much longer as it | ||
| 2754 | generally means rebuilding things that do not necessarily need | ||
| 2755 | to be rebuilt. | ||
| 2756 | </p><p> | ||
| 2757 | The Yocto Project implements shared state code that supports | ||
| 2758 | incremental builds. | ||
| 2759 | The implementation of the shared state code answers the following | ||
| 2760 | questions that were fundamental roadblocks within the OpenEmbedded | ||
| 2761 | incremental build support system: | ||
| 2762 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> | ||
| 2763 | What pieces of the system have changed and what pieces have | ||
| 2764 | not changed? | ||
| 2765 | </p></li><li class="listitem"><p> | ||
| 2766 | How are changed pieces of software removed and replaced? | ||
| 2767 | </p></li><li class="listitem"><p> | ||
| 2768 | How are pre-built components that do not need to be rebuilt | ||
| 2769 | from scratch used when they are available? | ||
| 2770 | </p></li></ul></div><p> | ||
| 2771 | </p><p> | ||
| 2772 | For the first question, the build system detects changes in the | ||
| 2773 | "inputs" to a given task by creating a checksum (or signature) of | ||
| 2774 | the task's inputs. | ||
| 2775 | If the checksum changes, the system assumes the inputs have changed | ||
| 2776 | and the task needs to be rerun. | ||
| 2777 | For the second question, the shared state (sstate) code tracks | ||
| 2778 | which tasks add which output to the build process. | ||
| 2779 | This means the output from a given task can be removed, upgraded | ||
| 2780 | or otherwise manipulated. | ||
| 2781 | The third question is partly addressed by the solution for the | ||
| 2782 | second question assuming the build system can fetch the sstate | ||
| 2783 | objects from remote locations and install them if they are deemed | ||
| 2784 | to be valid. | ||
| 2785 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> | ||
| 2786 | The OpenEmbedded build system does not maintain | ||
| 2787 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-PR" target="_top"><code class="filename">PR</code></a> | ||
| 2788 | information as part of the shared state packages. | ||
| 2789 | Consequently, considerations exist that affect maintaining | ||
| 2790 | shared state feeds. | ||
| 2791 | For information on how the OpenEmbedded build system | ||
| 2792 | works with packages and can track incrementing | ||
| 2793 | <code class="filename">PR</code> information, see the | ||
| 2794 | "<a class="ulink" href="http://www.yoctoproject.org/docs/2.5/dev-manual/dev-manual.html#automatically-incrementing-a-binary-package-revision-number" target="_top">Automatically Incrementing a Binary Package Revision Number</a>" | ||
| 2795 | section in the Yocto Project Development Tasks Manual. | ||
| 2796 | </div><p> | ||
| 2797 | </p><p> | ||
| 2798 | The rest of this section goes into detail about the overall | ||
| 2799 | incremental build architecture, the checksums (signatures), shared | ||
| 2800 | state, and some tips and tricks. | ||
| 2801 | </p><div class="section" title="3.3.1. Overall Architecture"><div class="titlepage"><div><div><h3 class="title" id="overall-architecture">3.3.1. Overall Architecture<span class="permalink"><a alt="Permalink" title="Permalink" href="#overall-architecture">¶</a></span></h3></div></div></div><p> | ||
| 2802 | When determining what parts of the system need to be built, | ||
| 2803 | BitBake works on a per-task basis rather than a per-recipe | ||
| 2804 | basis. | ||
| 2805 | You might wonder why using a per-task basis is preferred over | ||
| 2806 | a per-recipe basis. | ||
| 2807 | To help explain, consider having the IPK packaging backend | ||
| 2808 | enabled and then switching to DEB. | ||
| 2809 | In this case, the | ||
| 2810 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-tasks-install" target="_top"><code class="filename">do_install</code></a> | ||
| 2811 | and | ||
| 2812 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-tasks-package" target="_top"><code class="filename">do_package</code></a> | ||
| 2813 | task outputs are still valid. | ||
| 2814 | However, with a per-recipe approach, the build would not | ||
| 2815 | include the <code class="filename">.deb</code> files. | ||
| 2816 | Consequently, you would have to invalidate the whole build and | ||
| 2817 | rerun it. | ||
| 2818 | Rerunning everything is not the best solution. | ||
| 2819 | Also, in this case, the core must be "taught" much about | ||
| 2820 | specific tasks. | ||
| 2821 | This methodology does not scale well and does not allow users | ||
| 2822 | to easily add new tasks in layers or as external recipes | ||
| 2823 | without touching the packaged-staging core. | ||
| 2824 | </p></div><div class="section" title="3.3.2. Checksums (Signatures)"><div class="titlepage"><div><div><h3 class="title" id="overview-checksums">3.3.2. Checksums (Signatures)<span class="permalink"><a alt="Permalink" title="Permalink" href="#overview-checksums">¶</a></span></h3></div></div></div><p> | ||
| 2825 | The shared state code uses a checksum, which is a unique | ||
| 2826 | signature of a task's inputs, to determine if a task needs to | ||
| 2827 | be run again. | ||
| 2828 | Because it is a change in a task's inputs that triggers a | ||
| 2829 | rerun, the process needs to detect all the inputs to a given | ||
| 2830 | task. | ||
| 2831 | For shell tasks, this turns out to be fairly easy because | ||
| 2832 | the build process generates a "run" shell script for each task | ||
| 2833 | and it is possible to create a checksum that gives you a good | ||
| 2834 | idea of when the task's data changes. | ||
| 2835 | </p><p> | ||
| 2836 | To complicate the problem, there are things that should not be | ||
| 2837 | included in the checksum. | ||
| 2838 | First, there is the actual specific build path of a given | ||
| 2839 | task - the | ||
| 2840 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-WORKDIR" target="_top"><code class="filename">WORKDIR</code></a>. | ||
| 2841 | It does not matter if the work directory changes because it | ||
| 2842 | should not affect the output for target packages. | ||
| 2843 | Also, the build process has the objective of making native | ||
| 2844 | or cross packages relocatable. | ||
| 2845 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> | ||
| 2846 | Both native and cross packages run on the build host. | ||
| 2847 | However, cross packages generate output for the target | ||
| 2848 | architecture. | ||
| 2849 | </div><p> | ||
| 2850 | The checksum therefore needs to exclude | ||
| 2851 | <code class="filename">WORKDIR</code>. | ||
| 2852 | The simplistic approach for excluding the work directory is to | ||
| 2853 | set <code class="filename">WORKDIR</code> to some fixed value and | ||
| 2854 | create the checksum for the "run" script. | ||
| 2855 | </p><p> | ||
| 2856 | Another problem results from the "run" scripts containing | ||
| 2857 | functions that might or might not get called. | ||
| 2858 | The incremental build solution contains code that figures out | ||
| 2859 | dependencies between shell functions. | ||
| 2860 | This code is used to prune the "run" scripts down to the | ||
| 2861 | minimum set, thereby alleviating this problem and making the | ||
| 2862 | "run" scripts much more readable as a bonus. | ||
| 2863 | </p><p> | ||
| 2864 | So far we have solutions for shell scripts. | ||
| 2865 | What about Python tasks? | ||
| 2866 | The same approach applies even though these tasks are more | ||
| 2867 | difficult. | ||
| 2868 | The process needs to figure out what variables a Python | ||
| 2869 | function accesses and what functions it calls. | ||
| 2870 | Again, the incremental build solution contains code that first | ||
| 2871 | figures out the variable and function dependencies, and then | ||
| 2872 | creates a checksum for the data used as the input to the task. | ||
| 2873 | </p><p> | ||
| 2874 | Like the <code class="filename">WORKDIR</code> case, situations exist | ||
| 2875 | where dependencies should be ignored. | ||
| 2876 | For these cases, you can instruct the build process to | ||
| 2877 | ignore a dependency by using a line like the following: | ||
| 2878 | </p><pre class="literallayout"> | ||
| 2879 | PACKAGE_ARCHS[vardepsexclude] = "MACHINE" | ||
| 2880 | </pre><p> | ||
| 2881 | This example ensures that the | ||
| 2882 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-PACKAGE_ARCHS" target="_top"><code class="filename">PACKAGE_ARCHS</code></a> | ||
| 2883 | variable does not depend on the value of | ||
| 2884 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-MACHINE" target="_top"><code class="filename">MACHINE</code></a>, | ||
| 2885 | even if it does reference it. | ||
| 2886 | </p><p> | ||
| 2887 | Equally, there are cases where we need to add dependencies | ||
| 2888 | BitBake is not able to find. | ||
| 2889 | You can accomplish this by using a line like the following: | ||
| 2890 | </p><pre class="literallayout"> | ||
| 2891 | PACKAGE_ARCHS[vardeps] = "MACHINE" | ||
| 2892 | </pre><p> | ||
| 2893 | This example explicitly adds the <code class="filename">MACHINE</code> | ||
| 2894 | variable as a dependency for | ||
| 2895 | <code class="filename">PACKAGE_ARCHS</code>. | ||
| 2896 | </p><p> | ||
| 2897 | Consider a case with in-line Python, for example, where | ||
| 2898 | BitBake is not able to figure out dependencies. | ||
| 2899 | When running in debug mode (i.e. using | ||
| 2900 | <code class="filename">-DDD</code>), BitBake produces output when it | ||
| 2901 | discovers something for which it cannot figure out dependencies. | ||
| 2902 | The Yocto Project team has currently not managed to cover | ||
| 2903 | those dependencies in detail and is aware of the need to fix | ||
| 2904 | this situation. | ||
| 2905 | </p><p> | ||
| 2906 | Thus far, this section has limited discussion to the direct | ||
| 2907 | inputs into a task. | ||
| 2908 | Information based on direct inputs is referred to as the | ||
| 2909 | "basehash" in the code. | ||
| 2910 | However, there is still the question of a task's indirect | ||
| 2911 | inputs - the things that were already built and present in the | ||
| 2912 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#build-directory" target="_top">Build Directory</a>. | ||
| 2913 | The checksum (or signature) for a particular task needs to add | ||
| 2914 | the hashes of all the tasks on which the particular task | ||
| 2915 | depends. | ||
| 2916 | Choosing which dependencies to add is a policy decision. | ||
| 2917 | However, the effect is to generate a master checksum that | ||
| 2918 | combines the basehash and the hashes of the task's | ||
| 2919 | dependencies. | ||
| 2920 | </p><p> | ||
| 2921 | At the code level, there are a variety of ways both the | ||
| 2922 | basehash and the dependent task hashes can be influenced. | ||
| 2923 | Within the BitBake configuration file, we can give BitBake | ||
| 2924 | some extra information to help it construct the basehash. | ||
| 2925 | The following statement effectively results in a list of | ||
| 2926 | global variable dependency excludes - variables never | ||
| 2927 | included in any checksum: | ||
| 2928 | </p><pre class="literallayout"> | ||
| 2929 | BB_HASHBASE_WHITELIST ?= "TMPDIR FILE PATH PWD BB_TASKHASH BBPATH DL_DIR \ | ||
| 2930 | SSTATE_DIR THISDIR FILESEXTRAPATHS FILE_DIRNAME HOME LOGNAME SHELL TERM \ | ||
| 2931 | USER FILESPATH STAGING_DIR_HOST STAGING_DIR_TARGET COREBASE PRSERV_HOST \ | ||
| 2932 | PRSERV_DUMPDIR PRSERV_DUMPFILE PRSERV_LOCKDOWN PARALLEL_MAKE \ | ||
| 2933 | CCACHE_DIR EXTERNAL_TOOLCHAIN CCACHE CCACHE_DISABLE LICENSE_PATH SDKPKGSUFFIX" | ||
| 2934 | </pre><p> | ||
| 2935 | The previous example excludes | ||
| 2936 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-WORKDIR" target="_top"><code class="filename">WORKDIR</code></a> | ||
| 2937 | since that variable is actually constructed as a path within | ||
| 2938 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-TMPDIR" target="_top"><code class="filename">TMPDIR</code></a>, | ||
| 2939 | which is on the whitelist. | ||
| 2940 | </p><p> | ||
| 2941 | The rules for deciding which hashes of dependent tasks to | ||
| 2942 | include through dependency chains are more complex and are | ||
| 2943 | generally accomplished with a Python function. | ||
| 2944 | The code in <code class="filename">meta/lib/oe/sstatesig.py</code> shows | ||
| 2945 | two examples of this and also illustrates how you can insert | ||
| 2946 | your own policy into the system if so desired. | ||
| 2947 | This file defines the two basic signature generators | ||
| 2948 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#oe-core" target="_top">OE-Core</a> | ||
| 2949 | uses: "OEBasic" and "OEBasicHash". | ||
| 2950 | By default, there is a dummy "noop" signature handler enabled | ||
| 2951 | in BitBake. | ||
| 2952 | This means that behavior is unchanged from previous versions. | ||
| 2953 | OE-Core uses the "OEBasicHash" signature handler by default | ||
| 2954 | through this setting in the <code class="filename">bitbake.conf</code> | ||
| 2955 | file: | ||
| 2956 | </p><pre class="literallayout"> | ||
| 2957 | BB_SIGNATURE_HANDLER ?= "OEBasicHash" | ||
| 2958 | </pre><p> | ||
| 2959 | The "OEBasicHash" <code class="filename">BB_SIGNATURE_HANDLER</code> | ||
| 2960 | is the same as the "OEBasic" version but adds the task hash to | ||
| 2961 | the stamp files. | ||
| 2962 | This results in any | ||
| 2963 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#metadata" target="_top">Metadata</a> | ||
| 2964 | change that changes the task hash, automatically | ||
| 2965 | causing the task to be run again. | ||
| 2966 | This removes the need to bump | ||
| 2967 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-PR" target="_top"><code class="filename">PR</code></a> | ||
| 2968 | values, and changes to Metadata automatically ripple across | ||
| 2969 | the build. | ||
| 2970 | </p><p> | ||
| 2971 | It is also worth noting that the end result of these | ||
| 2972 | signature generators is to make some dependency and hash | ||
| 2973 | information available to the build. | ||
| 2974 | This information includes: | ||
| 2975 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> | ||
| 2976 | <code class="filename">BB_BASEHASH_task-</code><em class="replaceable"><code>taskname</code></em>: | ||
| 2977 | The base hashes for each task in the recipe. | ||
| 2978 | </p></li><li class="listitem"><p> | ||
| 2979 | <code class="filename">BB_BASEHASH_</code><em class="replaceable"><code>filename</code></em><code class="filename">:</code><em class="replaceable"><code>taskname</code></em>: | ||
| 2980 | The base hashes for each dependent task. | ||
| 2981 | </p></li><li class="listitem"><p> | ||
| 2982 | <code class="filename">BBHASHDEPS_</code><em class="replaceable"><code>filename</code></em><code class="filename">:</code><em class="replaceable"><code>taskname</code></em>: | ||
| 2983 | The task dependencies for each task. | ||
| 2984 | </p></li><li class="listitem"><p> | ||
| 2985 | <code class="filename">BB_TASKHASH</code>: | ||
| 2986 | The hash of the currently running task. | ||
| 2987 | </p></li></ul></div><p> | ||
| 2988 | </p></div><div class="section" title="3.3.3. Shared State"><div class="titlepage"><div><div><h3 class="title" id="shared-state">3.3.3. Shared State<span class="permalink"><a alt="Permalink" title="Permalink" href="#shared-state">¶</a></span></h3></div></div></div><p> | ||
| 2989 | Checksums and dependencies, as discussed in the previous | ||
| 2990 | section, solve half the problem of supporting a shared state. | ||
| 2991 | The other part of the problem is being able to use checksum | ||
| 2992 | information during the build and being able to reuse or rebuild | ||
| 2993 | specific components. | ||
| 2994 | </p><p> | ||
| 2995 | The | ||
| 2996 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-classes-sstate" target="_top"><code class="filename">sstate</code></a> | ||
| 2997 | class is a relatively generic implementation of how to | ||
| 2998 | "capture" a snapshot of a given task. | ||
| 2999 | The idea is that the build process does not care about the | ||
| 3000 | source of a task's output. | ||
| 3001 | Output could be freshly built or it could be downloaded and | ||
| 3002 | unpacked from somewhere - the build process does not need to | ||
| 3003 | worry about its origin. | ||
| 3004 | </p><p> | ||
| 3005 | There are two types of output, one is just about creating a | ||
| 3006 | directory in | ||
| 3007 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-WORKDIR" target="_top"><code class="filename">WORKDIR</code></a>. | ||
| 3008 | A good example is the output of either | ||
| 3009 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-tasks-install" target="_top"><code class="filename">do_install</code></a> | ||
| 3010 | or | ||
| 3011 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-tasks-package" target="_top"><code class="filename">do_package</code></a>. | ||
| 3012 | The other type of output occurs when a set of data is merged | ||
| 3013 | into a shared directory tree such as the sysroot. | ||
| 3014 | </p><p> | ||
| 3015 | The Yocto Project team has tried to keep the details of the | ||
| 3016 | implementation hidden in <code class="filename">sstate</code> class. | ||
| 3017 | From a user's perspective, adding shared state wrapping to a task | ||
| 3018 | is as simple as this | ||
| 3019 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-tasks-deploy" target="_top"><code class="filename">do_deploy</code></a> | ||
| 3020 | example taken from the | ||
| 3021 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-classes-deploy" target="_top"><code class="filename">deploy</code></a> | ||
| 3022 | class: | ||
| 3023 | </p><pre class="literallayout"> | ||
| 3024 | DEPLOYDIR = "${WORKDIR}/deploy-${PN}" | ||
| 3025 | SSTATETASKS += "do_deploy" | ||
| 3026 | do_deploy[sstate-inputdirs] = "${DEPLOYDIR}" | ||
| 3027 | do_deploy[sstate-outputdirs] = "${DEPLOY_DIR_IMAGE}" | ||
| 3028 | |||
| 3029 | python do_deploy_setscene () { | ||
| 3030 | sstate_setscene(d) | ||
| 3031 | } | ||
| 3032 | addtask do_deploy_setscene | ||
| 3033 | do_deploy[dirs] = "${DEPLOYDIR} ${B}" | ||
| 3034 | </pre><p> | ||
| 3035 | The following list explains the previous example: | ||
| 3036 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> | ||
| 3037 | Adding "do_deploy" to <code class="filename">SSTATETASKS</code> | ||
| 3038 | adds some required sstate-related processing, which is | ||
| 3039 | implemented in the | ||
| 3040 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-classes-sstate" target="_top"><code class="filename">sstate</code></a> | ||
| 3041 | class, to before and after the | ||
| 3042 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-tasks-deploy" target="_top"><code class="filename">do_deploy</code></a> | ||
| 3043 | task. | ||
| 3044 | </p></li><li class="listitem"><p> | ||
| 3045 | The | ||
| 3046 | <code class="filename">do_deploy[sstate-inputdirs] = "${DEPLOYDIR}"</code> | ||
| 3047 | declares that <code class="filename">do_deploy</code> places its | ||
| 3048 | output in <code class="filename">${DEPLOYDIR}</code> when run | ||
| 3049 | normally (i.e. when not using the sstate cache). | ||
| 3050 | This output becomes the input to the shared state cache. | ||
| 3051 | </p></li><li class="listitem"><p> | ||
| 3052 | The | ||
| 3053 | <code class="filename">do_deploy[sstate-outputdirs] = "${DEPLOY_DIR_IMAGE}"</code> | ||
| 3054 | line causes the contents of the shared state cache to be | ||
| 3055 | copied to <code class="filename">${DEPLOY_DIR_IMAGE}</code>. | ||
| 3056 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> | ||
| 3057 | If <code class="filename">do_deploy</code> is not already in | ||
| 3058 | the shared state cache or if its input checksum | ||
| 3059 | (signature) has changed from when the output was | ||
| 3060 | cached, the task will be run to populate the shared | ||
| 3061 | state cache, after which the contents of the shared | ||
| 3062 | state cache is copied to | ||
| 3063 | <code class="filename">${DEPLOY_DIR_IMAGE}</code>. | ||
| 3064 | If <code class="filename">do_deploy</code> is in the shared | ||
| 3065 | state cache and its signature indicates that the | ||
| 3066 | cached output is still valid (i.e. if no | ||
| 3067 | relevant task inputs have changed), then the | ||
| 3068 | contents of the shared state cache will be copied | ||
| 3069 | directly to | ||
| 3070 | <code class="filename">${DEPLOY_DIR_IMAGE}</code> by the | ||
| 3071 | <code class="filename">do_deploy_setscene</code> task | ||
| 3072 | instead, skipping the | ||
| 3073 | <code class="filename">do_deploy</code> task. | ||
| 3074 | </div><p> | ||
| 3075 | </p></li><li class="listitem"><p> | ||
| 3076 | The following task definition is glue logic needed to | ||
| 3077 | make the previous settings effective: | ||
| 3078 | </p><pre class="literallayout"> | ||
| 3079 | python do_deploy_setscene () { | ||
| 3080 | sstate_setscene(d) | ||
| 3081 | } | ||
| 3082 | addtask do_deploy_setscene | ||
| 3083 | </pre><p> | ||
| 3084 | <code class="filename">sstate_setscene()</code> takes the flags | ||
| 3085 | above as input and accelerates the | ||
| 3086 | <code class="filename">do_deploy</code> task through the | ||
| 3087 | shared state cache if possible. | ||
| 3088 | If the task was accelerated, | ||
| 3089 | <code class="filename">sstate_setscene()</code> returns True. | ||
| 3090 | Otherwise, it returns False, and the normal | ||
| 3091 | <code class="filename">do_deploy</code> task runs. | ||
| 3092 | For more information, see the | ||
| 3093 | "<a class="ulink" href="http://www.yoctoproject.org/docs/2.5/bitbake-user-manual/bitbake-user-manual.html#setscene" target="_top">setscene</a>" | ||
| 3094 | section in the BitBake User Manual. | ||
| 3095 | </p></li><li class="listitem"><p> | ||
| 3096 | The <code class="filename">do_deploy[dirs] = "${DEPLOYDIR} ${B}"</code> | ||
| 3097 | line creates <code class="filename">${DEPLOYDIR}</code> and | ||
| 3098 | <code class="filename">${B}</code> before the | ||
| 3099 | <code class="filename">do_deploy</code> task runs, and also sets | ||
| 3100 | the current working directory of | ||
| 3101 | <code class="filename">do_deploy</code> to | ||
| 3102 | <code class="filename">${B}</code>. | ||
| 3103 | For more information, see the | ||
| 3104 | "<a class="ulink" href="http://www.yoctoproject.org/docs/2.5/bitbake-user-manual/bitbake-user-manual.html#variable-flags" target="_top">Variable Flags</a>" | ||
| 3105 | section in the BitBake User Manual. | ||
| 3106 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> | ||
| 3107 | In cases where | ||
| 3108 | <code class="filename">sstate-inputdirs</code> and | ||
| 3109 | <code class="filename">sstate-outputdirs</code> would be the | ||
| 3110 | same, you can use | ||
| 3111 | <code class="filename">sstate-plaindirs</code>. | ||
| 3112 | For example, to preserve the | ||
| 3113 | <code class="filename">${PKGD}</code> and | ||
| 3114 | <code class="filename">${PKGDEST}</code> output from the | ||
| 3115 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-tasks-package" target="_top"><code class="filename">do_package</code></a> | ||
| 3116 | task, use the following: | ||
| 3117 | <pre class="literallayout"> | ||
| 3118 | do_package[sstate-plaindirs] = "${PKGD} ${PKGDEST}" | ||
| 3119 | </pre></div><p> | ||
| 3120 | </p></li><li class="listitem"><p> | ||
| 3121 | <code class="filename">sstate-inputdirs</code> and | ||
| 3122 | <code class="filename">sstate-outputdirs</code> can also be used | ||
| 3123 | with multiple directories. | ||
| 3124 | For example, the following declares | ||
| 3125 | <code class="filename">PKGDESTWORK</code> and | ||
| 3126 | <code class="filename">SHLIBWORK</code> as shared state | ||
| 3127 | input directories, which populates the shared state | ||
| 3128 | cache, and <code class="filename">PKGDATA_DIR</code> and | ||
| 3129 | <code class="filename">SHLIBSDIR</code> as the corresponding | ||
| 3130 | shared state output directories: | ||
| 3131 | </p><pre class="literallayout"> | ||
| 3132 | do_package[sstate-inputdirs] = "${PKGDESTWORK} ${SHLIBSWORKDIR}" | ||
| 3133 | do_package[sstate-outputdirs] = "${PKGDATA_DIR} ${SHLIBSDIR}" | ||
| 3134 | </pre><p> | ||
| 3135 | </p></li><li class="listitem"><p> | ||
| 3136 | These methods also include the ability to take a | ||
| 3137 | lockfile when manipulating shared state directory | ||
| 3138 | structures, for cases where file additions or removals | ||
| 3139 | are sensitive: | ||
| 3140 | </p><pre class="literallayout"> | ||
| 3141 | do_package[sstate-lockfile] = "${PACKAGELOCK}" | ||
| 3142 | </pre><p> | ||
| 3143 | </p></li></ul></div><p> | ||
| 3144 | </p><p> | ||
| 3145 | Behind the scenes, the shared state code works by looking in | ||
| 3146 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-SSTATE_DIR" target="_top"><code class="filename">SSTATE_DIR</code></a> | ||
| 3147 | and | ||
| 3148 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-SSTATE_MIRRORS" target="_top"><code class="filename">SSTATE_MIRRORS</code></a> | ||
| 3149 | for shared state files. | ||
| 3150 | Here is an example: | ||
| 3151 | </p><pre class="literallayout"> | ||
| 3152 | SSTATE_MIRRORS ?= "\ | ||
| 3153 | file://.* http://someserver.tld/share/sstate/PATH;downloadfilename=PATH \n \ | ||
| 3154 | file://.* file:///some/local/dir/sstate/PATH" | ||
| 3155 | </pre><p> | ||
| 3156 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> | ||
| 3157 | The shared state directory | ||
| 3158 | (<code class="filename">SSTATE_DIR</code>) is organized into | ||
| 3159 | two-character subdirectories, where the subdirectory | ||
| 3160 | names are based on the first two characters of the hash. | ||
| 3161 | If the shared state directory structure for a mirror has the | ||
| 3162 | same structure as <code class="filename">SSTATE_DIR</code>, you must | ||
| 3163 | specify "PATH" as part of the URI to enable the build system | ||
| 3164 | to map to the appropriate subdirectory. | ||
| 3165 | </div><p> | ||
| 3166 | </p><p> | ||
| 3167 | The shared state package validity can be detected just by | ||
| 3168 | looking at the filename since the filename contains the task | ||
| 3169 | checksum (or signature) as described earlier in this section. | ||
| 3170 | If a valid shared state package is found, the build process | ||
| 3171 | downloads it and uses it to accelerate the task. | ||
| 3172 | </p><p> | ||
| 3173 | The build processes use the <code class="filename">*_setscene</code> | ||
| 3174 | tasks for the task acceleration phase. | ||
| 3175 | BitBake goes through this phase before the main execution | ||
| 3176 | code and tries to accelerate any tasks for which it can find | ||
| 3177 | shared state packages. | ||
| 3178 | If a shared state package for a task is available, the | ||
| 3179 | shared state package is used. | ||
| 3180 | This means the task and any tasks on which it is dependent | ||
| 3181 | are not executed. | ||
| 3182 | </p><p> | ||
| 3183 | As a real world example, the aim is when building an IPK-based | ||
| 3184 | image, only the | ||
| 3185 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-tasks-package_write_ipk" target="_top"><code class="filename">do_package_write_ipk</code></a> | ||
| 3186 | tasks would have their shared state packages fetched and | ||
| 3187 | extracted. | ||
| 3188 | Since the sysroot is not used, it would never get extracted. | ||
| 3189 | This is another reason why a task-based approach is preferred | ||
| 3190 | over a recipe-based approach, which would have to install the | ||
| 3191 | output from every task. | ||
| 3192 | </p></div><div class="section" title="3.3.4. Tips and Tricks"><div class="titlepage"><div><div><h3 class="title" id="tips-and-tricks">3.3.4. Tips and Tricks<span class="permalink"><a alt="Permalink" title="Permalink" href="#tips-and-tricks">¶</a></span></h3></div></div></div><p> | ||
| 3193 | The code in the build system that supports incremental builds | ||
| 3194 | is not simple code. | ||
| 3195 | This section presents some tips and tricks that help you work | ||
| 3196 | around issues related to shared state code. | ||
| 3197 | </p><div class="section" title="3.3.4.1. Debugging"><div class="titlepage"><div><div><h4 class="title" id="overview-debugging">3.3.4.1. Debugging<span class="permalink"><a alt="Permalink" title="Permalink" href="#overview-debugging">¶</a></span></h4></div></div></div><p> | ||
| 3198 | Seeing what metadata went into creating the input signature | ||
| 3199 | of a shared state (sstate) task can be a useful debugging | ||
| 3200 | aid. | ||
| 3201 | This information is available in signature information | ||
| 3202 | (<code class="filename">siginfo</code>) files in | ||
| 3203 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-SSTATE_DIR" target="_top"><code class="filename">SSTATE_DIR</code></a>. | ||
| 3204 | For information on how to view and interpret information in | ||
| 3205 | <code class="filename">siginfo</code> files, see the | ||
| 3206 | "<a class="ulink" href="http://www.yoctoproject.org/docs/2.5/dev-manual/dev-manual.html#dev-viewing-task-variable-dependencies" target="_top">Viewing Task Variable Dependencies</a>" | ||
| 3207 | section in the Yocto Project Development Tasks Manual. | ||
| 3208 | </p></div><div class="section" title="3.3.4.2. Invalidating Shared State"><div class="titlepage"><div><div><h4 class="title" id="invalidating-shared-state">3.3.4.2. Invalidating Shared State<span class="permalink"><a alt="Permalink" title="Permalink" href="#invalidating-shared-state">¶</a></span></h4></div></div></div><p> | ||
| 3209 | The OpenEmbedded build system uses checksums and shared | ||
| 3210 | state cache to avoid unnecessarily rebuilding tasks. | ||
| 3211 | Collectively, this scheme is known as "shared state code." | ||
| 3212 | </p><p> | ||
| 3213 | As with all schemes, this one has some drawbacks. | ||
| 3214 | It is possible that you could make implicit changes to your | ||
| 3215 | code that the checksum calculations do not take into | ||
| 3216 | account. | ||
| 3217 | These implicit changes affect a task's output but do not | ||
| 3218 | trigger the shared state code into rebuilding a recipe. | ||
| 3219 | Consider an example during which a tool changes its output. | ||
| 3220 | Assume that the output of <code class="filename">rpmdeps</code> | ||
| 3221 | changes. | ||
| 3222 | The result of the change should be that all the | ||
| 3223 | <code class="filename">package</code> and | ||
| 3224 | <code class="filename">package_write_rpm</code> shared state cache | ||
| 3225 | items become invalid. | ||
| 3226 | However, because the change to the output is | ||
| 3227 | external to the code and therefore implicit, | ||
| 3228 | the associated shared state cache items do not become | ||
| 3229 | invalidated. | ||
| 3230 | In this case, the build process uses the cached items | ||
| 3231 | rather than running the task again. | ||
| 3232 | Obviously, these types of implicit changes can cause | ||
| 3233 | problems. | ||
| 3234 | </p><p> | ||
| 3235 | To avoid these problems during the build, you need to | ||
| 3236 | understand the effects of any changes you make. | ||
| 3237 | Realize that changes you make directly to a function | ||
| 3238 | are automatically factored into the checksum calculation. | ||
| 3239 | Thus, these explicit changes invalidate the associated | ||
| 3240 | area of shared state cache. | ||
| 3241 | However, you need to be aware of any implicit changes that | ||
| 3242 | are not obvious changes to the code and could affect | ||
| 3243 | the output of a given task. | ||
| 3244 | </p><p> | ||
| 3245 | When you identify an implicit change, you can easily | ||
| 3246 | take steps to invalidate the cache and force the tasks | ||
| 3247 | to run. | ||
| 3248 | The steps you can take are as simple as changing a | ||
| 3249 | function's comments in the source code. | ||
| 3250 | For example, to invalidate package shared state files, | ||
| 3251 | change the comment statements of | ||
| 3252 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-tasks-package" target="_top"><code class="filename">do_package</code></a> | ||
| 3253 | or the comments of one of the functions it calls. | ||
| 3254 | Even though the change is purely cosmetic, it causes the | ||
| 3255 | checksum to be recalculated and forces the OpenEmbedded | ||
| 3256 | build system to run the task again. | ||
| 3257 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> | ||
| 3258 | For an example of a commit that makes a cosmetic | ||
| 3259 | change to invalidate shared state, see this | ||
| 3260 | <a class="ulink" href="http://git.yoctoproject.org/cgit.cgi/poky/commit/meta/classes/package.bbclass?id=737f8bbb4f27b4837047cb9b4fbfe01dfde36d54" target="_top">commit</a>. | ||
| 3261 | </div><p> | ||
| 3262 | </p></div></div></div><div class="section" title="3.4. Automatically Added Runtime Dependencies"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="automatically-added-runtime-dependencies">3.4. Automatically Added Runtime Dependencies<span class="permalink"><a alt="Permalink" title="Permalink" href="#automatically-added-runtime-dependencies">¶</a></span></h2></div></div></div><p> | ||
| 3263 | The OpenEmbedded build system automatically adds common types of | ||
| 3264 | runtime dependencies between packages, which means that you do not | ||
| 3265 | need to explicitly declare the packages using | ||
| 3266 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-RDEPENDS" target="_top"><code class="filename">RDEPENDS</code></a>. | ||
| 3267 | Three automatic mechanisms exist (<code class="filename">shlibdeps</code>, | ||
| 3268 | <code class="filename">pcdeps</code>, and <code class="filename">depchains</code>) | ||
| 3269 | that handle shared libraries, package configuration (pkg-config) | ||
| 3270 | modules, and <code class="filename">-dev</code> and | ||
| 3271 | <code class="filename">-dbg</code> packages, respectively. | ||
| 3272 | For other types of runtime dependencies, you must manually declare | ||
| 3273 | the dependencies. | ||
| 3274 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> | ||
| 3275 | <code class="filename">shlibdeps</code>: | ||
| 3276 | During the | ||
| 3277 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-tasks-package" target="_top"><code class="filename">do_package</code></a> | ||
| 3278 | task of each recipe, all shared libraries installed by the | ||
| 3279 | recipe are located. | ||
| 3280 | For each shared library, the package that contains the | ||
| 3281 | shared library is registered as providing the shared | ||
| 3282 | library. | ||
| 3283 | More specifically, the package is registered as providing | ||
| 3284 | the | ||
| 3285 | <a class="ulink" href="https://en.wikipedia.org/wiki/Soname" target="_top">soname</a> | ||
| 3286 | of the library. | ||
| 3287 | The resulting shared-library-to-package mapping | ||
| 3288 | is saved globally in | ||
| 3289 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-PKGDATA_DIR" target="_top"><code class="filename">PKGDATA_DIR</code></a> | ||
| 3290 | by the | ||
| 3291 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-tasks-packagedata" target="_top"><code class="filename">do_packagedata</code></a> | ||
| 3292 | task.</p><p>Simultaneously, all executables and shared libraries | ||
| 3293 | installed by the recipe are inspected to see what shared | ||
| 3294 | libraries they link against. | ||
| 3295 | For each shared library dependency that is found, | ||
| 3296 | <code class="filename">PKGDATA_DIR</code> is queried to | ||
| 3297 | see if some package (likely from a different recipe) | ||
| 3298 | contains the shared library. | ||
| 3299 | If such a package is found, a runtime dependency is added | ||
| 3300 | from the package that depends on the shared library to the | ||
| 3301 | package that contains the library.</p><p>The automatically added runtime dependency also | ||
| 3302 | includes a version restriction. | ||
| 3303 | This version restriction specifies that at least the | ||
| 3304 | current version of the package that provides the shared | ||
| 3305 | library must be used, as if | ||
| 3306 | "<em class="replaceable"><code>package</code></em> (>= <em class="replaceable"><code>version</code></em>)" | ||
| 3307 | had been added to | ||
| 3308 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-RDEPENDS" target="_top"><code class="filename">RDEPENDS</code></a>. | ||
| 3309 | This forces an upgrade of the package containing the shared | ||
| 3310 | library when installing the package that depends on the | ||
| 3311 | library, if needed.</p><p>If you want to avoid a package being registered as | ||
| 3312 | providing a particular shared library (e.g. because the library | ||
| 3313 | is for internal use only), then add the library to | ||
| 3314 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-PRIVATE_LIBS" target="_top"><code class="filename">PRIVATE_LIBS</code></a> | ||
| 3315 | inside the package's recipe. | ||
| 3316 | </p></li><li class="listitem"><p> | ||
| 3317 | <code class="filename">pcdeps</code>: | ||
| 3318 | During the | ||
| 3319 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-tasks-package" target="_top"><code class="filename">do_package</code></a> | ||
| 3320 | task of each recipe, all pkg-config modules | ||
| 3321 | (<code class="filename">*.pc</code> files) installed by the recipe | ||
| 3322 | are located. | ||
| 3323 | For each module, the package that contains the module is | ||
| 3324 | registered as providing the module. | ||
| 3325 | The resulting module-to-package mapping is saved globally in | ||
| 3326 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-PKGDATA_DIR" target="_top"><code class="filename">PKGDATA_DIR</code></a> | ||
| 3327 | by the | ||
| 3328 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-tasks-packagedata" target="_top"><code class="filename">do_packagedata</code></a> | ||
| 3329 | task.</p><p>Simultaneously, all pkg-config modules installed by | ||
| 3330 | the recipe are inspected to see what other pkg-config | ||
| 3331 | modules they depend on. | ||
| 3332 | A module is seen as depending on another module if it | ||
| 3333 | contains a "Requires:" line that specifies the other module. | ||
| 3334 | For each module dependency, | ||
| 3335 | <code class="filename">PKGDATA_DIR</code> is queried to see if some | ||
| 3336 | package contains the module. | ||
| 3337 | If such a package is found, a runtime dependency is added | ||
| 3338 | from the package that depends on the module to the package | ||
| 3339 | that contains the module. | ||
| 3340 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> | ||
| 3341 | The <code class="filename">pcdeps</code> mechanism most often | ||
| 3342 | infers dependencies between <code class="filename">-dev</code> | ||
| 3343 | packages. | ||
| 3344 | </div><p> | ||
| 3345 | </p></li><li class="listitem"><p> | ||
| 3346 | <code class="filename">depchains</code>: | ||
| 3347 | If a package <code class="filename">foo</code> depends on a package | ||
| 3348 | <code class="filename">bar</code>, then <code class="filename">foo-dev</code> | ||
| 3349 | and <code class="filename">foo-dbg</code> are also made to depend on | ||
| 3350 | <code class="filename">bar-dev</code> and | ||
| 3351 | <code class="filename">bar-dbg</code>, respectively. | ||
| 3352 | Taking the <code class="filename">-dev</code> packages as an | ||
| 3353 | example, the <code class="filename">bar-dev</code> package might | ||
| 3354 | provide headers and shared library symlinks needed by | ||
| 3355 | <code class="filename">foo-dev</code>, which shows the need | ||
| 3356 | for a dependency between the packages.</p><p>The dependencies added by | ||
| 3357 | <code class="filename">depchains</code> are in the form of | ||
| 3358 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-RRECOMMENDS" target="_top"><code class="filename">RRECOMMENDS</code></a>. | ||
| 3359 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> | ||
| 3360 | By default, <code class="filename">foo-dev</code> also has an | ||
| 3361 | <code class="filename">RDEPENDS</code>-style dependency on | ||
| 3362 | <code class="filename">foo</code>, because the default value of | ||
| 3363 | <code class="filename">RDEPENDS_${PN}-dev</code> (set in | ||
| 3364 | <code class="filename">bitbake.conf</code>) includes | ||
| 3365 | "${PN}". | ||
| 3366 | </div><p>To ensure that the dependency chain is never broken, | ||
| 3367 | <code class="filename">-dev</code> and <code class="filename">-dbg</code> | ||
| 3368 | packages are always generated by default, even if the | ||
| 3369 | packages turn out to be empty. | ||
| 3370 | See the | ||
| 3371 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-ALLOW_EMPTY" target="_top"><code class="filename">ALLOW_EMPTY</code></a> | ||
| 3372 | variable for more information. | ||
| 3373 | </p></li></ul></div><p> | ||
| 3374 | </p><p> | ||
| 3375 | The <code class="filename">do_package</code> task depends on the | ||
| 3376 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-tasks-packagedata" target="_top"><code class="filename">do_packagedata</code></a> | ||
| 3377 | task of each recipe in | ||
| 3378 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-DEPENDS" target="_top"><code class="filename">DEPENDS</code></a> | ||
| 3379 | through use of a | ||
| 3380 | <code class="filename">[</code><a class="ulink" href="http://www.yoctoproject.org/docs/2.5/bitbake-user-manual/bitbake-user-manual.html#variable-flags" target="_top"><code class="filename">deptask</code></a><code class="filename">]</code> | ||
| 3381 | declaration, which guarantees that the required | ||
| 3382 | shared-library/module-to-package mapping information will be available | ||
| 3383 | when needed as long as <code class="filename">DEPENDS</code> has been | ||
| 3384 | correctly set. | ||
| 3385 | </p></div><div class="section" title="3.5. Fakeroot and Pseudo"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="fakeroot-and-pseudo">3.5. Fakeroot and Pseudo<span class="permalink"><a alt="Permalink" title="Permalink" href="#fakeroot-and-pseudo">¶</a></span></h2></div></div></div><p> | ||
| 3386 | Some tasks are easier to implement when allowed to perform certain | ||
| 3387 | operations that are normally reserved for the root user (e.g. | ||
| 3388 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-tasks-install" target="_top"><code class="filename">do_install</code></a>, | ||
| 3389 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-tasks-package_write_deb" target="_top"><code class="filename">do_package_write*</code></a>, | ||
| 3390 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-tasks-rootfs" target="_top"><code class="filename">do_rootfs</code></a>, | ||
| 3391 | and | ||
| 3392 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-tasks-image" target="_top"><code class="filename">do_image*</code></a>). | ||
| 3393 | For example, the <code class="filename">do_install</code> task benefits | ||
| 3394 | from being able to set the UID and GID of installed files to | ||
| 3395 | arbitrary values. | ||
| 3396 | </p><p> | ||
| 3397 | One approach to allowing tasks to perform root-only operations | ||
| 3398 | would be to require BitBake to run as root. | ||
| 3399 | However, this method is cumbersome and has security issues. | ||
| 3400 | The approach that is actually used is to run tasks that benefit | ||
| 3401 | from root privileges in a "fake" root environment. | ||
| 3402 | Within this environment, the task and its child processes believe | ||
| 3403 | that they are running as the root user, and see an internally | ||
| 3404 | consistent view of the filesystem. | ||
| 3405 | As long as generating the final output (e.g. a package or an image) | ||
| 3406 | does not require root privileges, the fact that some earlier | ||
| 3407 | steps ran in a fake root environment does not cause problems. | ||
| 3408 | </p><p> | ||
| 3409 | The capability to run tasks in a fake root environment is known as | ||
| 3410 | "<a class="ulink" href="http://man.he.net/man1/fakeroot" target="_top">fakeroot</a>", | ||
| 3411 | which is derived from the BitBake keyword/variable | ||
| 3412 | flag that requests a fake root environment for a task. | ||
| 3413 | </p><p> | ||
| 3414 | In the OpenEmbedded build system, the program that implements | ||
| 3415 | fakeroot is known as Pseudo. | ||
| 3416 | Pseudo overrides system calls by using the environment variable | ||
| 3417 | <code class="filename">LD_PRELOAD</code>, which results in the illusion | ||
| 3418 | of running as root. | ||
| 3419 | To keep track of "fake" file ownership and permissions resulting | ||
| 3420 | from operations that require root permissions, Pseudo uses | ||
| 3421 | an SQLite 3 database. | ||
| 3422 | This database is stored in | ||
| 3423 | <code class="filename">${</code><a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-WORKDIR" target="_top"><code class="filename">WORKDIR</code></a><code class="filename">}/pseudo/files.db</code> | ||
| 3424 | for individual recipes. | ||
| 3425 | Storing the database in a file as opposed to in memory | ||
| 3426 | gives persistence between tasks and builds, which is not | ||
| 3427 | accomplished using fakeroot. | ||
| 3428 | </p><div class="note" title="Caution" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Caution</h3> | ||
| 3429 | If you add your own task that manipulates the same files or | ||
| 3430 | directories as a fakeroot task, then that task also needs to | ||
| 3431 | run under fakeroot. | ||
| 3432 | Otherwise, the task cannot run root-only operations, and | ||
| 3433 | cannot see the fake file ownership and permissions set by the | ||
| 3434 | other task. | ||
| 3435 | You need to also add a dependency on | ||
| 3436 | <code class="filename">virtual/fakeroot-native:do_populate_sysroot</code>, | ||
| 3437 | giving the following: | ||
| 3438 | <pre class="literallayout"> | ||
| 3439 | fakeroot do_mytask () { | ||
| 3440 | ... | ||
| 3441 | } | ||
| 3442 | do_mytask[depends] += "virtual/fakeroot-native:do_populate_sysroot" | ||
| 3443 | </pre></div><p> | ||
| 3444 | For more information, see the | ||
| 3445 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/bitbake-user-manual/bitbake-user-manual.html#var-FAKEROOT" target="_top"><code class="filename">FAKEROOT*</code></a> | ||
| 3446 | variables in the BitBake User Manual. | ||
| 3447 | You can also reference the | ||
| 3448 | "<a class="ulink" href="http://www.ibm.com/developerworks/opensource/library/os-aapseudo1/index.html" target="_top">Pseudo</a>" | ||
| 3449 | and | ||
| 3450 | "<a class="ulink" href="https://github.com/wrpseudo/pseudo/wiki/WhyNotFakeroot" target="_top">Why Not Fakeroot?</a>" | ||
| 3451 | articles for background information on Pseudo. | ||
| 3452 | </p></div><div class="section" title="3.6. Wayland"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="wayland">3.6. Wayland<span class="permalink"><a alt="Permalink" title="Permalink" href="#wayland">¶</a></span></h2></div></div></div><p> | ||
| 3453 | <a class="ulink" href="http://en.wikipedia.org/wiki/Wayland_(display_server_protocol)" target="_top">Wayland</a> | ||
| 3454 | is a computer display server protocol that | ||
| 3455 | provides a method for compositing window managers to communicate | ||
| 3456 | directly with applications and video hardware and expects them to | ||
| 3457 | communicate with input hardware using other libraries. | ||
| 3458 | Using Wayland with supporting targets can result in better control | ||
| 3459 | over graphics frame rendering than an application might otherwise | ||
| 3460 | achieve. | ||
| 3461 | </p><p> | ||
| 3462 | The Yocto Project provides the Wayland protocol libraries and the | ||
| 3463 | reference | ||
| 3464 | <a class="ulink" href="http://en.wikipedia.org/wiki/Wayland_(display_server_protocol)#Weston" target="_top">Weston</a> | ||
| 3465 | compositor as part of its release. | ||
| 3466 | This section describes what you need to do to implement Wayland and | ||
| 3467 | use the compositor when building an image for a supporting target. | ||
| 3468 | </p><div class="section" title="3.6.1. Support"><div class="titlepage"><div><div><h3 class="title" id="wayland-support">3.6.1. Support<span class="permalink"><a alt="Permalink" title="Permalink" href="#wayland-support">¶</a></span></h3></div></div></div><p> | ||
| 3469 | The Wayland protocol libraries and the reference Weston | ||
| 3470 | compositor ship as integrated packages in the | ||
| 3471 | <code class="filename">meta</code> layer of the | ||
| 3472 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#source-directory" target="_top">Source Directory</a>. | ||
| 3473 | Specifically, you can find the recipes that build both Wayland | ||
| 3474 | and Weston at | ||
| 3475 | <code class="filename">meta/recipes-graphics/wayland</code>. | ||
| 3476 | </p><p> | ||
| 3477 | You can build both the Wayland and Weston packages for use only | ||
| 3478 | with targets that accept the | ||
| 3479 | <a class="ulink" href="https://en.wikipedia.org/wiki/Mesa_(computer_graphics)" target="_top">Mesa 3D and Direct Rendering Infrastructure</a>, | ||
| 3480 | which is also known as Mesa DRI. | ||
| 3481 | This implies that you cannot build and use the packages if your | ||
| 3482 | target uses, for example, the | ||
| 3483 | <span class="trademark">Intel</span>® Embedded Media | ||
| 3484 | and Graphics Driver | ||
| 3485 | (<span class="trademark">Intel</span>® EMGD) that | ||
| 3486 | overrides Mesa DRI. | ||
| 3487 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> | ||
| 3488 | Due to lack of EGL support, Weston 1.0.3 will not run | ||
| 3489 | directly on the emulated QEMU hardware. | ||
| 3490 | However, this version of Weston will run under X emulation | ||
| 3491 | without issues. | ||
| 3492 | </div><p> | ||
| 3493 | </p></div><div class="section" title="3.6.2. Enabling Wayland in an Image"><div class="titlepage"><div><div><h3 class="title" id="enabling-wayland-in-an-image">3.6.2. Enabling Wayland in an Image<span class="permalink"><a alt="Permalink" title="Permalink" href="#enabling-wayland-in-an-image">¶</a></span></h3></div></div></div><p> | ||
| 3494 | To enable Wayland, you need to enable it to be built and enable | ||
| 3495 | it to be included in the image. | ||
| 3496 | </p><div class="section" title="3.6.2.1. Building"><div class="titlepage"><div><div><h4 class="title" id="enable-building">3.6.2.1. Building<span class="permalink"><a alt="Permalink" title="Permalink" href="#enable-building">¶</a></span></h4></div></div></div><p> | ||
| 3497 | To cause Mesa to build the <code class="filename">wayland-egl</code> | ||
| 3498 | platform and Weston to build Wayland with Kernel Mode | ||
| 3499 | Setting | ||
| 3500 | (<a class="ulink" href="https://wiki.archlinux.org/index.php/Kernel_Mode_Setting" target="_top">KMS</a>) | ||
| 3501 | support, include the "wayland" flag in the | ||
| 3502 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-DISTRO_FEATURES" target="_top"><code class="filename">DISTRO_FEATURES</code></a> | ||
| 3503 | statement in your <code class="filename">local.conf</code> file: | ||
| 3504 | </p><pre class="literallayout"> | ||
| 3505 | DISTRO_FEATURES_append = " wayland" | ||
| 3506 | </pre><p> | ||
| 3507 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> | ||
| 3508 | If X11 has been enabled elsewhere, Weston will build | ||
| 3509 | Wayland with X11 support | ||
| 3510 | </div><p> | ||
| 3511 | </p></div><div class="section" title="3.6.2.2. Installing"><div class="titlepage"><div><div><h4 class="title" id="enable-installation-in-an-image">3.6.2.2. Installing<span class="permalink"><a alt="Permalink" title="Permalink" href="#enable-installation-in-an-image">¶</a></span></h4></div></div></div><p> | ||
| 3512 | To install the Wayland feature into an image, you must | ||
| 3513 | include the following | ||
| 3514 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-CORE_IMAGE_EXTRA_INSTALL" target="_top"><code class="filename">CORE_IMAGE_EXTRA_INSTALL</code></a> | ||
| 3515 | statement in your <code class="filename">local.conf</code> file: | ||
| 3516 | </p><pre class="literallayout"> | ||
| 3517 | CORE_IMAGE_EXTRA_INSTALL += "wayland weston" | ||
| 3518 | </pre><p> | ||
| 3519 | </p></div></div><div class="section" title="3.6.3. Running Weston"><div class="titlepage"><div><div><h3 class="title" id="running-weston">3.6.3. Running Weston<span class="permalink"><a alt="Permalink" title="Permalink" href="#running-weston">¶</a></span></h3></div></div></div><p> | ||
| 3520 | To run Weston inside X11, enabling it as described earlier and | ||
| 3521 | building a Sato image is sufficient. | ||
| 3522 | If you are running your image under Sato, a Weston Launcher | ||
| 3523 | appears in the "Utility" category. | ||
| 3524 | </p><p> | ||
| 3525 | Alternatively, you can run Weston through the command-line | ||
| 3526 | interpretor (CLI), which is better suited for development work. | ||
| 3527 | To run Weston under the CLI, you need to do the following after | ||
| 3528 | your image is built: | ||
| 3529 | </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p> | ||
| 3530 | Run these commands to export | ||
| 3531 | <code class="filename">XDG_RUNTIME_DIR</code>: | ||
| 3532 | </p><pre class="literallayout"> | ||
| 3533 | mkdir -p /tmp/$USER-weston | ||
| 3534 | chmod 0700 /tmp/$USER-weston | ||
| 3535 | export XDG_RUNTIME_DIR=/tmp/$USER-weston | ||
| 3536 | </pre><p> | ||
| 3537 | </p></li><li class="listitem"><p> | ||
| 3538 | Launch Weston in the shell: | ||
| 3539 | </p><pre class="literallayout"> | ||
| 3540 | weston | ||
| 3541 | </pre></li></ol></div><p> | ||
| 3542 | </p></div></div><div class="section" title="3.7. Licenses"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="overview-licenses">3.7. Licenses<span class="permalink"><a alt="Permalink" title="Permalink" href="#overview-licenses">¶</a></span></h2></div></div></div><p> | ||
| 3543 | This section describes the mechanism by which the OpenEmbedded | ||
| 3544 | build system tracks changes to licensing text. | ||
| 3545 | The section also describes how to enable commercially licensed | ||
| 3546 | recipes, which by default are disabled. | ||
| 3547 | </p><p> | ||
| 3548 | For information that can help you maintain compliance with | ||
| 3549 | various open source licensing during the lifecycle of the product, | ||
| 3550 | see the | ||
| 3551 | "<a class="ulink" href="http://www.yoctoproject.org/docs/2.5/dev-manual/dev-manual.html#maintaining-open-source-license-compliance-during-your-products-lifecycle" target="_top">Maintaining Open Source License Compliance During Your Project's Lifecycle</a>" | ||
| 3552 | section in the Yocto Project Development Tasks Manual. | ||
| 3553 | </p><div class="section" title="3.7.1. Tracking License Changes"><div class="titlepage"><div><div><h3 class="title" id="usingpoky-configuring-LIC_FILES_CHKSUM">3.7.1. Tracking License Changes<span class="permalink"><a alt="Permalink" title="Permalink" href="#usingpoky-configuring-LIC_FILES_CHKSUM">¶</a></span></h3></div></div></div><p> | ||
| 3554 | The license of an upstream project might change in the future. | ||
| 3555 | In order to prevent these changes going unnoticed, the | ||
| 3556 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-LIC_FILES_CHKSUM" target="_top"><code class="filename">LIC_FILES_CHKSUM</code></a> | ||
| 3557 | variable tracks changes to the license text. The checksums are | ||
| 3558 | validated at the end of the configure step, and if the | ||
| 3559 | checksums do not match, the build will fail. | ||
| 3560 | </p><div class="section" title="3.7.1.1. Specifying the LIC_FILES_CHKSUM Variable"><div class="titlepage"><div><div><h4 class="title" id="usingpoky-specifying-LIC_FILES_CHKSUM">3.7.1.1. Specifying the <code class="filename">LIC_FILES_CHKSUM</code> Variable<span class="permalink"><a alt="Permalink" title="Permalink" href="#usingpoky-specifying-LIC_FILES_CHKSUM">¶</a></span></h4></div></div></div><p> | ||
| 3561 | The <code class="filename">LIC_FILES_CHKSUM</code> | ||
| 3562 | variable contains checksums of the license text in the | ||
| 3563 | source code for the recipe. | ||
| 3564 | Following is an example of how to specify | ||
| 3565 | <code class="filename">LIC_FILES_CHKSUM</code>: | ||
| 3566 | </p><pre class="literallayout"> | ||
| 3567 | LIC_FILES_CHKSUM = "file://COPYING;md5=xxxx \ | ||
| 3568 | file://licfile1.txt;beginline=5;endline=29;md5=yyyy \ | ||
| 3569 | file://licfile2.txt;endline=50;md5=zzzz \ | ||
| 3570 | ..." | ||
| 3571 | </pre><p> | ||
| 3572 | </p><div class="note" title="Notes" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Notes</h3><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> | ||
| 3573 | When using "beginline" and "endline", realize | ||
| 3574 | that line numbering begins with one and not | ||
| 3575 | zero. | ||
| 3576 | Also, the included lines are inclusive (i.e. | ||
| 3577 | lines five through and including 29 in the | ||
| 3578 | previous example for | ||
| 3579 | <code class="filename">licfile1.txt</code>). | ||
| 3580 | </p></li><li class="listitem"><p> | ||
| 3581 | When a license check fails, the selected license | ||
| 3582 | text is included as part of the QA message. | ||
| 3583 | Using this output, you can determine the exact | ||
| 3584 | start and finish for the needed license text. | ||
| 3585 | </p></li></ul></div></div><p> | ||
| 3586 | </p><p> | ||
| 3587 | The build system uses the | ||
| 3588 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-S" target="_top"><code class="filename">S</code></a> | ||
| 3589 | variable as the default directory when searching files | ||
| 3590 | listed in <code class="filename">LIC_FILES_CHKSUM</code>. | ||
| 3591 | The previous example employs the default directory. | ||
| 3592 | </p><p> | ||
| 3593 | Consider this next example: | ||
| 3594 | </p><pre class="literallayout"> | ||
| 3595 | LIC_FILES_CHKSUM = "file://src/ls.c;beginline=5;endline=16;\ | ||
| 3596 | md5=bb14ed3c4cda583abc85401304b5cd4e" | ||
| 3597 | LIC_FILES_CHKSUM = "file://${WORKDIR}/license.html;md5=5c94767cedb5d6987c902ac850ded2c6" | ||
| 3598 | </pre><p> | ||
| 3599 | </p><p> | ||
| 3600 | The first line locates a file in | ||
| 3601 | <code class="filename">${S}/src/ls.c</code> and isolates lines five | ||
| 3602 | through 16 as license text. | ||
| 3603 | The second line refers to a file in | ||
| 3604 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-WORKDIR" target="_top"><code class="filename">WORKDIR</code></a>. | ||
| 3605 | </p><p> | ||
| 3606 | Note that <code class="filename">LIC_FILES_CHKSUM</code> variable is | ||
| 3607 | mandatory for all recipes, unless the | ||
| 3608 | <code class="filename">LICENSE</code> variable is set to "CLOSED". | ||
| 3609 | </p></div><div class="section" title="3.7.1.2. Explanation of Syntax"><div class="titlepage"><div><div><h4 class="title" id="usingpoky-LIC_FILES_CHKSUM-explanation-of-syntax">3.7.1.2. Explanation of Syntax<span class="permalink"><a alt="Permalink" title="Permalink" href="#usingpoky-LIC_FILES_CHKSUM-explanation-of-syntax">¶</a></span></h4></div></div></div><p> | ||
| 3610 | As mentioned in the previous section, the | ||
| 3611 | <code class="filename">LIC_FILES_CHKSUM</code> variable lists all | ||
| 3612 | the important files that contain the license text for the | ||
| 3613 | source code. | ||
| 3614 | It is possible to specify a checksum for an entire file, | ||
| 3615 | or a specific section of a file (specified by beginning and | ||
| 3616 | ending line numbers with the "beginline" and "endline" | ||
| 3617 | parameters, respectively). | ||
| 3618 | The latter is useful for source files with a license | ||
| 3619 | notice header, README documents, and so forth. | ||
| 3620 | If you do not use the "beginline" parameter, then it is | ||
| 3621 | assumed that the text begins on the first line of the file. | ||
| 3622 | Similarly, if you do not use the "endline" parameter, | ||
| 3623 | it is assumed that the license text ends with the last | ||
| 3624 | line of the file. | ||
| 3625 | </p><p> | ||
| 3626 | The "md5" parameter stores the md5 checksum of the license | ||
| 3627 | text. | ||
| 3628 | If the license text changes in any way as compared to | ||
| 3629 | this parameter then a mismatch occurs. | ||
| 3630 | This mismatch triggers a build failure and notifies | ||
| 3631 | the developer. | ||
| 3632 | Notification allows the developer to review and address | ||
| 3633 | the license text changes. | ||
| 3634 | Also note that if a mismatch occurs during the build, | ||
| 3635 | the correct md5 checksum is placed in the build log and | ||
| 3636 | can be easily copied to the recipe. | ||
| 3637 | </p><p> | ||
| 3638 | There is no limit to how many files you can specify using | ||
| 3639 | the <code class="filename">LIC_FILES_CHKSUM</code> variable. | ||
| 3640 | Generally, however, every project requires a few | ||
| 3641 | specifications for license tracking. | ||
| 3642 | Many projects have a "COPYING" file that stores the | ||
| 3643 | license information for all the source code files. | ||
| 3644 | This practice allows you to just track the "COPYING" | ||
| 3645 | file as long as it is kept up to date. | ||
| 3646 | </p><div class="note" title="Tips" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tips</h3><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> | ||
| 3647 | If you specify an empty or invalid "md5" | ||
| 3648 | parameter, BitBake returns an md5 mis-match | ||
| 3649 | error and displays the correct "md5" parameter | ||
| 3650 | value during the build. | ||
| 3651 | The correct parameter is also captured in | ||
| 3652 | the build log. | ||
| 3653 | </p></li><li class="listitem"><p> | ||
| 3654 | If the whole file contains only license text, | ||
| 3655 | you do not need to use the "beginline" and | ||
| 3656 | "endline" parameters. | ||
| 3657 | </p></li></ul></div></div><p> | ||
| 3658 | </p></div></div><div class="section" title="3.7.2. Enabling Commercially Licensed Recipes"><div class="titlepage"><div><div><h3 class="title" id="enabling-commercially-licensed-recipes">3.7.2. Enabling Commercially Licensed Recipes<span class="permalink"><a alt="Permalink" title="Permalink" href="#enabling-commercially-licensed-recipes">¶</a></span></h3></div></div></div><p> | ||
| 3659 | By default, the OpenEmbedded build system disables | ||
| 3660 | components that have commercial or other special licensing | ||
| 3661 | requirements. | ||
| 3662 | Such requirements are defined on a | ||
| 3663 | recipe-by-recipe basis through the | ||
| 3664 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-LICENSE_FLAGS" target="_top"><code class="filename">LICENSE_FLAGS</code></a> | ||
| 3665 | variable definition in the affected recipe. | ||
| 3666 | For instance, the | ||
| 3667 | <code class="filename">poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly</code> | ||
| 3668 | recipe contains the following statement: | ||
| 3669 | </p><pre class="literallayout"> | ||
| 3670 | LICENSE_FLAGS = "commercial" | ||
| 3671 | </pre><p> | ||
| 3672 | Here is a slightly more complicated example that contains both | ||
| 3673 | an explicit recipe name and version (after variable expansion): | ||
| 3674 | </p><pre class="literallayout"> | ||
| 3675 | LICENSE_FLAGS = "license_${PN}_${PV}" | ||
| 3676 | </pre><p> | ||
| 3677 | In order for a component restricted by a | ||
| 3678 | <code class="filename">LICENSE_FLAGS</code> definition to be enabled and | ||
| 3679 | included in an image, it needs to have a matching entry in the | ||
| 3680 | global | ||
| 3681 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-LICENSE_FLAGS_WHITELIST" target="_top"><code class="filename">LICENSE_FLAGS_WHITELIST</code></a> | ||
| 3682 | variable, which is a variable typically defined in your | ||
| 3683 | <code class="filename">local.conf</code> file. | ||
| 3684 | For example, to enable the | ||
| 3685 | <code class="filename">poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly</code> | ||
| 3686 | package, you could add either the string | ||
| 3687 | "commercial_gst-plugins-ugly" or the more general string | ||
| 3688 | "commercial" to <code class="filename">LICENSE_FLAGS_WHITELIST</code>. | ||
| 3689 | See the | ||
| 3690 | "<a class="link" href="#license-flag-matching" title="3.7.2.1. License Flag Matching">License Flag Matching</a>" | ||
| 3691 | section for a full | ||
| 3692 | explanation of how <code class="filename">LICENSE_FLAGS</code> matching | ||
| 3693 | works. | ||
| 3694 | Here is the example: | ||
| 3695 | </p><pre class="literallayout"> | ||
| 3696 | LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly" | ||
| 3697 | </pre><p> | ||
| 3698 | Likewise, to additionally enable the package built from the | ||
| 3699 | recipe containing | ||
| 3700 | <code class="filename">LICENSE_FLAGS = "license_${PN}_${PV}"</code>, | ||
| 3701 | and assuming that the actual recipe name was | ||
| 3702 | <code class="filename">emgd_1.10.bb</code>, the following string would | ||
| 3703 | enable that package as well as the original | ||
| 3704 | <code class="filename">gst-plugins-ugly</code> package: | ||
| 3705 | </p><pre class="literallayout"> | ||
| 3706 | LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly license_emgd_1.10" | ||
| 3707 | </pre><p> | ||
| 3708 | As a convenience, you do not need to specify the complete | ||
| 3709 | license string in the whitelist for every package. | ||
| 3710 | You can use an abbreviated form, which consists | ||
| 3711 | of just the first portion or portions of the license | ||
| 3712 | string before the initial underscore character or characters. | ||
| 3713 | A partial string will match any license that contains the | ||
| 3714 | given string as the first portion of its license. | ||
| 3715 | For example, the following whitelist string will also match | ||
| 3716 | both of the packages previously mentioned as well as any other | ||
| 3717 | packages that have licenses starting with "commercial" or | ||
| 3718 | "license". | ||
| 3719 | </p><pre class="literallayout"> | ||
| 3720 | LICENSE_FLAGS_WHITELIST = "commercial license" | ||
| 3721 | </pre><p> | ||
| 3722 | </p><div class="section" title="3.7.2.1. License Flag Matching"><div class="titlepage"><div><div><h4 class="title" id="license-flag-matching">3.7.2.1. License Flag Matching<span class="permalink"><a alt="Permalink" title="Permalink" href="#license-flag-matching">¶</a></span></h4></div></div></div><p> | ||
| 3723 | License flag matching allows you to control what recipes | ||
| 3724 | the OpenEmbedded build system includes in the build. | ||
| 3725 | Fundamentally, the build system attempts to match | ||
| 3726 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-LICENSE_FLAGS" target="_top"><code class="filename">LICENSE_FLAGS</code></a> | ||
| 3727 | strings found in recipes against | ||
| 3728 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-LICENSE_FLAGS_WHITELIST" target="_top"><code class="filename">LICENSE_FLAGS_WHITELIST</code></a> | ||
| 3729 | strings found in the whitelist. | ||
| 3730 | A match causes the build system to include a recipe in the | ||
| 3731 | build, while failure to find a match causes the build | ||
| 3732 | system to exclude a recipe. | ||
| 3733 | </p><p> | ||
| 3734 | In general, license flag matching is simple. | ||
| 3735 | However, understanding some concepts will help you | ||
| 3736 | correctly and effectively use matching. | ||
| 3737 | </p><p> | ||
| 3738 | Before a flag | ||
| 3739 | defined by a particular recipe is tested against the | ||
| 3740 | contents of the whitelist, the expanded string | ||
| 3741 | <code class="filename">_${PN}</code> is appended to the flag. | ||
| 3742 | This expansion makes each | ||
| 3743 | <code class="filename">LICENSE_FLAGS</code> value recipe-specific. | ||
| 3744 | After expansion, the string is then matched against the | ||
| 3745 | whitelist. | ||
| 3746 | Thus, specifying | ||
| 3747 | <code class="filename">LICENSE_FLAGS = "commercial"</code> | ||
| 3748 | in recipe "foo", for example, results in the string | ||
| 3749 | <code class="filename">"commercial_foo"</code>. | ||
| 3750 | And, to create a match, that string must appear in the | ||
| 3751 | whitelist. | ||
| 3752 | </p><p> | ||
| 3753 | Judicious use of the <code class="filename">LICENSE_FLAGS</code> | ||
| 3754 | strings and the contents of the | ||
| 3755 | <code class="filename">LICENSE_FLAGS_WHITELIST</code> variable | ||
| 3756 | allows you a lot of flexibility for including or excluding | ||
| 3757 | recipes based on licensing. | ||
| 3758 | For example, you can broaden the matching capabilities by | ||
| 3759 | using license flags string subsets in the whitelist. | ||
| 3760 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> | ||
| 3761 | When using a string subset, be sure to use the part of | ||
| 3762 | the expanded string that precedes the appended | ||
| 3763 | underscore character (e.g. | ||
| 3764 | <code class="filename">usethispart_1.3</code>, | ||
| 3765 | <code class="filename">usethispart_1.4</code>, and so forth). | ||
| 3766 | </div><p> | ||
| 3767 | For example, simply specifying the string "commercial" in | ||
| 3768 | the whitelist matches any expanded | ||
| 3769 | <code class="filename">LICENSE_FLAGS</code> definition that starts | ||
| 3770 | with the string "commercial" such as "commercial_foo" and | ||
| 3771 | "commercial_bar", which are the strings the build system | ||
| 3772 | automatically generates for hypothetical recipes named | ||
| 3773 | "foo" and "bar" assuming those recipes simply specify the | ||
| 3774 | following: | ||
| 3775 | </p><pre class="literallayout"> | ||
| 3776 | LICENSE_FLAGS = "commercial" | ||
| 3777 | </pre><p> | ||
| 3778 | Thus, you can choose to exhaustively | ||
| 3779 | enumerate each license flag in the whitelist and | ||
| 3780 | allow only specific recipes into the image, or | ||
| 3781 | you can use a string subset that causes a broader range of | ||
| 3782 | matches to allow a range of recipes into the image. | ||
| 3783 | </p><p> | ||
| 3784 | This scheme works even if the | ||
| 3785 | <code class="filename">LICENSE_FLAGS</code> string already | ||
| 3786 | has <code class="filename">_${PN}</code> appended. | ||
| 3787 | For example, the build system turns the license flag | ||
| 3788 | "commercial_1.2_foo" into "commercial_1.2_foo_foo" and | ||
| 3789 | would match both the general "commercial" and the specific | ||
| 3790 | "commercial_1.2_foo" strings found in the whitelist, as | ||
| 3791 | expected. | ||
| 3792 | </p><p> | ||
| 3793 | Here are some other scenarios: | ||
| 3794 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> | ||
| 3795 | You can specify a versioned string in the recipe | ||
| 3796 | such as "commercial_foo_1.2" in a "foo" recipe. | ||
| 3797 | The build system expands this string to | ||
| 3798 | "commercial_foo_1.2_foo". | ||
| 3799 | Combine this license flag with a whitelist that has | ||
| 3800 | the string "commercial" and you match the flag | ||
| 3801 | along with any other flag that starts with the | ||
| 3802 | string "commercial". | ||
| 3803 | </p></li><li class="listitem"><p> | ||
| 3804 | Under the same circumstances, you can use | ||
| 3805 | "commercial_foo" in the whitelist and the build | ||
| 3806 | system not only matches "commercial_foo_1.2" but | ||
| 3807 | also matches any license flag with the string | ||
| 3808 | "commercial_foo", regardless of the version. | ||
| 3809 | </p></li><li class="listitem"><p> | ||
| 3810 | You can be very specific and use both the | ||
| 3811 | package and version parts in the whitelist (e.g. | ||
| 3812 | "commercial_foo_1.2") to specifically match a | ||
| 3813 | versioned recipe. | ||
| 3814 | </p></li></ul></div><p> | ||
| 3815 | </p></div><div class="section" title="3.7.2.2. Other Variables Related to Commercial Licenses"><div class="titlepage"><div><div><h4 class="title" id="other-variables-related-to-commercial-licenses">3.7.2.2. Other Variables Related to Commercial Licenses<span class="permalink"><a alt="Permalink" title="Permalink" href="#other-variables-related-to-commercial-licenses">¶</a></span></h4></div></div></div><p> | ||
| 3816 | Other helpful variables related to commercial | ||
| 3817 | license handling exist and are defined in the | ||
| 3818 | <code class="filename">poky/meta/conf/distro/include/default-distrovars.inc</code> file: | ||
| 3819 | </p><pre class="literallayout"> | ||
| 3820 | COMMERCIAL_AUDIO_PLUGINS ?= "" | ||
| 3821 | COMMERCIAL_VIDEO_PLUGINS ?= "" | ||
| 3822 | </pre><p> | ||
| 3823 | If you want to enable these components, you can do so by | ||
| 3824 | making sure you have statements similar to the following | ||
| 3825 | in your <code class="filename">local.conf</code> configuration file: | ||
| 3826 | </p><pre class="literallayout"> | ||
| 3827 | COMMERCIAL_AUDIO_PLUGINS = "gst-plugins-ugly-mad \ | ||
| 3828 | gst-plugins-ugly-mpegaudioparse" | ||
| 3829 | COMMERCIAL_VIDEO_PLUGINS = "gst-plugins-ugly-mpeg2dec \ | ||
| 3830 | gst-plugins-ugly-mpegstream gst-plugins-bad-mpegvideoparse" | ||
| 3831 | LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly commercial_gst-plugins-bad commercial_qmmp" | ||
| 3832 | </pre><p> | ||
| 3833 | Of course, you could also create a matching whitelist | ||
| 3834 | for those components using the more general "commercial" | ||
| 3835 | in the whitelist, but that would also enable all the | ||
| 3836 | other packages with | ||
| 3837 | <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-LICENSE_FLAGS" target="_top"><code class="filename">LICENSE_FLAGS</code></a> | ||
| 3838 | containing "commercial", which you may or may not want: | ||
| 3839 | </p><pre class="literallayout"> | ||
| 3840 | LICENSE_FLAGS_WHITELIST = "commercial" | ||
| 3841 | </pre><p> | ||
| 3842 | </p><p> | ||
| 3843 | Specifying audio and video plug-ins as part of the | ||
| 3844 | <code class="filename">COMMERCIAL_AUDIO_PLUGINS</code> and | ||
| 3845 | <code class="filename">COMMERCIAL_VIDEO_PLUGINS</code> statements | ||
| 3846 | (along with the enabling | ||
| 3847 | <code class="filename">LICENSE_FLAGS_WHITELIST</code>) includes the | ||
| 3848 | plug-ins or components into built images, thus adding | ||
| 3849 | support for media formats or components. | ||
| 3850 | </p></div></div></div><div class="section" title="3.8. x32 psABI"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="x32">3.8. x32 psABI<span class="permalink"><a alt="Permalink" title="Permalink" href="#x32">¶</a></span></h2></div></div></div><p> | ||
| 3851 | x32 processor-specific Application Binary Interface | ||
| 3852 | (<a class="ulink" href="https://software.intel.com/en-us/node/628948" target="_top">x32 psABI</a>) | ||
| 3853 | is a native 32-bit processor-specific ABI for | ||
| 3854 | <span class="trademark">Intel</span>® 64 (x86-64) | ||
| 3855 | architectures. | ||
| 3856 | An ABI defines the calling conventions between functions in a | ||
| 3857 | processing environment. | ||
| 3858 | The interface determines what registers are used and what the sizes are | ||
| 3859 | for various C data types. | ||
| 3860 | </p><p> | ||
| 3861 | Some processing environments prefer using 32-bit applications even | ||
| 3862 | when running on Intel 64-bit platforms. | ||
| 3863 | Consider the i386 psABI, which is a very old 32-bit ABI for Intel | ||
| 3864 | 64-bit platforms. | ||
| 3865 | The i386 psABI does not provide efficient use and access of the | ||
| 3866 | Intel 64-bit processor resources, leaving the system underutilized. | ||
| 3867 | Now consider the x86_64 psABI. | ||
| 3868 | This ABI is newer and uses 64-bits for data sizes and program | ||
| 3869 | pointers. | ||
| 3870 | The extra bits increase the footprint size of the programs, | ||
| 3871 | libraries, and also increases the memory and file system size | ||
| 3872 | requirements. | ||
| 3873 | Executing under the x32 psABI enables user programs to utilize CPU | ||
| 3874 | and system resources more efficiently while keeping the memory | ||
| 3875 | footprint of the applications low. | ||
| 3876 | Extra bits are used for registers but not for addressing mechanisms. | ||
| 3877 | </p><p> | ||
| 3878 | The Yocto Project supports the final specifications of x32 psABI | ||
| 3879 | as follows: | ||
| 3880 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> | ||
| 3881 | You can create packages and images in x32 psABI format on | ||
| 3882 | x86_64 architecture targets. | ||
| 3883 | </p></li><li class="listitem"><p> | ||
| 3884 | You can successfully build recipes with the x32 toolchain. | ||
| 3885 | </p></li><li class="listitem"><p> | ||
| 3886 | You can create and boot | ||
| 3887 | <code class="filename">core-image-minimal</code> and | ||
| 3888 | <code class="filename">core-image-sato</code> images. | ||
| 3889 | </p></li><li class="listitem"><p> | ||
| 3890 | RPM Package Manager (RPM) support exists for x32 binaries. | ||
| 3891 | </p></li><li class="listitem"><p> | ||
| 3892 | Support for large images exists. | ||
| 3893 | </p></li></ul></div><p> | ||
| 3894 | </p><p> | ||
| 3895 | For steps on how to use x32 psABI, see the | ||
| 3896 | "<a class="ulink" href="http://www.yoctoproject.org/docs/2.5/dev-manual/dev-manual.html#using-x32-psabi" target="_top">Using x32 psABI</a>" | ||
| 3897 | section in the Yocto Project Development Tasks Manual. | ||
| 3898 | </p></div></div> | ||
| 3899 | |||
| 3900 | </div></body></html> \ No newline at end of file | ||
diff --git a/documentation/getting-started/getting-started.tgz b/documentation/getting-started/getting-started.tgz new file mode 100644 index 0000000000..829706d5d3 --- /dev/null +++ b/documentation/getting-started/getting-started.tgz | |||
| Binary files differ | |||
diff --git a/documentation/getting-started/getting-started.xml b/documentation/getting-started/getting-started.xml new file mode 100644 index 0000000000..930a202e1a --- /dev/null +++ b/documentation/getting-started/getting-started.xml | |||
| @@ -0,0 +1,94 @@ | |||
| 1 | <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" | ||
| 2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" | ||
| 3 | [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > | ||
| 4 | |||
| 5 | <book id='getting-started-manual' lang='en' | ||
| 6 | xmlns:xi="http://www.w3.org/2003/XInclude" | ||
| 7 | xmlns="http://docbook.org/ns/docbook" | ||
| 8 | > | ||
| 9 | <bookinfo> | ||
| 10 | |||
| 11 | <mediaobject> | ||
| 12 | <imageobject> | ||
| 13 | <imagedata fileref='figures/getting-started-title.png' | ||
| 14 | format='SVG' | ||
| 15 | align='left' scalefit='1' width='100%'/> | ||
| 16 | </imageobject> | ||
| 17 | </mediaobject> | ||
| 18 | |||
| 19 | <title> | ||
| 20 | Getting Started With Yocto Project | ||
| 21 | </title> | ||
| 22 | |||
| 23 | <authorgroup> | ||
| 24 | <author> | ||
| 25 | <firstname>Scott</firstname> <surname>Rifenbark</surname> | ||
| 26 | <affiliation> | ||
| 27 | <orgname>Scotty's Documentation Services, INC</orgname> | ||
| 28 | </affiliation> | ||
| 29 | <email>srifenbark@gmail.com</email> | ||
| 30 | </author> | ||
| 31 | </authorgroup> | ||
| 32 | |||
| 33 | <revhistory> | ||
| 34 | <revision> | ||
| 35 | <revnumber>2.5</revnumber> | ||
| 36 | <date>April 2018</date> | ||
| 37 | <revremark>The initial document released with the Yocto Project 2.5 Release.</revremark> | ||
| 38 | </revision> | ||
| 39 | </revhistory> | ||
| 40 | |||
| 41 | <copyright> | ||
| 42 | <year>©RIGHT_YEAR;</year> | ||
| 43 | <holder>Linux Foundation</holder> | ||
| 44 | </copyright> | ||
| 45 | |||
| 46 | <legalnotice> | ||
| 47 | <para> | ||
| 48 | Permission is granted to copy, distribute and/or modify this document under | ||
| 49 | the terms of the <ulink type="http" url="http://creativecommons.org/licenses/by-sa/2.0/uk/"> | ||
| 50 | Creative Commons Attribution-Share Alike 2.0 UK: England & Wales</ulink> as published by | ||
| 51 | Creative Commons. | ||
| 52 | </para> | ||
| 53 | <note><title>Manual Notes</title> | ||
| 54 | <itemizedlist> | ||
| 55 | <listitem><para> | ||
| 56 | This version of the | ||
| 57 | <emphasis>Yocto Project Overview Manual</emphasis> | ||
| 58 | is for the &YOCTO_DOC_VERSION; release of the | ||
| 59 | Yocto Project. | ||
| 60 | To be sure you have the latest version of the manual | ||
| 61 | for this release, use the manual from the | ||
| 62 | <ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink>. | ||
| 63 | </para></listitem> | ||
| 64 | <listitem><para> | ||
| 65 | For manuals associated with other releases of the Yocto | ||
| 66 | Project, go to the | ||
| 67 | <ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink> | ||
| 68 | and use the drop-down "Active Releases" button | ||
| 69 | and choose the manual associated with the desired | ||
| 70 | Yocto Project. | ||
| 71 | </para></listitem> | ||
| 72 | <listitem><para> | ||
| 73 | To report any inaccuracies or problems with this | ||
| 74 | manual, send an email to the Yocto Project | ||
| 75 | discussion group at | ||
| 76 | <filename>yocto@yoctoproject.com</filename> or log into | ||
| 77 | the freenode <filename>#yocto</filename> channel. | ||
| 78 | </para></listitem> | ||
| 79 | </itemizedlist> | ||
| 80 | </note> | ||
| 81 | </legalnotice> | ||
| 82 | |||
| 83 | </bookinfo> | ||
| 84 | |||
| 85 | <xi:include href="getting-started-intro.xml"/> | ||
| 86 | |||
| 87 | <xi:include href="getting-started-development-environment.xml"/> | ||
| 88 | |||
| 89 | <xi:include href="getting-started-concepts.xml"/> | ||
| 90 | |||
| 91 | </book> | ||
| 92 | <!-- | ||
| 93 | vim: expandtab tw=80 ts=4 | ||
| 94 | --> | ||
