diff options
Diffstat (limited to 'docs/usermanual')
| -rw-r--r-- | docs/usermanual/chapters/common_use_cases.xml | 45 | ||||
| -rw-r--r-- | docs/usermanual/chapters/comparing.xml | 18 | ||||
| -rw-r--r-- | docs/usermanual/chapters/features.xml | 10 | ||||
| -rw-r--r-- | docs/usermanual/chapters/getting_oe.xml | 26 | ||||
| -rw-r--r-- | docs/usermanual/chapters/metadata.xml | 18 | ||||
| -rw-r--r-- | docs/usermanual/chapters/recipes.xml | 66 | ||||
| -rw-r--r-- | docs/usermanual/chapters/usage.xml | 64 |
7 files changed, 134 insertions, 113 deletions
diff --git a/docs/usermanual/chapters/common_use_cases.xml b/docs/usermanual/chapters/common_use_cases.xml index 7ae3ee5ada..d86d0ca8d1 100644 --- a/docs/usermanual/chapters/common_use_cases.xml +++ b/docs/usermanual/chapters/common_use_cases.xml @@ -7,11 +7,12 @@ <para>Creating a new distribution is not complicated, however we urge you to try existing distributions first, because it's also very easy to do - wrong. The config need to be created in /conf/distro directory. So what - has to be inside? <itemizedlist> + wrong. The config needs to be created in $OEBASE/openembedded/conf/distro + directory. So what has to be inside? + <itemizedlist> <listitem> <para><command>DISTRO_VERSION</command> so users will know which - version of distribution they use.</para> + version of the distribution they are using.</para> </listitem> <listitem> @@ -71,29 +72,30 @@ SRCDATE = "20061014" <section id="commonuse_new_machine"> <title>Adding a new Machine</title> - <para>To be able to build for device OpenEmbedded have to know it, so - machine config file need to be written. All those configs are stored in - /conf/machine/ directory.</para> + <para>To be able to build for a device OpenEmbedded has to know about it, + so a machine config file needs to be written. All of the machine + configs are stored in $OEBASE/openembedded/conf/machine/ directory.</para> <para>As usual some variables are required: <itemizedlist> <listitem> - <para><command>TARGET_ARCH</command> which describe which CPU - architecture does machine use.</para> + <para><command>TARGET_ARCH</command> describes which CPU + architecture the machine uses.</para> </listitem> <listitem> - <para><command>MACHINE_FEATURES</command> which describe which - features device has. More about it in <link + <para><command>MACHINE_FEATURES</command> which describes which + features the device has. More about it in <link linkend="task-base">task-base</link> section.</para> </listitem> <listitem> <para><command>PREFERRED_PROVIDER_virtual/kernel</command> has to - point into proper kernel recipe for this machine.</para> + point to the proper kernel recipe for this machine.</para> </listitem> </itemizedlist></para> - <para>Next kernel recipe needs to be added.</para> + <para>Next the kernel recipe needs to be added if it doesn't already exist. + </para> </section> <section id="commonuse_new_package"> @@ -105,7 +107,7 @@ SRCDATE = "20061014" <section> <title>building from unstable source code</title> <para>Building against the latest, bleeding-edge source has some intricacies of its own. - For one, it is desirable to pin down a 1 code revision that is known to build to + For one, it is desirable to pin down a code revision that is known to build to prevent random breakage in OE at the most inopportune time for all OE users. Here is how to do that properly. <itemizedlist> @@ -113,7 +115,8 @@ SRCDATE = "20061014" <listitem><para>for cvs: add 'PV = "1.1+cvs${SRCREV}"' to your bb file.</para></listitem> </itemizedlist> Accompany either with an entry to conf/distro/include/sane-srcrevs.inc for a revision that you know - builds successfully. + builds successfully. It is also common to define the stable SRCREV + for your package directly in the package recipe. </para> <para> If you really absolutely have to follow the latest commits, you can do that by adding @@ -126,7 +129,7 @@ SRCDATE = "20061014" <section id="commonuse_new_image"> <title>Creating your own image</title> - <para>Creating own image is easy - only few variables needs to be set: + <para>Creating own image is easy - only few variables need to be set: <itemizedlist> <listitem> <para><command>IMAGE_BASENAME</command> to give a name for your own @@ -147,7 +150,7 @@ SRCDATE = "20061014" <para><command>IMAGE_LINGUAS</command> is an optional list of languages which has to be installed into the image</para> </listitem> - </itemizedlist> Then adding of the <emphasis>image</emphasis> class use: + </itemizedlist> Then add the <emphasis>image</emphasis> class using: <screen> inherit image </screen> And the image recipe is ready for usage.</para> @@ -240,7 +243,7 @@ export LOCALDIR=$PWD/secret-isv </screen> <para>Use <command>source build_source</command> to source the script, - use <command>env</command> to check that the variable where + use <command>env</command> to check that the variables were exported.</para> </section> @@ -484,8 +487,8 @@ RDEPENDS_${PN} += "\ <title>Putting it together</title> <para>In the previous two sections we have prepared the host and target side. One thing that is missing is combining the two newly - created tasks and actually create the SDK. This is what we are going - to do now.</para> + created tasks and actually creating the SDK. This is what we are + going to do now.</para> <para>Create <filename>meta-toolchain-YOU.bb</filename> in the <filename>recipes/meta</filename> directory and place the following @@ -529,7 +532,7 @@ SDK_SUFFIX = "toolchain-YOUR" optional dependencies like directFB, glib-2.0, gstreamer-0.10, tslib and more esoteric dependencies like mysql and postgres. This allows developers to simply start developing using Qt and enables system - integrator to easily recompile Qt and base libraries without tracking + integrators to easily recompile Qt and base libraries without tracking down extra dependencies. </para> @@ -575,7 +578,7 @@ $ <command>bitbake</command> meta-toolchain-qte should start by downloading the SDK and untar it to the root folder (<filename>/</filename>). Once this operation is finished you will find a new directory <filename>/usr/local/angstrom/arm/</filename> and - it contains the <filename>environment-setup</filename> to setup the + it contains the <filename>environment-setup</filename> file to setup the <emphasis>QMAKESPEC</emphasis> and various other paths. </para> diff --git a/docs/usermanual/chapters/comparing.xml b/docs/usermanual/chapters/comparing.xml index 1347010977..cfdaa95fbe 100644 --- a/docs/usermanual/chapters/comparing.xml +++ b/docs/usermanual/chapters/comparing.xml @@ -5,13 +5,13 @@ <section id="comparing_buildroot"> <title>buildroot</title> - <para>Writing of <application>BitBake</application> recipes is more easy + <para>Writing of <application>BitBake</application> recipes is easier and more intuitive than writing Makefiles while providing higher flexibility. This allows you to tweak specific recipes for your very - special needs and to add new recipes very fast. You can build toolchains, + special needs and to add new recipes quickly. You can build toolchains, Software Distribution Kits (SDKs), complete Distributions or just single - packages. The flexibility of OpenEmbedded allows you to reuse the once - written recipes for many different purposes. OpenEmbedded provides + packages. The flexibility of OpenEmbedded allows you to reuse recipes + for many different purposes. OpenEmbedded provides everything buildroot will be able to provide. But in contrast to buildroot OpenEmbedded will allow you to achieve what you really want to achieve. You can add new package formats, new filesystems, new output formats @@ -21,11 +21,11 @@ <section id="comparing_crosstool"> <title>crosstool</title> - <para>Crosstool allows to create toolchains for you. It can only create + <para>Crosstool allows the creation of toolchains. It can only create the initial toolchain for you. It will not compile other needed libraries - or applications for you, it will not be able to track dependencies or to + or applications for you, it will not be able to track dependencies or package them properly. OpenEmbedded supports all configurations crosstool - supports. You can start to create toolchains with OpenEmbedded, then as + supports. You can start by creating toolchains with OpenEmbedded, then as your needs grow create a more complete SDK from already present base libraries and applications and if you recognize you need to have packages for the target you have them almost built already.</para> @@ -38,7 +38,7 @@ cross-compiling is hard itself but many people misuse the buildsystem they use to build their software. This will lead to a variety of issues you can run into. This can be failing tests on configuration because of executing - cross compiled binaries or crashes at run-time due wrong sizes of basic + cross compiled binaries or crashes at run-time due to wrong sizes of basic types. When utilizing OpenEmbedded you avoid searching for patches at many different places and will be able to get things done more quickly. <application>OpenEmbedded</application> allows you to choose from a pool @@ -48,4 +48,4 @@ output formats and filesystems. This allows you to create complete and specialized distributions easily.</para> </section> -</chapter>
\ No newline at end of file +</chapter> diff --git a/docs/usermanual/chapters/features.xml b/docs/usermanual/chapters/features.xml index 3cbf1d8d1d..880b75cc37 100644 --- a/docs/usermanual/chapters/features.xml +++ b/docs/usermanual/chapters/features.xml @@ -22,9 +22,9 @@ <para>Run-time Dependencies (<command>RDEPENDS</command>) will be added when packaging the software. They should only contain the minimal dependencies to run the program. OpenEmbedded will analyze each packaged - binary and search for <command>SO_NEEDED</command> libraries. The - libraries are absolutely required by the program then OpenEmbedded is - searching for packages that installs these libraries. these packages are + binary and search for <command>SO_NEEDED</command> libraries. These + libraries are absolutely required by the program so OpenEmbedded will + search for packages that install these libraries. These packages are automatically added to the <command>RDEPENDS</command>. As a packager you don't need to worry about shared libraries anymore they will be added automatically.</para> @@ -52,9 +52,9 @@ BBFILE_PRIORITY_local = "10" <title>Task-base <anchor id="task-base" /></title> <para>Task-base is new way of creating basic root filesystems. Instead of - having each machine setting a ton of duplicate variables, this allow a + having each machine setting a ton of duplicate variables, this allows a machine to specify its features and <command>task-base</command> builds it - a customised package based on what the machine needs along with what the + a customized package based on what the machine needs along with what the distro supports.</para> <para>To illustrate, the distro config file can say: <screen> diff --git a/docs/usermanual/chapters/getting_oe.xml b/docs/usermanual/chapters/getting_oe.xml index d18c9557e3..c82df3a73f 100644 --- a/docs/usermanual/chapters/getting_oe.xml +++ b/docs/usermanual/chapters/getting_oe.xml @@ -98,7 +98,7 @@ $ <command>git</command> clone git://git.openembedded.org/openembedded</screen> seems good practice to update your OpenEmbedded tree at least daily. To do this, run: <screen> -$ <command>cd</command> $OEBASE +$ <command>cd</command> $OEBASE/openembedded $ <command>git</command> pull</screen> </para> </section> @@ -142,7 +142,7 @@ $ <command>git</command> pull</screen> <para>Since the path to your OpenEmbedded installation will be used in many places, setting it in your environment will allow you to use - the <varname>$OEBASE</varname> variable in all pathes and make it + the <varname>$OEBASE</varname> variable in all paths and make it easier to change in the future should the need arise. To set <varname>$OEBASE</varname> if you use a Bourne like shell <footnote> @@ -342,6 +342,16 @@ MACHINE = "om-gta01"</screen> </varlistentry> <varlistentry> + <term><literal>base-image</literal></term> + <listitem> + <para>Build an image that is the smallest possible image + which allows for ssh access and the ability to install + additional packages using ipkg. + </para> + </listitem> + </varlistentry> + + <varlistentry> <term><literal>console-image</literal></term> <listitem> <para>Build an image without the X11, gtk+, or qt windowing @@ -463,9 +473,10 @@ MACHINE = "om-gta01"</screen> </varlistentry> <varlistentry> - <term><literal>task-native-sdk</literal></term> + <term><literal>task-sdk-native</literal></term> <listitem> - <para>Mata-package for native (on-device) SDK. + <para>Meta-package for native (on-device) SDK. i.e. libc, gcc, + make, etc. </para> </listitem> </varlistentry> @@ -536,6 +547,13 @@ MACHINE = "om-gta01"</screen> <para>Builds the appropriate kernel for your device.</para> </listitem> </varlistentry> + + <varlistentry> + <term><literal>virtual/bootloader</literal></term> + <listitem> + <para>Builds the appropriate bootloader for your device.</para> + </listitem> + </varlistentry> </variablelist> </para> </section> diff --git a/docs/usermanual/chapters/metadata.xml b/docs/usermanual/chapters/metadata.xml index bbf6f733bb..794c66ce15 100644 --- a/docs/usermanual/chapters/metadata.xml +++ b/docs/usermanual/chapters/metadata.xml @@ -95,7 +95,7 @@ <para>OpenEmbedded has files ending with <emphasis>.conf</emphasis>, <emphasis>.inc</emphasis>, <emphasis>.bb</emphasis> - and<emphasis>.bbclass</emphasis>. The syntax and semantics of these files + and <emphasis>.bbclass</emphasis>. The syntax and semantics of these files are best described in the <ulink url="http://bitbake.berlios.de/manual"><application>BitBake</application> manual</ulink>.</para> @@ -111,7 +111,7 @@ <section id="metadata_writing_data"> <title>Writing Meta Data (Adding packages)</title> - <para>This page will guide you trough the effort of writing a .bb file or + <para>This page will guide you through the effort of writing a .bb file or <emphasis>recipe</emphasis> in BitBake speak.</para> <para>Let's start with the easy stuff, like the package description, @@ -128,23 +128,23 @@ DEPENDS = "gtk+" RDEPENDS = "cool-ttf-fonts" </screen> The package needs gtk+ to build ('DEPENDS') and requires the 'cool-ttf-fonts' package to run ('RDEPENDS'). OE will add - run-time dependencies on libraries on its own via the so called - <emphasis>shlibs</emphasis>-code, but you need to specify everything other + run-time dependencies on libraries on its own via the so called + <emphasis>shlibs</emphasis>-code, but you need to specify everything else by yourself, which in this case is the 'cool-ttf-fonts' package.</para> <para>After entering all this OE will know what to build before trying to build your application, but it doesn't know where to get it yet. So let's add the source location: <screen> SRC_URI = "http://www.host.com/foo/files/${P}.tar.bz2;md5sum=yoursum" - </screen> This will tell the fetcher to where to download the + </screen> This will tell the fetcher where to download the sources from and it will check the integrity using md5sum if you provided the appropriate <emphasis>yoursum</emphasis>. You can make one by doing <screen>md5sum foo-1.9.tar.bz2</screen> and replacing <emphasis>yoursum</emphasis> with the md5sum on your screen. A typical - md5sum will look like this: <screen>a6434b0fc8a54c3dec3d6875bf3be8mtn </screen>Notice - the <emphasis>${P}</emphasis> variable, that one holds the package name, - <emphasis>${PN}</emphasis> in BitBake speak and the package version, - <emphasis>${PV}</emphasis> in BitBake speak. It's a short way of writing + md5sum will look like this: <screen>a6434b0fc8a54c3dec3d6875bf3be868 </screen>Notice + the <emphasis>${P}</emphasis> variable holds the package name + (<emphasis>${PN}</emphasis> in BitBake speak) and the package version + (<emphasis>${PV}</emphasis> in BitBake speak). It's a short way of writing <emphasis>${PN}-${PV}</emphasis>. Using this notation means you can copy the recipe when a new version is released without having to alter the contents. You do need to check if everything is still correct, because new diff --git a/docs/usermanual/chapters/recipes.xml b/docs/usermanual/chapters/recipes.xml index 6a574d87b7..0bbc05f813 100644 --- a/docs/usermanual/chapters/recipes.xml +++ b/docs/usermanual/chapters/recipes.xml @@ -154,7 +154,7 @@ VAR2 = "The version is ${PV}"</screen></para> <para>The following example:<screen>VAR1 ?= "New value"</screen>will set <emphasis role="bold">VAR1</emphasis> to <emphasis>"New - value"</emphasis> if its currently empty. However if it was already + value"</emphasis> if it is currently empty. However if it was already set it would be unchanged. In the following <emphasis role="bold">VAR1</emphasis> is left with the value <emphasis>"Original value"</emphasis>:<screen>VAR1 = "Original value" @@ -290,7 +290,7 @@ mv fixed.recipe.bb myrecipe.bb</screen></para> </variablelist> <para>For a detailed description of the syntax for the bitbake recipe - files you should refer to the bitbake use manual.</para> + files you should refer to the bitbake user manual.</para> </section> <section id="recipes_versioning" xreflabel="versioning"> @@ -418,7 +418,7 @@ mv fixed.recipe.bb myrecipe.bb</screen></para> <section id="recipes_variables" xreflabel="variables"> <title>Variables</title> - <para>One of the most confusing part of bitbake recipes for new users is + <para>One of the most confusing parts of bitbake recipes for new users is the large amount of variables that appear to be available to change and/or control the behaviour of some aspect of the recipe. Some variables, such as those derived from the file name are reasonably obvious, others are not @@ -503,7 +503,7 @@ mv fixed.recipe.bb myrecipe.bb</screen></para> <para>Practically all recipes start with a header section which describes various aspects of the package that is being built. This information is typically used directly by the package format (such as ipkg or deb) as - its meta data used to describe the package.</para> + meta data used to describe the package.</para> <para>Variables used in the header include:</para> @@ -536,7 +536,7 @@ mv fixed.recipe.bb myrecipe.bb</screen></para> <term>SECTION</term> <listitem> - <para>The section is used to categorise the application into a + <para>The section is used to categorize the application into a specific group. Often used by GUI based installers to help users when searching for software.</para> @@ -625,7 +625,7 @@ mv fixed.recipe.bb myrecipe.bb</screen></para> file or a compressed archive file, such as .tar.gz or .zip, then the files will be uncompressed and extracted from the archive automatically.</para> - <para>Archive files will be extracted from with the working directory, + <para>Archive files will be extracted from within the working directory, <emphasis role="bold">${WORKDIR}</emphasis> and plain files will be copied into the same directory. Patches will be applied from within the unpacked source directory, <emphasis role="bold">${S}</emphasis>. (Details on these @@ -722,7 +722,7 @@ mv fixed.recipe.bb myrecipe.bb</screen></para> <listitem> <para>This is where patches are applied and where the program is - expected to be compiled in.</para> + expected to be compiled.</para> </listitem> </varlistentry> @@ -790,7 +790,7 @@ mv fixed.recipe.bb myrecipe.bb</screen></para> file://watchquagga.default"</screen>The recipe has two init files and two configuration files, which are not patches, but are actually files that it wants to include in the generated packages. Bitbake will - copy these files into the work directory. So to access them during the + copy these files into the working directory. So to access them during the install task we refer to them via the <emphasis role="bold">WORKDIR</emphasis> variable:<screen>do_install () { # Install init script and default settings @@ -809,7 +809,7 @@ mv fixed.recipe.bb myrecipe.bb</screen></para> directory called <emphasis role="bold"><packagename>-<version></emphasis> in the <emphasis role="bold">WORKDIR</emphasis> directory. This is the - directory in which it will change into before patching, compiling and + directory it will change into before patching, compiling and installing the package.</para> <para>For example, we have a package called <emphasis @@ -875,7 +875,7 @@ S = "${WORKDIR}/widgets"</screen></para> <title>Staging directories</title> <para>Staging is used to make libraries, headers and binaries available - for the build of one recipe for use by another recipe. Building a + from the build of one recipe for use by another recipe. Building a library for example requires that packages be created containing the libraries and headers for development on the target as well as making them available on the host for building other packages that need the @@ -1339,7 +1339,7 @@ $</screen>This shows us that the helloworld program is for an SH programs that you need to run a configure script for, passing various parameters, and then make. To make these work when cross-compiling you need to provides a lot of variables to the configure script. But all the - hard work as already been done for you. There's an <xref + hard work has already been done for you. There's an <xref linkend="autotools_class" /> which takes care of most of the complexity of building an autotools based package.</para> @@ -1387,7 +1387,7 @@ inherit autotools</screen></para> </listitem> <listitem> - <para>Make modifications to prevent the configure script from tying + <para>Make modifications to prevent the configure script from trying to compile and run programs - any programs it compiles will be for the target and not the host and so cannot be run.</para> </listitem> @@ -1519,7 +1519,7 @@ inherit autotools</screen></para> role="bold">.so</emphasis>, <emphasis role="bold">.a</emphasis> and associated libtool <emphasis role="bold">.la</emphasis> libraries. It will determine the appropriate libraries to install and take care - of any modifications that may be require for <emphasis + of any modifications that may be required for <emphasis role="bold">.la</emphasis> files.</para> <para>This function supports the following options:</para> @@ -1839,7 +1839,7 @@ NOTE: package helloworld-0.1-r0: task do_package_write: completed</screen>We <section> <title>Default packages and files</title> - <para>The defaults package settings are defined in <emphasis + <para>The default package settings are defined in <emphasis role="bold">conf/bitbake.conf</emphasis> and are suitable for a lot of recipes without any changes. The following list shows the default values for the packaging related variables:</para> @@ -2363,7 +2363,7 @@ addtask unpack_extra after do_unpack before do_patch</screen></para> <para>Often a certain pattern is followed in more than one recipe, or maybe some complex python based functionality is required to achieve the desired end result. This is achieved through the use of classes, which can - be found in the classes subdirectory at the top-level of on OE + be found in the classes subdirectory at the top-level of an OE checkout.</para> <para>Being aware of the available classes and understanding their @@ -2390,7 +2390,7 @@ addtask unpack_extra after do_unpack before do_patch</screen></para> <para>A class is used via the inherit method. The following is an example for the <emphasis>curl</emphasis> recipe showing that it uses three classes:<screen>inherit autotools pkgconfig binconfig</screen>In this case - it is utilising the services of three separate classes:</para> + it is utilizing the services of three separate classes:</para> <variablelist> <varlistentry> @@ -2443,7 +2443,7 @@ addtask unpack_extra after do_unpack before do_patch</screen></para> libraries, available for use by other recipes. This is different to installing because installing is about making things available for packaging and then eventually for use on the target device. Staging on the - other hand is about making things available on the host system for use by + other hand is about making things available on the host system for use in building later applications.</para> <para>Taking bzip2 as an example you can see that it stages a header file @@ -2463,7 +2463,7 @@ addtask unpack_extra after do_unpack before do_patch</screen></para> <term>STAGING_INCDIR</term> <listitem> - <para>The directory into which staged headers files should be + <para>The directory into which staged header files should be installed. This is the equivalent of the standard <emphasis role="bold">/usr/include</emphasis> directory.</para> </listitem> @@ -2531,7 +2531,7 @@ EXTRA_OECONF = "--disable-ldap \ script of the package. In the gnupg case it needs to be told where the bzip2 headers and libraries are, and this is done via the <emphasis>--with-bzip2</emphasis> option. In this case it points to - the directory which include the lib and include subdirectories. + the directory which includes the lib and include subdirectories. Since OE doesn't define a variable for one level above the include and lib directories <emphasis role="bold">..</emphasis> is used to indicate one directory up. Without this, gnupg would search the host @@ -2717,9 +2717,9 @@ pkg_postinst_${PN}-rdisc6 () { <listitem> <para>This class is used when installing and/or removing qpf fonts. - It register scripts to update the font paths and font cache + It registers scripts to update the font paths and font cache information to ensure that the font information is kept up to date - as fonts and installed and removed.</para> + as fonts are installed and removed.</para> </listitem> </varlistentry> @@ -2972,7 +2972,7 @@ fi</screen></para> </listitem> <listitem> - <para>How do handle incrementally creating patches</para> + <para>How to handle incrementally creating patches</para> </listitem> <listitem> @@ -3025,7 +3025,7 @@ fi</screen></para> </orderedlist> <para>This results in the packaging system, such as ipkg, considering - the released version to be older then the rc version.</para> + the released version to be older than the rc version.</para> <para>In OpenEmbedded the correct naming of pre and rc versions is to use the previous version number followed by a + followed by the new version @@ -3138,7 +3138,7 @@ do_configure() { role="bold">0_9_0</emphasis>.</para> <para>Some of the more common python code in use in existing recipes is - shown in the following table:</para> + shown in the following list:</para> <variablelist> <varlistentry> @@ -3389,7 +3389,7 @@ $</screen>then we would expect it to select version (since all of the existing versions have a preference of 0). Note that you can still call bitbake directly on the recipe:<screen>bitbake -b recipes/procps/procps_4.0.0.bb</screen>This enables you to test, and fix the package manually without having bitbake - automatically select normally.</para> + automatically select it normally.</para> <para>By using this feature in conjunction with overrides you can also disable (or select) specific versions based on the override. The following @@ -3418,7 +3418,7 @@ $</screen>then we would expect it to select version </listitem> <listitem> - <para>samlpe/standard script?</para> + <para>sample/standard script?</para> </listitem> <listitem> @@ -3445,13 +3445,13 @@ $</screen>then we would expect it to select version from other packages.</para> <para>The most common reason for alternatives is to reduce the size of the - binaries. But cutting down on features, built in help and error messages + binaries. By cutting down on features, built in help, error messages and combining multiple binaries into one large binary it's possible to save considerable space. Often users are not expected to use the commands interactively in embedded appliances and therefore these changes have no visible effect to the user. In some situations users may have interactive access, or they may be more advanced users who want shell access on - appliances that normal don't provide it, and in these cases they should be + appliances that normally don't provide it, and in these cases they should be able to install the full functional version if they desire.</para> <section> @@ -3478,7 +3478,7 @@ update-alternatives: Linking //usr/bin/find to find.findutils update-alternatives: Linking //usr/bin/xargs to xargs.findutils</screen></para> <para>Then we see that the standard version of find changes to the full - featured implement ion:<screen>root@titan:~$ find --version + featured implementation:<screen>root@titan:~$ find --version find --version GNU find version 4.2.29 Features enabled: D_TYPE O_NOFOLLOW(enabled) LEAF_OPTIMISATION @@ -3576,7 +3576,7 @@ which find </listitem> <listitem> - <para>even if your distro don't use /var in tmpfs, others do</para> + <para>even if your distro doesn't use /var in tmpfs, others do</para> </listitem> <listitem> @@ -3588,7 +3588,7 @@ which find <section> <title>Logging and log files</title> - <para>As a consequence of the non-volatile and/or small capacity of the + <para>As a consequence of the volatile and/or small capacity of the <emphasis role="bold">/var</emphasis> file system some distributions choose methods of logging other than writing to a file. The most typical is the use of an in-memory circular log buffer which can be read using @@ -3616,7 +3616,7 @@ which find </listitem> <listitem> - <para>Don't include any <command>/var</command> directories, file or + <para>Don't include any <command>/var</command> directories, files or symlinks in packages. They would be lost on a reboot and so should not be included in packages.</para> </listitem> @@ -3643,7 +3643,7 @@ which find <itemizedlist> <listitem> - <para>about optimisation</para> + <para>about optimization</para> </listitem> <listitem> diff --git a/docs/usermanual/chapters/usage.xml b/docs/usermanual/chapters/usage.xml index 1563dc3eac..9703e3677b 100644 --- a/docs/usermanual/chapters/usage.xml +++ b/docs/usermanual/chapters/usage.xml @@ -9,11 +9,11 @@ what OpenEmbedded is all about, which is taking a lot of software and creating something that you can run on another device. This involves downloading some source code, compiling it, creating packages (like .deb - or .rpm) and/or creating boot images that can written to flash on the + or .rpm) and/or creating boot images that can be written to flash on the device. The difficulties of cross-compiling and the variety of devices which can be supported lead to a lot more complexity in an OpenEmbedded based distribution than you'd find in a typical desktop distribution - (for which cross-compiling isn't needed).</para> + (where which cross-compiling isn't needed).</para> <para>A major part of OpenEmbedded deals with compiling source code for various projects. For each project this generally requires the same basic @@ -67,7 +67,7 @@ <listitem> <para>Tool chains (compiler, linker etc) are often difficult to compile. Cross tool chains are even more difficult. Typically you'd go - out and download a tool chain made by someone else - but not when your + out and download a tool chain made by someone else - but not when you're using OE. In OE the entire toolchain is built as part of the process. This may make things take longer initially and may make it more difficult to get started but makes it easier to apply patches and test @@ -123,7 +123,7 @@ helping you understand how to debug and develop within OpenEmbedded.</para> - <para>You'll also not a lot of reference to variables that define specific + <para>You'll also note a lot of references to variables that define specific directories or change the behaviour of some part of the build process. You should refer to <xref linkend="chapter_recipes" /> for full details on these variables.</para> @@ -160,7 +160,7 @@ <listitem> <para>This directory contains distribution related files. A distribution decides how various activities are handled in the final - image, such as how networking configured, if usb devices will be + image, such as how networking is configured, if usb devices will be supported, what packaging system is used, which libc is used etc.</para> </listitem> @@ -193,8 +193,8 @@ <section id="usage_workspace" xreflabel="workspace"> <title>Work space</title> - <para>Let's start out by taking a look at a typically working area. Note - that this may not be exactly what see - there are a lot of options that + <para>Let's start out by taking a look at a typical working area. Note + that this may not be exactly what you see - there are a lot of options that can effect exactly how things are done, but it gives us a pretty good idea of whats going on. What we are looking at here is the tmp directory (as specified by TMPDIR in your local.conf):<screen>$ <command>find</command> tmp -maxdepth 2 -type d @@ -303,10 +303,10 @@ tmp/deploy/images</screen></para> </varlistentry> <varlistentry> - <term>staging</term> + <term>sysroots</term> <listitem> - <para>Contains the staging area, which is used to stored natively + <para>Contains the staging area, which is used to store natively compiled tools and and libraries and headers for the target that are required for building other software.</para> </listitem> @@ -324,9 +324,9 @@ tmp/deploy/images</screen></para> </variablelist> <para>When people refer to the <emphasis>"tmp directory"</emphasis> this - is the directory them are talking about.</para> + is the directory they are talking about.</para> - <para>To perform a complete rebuild from script you would usually rename + <para>To perform a complete rebuild from scratch you would usually rename or delete tmp and then restart your build. I recommend keeping one old version of tmp around to use for comparison if something goes wrong with your new build. For example:<screen>$ <command>rm</command> -fr tmp.OLD @@ -339,7 +339,7 @@ $ <command>bitbake</command> bootstrap-image</screen></para> <para>The work directory is where all source code is unpacked into, where source is configured, compiled and packaged. In other words this is where all the action happens. Each bitbake recipe will produce a - corresponding sub directory in the work directory. The sub directory + corresponding subdirectory in the work directory. The subdirectory name will contain the recipe name, version and the release number (as defined by the PR variable within the recipe).</para> @@ -348,9 +348,9 @@ $ <command>bitbake</command> bootstrap-image</screen></para> tmp/work tmp/work/busybox-1.2.1-r13 tmp/work/libice-1_1.0.3-r0 -tmp/work/arpwatch-2.1a15-r2</screen>You can see that the first three (of +tmp/work/arpwatch-2.1a15-r2</screen>You can see the first three (of several hundred) recipes here and they are for release 13 of busybox - 1.2.1, release 0 or libice 1.1.0.3 and release 2 of arpwatch 2.1a15. + 1.2.1, release 0 of libice 1.1.0.3 and release 2 of arpwatch 2.1a15. It's also possible that you may just have a sub directory for your targets architecture and operating system in which case these directories will be in that additional subdirectory, as shown @@ -446,7 +446,7 @@ tmp/work/lzo-1.08-r14/image</screen></para> install into <emphasis role="bold">${D}/usr/bin</emphasis> and <emphasis role="bold">${D}/usr/lib</emphasis> instead. When installed on the target the ${D} will be not be included so - they'll end up in the correct place. You definitely don't wont + they'll end up in the correct place. You definitely don't want files on your host system being replaced by cross-compiled binaries for your target!</para> </listitem> @@ -544,14 +544,14 @@ tmp/work/lzo-1.08-r14/install/lzo/usr/lib/liblzo.so.1.0.0</screen></para> packages. You probably need to start out by downloading the source code, then unpacking the source code. Maybe you need to apply some patches for some reason. Then you might run the configure script of the package, - perhaps passing it some options to configure it to your liking. The you - might run "make install" to install the software. If your actually going + perhaps passing it some options to configure it to your liking. Then you + might run "make install" to install the software. If you're actually going to make some packages, such as .deb or .rpm, then you'd have additional tasks you'd perform to make them.</para> <para>You find that building things in OpenEmbedded works in a similar way - there are a number of tasks that are executed in a predefined order for - each recipe. Any many of the tasks correspond to those listed above like + each recipe. Many of the tasks correspond to those listed above like <emphasis>"download the source"</emphasis>. In fact you've probably already seen some of the names of these tasks - bitbake displays them as they are processed:<screen>$ <command>bitbake</command> lzo @@ -718,7 +718,7 @@ NOTE: build 200705041709: completed</screen><note> <para>The <emphasis>configure</emphasis> task takes care of the configuration of the package. Running a configure script (<emphasis>"./configure <options>"</emphasis>) is probably the - form of configuration that is most recognised but it's not the only + form of configuration that is most recognized but it's not the only configuration system that exists.</para> </listitem> </varlistentry> @@ -748,7 +748,7 @@ NOTE: build 200705041709: completed</screen><note> <para>This is different from the <emphasis>install</emphasis> task in that this is responsible for making available libraries and headers for use during build on the development host. Therefore - it's libraries which normal have to stage things while + it is libraries which normally have to stage things while applications normally don't need to. The <emphasis>install</emphasis> task on the other hand is making files available for packaging and ultimately installation on the @@ -762,7 +762,7 @@ NOTE: build 200705041709: completed</screen><note> <listitem> <para>The <emphasis>install</emphasis> task is responsible for - actually installing everything. Now this needs to install the + actually installing everything. This needs to install the software into the destination directory, <emphasis role="bold">D</emphasis>. This directory won't actually be a part of the final package though. In other words if you install something @@ -782,7 +782,7 @@ NOTE: build 200705041709: completed</screen><note> package. It moves the files for the destination directory, <emphasis role="bold">${D}</emphasis>, that they were installed in into the appropriate packages subdirectory. Usually there will be a main - package a separate documentation (-doc), development (-dev) and + package, a separate documentation (-doc), development (-dev) and debugging packages (-dbg) for example.</para> </listitem> </varlistentry> @@ -808,11 +808,11 @@ NOTE: build 200705041709: completed</screen><note> <emphasis>install</emphasis>. This is slightly confusing but any task <emphasis>x</emphasis> is implemented via a function called <emphasis>do_x</emphasis> in the class or recipe where it is defined. - See places refer to the tasks via their name only and some with the + Some places refer to the tasks via their name only and some with the <emphasis>do</emphasis> prefix.</para> </note> - <para>You will almost certainly notice tasks beyond these ones - there are + <para>You will almost certainly notice tasks beyond the ones above - there are various methods available to insert additional tasks into the tasks sequence. As an example the <emphasis role="bold">insane.bbclass</emphasis>, which performs various QA checks, @@ -822,7 +822,7 @@ NOTE: build 200705041709: completed</screen><note> another new task called <emphasis>qa_staging</emphasis> between <emphasis>populate_sysroot</emphasis> and <emphasis>build</emphasis> tasks. The former validates the result of the - <emphasis>configure</emphasis> task and the late the results of the + <emphasis>configure</emphasis> task and the later the results of the <emphasis>populate_sysroot</emphasis> task.</para> <para>To determine the full list of tasks available for a specific recipe @@ -943,8 +943,8 @@ $ <command>bitbake</command> -b <bb-file> -D</screen></para> <listitem> <para>Unpack the source file but don't apply the patches yet. Sometimes you may want to look at the extracted, but not patched - source code and that's what just unpacking will give you (some - time's handy to get diffs generated against the original + source code and that's what just unpacking will give you + (sometimes handy to get diffs generated against the original source).</para> </listitem> </varlistentry> @@ -961,7 +961,7 @@ $ <command>bitbake</command> -b <bb-file> -D</screen></para> <term>configure</term> <listitem> - <para>Performs and configuration that is required for the + <para>Performs any configuration that is required for the software.</para> </listitem> </varlistentry> @@ -1013,12 +1013,12 @@ $ <command>bitbake</command> -b <bb-file> -D</screen></para> </varlistentry> </variablelist> - <para>Note that each of the actions that corresponds to task's will run + <para>Note that each of the actions that corresponds to a task will run any preceding tasks that have not yet been performed. So starting with compile will also perform the fetch, unpack, patch and configure actions.</para> - <para>A typically development session might involve editing files in the + <para>A typical development session might involve editing files in the working directory and then recompiling until it all works:<screen>[<emphasis>... test ...</emphasis>] $ <command>bitbake</command> -b recipes/testapp/testapp_4.3.bb -c compile -D @@ -1072,7 +1072,7 @@ $ <command>vi</command> recipes/testapp/testapp_4.3.bb</screen>At this stage you build a specific recipe:<screen>BB>> build net-snmp</screen>If it fails you may want to clean the build before trying again:<screen>BB>> clean net-snmp</screen>If you update the recipe by editing the .bb file (to fix some issues) then - you will want to clean the package, reparse the modified recipe, and the + you will want to clean the package, reparse the modified recipe, and then build again:<screen>BB>> clean net-snmp BB>> reparse net-snmp BB>> build net-snmp</screen>Note that you can use wildcards in the @@ -1088,7 +1088,7 @@ BB>> build net-snmp</screen>Note that you can use wildcards in the various environment variables, such as <emphasis role="bold">CC</emphasis> and <emphasis role="bold">PATH</emphasis> etc, to values suitable for cross-compiling. If you wish to manually run configure scripts and compile - file during development it would be nice to have all those values set for + files during development it would be nice to have all those values set for you. This is what devshell does - it provides you with an interactive shell with all the appropriate variables set for cross-compiling.</para> |