From 750dc0a90438b48cabf552531e4e132e3a914782 Mon Sep 17 00:00:00 2001 From: Jamie Lenehan Date: Wed, 14 Mar 2007 22:24:43 +0000 Subject: class_autotools: Update the description of the site files to account for the changes to enable multiple site files, package specific site files, common site files and site file aliases. --- usermanual/reference/class_autotools.xml | 140 +++++++++++++++++++++++++------ 1 file changed, 115 insertions(+), 25 deletions(-) diff --git a/usermanual/reference/class_autotools.xml b/usermanual/reference/class_autotools.xml index e4ed62ece0..25c32d8e50 100644 --- a/usermanual/reference/class_autotools.xml +++ b/usermanual/reference/class_autotools.xml @@ -25,7 +25,7 @@ SRC_URI = "${SOURCEFORGE_MIRROR}/netcat/netcat-${PV}.tar.bz2" inherit autotoolsThe header is defined, the location of the source code and then the inherit. For the simplest cases this is all that is - required. If you need to pass additionol parameters to the configure script, + required. If you need to pass additional parameters to the configure script, such as for enabling and/or disabling options, then they can be specified via the EXTRA_OECONF variable. This example from the lftp recipe shows several extra options being passed to the configure @@ -75,10 +75,108 @@ do_install_append () { The autotools configuration method has support for caching the results of tests. In the cross-compilation case it is sometimes necessary - to prime the cache with pre-calculated results (since tests designed to + to prime the cache with per-calculated results (since tests designed to run on the target cannot be run when cross-compiling). These are defined - via the site file for the architecture you are using which is found in - org.openembedded.dev/site/<arch>-<target-os>. + via the site file(s) for the architecture you are using and may be + specific to the package you are building. + + Which site files are used is determined via the + classes/siteinfo.bbclass class file and you should + check that file to determine the names that apply to your target. + Typically the following site files will be checked for, and used if + found: + + + + endian-(big|little) + + + Either endian-big or + endian-little depending on the endianess of the + target. This site file would contain defines that only change based + on if the target is little endian or big endian. + + + + + bit-(32|64) + + + Either bit-32 or bit-64 + depending on the bitsize of the target. This site file would contain + defines that only change based on if the target is a 32-bit or + 64-bit cpu. + + + + + common-(libc|uclibc) + + + Either common-libc or + common-uclibc based on the C library being used + for the target. This site file would contain defines the are + specific to the C library being used. + + + + + <arch>-common + + + A common site file for the target architecture. For i386, + i485, i586 and i686 this would be x86-common, for + sh3 and sh4 this would be sh-common and for + various arm targets this would be + arm-common. + + + + + common + + + This is a site file which is common for all targets and + contains definitions which remain the same no matter what target is + being built. + + + + + Each of the supported site file for a target is checked for in + several locations, and each one found will be used in order. The following + locations are checked: + + + + org.openembedded.dev/packages/<packagename>/site-<version>/ + + + This directory is for site files which are specific to a + particular version (where version is the PV of the package) of a + package. + + + + + org.openembedded.dev/packages/<packagename>/site/ + + + This directory is for site files which are specific to a + particular package, but apply to all versions of the package. + + + + + org.openembedded.dev/site/ + + + This directory is for site files that are common to all + packages. Originally this was the only site file directory that was + supported. + + + There are some things that you should keep in mind about the caching of configure tests: @@ -125,27 +223,19 @@ do_install_append () { calling configure and it will then not be replaced by the value from the site file. - Sometimes it's useful to manually check values from the site file. - This can prove useful in situations where autotools is not used but you - still need some of the same information that an autotools configure script - would require. The following from the net-snmp recipe shows an example of - using the existing site file entries for endianess to pass the required - endianess option to the configure script:do_configure() { - # endianness fun.. inspired by openssl.inc - . ${CONFIG_SITE} - if [ "x$ac_cv_c_bigendian" = "xyes" -o "x$ac_cv_c_littleendian" = "xno" ]; then - ENDIANESS=" --with-endianness=big" - elif [ "x$ac_cv_c_littleendian" = "xyes" -o "x$ac_cv_c_bigendian" = "xno" ]; then - ENDIANESS=" --with-endianness=little" - else - oefatal do_configure cannot determine endianess - fi - oe_runconf $ENDIANESS -}It is also possible to disable the use of the cached values from the - site file by clearing the definition of CONFIG_SITE - prior to running the configure script. Doing this will disable the use of - the site file entirely. This however should be used as a last resort. The - following example from the db recipe shows an example of this:# Cancel the site stuff - it's set for db3 and destroys the + + Site files are applied in order, so the application specific site + files will be applied prior to the top level site file entries. The use + of conditional assignment means that the first definition found will + apply, while when not using conditionals the last definition found will + apply. + + + It is possible to disable the use of the cached values from the site + file by clearing the definition of CONFIG_SITE prior to + running the configure script. Doing this will disable the use of the site + file entirely. This however should be used as a last resort. The following + example from the db recipe shows an example of this:# Cancel the site stuff - it's set for db3 and destroys the # configure. CONFIG_SITE = "" do_configure() { -- cgit 1.2.3-korg From 845b0062935f20e90551cace2520e70f1ca4e5f6 Mon Sep 17 00:00:00 2001 From: Jamie Lenehan Date: Wed, 14 Mar 2007 23:29:45 +0000 Subject: usermanual: Add a siteinfo class section to the reference manual. Move the siteinfo class related stuff from the autotools class section into the siteuinfo class section and add details on the SITEINFO_ENDIANESS and SITEINFO_BITS variables. --- usermanual/reference/class_autotools.xml | 102 +----------------- usermanual/reference/class_siteinfo.xml | 180 +++++++++++++++++++++++++++++++ usermanual/usermanual.xml | 3 + 3 files changed, 188 insertions(+), 97 deletions(-) create mode 100644 usermanual/reference/class_siteinfo.xml diff --git a/usermanual/reference/class_autotools.xml b/usermanual/reference/class_autotools.xml index 25c32d8e50..a9e1a5721a 100644 --- a/usermanual/reference/class_autotools.xml +++ b/usermanual/reference/class_autotools.xml @@ -80,103 +80,11 @@ do_install_append () { via the site file(s) for the architecture you are using and may be specific to the package you are building. - Which site files are used is determined via the - classes/siteinfo.bbclass class file and you should - check that file to determine the names that apply to your target. - Typically the following site files will be checked for, and used if - found: - - - - endian-(big|little) - - - Either endian-big or - endian-little depending on the endianess of the - target. This site file would contain defines that only change based - on if the target is little endian or big endian. - - - - - bit-(32|64) - - - Either bit-32 or bit-64 - depending on the bitsize of the target. This site file would contain - defines that only change based on if the target is a 32-bit or - 64-bit cpu. - - - - - common-(libc|uclibc) - - - Either common-libc or - common-uclibc based on the C library being used - for the target. This site file would contain defines the are - specific to the C library being used. - - - - - <arch>-common - - - A common site file for the target architecture. For i386, - i485, i586 and i686 this would be x86-common, for - sh3 and sh4 this would be sh-common and for - various arm targets this would be - arm-common. - - - - - common - - - This is a site file which is common for all targets and - contains definitions which remain the same no matter what target is - being built. - - - - - Each of the supported site file for a target is checked for in - several locations, and each one found will be used in order. The following - locations are checked: - - - - org.openembedded.dev/packages/<packagename>/site-<version>/ - - - This directory is for site files which are specific to a - particular version (where version is the PV of the package) of a - package. - - - - - org.openembedded.dev/packages/<packagename>/site/ - - - This directory is for site files which are specific to a - particular package, but apply to all versions of the package. - - - - - org.openembedded.dev/site/ - - - This directory is for site files that are common to all - packages. Originally this was the only site file directory that was - supported. - - - + Autoconf uses site files as definied in the + CONFIG_SITE variable, which is a space seperate list of + files to load in the specified order. Details on how this variable is set + is provided in the (the class + responsbile for setting the variable) section. There are some things that you should keep in mind about the caching of configure tests: diff --git a/usermanual/reference/class_siteinfo.xml b/usermanual/reference/class_siteinfo.xml new file mode 100644 index 0000000000..4d66e85e7c --- /dev/null +++ b/usermanual/reference/class_siteinfo.xml @@ -0,0 +1,180 @@ + +
+ siteinfo class + + The siteinfo class provides information for a target with a particular + emphasis on determining the names of the site files to be passed to + autoconf, as described in the . Full site + information for your target can be determined by looking at the table in the + class implementation found in the + classes/siteinfo.bbclass file. A typical entry contains + the name of the target and a list of site information for the + target: "sh4-linux": "endian-little bit-32 common-glibc sh-common",In + the above example for sh4-linux target (that's a build for an sh4 processor + using glibc) we see that the endianess and bit-size of target are defined + and an additional set of site files that should be used are listed. These + include a common site file for glibc and a common site file for sh + processors (so sh3 and sh4 can share defines). A "common" + entry is automatically added to the end of each of the definitions during + processing. + + The class makes available three variables based on the information + provided for a target: + + + + SITEINFO_ENDIANESS + + + Defines the endianess of the target as either + "le" (little endian) or "be" + (big endian). The target must list either + endian-little or endian-big in + it's site information. + + + + + SITEINFO_BITS + + + Defines the bitsize of the target as either + "32" or "64". The target must + list either bit-32 or bit-64 in + it's site information. + + + + + CONFIG_SITE + + + Defines the site files to be used by autoconf. This is a space + separated list of one or more site files for the target. + + + + + A typical use for the SITEINFO_ENDIANESS and + SITEINFO_BITS variables is to provide configuration + within a recipe based on their values. The following example from the + openssl recipe showw the correct define for the + endiness of the target being passed to openssl via the compiler flags. The + define to add to the flags is set based on the value of the + SITEINFO_ENDIANESS variable. Note that use of the + base_conditional method (see the section) to select a value conditional + on the endianess setting: + + # Additional flag based on target endiness (see siteinfo.bbclass) + CFLAG="${CFLAG} ${@base_conditional('SITEINFO_ENDIANESS', 'le', '-DL_ENDIAN', '-DB_ENDIAN', d)}" + +
+ CONFIG_SITE: The autoconf site files + + The autotools configuration method has support for caching the + results of tests. In the cross-compilation case it is sometimes necessary + to prime the cache with per-calculated results (since tests designed to + run on the target cannot be run when cross-compiling). These are defined + via the site file(s) for the architecture you are using and may be + specific to the package you are building. + + Which site files are used is determined via the + CONFIG_SITE definition which is calculated via the + siteinfo class. Typically the following site files will be checked for, + and used in the order found: + + + + endian-(big|little) + + + Either endian-big or + endian-little depending on the endianess of the + target. This site file would contain defines that only change based + on if the target is little endian or big endian. + + + + + bit-(32|64) + + + Either bit-32 or bit-64 + depending on the bitsize of the target. This site file would contain + defines that only change based on if the target is a 32-bit or + 64-bit cpu. + + + + + common-(libc|uclibc) + + + Either common-libc or + common-uclibc based on the C library being used + for the target. This site file would contain defines the are + specific to the C library being used. + + + + + <arch>-common + + + A common site file for the target architecture. For i386, + i485, i586 and i686 this would be x86-common, for + sh3 and sh4 this would be sh-common and for + various arm targets this would be + arm-common. + + + + + common + + + This is a site file which is common for all targets and + contains definitions which remain the same no matter what target is + being built. + + + + + Each of the supported site files for a target is will be checked for + in several different directories. Each time a file is found it as added to + the list of files in the CONFIG_SITE variable. The + following directories are checked: + + + + org.openembedded.dev/packages/<packagename>/site-<version>/ + + + This directory is for site files which are specific to a + particular version (where version is the PV of the package) of a + package. + + + + + org.openembedded.dev/packages/<packagename>/site/ + + + This directory is for site files which are specific to a + particular package, but apply to all versions of the package. + + + + + org.openembedded.dev/site/ + + + This directory is for site files that are common to all + packages. Originally this was the only site file directory that was + supported. + + + +
+
\ No newline at end of file diff --git a/usermanual/usermanual.xml b/usermanual/usermanual.xml index 8f9cdd53fd..e978dd50cc 100644 --- a/usermanual/usermanual.xml +++ b/usermanual/usermanual.xml @@ -17,6 +17,7 @@ + @@ -865,6 +866,8 @@ NOTE: Couldn't find shared library provider for libm.so.6 &var-section; + &class-siteinfo; + &var-src-uri; &class-update-alternatives; -- cgit 1.2.3-korg From 7b153a75335a572a2ba78bee5bf4a4c60f0c8c82 Mon Sep 17 00:00:00 2001 From: Jamie Lenehan Date: Thu, 15 Mar 2007 00:02:06 +0000 Subject: recipes: Fill out the section on DEFAULT_PREFERENCE. --- usermanual/chapters/recipes.xml | 67 ++++++++++++++++++++++++++++++----------- 1 file changed, 49 insertions(+), 18 deletions(-) diff --git a/usermanual/chapters/recipes.xml b/usermanual/chapters/recipes.xml index 83c3f39279..786b80540c 100644 --- a/usermanual/chapters/recipes.xml +++ b/usermanual/chapters/recipes.xml @@ -2001,7 +2001,8 @@ NOTE: package helloworld-0.1-r0: task do_package_write: completedWe matched via wildcards. Consider the case where we have three binaries in the /usr/bin directory and we want the test program in a separate package:/usr/bin/programa /usr/bin/programb /usr/bin/testSo - we define a new package and instruct bitbake to /usr/bin/test in it. + we define a new package and instruct bitbake to /usr/bin/test in + it. FILES-${PN}-test = "${bindir}/test" PACKAGES += "FILES-${PN}-test" @@ -2019,7 +2020,8 @@ PACKAGES += "FILES-${PN}-test" processing of the ${PN}-test package. - To achieve what we are trying to accomplish we have two options: + To achieve what we are trying to accomplish we have two + options: @@ -3103,21 +3105,50 @@ do_configure() {
Preferences: How to disable packages - This section is to be completed. - - - - what DEFAULT_PREFERENCE does - - - - why you would want to use it - - - - using it with overrides - - + When bitbake is asked to build a package and multiple version of + that package are available it will normally select the version with the + highest version number (where the version is defined via the + PV variable). + + For example if we were to ask bitbake to build procps and the + following packages are available:~/oe%> ls packages/procps +procps-3.1.15/ procps-3.2.1/ procps-3.2.5/ procps-3.2.7/ procps.inc +procps_3.1.15.bb procps_3.2.1.bb procps_3.2.5.bb procps_3.2.7.bb +~/oe%>then we would expect that version 3.2.7 + (the highest version number) would be built. + + Sometimes this is not what you actually want to happen though. + Perhaps you have added a new version does not yet work or maybe the new + version has no support for your target yet. Help is at hand since bitbake + is not only looking at the version to decided which version to build but + is also looking at the preference for the versions, as defined via a + DEFAULT_PREFERENCE variable contained without the + recipes. + + By default DEFAULT_PREFERENCE is set to zero. + Bitbake will find the highest preference that is available and then for + all the packages at the preference level it will select the package with + the highest version. In general this means that adding a positive + DEFAULT_PREFERENCE will cause the package to be + preferred over other versions and a negative + DEFAULT_PREFERENCE will cause all other packages to be + preferred. + + Imagine that you are adding procps version 4.0.0, but that it does + not yet work. You could delete it to make procps build so you can build a + working image, but what you really want it just for version 4.0.0 to be + ignored until it works. By adding:DEFAULT_PREFERENCE = "-1"to + the recipe it'll cause it to be ignored by bitbake (since all the existing + versions have a preference of 0). Note that you can still call bitbake + directly on the recipe:bitbake -b packages/procps/procps_4.0.0.bbThis + enables you to test, and fix the package manually without having bitbake + automatically select normally. + + By using this in conjunction with overrides you can also disable (or + select) specific version for a specific architecture. The following + example from glibc shows that this version has been disabled for the sh3 + architecture because it doesn't support sh3. This will force bitbake to + try and select one of the other versions instead:packages/glibc/glibc_2.3.2+cvs20040726.bb:DEFAULT_PREFERENCE_sh3 = "-99"
@@ -3418,4 +3449,4 @@ which find
- + \ No newline at end of file -- cgit 1.2.3-korg From c5def93a47cd12c94f448c5531c89d2025bb20d2 Mon Sep 17 00:00:00 2001 From: Jamie Lenehan Date: Thu, 15 Mar 2007 06:50:22 +0000 Subject: recipes: Add details in the packaging section on how to avoid having to package up some files. --- usermanual/chapters/recipes.xml | 36 ++++++++++++++++++++++++++++++++---- 1 file changed, 32 insertions(+), 4 deletions(-) diff --git a/usermanual/chapters/recipes.xml b/usermanual/chapters/recipes.xml index 786b80540c..f4da35ba4d 100644 --- a/usermanual/chapters/recipes.xml +++ b/usermanual/chapters/recipes.xml @@ -1999,9 +1999,9 @@ NOTE: package helloworld-0.1-r0: task do_package_write: completedWe Note that the order of packages effects the files that will be matched via wildcards. Consider the case where we have three binaries in - the /usr/bin directory and we want the test program in a separate - package:/usr/bin/programa /usr/bin/programb /usr/bin/testSo - we define a new package and instruct bitbake to /usr/bin/test in + the /usr/bin directory and we want the test program + in a separate package:/usr/bin/programa /usr/bin/programb /usr/bin/testSo + we define a new package and instruct bitbake to include /usr/bin/test in it. FILES-${PN}-test = "${bindir}/test" @@ -2113,6 +2113,34 @@ NOTE: package helloworld-0.1-r0: task do_package: completedExcept in behind by a recipe. +
+ Excluding files + + There's no actual support for explicitly excluding files from + packaging. You could just leave them out of any package, but then you'll + get warnings (or errors if requesting full package checking) during + packaging which is not desirable. It also doesn't let other people know + that you've deliberately avoided packaging the file or files. + + In order to exclude a file totally you should avoid installing it + in the first place during the install task. + + In some cases it may be easier to let the package install the file + and then explicitly remove the file and the end of the install task. The + following example from the samba recipe shows the removal of several + files that get installed via the default install task generated by the + . By using + do_install_append these commands and run after the + autotools generated install task: + + do_install_append() { + ... + rm -f ${D}${bindir}/*.old + rm -f ${D}${sbindir}/*.old + ... +} +
+
Debian naming @@ -3108,7 +3136,7 @@ do_configure() { When bitbake is asked to build a package and multiple version of that package are available it will normally select the version with the highest version number (where the version is defined via the - PV variable). + PV variable). For example if we were to ask bitbake to build procps and the following packages are available:~/oe%> ls packages/procps -- cgit 1.2.3-korg From 55b9739d22ea4763397a710c84c5d98be536bf26 Mon Sep 17 00:00:00 2001 From: Jamie Lenehan Date: Thu, 15 Mar 2007 07:02:23 +0000 Subject: recipes: Update the sample package output to show that packages now go into deploy/ipkg/ rather than just deploy/ipkg to reflect recent changes. --- usermanual/chapters/recipes.xml | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/usermanual/chapters/recipes.xml b/usermanual/chapters/recipes.xml index f4da35ba4d..3462c11acc 100644 --- a/usermanual/chapters/recipes.xml +++ b/usermanual/chapters/recipes.xml @@ -1212,8 +1212,8 @@ NOTE: package helloworld-0.1-r0: task do_package: started NOTE: package helloworld-0.1-r0: task do_package: completed NOTE: package helloworld-0.1-r0: task do_package_write: started NOTE: Not creating empty archive for helloworld-dbg-0.1-r0 -Packaged contents of helloworld into /home/lenehan/devel/oe/build/titan-glibc-25/tmp/deploy/ipk/helloworld_0.1-r0_sh4.ipk -Packaged contents of helloworld-doc into /home/lenehan/devel/oe/build/titan-glibc-25/tmp/deploy/ipk/helloworld-doc_0.1-r0_sh4.ipk +Packaged contents of helloworld into /home/lenehan/devel/oe/build/titan-glibc-25/tmp/deploy/ipk/sh4/helloworld_0.1-r0_sh4.ipk +Packaged contents of helloworld-doc into /home/lenehan/devel/oe/build/titan-glibc-25/tmp/deploy/ipk/sh4/helloworld-doc_0.1-r0_sh4.ipk NOTE: Not creating empty archive for helloworld-dev-0.1-r0 NOTE: Not creating empty archive for helloworld-locale-0.1-r0 NOTE: package helloworld-0.1-r0: task do_package_write: completed @@ -1228,9 +1228,9 @@ Build statistics: The package was successfully built, the output consists of two .ipkg files, which are ready to be installed on the target. One contains - the binary and the other contains the readme file:~/oe%> ls -l tmp/deploy/ipk/helloworld* --rw-r--r-- 1 lenehan lenehan 3040 Jan 12 14:46 tmp/deploy/ipk/helloworld_0.1-r0_sh4.ipk --rw-r--r-- 1 lenehan lenehan 768 Jan 12 14:46 tmp/deploy/ipk/helloworld-doc_0.1-r0_sh4.ipk + the binary and the other contains the readme file:~/oe%> ls -l tmp/deploy/ipk/*/helloworld* +-rw-r--r-- 1 lenehan lenehan 3040 Jan 12 14:46 tmp/deploy/ipk/sh4/helloworld_0.1-r0_sh4.ipk +-rw-r--r-- 1 lenehan lenehan 768 Jan 12 14:46 tmp/deploy/ipk/sh4/helloworld-doc_0.1-r0_sh4.ipk ~/oe%> It's worthwhile looking at the working directory to see where @@ -1714,8 +1714,8 @@ inherit autotools example of the packaging output from the helloworld example above shows this packaging in action:[NOTE: package helloworld-0.1-r0: task do_package_write: started NOTE: Not creating empty archive for helloworld-dbg-0.1-r0 -Packaged contents of helloworld into /home/lenehan/devel/oe/build/titan-glibc-25/tmp/deploy/ipk/helloworld_0.1-r0_sh4.ipk -Packaged contents of helloworld-doc into /home/lenehan/devel/oe/build/titan-glibc-25/tmp/deploy/ipk/helloworld-doc_0.1-r0_sh4.ipk +Packaged contents of helloworld into /home/lenehan/devel/oe/build/titan-glibc-25/tmp/deploy/ipk/sh4/helloworld_0.1-r0_sh4.ipk +Packaged contents of helloworld-doc into /home/lenehan/devel/oe/build/titan-glibc-25/tmp/deploy/ipk/sh4/helloworld-doc_0.1-r0_sh4.ipk NOTE: Not creating empty archive for helloworld-dev-0.1-r0 NOTE: Not creating empty archive for helloworld-locale-0.1-r0 NOTE: package helloworld-0.1-r0: task do_package_write: completedWe -- cgit 1.2.3-korg From bd223c6d29f2bc1b6fda88dcbaab5d02d01ab76e Mon Sep 17 00:00:00 2001 From: Jamie Lenehan Date: Fri, 16 Mar 2007 00:08:57 +0000 Subject: reference/dirs_staging: Update some paths to match recent change make to bitbake.conf. --- usermanual/reference/dirs_staging.xml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/usermanual/reference/dirs_staging.xml b/usermanual/reference/dirs_staging.xml index c9ab09fbec..25f3685aad 100644 --- a/usermanual/reference/dirs_staging.xml +++ b/usermanual/reference/dirs_staging.xml @@ -79,7 +79,7 @@ STAGING_BINDIR - ${STAGING_DIR}/${BUILD_SYS}/bin + ${STAGING_DIR}/${HOST_SYS}/bin @@ -139,7 +139,7 @@ PKG_CONFIG_PATH - ${STAGING_DATADIR}/pkgconfig + ${STAGING_LIBDIR}/pkgconfig -- cgit 1.2.3-korg From c154e4300447e50c7e56f180739b7e76329ac5e1 Mon Sep 17 00:00:00 2001 From: Jamie Lenehan Date: Fri, 16 Mar 2007 00:19:12 +0000 Subject: recipes: Update the note about the PR variable making it clear that it never goes backwards and that you should always increase it if you are unsure about what effect it has on the generated packages. --- usermanual/chapters/recipes.xml | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/usermanual/chapters/recipes.xml b/usermanual/chapters/recipes.xml index 3462c11acc..f889acd395 100644 --- a/usermanual/chapters/recipes.xml +++ b/usermanual/chapters/recipes.xml @@ -335,6 +335,17 @@ mv fixed.recipe.bb myrecipe.bb It is good practice to always define PR in your recipes, even for the "r0" release, so that when editing the recipe it is clear that the PR number needs to be updated. + + You should always increment PR when modifying a recipe. + Sometimes this can be avoided if the change will have no effect on the + actual packages generated by the recipe, such as updating the SRC_URI + to point to a new host. If in any doubt then you should increase the + PR regardless of what has been changed. + + The PR value should never be decremented. If you accidentally + submit a large PR value for example then it should be left at the + value and just increased for new releases, not reset back to a lower + version. When a recipe is being processed some variables are automatically -- cgit 1.2.3-korg From 60a8d23752b2e0ffe9aeb2c4220ab7a1bb5f10eb Mon Sep 17 00:00:00 2001 From: Jamie Lenehan Date: Sat, 17 Mar 2007 00:25:05 +0000 Subject: recipes: Fill in some details on the debian library policy in the packing section. --- usermanual/chapters/recipes.xml | 80 +++++++++++++++++++++++++++++++++++++---- 1 file changed, 73 insertions(+), 7 deletions(-) diff --git a/usermanual/chapters/recipes.xml b/usermanual/chapters/recipes.xml index f889acd395..7ed33868f5 100644 --- a/usermanual/chapters/recipes.xml +++ b/usermanual/chapters/recipes.xml @@ -345,7 +345,7 @@ mv fixed.recipe.bb myrecipe.bb The PR value should never be decremented. If you accidentally submit a large PR value for example then it should be left at the value and just increased for new releases, not reset back to a lower - version. + version. When a recipe is being processed some variables are automatically @@ -2155,13 +2155,79 @@ NOTE: package helloworld-0.1-r0: task do_package: completedExcept in
Debian naming - This section is to be completed + A special debian library name policy can be + applied for packages that contain a single shared library. When enabled + packages will be renamed to match the debian policy for such + packages. + + Debian naming is enabled by including the debian class via either + local.conf or your distributions configuration + file:INHERIT += "debian" + + The policy works by looking at the shared library name and version + and will automatically rename the package to + <libname><lib-major-version>. For + example if the package name (PN) is foo and the + package ships a file named libfoo.so.1.2.3 then the + package will be renamed to libfoo1 to follow the + debian policy. + + If we look at the lzo_1.08.bb recipe, + currently at release 14, it generates a package containing a single + shared library :~oe/build/titan-glibc-25%> find tmp/work/lzo-1.08-r14/install/ +tmp/work/lzo-1.08-r14/install/lzo +tmp/work/lzo-1.08-r14/install/lzo/usr +tmp/work/lzo-1.08-r14/install/lzo/usr/lib +tmp/work/lzo-1.08-r14/install/lzo/usr/lib/liblzo.so.1 +tmp/work/lzo-1.08-r14/install/lzo/usr/lib/liblzo.so.1.0.0Without + debian naming this package would have been called + lzo_1.08-r14_sh4.ipk (and the corresponding dev and + dbg packages would have been called + lzo-dbg_1.08-r14_sh4.ipk and + lzo-dev_1.08-r14_sh4.ipk). However with debian naming + enabled the package is renamed based on the name of the shared library, + which is liblzo.so.1.0.0 in this case. So the name + lzo is replaced with + liblzo1:~oe/build/titan-glibc-25%> find tmp/deploy/ipk/ -name '*lzo*' +tmp/deploy/ipk/sh4/liblzo1_1.08-r14_sh4.ipk +tmp/deploy/ipk/sh4/liblzo-dev_1.08-r14_sh4.ipk +tmp/deploy/ipk/sh4/liblzo-dbg_1.08-r14_sh4.ipk + + Some variables are available which effect the operation of the + debian renaming class: - - - inherit += "debian" - - + + + LEAD_SONAME + + + If the package actually contains multiple shared libraries + then one will be selected automatically and a warning will be + generated. This variable is a regular expression which is used to + select which shared library from those available is to be used for + debian renaming. + + + + + DEBIAN_NOAUTONAME_<pkgname> + + + If this variable is set to 1 for a package then debian + renaming will not be applied for the package. + + + + + AUTO_LIBNAME_PKGS + + + If set this variable specifies the prefix of packages which + will be subject to debian renaming. This can be used to prevent + all of the packages being renamed via the renaming policy. + + +
-- cgit 1.2.3-korg From 61459e55980ecc0aa5cbd94cfa8e5ef658150ec0 Mon Sep 17 00:00:00 2001 From: Jamie Lenehan Date: Sun, 29 Apr 2007 13:27:08 +0000 Subject: recipes: Clean up some of the spelling and grammar in the DEFAULT_PREFERENCE section. --- usermanual/chapters/recipes.xml | 59 ++++++++++++++++++++++------------------- 1 file changed, 31 insertions(+), 28 deletions(-) diff --git a/usermanual/chapters/recipes.xml b/usermanual/chapters/recipes.xml index 7ed33868f5..a7904f2b58 100644 --- a/usermanual/chapters/recipes.xml +++ b/usermanual/chapters/recipes.xml @@ -3210,50 +3210,53 @@ do_configure() {
Preferences: How to disable packages - When bitbake is asked to build a package and multiple version of - that package are available it will normally select the version with the - highest version number (where the version is defined via the - PV variable). + When bitbake is asked to build a package and multiple versions of + that package are available then bitbake will normally select the version + that has the highest version number (where the version number is defined + via the PV variable). For example if we were to ask bitbake to build procps and the following packages are available:~/oe%> ls packages/procps procps-3.1.15/ procps-3.2.1/ procps-3.2.5/ procps-3.2.7/ procps.inc procps_3.1.15.bb procps_3.2.1.bb procps_3.2.5.bb procps_3.2.7.bb -~/oe%>then we would expect that version 3.2.7 - (the highest version number) would be built. - - Sometimes this is not what you actually want to happen though. - Perhaps you have added a new version does not yet work or maybe the new - version has no support for your target yet. Help is at hand since bitbake - is not only looking at the version to decided which version to build but - is also looking at the preference for the versions, as defined via a - DEFAULT_PREFERENCE variable contained without the - recipes. - - By default DEFAULT_PREFERENCE is set to zero. - Bitbake will find the highest preference that is available and then for - all the packages at the preference level it will select the package with - the highest version. In general this means that adding a positive +~/oe%>then we would expect it to select version + 3.2.7 (the highest version number) to build. + + Sometimes this is not actually what you want to happen though. + Perhaps you have added a new version of the package that does not yet work + or maybe the new version has no support for your target yet. Help is at + hand since bitbake is not only looking at the version numbers to decided + which version to build but it is also looking at the preference for each + of those version. The preference is defined via the + DEFAULT_PREFERENCE variable contained within the + recipe. + + The default preference (when no + DEFAULT_PREFERENCE is specified) is zero. Bitbake will + find the highest preference that is available and then for all the + packages at the preference level it will select the package with the + highest version. In general this means that adding a positive DEFAULT_PREFERENCE will cause the package to be preferred over other versions and a negative DEFAULT_PREFERENCE will cause all other packages to be preferred. Imagine that you are adding procps version 4.0.0, but that it does - not yet work. You could delete it to make procps build so you can build a - working image, but what you really want it just for version 4.0.0 to be - ignored until it works. By adding:DEFAULT_PREFERENCE = "-1"to - the recipe it'll cause it to be ignored by bitbake (since all the existing - versions have a preference of 0). Note that you can still call bitbake - directly on the recipe:bitbake -b packages/procps/procps_4.0.0.bbThis + not yet work. You could delete or rename your new recipe so you can build + a working image, but what you really to do is just ignore the new 4.0.0 + version until it works. By adding:DEFAULT_PREFERENCE = "-1"to + the recipe this is what will happen. Bitbake will now ignore this version + (since all of the existing versions have a preference of 0). Note that you + can still call bitbake directly on the recipe:bitbake -b packages/procps/procps_4.0.0.bbThis enables you to test, and fix the package manually without having bitbake automatically select normally. - By using this in conjunction with overrides you can also disable (or - select) specific version for a specific architecture. The following + By using this feature in conjunction with overrides you can also + disable (or select) specific versions based on the override. The following example from glibc shows that this version has been disabled for the sh3 architecture because it doesn't support sh3. This will force bitbake to - try and select one of the other versions instead:packages/glibc/glibc_2.3.2+cvs20040726.bb:DEFAULT_PREFERENCE_sh3 = "-99" + try and select one of the other available versions of glibc + instead:packages/glibc/glibc_2.3.2+cvs20040726.bb:DEFAULT_PREFERENCE_sh3 = "-99"
-- cgit 1.2.3-korg From a35403110d02609e837e2c9835566825a5c75574 Mon Sep 17 00:00:00 2001 From: Jamie Lenehan Date: Wed, 2 May 2007 09:48:24 +0000 Subject: usermanual: Clean up the using bitbake/oe chapter to the point where it's almost useable. Still not included in user manual yet, probably needs a bit more work before that hppens. --- usermanual/chapters/usage.xml | 903 +++++++++++++++++++++++++++++++++++++----- usermanual/usermanual.xml | 3 +- 2 files changed, 805 insertions(+), 101 deletions(-) diff --git a/usermanual/chapters/usage.xml b/usermanual/chapters/usage.xml index 2e1f887d38..f2031b3346 100644 --- a/usermanual/chapters/usage.xml +++ b/usermanual/chapters/usage.xml @@ -1,138 +1,841 @@ - - Usage + + Using bitbake and OE
Introduction - Using bitbake + If your reading this manual you probably already have some idea of + what OpenEmbedded is all about, which is taking a lot of software and + creating something that you can run on another device. Its all about + downloading some source code, compiling it, creating packages (like .deb + or .rpm) and/or creating boot images that can written to flash on the + device. The complexities of cross-compiling and the variety of devices to + be supported lead to a lot more complexity in on OpenEmbedded based + distribution than you'd find in a typical desktop distribution (which + doesn't get cross-compiled). + + A major part of OpenEmbedded deals with compiling source code for + various projects. For each project OpenEmbedded has to: + + + + Download the source code, and any supporting files (such as + initscripts); + + + + Extract the source code and apply any patches that might be + wanted; + + + + Configure the software if needed (such as is done by running the + configure script); + + + + Compile everything; + + + + Package up all the files into some package format, like .deb or + .rpm or .ipk, ready for installation. + + + + As mentioned this is made for more complex than normal due + to: + + + + Cross-compiling: cross-compiling is difficult, and lots of + software has no support for cross-compiling. All packages included in + OE are cross-compiled; + + + + Due to cross-compiling the executable's that are created cannot + normally be run, so any software that tries to run things as part of + it's build process need to have changes made to handle this some other + way + + + + Of course there's a lot more to OE then just compiling packages + though. Just some of the things that OE can handle: + + + + Support for glibc and uclibc; + + + + Support for building for multiple targets; + + + + Dependencies - automatically building anything that is required + for the package your really want; + + + + Creation of flash and disk images for booting directly on the + target device; + + + + Support for various packaging formats; + + + + Automatically creating all of the cross-compiling tools you'll + need; + + + + Support for "native" packages that are built for the host + computer and not for the target; + + + + This chapter assumes you have master the Getting Start guides to + OpenEmbedded (see the OpenEmbedded web site for details), and therefore + have an appropriately configured setup and have managed to build the + cross-compilers for your target. This section talks you through some of + the background on what is happening with the aim of helping you understand + how to debug and develop within OpenEmbedded.
Work space - The work directory (the working area) is where all of the source is - extracted, patched and built: ~/devel/oe/build/titan-glibc-25%> ls - tmp/work/strace-4.5.14-r1 image/ install/ strace-4.5.14/ temp/ The - subdirectories in the working area are: image When the install is being - run for the package it's files are installed into this directory. They are - moved out when being placed into individual packages and so only the - directores it created should remain. Any other that remain have not been - packaged. - - install The install directory contains a subdirectory per package to - be created with the appropriate files located under each package (moved - from the image directory) and some files related to processing of the - packages. - - strace-4.5.14 This is the directory created by the extracted source - code. (Refered to by the S variable in the recipes). - - temp Scripts to perform the various stages (configure, compile, etc) - and the logs containing the output of those scripts. -
+ Let's start out by taking a look at a typically working area OE. + Note that this isn't exactly what you'll 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):%> find tmp -maxdepth 2 -type d +tmp +tmp/stamps +tmp/cross +tmp/cross/bin +tmp/cross/libexec +tmp/cross/lib +tmp/cross/share +tmp/cross/sh4-linux +tmp/cache +tmp/cache/titan +tmp/work +tmp/work/busybox-1.2.1-r13 +tmp/work/libice-1_1.0.3-r0 +tmp/work/arpwatch-2.1a15-r2 +... +tmp/rootfs +tmp/rootfs/bin +tmp/rootfs/usr +tmp/rootfs/media +tmp/rootfs/dev +tmp/rootfs/var +tmp/rootfs/lib +tmp/rootfs/sbin +tmp/rootfs/mnt +tmp/rootfs/boot +tmp/rootfs/sys +tmp/rootfs/proc +tmp/rootfs/etc +tmp/rootfs/home +tmp/rootfs/tmp +tmp/staging +tmp/staging/man +tmp/staging/x86_64-linux +tmp/staging/pkgdata +tmp/staging/pkgmaps +tmp/staging/var +tmp/staging/sh4-linux +tmp/staging/local +tmp/staging/etc +tmp/deploy +tmp/deploy/addons +tmp/deploy/ipk +tmp/deploy/sources +tmp/deploy/images -
- Temp dir + The various top level directories under tmp include: - The temp directory contains the scripts to perform various actions - and the log files generated by those actions: -
+ + + stamps + + + Nothing of interest to users in here. These time stamps are + used by bitbake to keep track of what tasks it has completed and + what tasks it still has outstanding. This is how it knows that + certain actions have been completed and it doesn't need to do them + again. + + + + + cross + + + Contains the cross-compiler toolchain. That is the gcc and + binutils that run on the host system but produce output for the + target system. + + + + + cache -
- Install dir + + Nothing of interest to users in here. This contains the + bitbake parse cache and is used to avoid the need to parse all of + the recipes each time bitbake is run. This makes bitbake a lot + faster on the 2nd and subsequent runs. + + - The install directory contains one subdirectory per package to be - generated, each containing the files to be included in that package, and - some package control files: + + work + + + The work directory. This is the directory in which all + packages are built - this is where the source code is extract, + patches applied, software configure, compiled, installed and + package. This is where you'll spend most of you time looking when + working in OE. + + + + + rootfs + + + The generated root filesystem image for your target device. + This is the contents of the root filesystem (NOTE: fakeroot means it + doesn't have the correct device special nodes and permissions to use + directly). + + + + + staging + + + Contains the staging area, which is used to stored natively + compiled tools and and libraries and headers for the target that are + required for building other software. + + + + + deploy + + + Contains the final output from OE. This includes the + installation packages (typically .ipkg packages) and flash and/or + disk images. This is where you go to get the final product. + + + + +
+ work directory + + The working directory is where all files are extracted and + everything is configured, compiled and packaged. In other words this is + where all the action happens. Each bitbake recipe will produce a + corresponding directory in the working area, with the name containing + the recipe name, version and the release number (as defined by the PR + variable in the recipe). + + In the following example we show some of the directories that are + created and in this case they are created directly in the work + directory:~%> find tmp/work -maxdepth 1 -type d | head -4 +tmp/work +tmp/work/busybox-1.2.1-r13 +tmp/work/libice-1_1.0.3-r0 +tmp/work/arpwatch-2.1a15-r2Depending on your distribution settings + you may have an additional subdirectory present:~%> find tmp/work -maxdepth 2 -type d | head -4 +tmp/work +tmp/work/sh4-linux +tmp/work/sh4-linux/busybox-1.2.1-r13 +tmp/work/sh4-linux/libice-1_1.0.3-r0 +tmp/work/sh4-linux/arpwatch-2.1a15-r2 + + where are additional directory corresponding to the target + architecture and OS has been inserted. This is added by the use of the + multimachine feature which is used to allow builds + for multiple targets within the one work directory (which in turn + enables the sharing of native functionality and a reduction in the time + taken to build for multiple machines). We'll assume multimachine is not + being used for the rest of this chapter, just remember to add the extra + directory if your distribution is using it. + + Using lzo 1.08 as an example we'll examine the working directory + and see what it contain for a typical recipe:%> find tmp/work/lzo-1.08-r14 -maxdepth 1 +tmp/work/lzo-1.08-r14 +tmp/work/lzo-1.08-r14/temp +tmp/work/lzo-1.08-r14/lzo-1.08 +tmp/work/lzo-1.08-r14/install +tmp/work/lzo-1.08-r14/image + + The directory, tmp/work/lzo-1.08-r14, is know as the working + directory for the recipe is held in the WORKDIR variable in bitbake. You'll sometimes see + recipes refer directly to WORKDIR and + if so this is the directory they are referring to. The 1.08 is the version of lzo and the r14 is the release number, as defined by the + PR variable in the recipe. + + Under WORKDIR there are four + directories: + + + + temp + + + The temp directories contains logs and in some cases scripts + that actually implement specific tasks. + + You can look at the logs in this directory to get more + information into what happened (or didn't happen). This is usually + the first thing to look at when things are going wrong and these + usually need to be included when reporting bugs. + + The scripts can be used to see what a particular task, such + as configure or compile, is trying to do. + + + + + lzo-1.08 + + + This is the unpacked source code directory, which was + created when the lzo source code was extracted in this directory. + The name and format of this directory is therefore dependent on + the actual source code packaging. Within recipes this directory is + referred to as S and is usually + expected to be named like this, that is + <name>-<version>. If the source + code extracts to somewhere else you would need to manually specify + the value of S in your + recipe. + + + + + install + + + The installation directory (or destination directory) is + where the software needs to be installed into in order to be + packaged. This directory is referred to as D in recipes. So instead of installing into + /usr/bin and /usr/lib for example you would need to + install into ${D}/usr/bin and + ${D}/usr/lib in order for the + packaging system to work. + + + + + image + + + The image directory is used to split the installed files + into separate packages. One subdirectory is created per package to + be generated and the files and moved from the install directory + (D) over to this directory as + each packaging instruction is processed. Typically there will be + separate documentation (-doc), debugging + (-dbg) and development + (-dev) packages automatically created. + + + + + The various variables that can be used in a recipe are described + in detail in the recipes chapter of this manual. + + What can you do with this information? How about checking out what + happened during the configuration of lzo:~%> less tmp/work/lzo-1.08-r14/temp/log.do_configure.* +... +checking whether ccache sh4-linux-gcc -ml -m4 suffers the -fschedule-insns bug... unknown +checking whether ccache sh4-linux-gcc -ml -m4 suffers the -fstrength-reduce bug... unknown +checking whether ccache sh4-linux-gcc -ml -m4 accepts -fstrict-aliasing... yes +checking the alignment of the assembler... 0 +checking whether to build assembler versions... no +configure: creating ./config.status +config.status: creating Makefile +config.status: creating examples/Makefile +config.status: creating include/Makefile +config.status: creating ltest/Makefile +config.status: creating minilzo/Makefile +config.status: creating src/Makefile +config.status: creating tests/Makefile +config.status: creating config.h +config.status: executing depfiles commands + + Or perhaps you want to see which files were included in each of + the generated packages:~%> find tmp/work/lzo-1.08-r14/install +tmp/work/lzo-1.08-r14/install +tmp/work/lzo-1.08-r14/install/lzo-doc +tmp/work/lzo-1.08-r14/install/lzo-dbg +tmp/work/lzo-1.08-r14/install/lzo-dbg/usr +tmp/work/lzo-1.08-r14/install/lzo-dbg/usr/lib +tmp/work/lzo-1.08-r14/install/lzo-dbg/usr/lib/.debug +tmp/work/lzo-1.08-r14/install/lzo-dbg/usr/lib/.debug/liblzo.so.1.0.0 +tmp/work/lzo-1.08-r14/install/lzo-dev +tmp/work/lzo-1.08-r14/install/lzo-dev/usr +tmp/work/lzo-1.08-r14/install/lzo-dev/usr/include +tmp/work/lzo-1.08-r14/install/lzo-dev/usr/include/lzo2a.h +tmp/work/lzo-1.08-r14/install/lzo-dev/usr/include/lzo1y.h +tmp/work/lzo-1.08-r14/install/lzo-dev/usr/include/lzo1.h +tmp/work/lzo-1.08-r14/install/lzo-dev/usr/include/lzo1b.h +tmp/work/lzo-1.08-r14/install/lzo-dev/usr/include/lzo1f.h +tmp/work/lzo-1.08-r14/install/lzo-dev/usr/include/lzoconf.h +tmp/work/lzo-1.08-r14/install/lzo-dev/usr/include/lzo1x.h +tmp/work/lzo-1.08-r14/install/lzo-dev/usr/include/lzo16bit.h +tmp/work/lzo-1.08-r14/install/lzo-dev/usr/include/lzo1a.h +tmp/work/lzo-1.08-r14/install/lzo-dev/usr/include/lzo1z.h +tmp/work/lzo-1.08-r14/install/lzo-dev/usr/include/lzoutil.h +tmp/work/lzo-1.08-r14/install/lzo-dev/usr/include/lzo1c.h +tmp/work/lzo-1.08-r14/install/lzo-dev/usr/lib +tmp/work/lzo-1.08-r14/install/lzo-dev/usr/lib/liblzo.a +tmp/work/lzo-1.08-r14/install/lzo-dev/usr/lib/liblzo.so +tmp/work/lzo-1.08-r14/install/lzo-dev/usr/lib/liblzo.la +tmp/work/lzo-1.08-r14/install/lzo.shlibdeps +tmp/work/lzo-1.08-r14/install/lzo-locale +tmp/work/lzo-1.08-r14/install/lzo +tmp/work/lzo-1.08-r14/install/lzo/usr +tmp/work/lzo-1.08-r14/install/lzo/usr/lib +tmp/work/lzo-1.08-r14/install/lzo/usr/lib/liblzo.so.1 +tmp/work/lzo-1.08-r14/install/lzo/usr/lib/liblzo.so.1.0.0 +
-
- Deploy dir +
+ Tasks + + When you build a software package you generally perform a number of + steps or tasks. These would include things like "download the source + code", "unpack the source code", "run the configure script", "build the + software", "install the software" etc. OpenEmbedded builds software in a + similar way - by performing a set of tasks. Understanding these tasks is + critical to understanding how things get done in OpenEmbedded. + + + + The following is a list of the most commonly seen tasks: + + + + fetch + + + The fetch task is responsible for fetching any source code + that is required. This means things such as downloading files and + checking out from svn or git repositories for example. + + + + + unpack + + + The unpack task is responsible for extracting files from + archives, such as .tar.gz, into the working area and copying any + additional files into the working area. + + + + + patch + + + The patch task is responsible for applying any patches to the + unpacked source code + + + + + configure + + + The configure task takes care of the configuration of the + package. Running a configure script ("./configure <options>") + is probably the form of configuration that is most recognised but + it's not the only configuration system that exists. + + + + + compile - The deploy directory is where the final packaged files (typically - .ipk files) and and flash images or nfs images etc end up. For our strace - example we end up with just two .ipk files, one for the application and - one for the documentation. + + The compile task actually compiles the software. This could be + as simple as running "make". + + + + + populate_staging (stage) + + + The populate_staging task (stage is an alternate, easier to + type name, that can be used to refer to this task) is responsible + for making available libraries and headers (if any) that may be + required by other packages to build. For example if you compile zlib + then it's headers and the library need to be made available for + other applications to include and link against. + + NOTE that this is different to the install (and packaging) + related tasks in that this is making available things for use during + build on the development host while the installed files are being + made available for use on the target device. + + + + + + + + + + + + + install + + + The install task is responsible for actually installing the + software. Now this needs to install the software into the + destination directory (${D}) but once package the destination + directory will be removed from all the files. In other words if you + install something into ${D}/bin then it will end up in the /bin + directory in the package and therefore on the target. + + + + + package + + + The package task takes the installed files and splits them + into separate directories under the ${WORKDIR}/install directory, + one per package. It moves the files for the destination directory, + ${D}, that they were installed in into the appropriate packages + subdirectory. Usually there will be a main package a separate + documentation (-doc), development (-dev) and debugging packages + (-dbg) for example. + + + + + package_write + + + The package_write task is responsible for taking each packages + subdirectory and creating any actual installation package, such as + .ipk, .deb or .rpm. + + + + + + + + + + + + + + + Note that these are not the only possible set of tasks. There are + various methods available to insert additional tasks in between existing + tasks if needed. As an example the insane.bbclass, which performs various + QA checks, does these checks by inserting a new task, qa_configure, + between the configure and compile tasks to check on the result of + configuration and another new tasks, qa_staging, between populate_staging + and build to validate the files that have been staged. + + + + You can see a list of all the tasks available for a specific recipe + by explicitly calling bitbake on the recipe and asking it for a list of + tasks: + + ~%> bitbake -b packages/perl/perl_5.8.8.bb -c listtasks +NOTE: package perl-5.8.8: started +NOTE: package perl-5.8.8-r11: task do_listtasks: started +do_fetchall +do_listtasks +do_rebuild +do_compile +do_build +do_populate_staging +do_mrproper +do_fetch +do_configure +do_clean +do_package +do_unpack +do_install +do_package_write +do_distribute_sources +do_showdata +do_qa_configure +do_qa_staging +do_patch +NOTE: package perl-5.8.8-r11: task do_listtasks: completed +NOTE: package perl-5.8.8: completed +~%> + + Note that do_ prefixed to the tasks - the + do_<task> is the name of the method that + implements the required functionality for + <task>, so the above is actually listing the + methods that implement the available tasks. It's sometimes a but confusing + but just remember that the do_ is the method name (with a definition + usually found in the of the .bbclass files in the classes + directory.)
-
+
Working with a single package When working on fixing and/or creating a single recipe you can ask - bitbake to deal with a single .bb file only. The -b <bb-file> option - asks bitbake to only process the named file. So to clean and rebuild a - single package you can do: %> bitbake -b <bb-file> -c clean %> - bitbake -D -b <bb-file> The various options that are useful here - are: -b <bb-file> Specify which recipe to process -c <action> - Specify which action to perform (see below) -D Enable debugging output. - This gives you a lot more output during the operation. -f Force on - operation. This is useful in getting bitbake to perform some operation it - normally wouldn't do. For example, if you try and compile twice ina row - then bitbake will not do anything on the second attempt since it has - already gone through the compile stage. By adding -f forces it the action - to take place. The most common actions (used with -c) are: fetch Will - download any files that need to be fetched. unpack Extracts the source - code into the working directory, but does not apply any patches. patch - Applies patches into the source in the working directory. configure Runs - the configuration task for the recipe. compile Actually compile - everything. stage Copy required files into the staging area. install - Install files that are going to be package. package Package files. - Normally this means creating the .ipkg files. clean Clean the package - - this deletes the entire working directory for the package, so on the next - build the source will be extracted, patches applied etc. Note that each - action will run any preceeding actions that have not yet been performed. - So starting with compile will also peform the fetch, unpack, patch and - configure actions. A typically development session would involve editing - files in the working directory and running: %> bitbake -f - packages/testapp/testapp_4.3.bb -c compile (Try and compile) look at logs, - edit some files in working area %> bitbake -f - packages/testapp/testapp_4.3.bb -c compile -f (Force re-compile) and then - once appropriate patches have been made and the recipe updated: %> - bitbake -f packages/testapp/testapp_4.3.bb -c clean (Remove working files) - %> bitbake -f packages/testapp/testapp_4.3.bb (Try everything from - scratch) A full list of available tasks for a specific package can be - obtained with the listtasks task: %> bitbake -f - packages/testapp/testapp_4.3.bb -c listtasks + bitbake to deal directly with a single .bb file only. The -b + <bb-file> option asks bitbake to only process the named + file. Note that this ignores any dependencies that are in the recipe, so + these must have already been handled. + + A typically example of this is to clean and then rebuild a package + with some debugging information: + + %> bitbake -b <bb-file> -c clean +%> bitbake -b <bb-file> -D + + The various options to bitbake that are useful here are: + + + + -b <bb-file> + + + Specify which recipe to process; + + + + + -c <action> + + + Specify which action to perform, typically the name of one of + the tasks supported by the recipe; + + + + + -D + + + Display debugging information, use two -D's for additional debugging. + + + + + -f + + + Force an operation. This is useful in getting bitbake to + perform some operation it normally wouldn't do. For example, if you + try and compile twice in a row then bitbake will not do anything on + the second attempt since it has already performed the compile task. + By adding -f it will force it to + perform the action regardless of if it thinks it's been done + previously. + + + + + The most common actions (used with -c) are: + + + + fetch + + + Try to download all of the required source files, but don't do + anything else with them. + + + + + unpack + + + 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). + + + + + patch + + + Apply any patches. + + + + + configure + + + Performs and configuration that is required for the + software. + + + + + compile + + + Perform the actual compilation steps of the software. + + + + + stage + + + If any files, such as header and libraries, will be required + by other packages then they need to be installed into the staging + area and that's what this task takes care of. + + + + + install + + + Install the software in preparation for packaging. + + + + + package + + + Package the software. Remember that this moves the files from + the installation directory, D, into the packing install area. So to + re-package you also need to re-install first. + + + + + clean + + + Delete the entire directory for this version of the software. + Usually done to allow a test build with no chance of old files or + changes being left behind. + + + + + Note that each of the actions that corresponds to task's 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. + + A typically development session might involve editing files in the + working directory and recompiling until it all works:[... test ...] +%> bitbake -b packages/testapp/testapp_4.3.bb -c compile -D + +[... save a copy of main.c and make some changes ...] +%> vi tmp/work/testapp-4.3-r0/main.c +%> bitbake -b packages/testapp/testapp_4.3.bb -c compile -D -f + +[... create a patch and add it to the recipe ...] +%> vi packages/testapp/testapp_4.3.bb + +[... test from clean ...] +%> bitbake -b packages/testapp/testapp_4.3.bb -c clean +%> bitbake -b packages/testapp/testapp_4.3.bb + +[... NOTE: How to create the patch is not covered at this point ...] + + Here's another example showing how you might go about fixing up the + packaging in your recipe:%> bitbake -b packages/testapp/testapp_4.3.bb -c install -f +%> bitbake -b packages/testapp/testapp_4.3.bb -c stage -f +%> find tmp/work/testapp_4.3/install +... +%> vi packages/testapp/testapp_4.3.bbAt this stage you play with + the PACKAGE_ and FILES_ variables and then repeat the above + sequence. + + Note how we install and then stage. This is one of those things + where understanding the tasks helps a lot! Remember that stage moves the + files from where they were installed (${D}) into the various + subdirectories (under ${WORKDIR}/install) + for each package. So if you try and run a stage task without a prior + install there won't be any files there to stage! Note also that the stage + tasks clears all the subdirectories in ${WORKDIR}/install so you won't get any left over + files. But beware, the install task doesn't clear ${D} directory, so any left over files from a + previous packing attempt will be left behind (which is ok if all you care + about it staging).
-
+
Interactive bitbake - To interactively test things use: %> bitbake -i this will open - the bitbake shell. From here there are a lot of commands available (try - help). First thing you will want to do is parse all of the recipes. - BB>> parse You can now build a specific recipe: BB>> build - net-snmp If it fails you may want to clean the build before trying again: - BB>> clean net-snmp 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 build again: BB>> clean net-snmp BB>> - reparse net-snmp BB>> build net-snmp Note that you can use wildcards - in the bitbake shell as well: BB>> build t* The interacive mode was - most useful with bitbake versions prior to 1.4 where the entire set of - recipes had to be reparsed each time bitbake was run. Since bitbake 1.4 - the parseing is cached between runs and so it is no where near as painful - to run individual bitbake commands and therefore the interactive mode is - no longer as important as it once was. [edit] + To interactively test things use:%> bitbake -ithis + will open the bitbake shell. From here there are a lot of commands + available (try help). + + First thing you will want to do is parse all of the recipes (recent + bitbake version do this automatically when needed, so you don't need to + manually do this anymore):BB>> parseYou can now + build a specific recipe:BB>> build net-snmpIf it + fails you may want to clean the build before trying again:BB>> clean net-snmpIf + 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 + build again:BB>> clean net-snmp +BB>> reparse net-snmp +BB>> build net-snmpNote that you can use wildcards in the + bitbake shell as well:BB>> build t* + +
Devshell - + [To be done]
-
- Workflow +
+ Patching and patch management - fetch Will download any files that need to be fetched. unpack - Extracts the source code into the working directory, but does not apply - any patches. patch Applies patches into the source in the working - directory. configure Runs the configuration task for the recipe. compile - Actually compile everything. stage Copy required files into the staging - area. install Install files that are going to be package. package Package - files. Normally this means creating the .ipkg files. + [To be done]
\ No newline at end of file diff --git a/usermanual/usermanual.xml b/usermanual/usermanual.xml index e978dd50cc..88d8a408b8 100644 --- a/usermanual/usermanual.xml +++ b/usermanual/usermanual.xml @@ -5,6 +5,7 @@ --> @@ -833,7 +834,7 @@ NOTE: Couldn't find shared library provider for libm.so.6 - + -- cgit 1.2.3-korg From 8572b86970698184c4e1d51bd4f46437963b7bae Mon Sep 17 00:00:00 2001 From: Jamie Lenehan Date: Wed, 2 May 2007 10:01:08 +0000 Subject: usermanual: The image_ipkg class is now just the image class. Update all references. Modify description to include details about how it can potentially support other packaging types now. Probably needs a more detailed check to see if anything else changed. --- usermanual/reference/class_image.xml | 291 +++++++++++++++++++++++++++++ usermanual/reference/class_image_ipkg.xml | 290 ---------------------------- usermanual/reference/class_rootfs_ipkg.xml | 6 +- usermanual/reference/fakeroot.xml | 4 +- usermanual/reference/image_types.xml | 2 +- usermanual/usermanual.xml | 4 +- 6 files changed, 299 insertions(+), 298 deletions(-) create mode 100644 usermanual/reference/class_image.xml delete mode 100644 usermanual/reference/class_image_ipkg.xml diff --git a/usermanual/reference/class_image.xml b/usermanual/reference/class_image.xml new file mode 100644 index 0000000000..7d203f888c --- /dev/null +++ b/usermanual/reference/class_image.xml @@ -0,0 +1,291 @@ + +
+ image class + + The image class is used to generate filesystem images containing a + root filesystem, as generated by the rootfs class for the package type, such + as , for use on the target device. This + could be a jffs2 image which is to be written directly + into the flash on the target device for example. In addition this class also + configures the ipkg feeds (where to get updates from) and is able to + generate multiple different image types. + + Summary of the actions performed by the + image_ipkg class: + + + + Inherits the rootfs class for the appropriate package type, + typically , in order to bring in the + functionality required to generate a root filesystem image. The root + filesystem image is generate from a set of of packages (typically .ipkg + packages), and then the required images are generated using the contents + of the root filesystem; + + + + Sets BUILD_ALL_DEPS = "1" to force the + dependency system to build all packages that are listed in the + RDEPENDS and/or RRECOMENDS of the + packages to be installed; + + + + Determines the name of the image device tables or table + (IMAGE_DEVICE_TABLES/IMAGE_DEVICE_TABLE) which will + be used to describe the device nodes to create in + /dev directory in the root filesystem; + + + + Erases the contents of any existing root filesystem image, + ${IMAGE_ROOTFS}; + + + + If devfs is not being used then the /dev + directory, ${IMAGE_ROOTFS}/dev, will be created and + then populated with the device nodes described by the image device table + or tables (using "makedevs -r ${IMAGE_ROOTFS} -D + <table>" for each device table); + + + + Calls into to install all of + the required packages into the root filesystem; + + + + Configures the ipkg feed information in the root filesystem for + the FEED_URIS; + + + + Runs any image pre-processing commands as specified via + ${IMAGE_PREPROCESS_COMMAND}; + + + + Calls bbimage on the root filesystem for each + required image type, as specified via + ${IMAGE_FSTYPES}, to generate the actual filesystem + images; + + + + Runs any image post-processing commands, as specified via + ${IMAGE_POSTPROCESS_COMMAND}. + + + + The following variables may be used to control some of the behaviour + of this class (remember we use to build + the filesystem image, so look at the variables defined by that class as + well): + + + + USE_DEVFS + + + Indicates if the image will be using devfs, the device + filesystem, or not. If devfs is being used then no + /dev directory will be required in the image. Set + to "1" to indicate that devfs is being used. Note + that devfs has been removed from the Linux kernel in the 2.6 series + and most platforms are moving towards the use of udev as a replacement + for devfs. + + Default: "0" + + + + + IMAGE_DEVICE_TABLES + + + Specifies one, or more, files containing a list of the device + nodes that should be created in the /dev directory + of the image. Each file is searched for via the + ${BBPATH} and therefore can be specified as a file + relative to the top of the build. Device files are processed in the + specified order. NOTE: If IMAGE_DEVICE_TABLE is set + then this variable is ignored. + + Example: IMAGE_DEVICE_TABLES = + "files/device_table-minimal.txt files/device_table_add-sci.txt + device_table_add-sm.txt" + + Default: + "files/device_table-minimal.txt" + + + + + IMAGE_DEVICE_TABLE + + + Specifies the file that lists the device nodes that should be + created in the /dev directory of the image. This + needs to be an absolute filename and so should be specified relative + to ${BBPATH}. Only a single device table is + supported. Use IMAGE_DEVICE_TABLES instead if you + want to use multiple device tables. + + Default: "" + + + + + IMAGE_PREPROCESS_COMMAND + + + Additional commands to run prior to processing the image. Note + that these command run within the same + instance as the rest of this class. + + Default: "" + + + + + IMAGE_POSTPROCESS_COMMAND + + + Additional commands to run after processing the image. Note that + these command run within the same instance + as the rest of this class. + + Default: "" + + + + + IMAGE_FSTYPES + + + Specifies the type of image files to create. The supported image + types, and details on modifying existing types and on creating new + types, are described in the section. + This variable is set to a space seperated list of image types to + generate. + + Example: "jffs2 tar.gz" + + Default: "jffs2" + + + + + FEED_URIS + + + The name of the feeds to be configured in the image by default. + Each entry consists of the feed name, followed by two pound signs and + then followed by the actual feed URI. + + Example: FEED_URIS = + "example##http://dist.example.com/ipkg-titan-glibc/" + + Default: "" + + + + +
+ Special node handling (fakeroot) + + Special nodes, such as /dev nodes, and files with + special permissions, such as suid files, are handled via the system. This means that when you view the contents + of the root filesystem these device appear to be created + incorrectly: + + The IMAGE_PREPROCESS_COMMAND and + IMAGE_POSTPROCESS_COMMAND variables will be processed + within the same instance as the rest of the + rest of this class. +
+ +
+ Device (/dev) nodes + + There are two variables that can be defined for creating device + nodes. The new method supports multiple device node tables and supports + searching for these tables via the ${BBPATH} so that + relative file names may be used. + + The following example from machine/titan.conf + shows the use of multiple device tables: + + # Add the SCI devices to minimal /dev +IMAGE_DEVICE_TABLES = "files/device_table-minimal.txt files/device_table_add-sci.txt device_table_add-sm.txt" + + + It uses the standard minimal device tables but adds some additional + items which are not normally needed: + + + + files/device_table-minimal.txt + + + This is the standard minimal set of device nodes. + + + + + files/device_table_add-sci.txt + + + This contains details for creating the + /dev/SC{0,1,2} nodes which are required for the + SH processors on board SCI and SCIF serial ports. On the titan + hardware the serial console is provided via one of these ports and + so we require the device node to be present. + + + + + device_table_add-sm.txt + + + This contains details for creating the + /dev/sm0 and /dev/sm0p{0,1,2} + devices nodes for the block driver, and the associated partitions, + that are used to manage the on board flash on the titan + hardware. + + + + + Prior to support for multiple device tables this would have required + the creation of a titan specific device table. +
+ +
+ Image types + + The type of filesystem images to create are specified via the + IMAGE_FSTYPES variable. A full description of the + available image types, options of the images and details on creating new + image types is provided in the + section. +
+ +
+ Package feeds (feed_uris) + + Package feeds are used by the ipkg command to determine where to + retrieve updates and new packages from. + + Multiple feeds are supported. Each feed provides a feed name and the + URL which will contain the packages. The following example shows the + addition of two feeds, one called base and one called + updates: + + FEED_URIS += " \ + base##http://oe.example.com/releases/${DISTRO_VERSION}/feed/base \ + updates##http://oe.example.com/releases/${DISTRO_VERSION}/feed/updates" +
+
\ No newline at end of file diff --git a/usermanual/reference/class_image_ipkg.xml b/usermanual/reference/class_image_ipkg.xml deleted file mode 100644 index 0b440eba45..0000000000 --- a/usermanual/reference/class_image_ipkg.xml +++ /dev/null @@ -1,290 +0,0 @@ - -
- image_ipkg class - - The image_ipkg class is used to generate filesystem images containing - a root filesystem, as generated by the , - for use on the target device. This could be a jffs2 - image which is to be written directly into the flash on the target device - for example. In addition this class also configures the ipkg feeds (where to - get updates from) and is able to generate multiple different image - types. - - Summary of the actions performed by the - image_ipkg class: - - - - Inherits the in order to - bring in the functionality required to generate a root filesystem image. - The root filesystem image is generate from a set of ipkg packages, and - then the required images are generated using the contents of the root - filesystem; - - - - Sets BUILD_ALL_DEPS = "1" to force the - dependency system to build all packages that are listed in the - RDEPENDS and/or RRECOMENDS of the - packages to be installed; - - - - Determines the name of the image device tables or table - (IMAGE_DEVICE_TABLES/IMAGE_DEVICE_TABLE) which will - be used to describe the device nodes to create in - /dev directory in the root filesystem; - - - - Erases the contents of any existing root filesystem image, - ${IMAGE_ROOTFS}; - - - - If devfs is not being used then the /dev - directory, ${IMAGE_ROOTFS}/dev, will be created and - then populated with the device nodes described by the image device table - or tables (using "makedevs -r ${IMAGE_ROOTFS} -D - <table>" for each device table); - - - - Calls into to install all of - the required packages into the root filesystem; - - - - Configures the ipkg feed information in the root filesystem for - the FEED_URIS; - - - - Runs any image pre-processing commands as specified via - ${IMAGE_PREPROCESS_COMMAND}; - - - - Calls bbimage on the root filesystem for each - required image type, as specified via - ${IMAGE_FSTYPES}, to generate the actual filesystem - images; - - - - Runs any image post-processing commands, as specified via - ${IMAGE_POSTPROCESS_COMMAND}. - - - - The following variables may be used to control some of the behaviour - of this class (remember we use to build - the filesystem image, so look at the variables defined by that class as - well): - - - - USE_DEVFS - - - Indicates if the image will be using devfs, the device - filesystem, or not. If devfs is being used then no - /dev directory will be required in the image. Set - to "1" to indicate that devfs is being used. Note - that devfs has been removed from the Linux kernel in the 2.6 series - and most platforms are moving towards the use of udev as a replacement - for devfs. - - Default: "0" - - - - - IMAGE_DEVICE_TABLES - - - Specifies one, or more, files containing a list of the device - nodes that should be created in the /dev directory - of the image. Each file is searched for via the - ${BBPATH} and therefore can be specified as a file - relative to the top of the build. Device files are processed in the - specified order. NOTE: If IMAGE_DEVICE_TABLE is set - then this variable is ignored. - - Example: IMAGE_DEVICE_TABLES = - "files/device_table-minimal.txt files/device_table_add-sci.txt - device_table_add-sm.txt" - - Default: - "files/device_table-minimal.txt" - - - - - IMAGE_DEVICE_TABLE - - - Specifies the file that lists the device nodes that should be - created in the /dev directory of the image. This - needs to be an absolute filename and so should be specified relative - to ${BBPATH}. Only a single device table is - supported. Use IMAGE_DEVICE_TABLES instead if you - want to use multiple device tables. - - Default: "" - - - - - IMAGE_PREPROCESS_COMMAND - - - Additional commands to run prior to processing the image. Note - that these command run within the same - instance as the rest of this class. - - Default: "" - - - - - IMAGE_POSTPROCESS_COMMAND - - - Additional commands to run after processing the image. Note that - these command run within the same instance - as the rest of this class. - - Default: "" - - - - - IMAGE_FSTYPES - - - Specifies the type of image files to create. The supported image - types, and details on modifying existing types and on creating new - types, are described in the section. - This variable is set to a space seperated list of image types to - generate. - - Example: "jffs2 tar.gz" - - Default: "jffs2" - - - - - FEED_URIS - - - The name of the feeds to be configured in the image by default. - Each entry consists of the feed name, followed by two pound signs and - then followed by the actual feed URI. - - Example: FEED_URIS = - "example##http://dist.example.com/ipkg-titan-glibc/" - - Default: "" - - - - -
- Special node handling (fakeroot) - - Special nodes, such as /dev nodes, and files with - special permissions, such as suid files, are handled via the system. This means that when you view the contents - of the root filesystem these device appear to be created - incorrectly: - - The IMAGE_PREPROCESS_COMMAND and - IMAGE_POSTPROCESS_COMMAND variables will be processed - within the same instance as the rest of the - rest of this class. -
- -
- Device (/dev) nodes - - There are two variables that can be defined for creating device - nodes. The new method supports multiple device node tables and supports - searching for these tables via the ${BBPATH} so that - relative file names may be used. - - The following example from machine/titan.conf - shows the use of multiple device tables: - - # Add the SCI devices to minimal /dev -IMAGE_DEVICE_TABLES = "files/device_table-minimal.txt files/device_table_add-sci.txt device_table_add-sm.txt" - - - It uses the standard minimal device tables but adds some additional - items which are not normally needed: - - - - files/device_table-minimal.txt - - - This is the standard minimal set of device nodes. - - - - - files/device_table_add-sci.txt - - - This contains details for creating the - /dev/SC{0,1,2} nodes which are required for the - SH processors on board SCI and SCIF serial ports. On the titan - hardware the serial console is provided via one of these ports and - so we require the device node to be present. - - - - - device_table_add-sm.txt - - - This contains details for creating the - /dev/sm0 and /dev/sm0p{0,1,2} - devices nodes for the block driver, and the associated partitions, - that are used to manage the on board flash on the titan - hardware. - - - - - Prior to support for multiple device tables this would have required - the creation of a titan specific device table. -
- -
- Image types - - The type of filesystem images to create are specified via the - IMAGE_FSTYPES variable. A full description of the - available image types, options of the images and details on creating new - image types is provided in the - section. -
- -
- Package feeds (feed_uris) - - Package feeds are used by the ipkg command to determine where to - retrieve updates and new packages from. - - Multiple feeds are supported. Each feed provides a feed name and the - URL which will contain the packages. The following example shows the - addition of two feeds, one called base and one called - updates: - - FEED_URIS += " \ - base##http://oe.example.com/releases/${DISTRO_VERSION}/feed/base \ - updates##http://oe.example.com/releases/${DISTRO_VERSION}/feed/updates" -
-
\ No newline at end of file diff --git a/usermanual/reference/class_rootfs_ipkg.xml b/usermanual/reference/class_rootfs_ipkg.xml index 930272ebf9..b60adf8e70 100644 --- a/usermanual/reference/class_rootfs_ipkg.xml +++ b/usermanual/reference/class_rootfs_ipkg.xml @@ -8,8 +8,8 @@ the root filesystem of the target device. This class is normally not used directly, but instead used from the - which creates images from a set of - .ipkg files. + which creates images from a set of package + (typically .ipkg) files. Summary of actions performed by the rootfs_ipkg class: @@ -210,6 +210,6 @@ The class also provides a function real_do_rootfs which is executed without and therefore can be - used from other classes, such as , that + used from other classes, such as , that are already running under the control of .
\ No newline at end of file diff --git a/usermanual/reference/fakeroot.xml b/usermanual/reference/fakeroot.xml index 68892fce87..5eb6a48eb0 100644 --- a/usermanual/reference/fakeroot.xml +++ b/usermanual/reference/fakeroot.xml @@ -5,7 +5,7 @@ The fakeroot program is designed to allow non-root users to perform actions that would normally require root privileges as part of the package generation process. It is used by the - for root filesystem creation and by the + for root filesystem creation and by the for the creation of filesystem images. Some recipes also use fakeroot to assist with parts of the package installation (usually) or building where root privligeses are expected by the package. @@ -32,7 +32,7 @@ the command will fail, telling is that we do not have permission to create device nodes:~%> mknod hdc b 22 0 mknod: `hdc': Operation not permittedYet the is able to create device nodes and include + linkend="image_class" /> is able to create device nodes and include them in the final images, all without the need to have root privileges. diff --git a/usermanual/reference/image_types.xml b/usermanual/reference/image_types.xml index 2efb9b8072..453f3600fb 100644 --- a/usermanual/reference/image_types.xml +++ b/usermanual/reference/image_types.xml @@ -7,7 +7,7 @@ several variables which can be used to control the type of output images and the settings for those images, such as endianess or compression ratios. This section details the available images and the variables that effect them. See - the section for details on how image + the section for details on how image generation is configured. The final root file system will consist of all of the files located in diff --git a/usermanual/usermanual.xml b/usermanual/usermanual.xml index 88d8a408b8..99dc72137b 100644 --- a/usermanual/usermanual.xml +++ b/usermanual/usermanual.xml @@ -13,7 +13,7 @@ - + @@ -857,7 +857,7 @@ NOTE: Couldn't find shared library provider for libm.so.6 &fakeroot; - &class-image_ipkg; + &class-image; &image-types; -- cgit 1.2.3-korg From e1cc792c540fe305f094a79ff633fe63110d7d4a Mon Sep 17 00:00:00 2001 From: Jamie Lenehan Date: Thu, 3 May 2007 12:47:10 +0000 Subject: usermanual: Update image types to match recent changes: - ext3 and ext3.gz have been added - cpio and cpio.gz have been added - default options for jffs2, squashfs and squashfs-lzma have been changed - ext2.gz now deletes tmp files so leftovers don't break next run - tar has been changed to make tars instead of tar.bz2's - force lzo to be disabled for jffs2 --- usermanual/reference/image_types.xml | 126 +++++++++++++++++++++++++++++------ 1 file changed, 105 insertions(+), 21 deletions(-) diff --git a/usermanual/reference/image_types.xml b/usermanual/reference/image_types.xml index 453f3600fb..8d01559fc0 100644 --- a/usermanual/reference/image_types.xml +++ b/usermanual/reference/image_types.xml @@ -93,17 +93,21 @@ Creates jffs2 "Journaling flash file system 2" images. This is a read/write, compressed filesystem for mtd (flash) devices. It is not supported for block - devices.IMAGE_CMD_jffs2 = "mkfs.jffs2 --root=${IMAGE_ROOTFS} \ + devices.IMAGE_CMD_jffs2 = "mkfs.jffs2 \ + -x lzo \ + --root=${IMAGE_ROOTFS} \ --faketime \ --output=${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.jffs2 \ ${EXTRA_IMAGECMD}" - The EXTRA_IMAGECMD variable for jffs2 is - passed to mkfs.jffs2 and by default is used to - enabled pad, to define the endianess and to specify the block - size: + The EXTRA_IMAGECMD variable for jffs2 + passed to mkfs.jffs2 and is left empty by + default:EXTRA_IMAGECMD_jffs2 = "" - EXTRA_IMAGECMD_jffs2 = "--pad --little-endian --eraseblock=0x40000" + This was not always empty, prior to 2007/05/02 the + EXTRA_IMAGECMD variable for jffs2 was set to + enable padding, to define the endianess and to specify the block + size:EXTRA_IMAGECMD_jffs2 = "--pad --little-endian --eraseblock=0x40000" @@ -121,8 +125,8 @@ ${EXTRA_IMAGECMD}" The EXTRA_IMAGECMD variable for cramfs is - passed to mkcramfs and is not used by - default. + passed to mkcramfs and is left empty by + default:EXTRA_IMAGECMD_cramfs = "" @@ -137,8 +141,8 @@ ${EXTRA_IMAGECMD}" The EXTRA_IMAGECMD variable for ext2 is - passed to genext2fs and is not used by - default. + passed to genext2fs and is left empty by + default:EXTRA_IMAGECMD_ext2 = "" The IMAGE_ROOTS_SIZE variable is used to specify the size of the ext2 image and is set to 64k by @@ -146,6 +150,27 @@ + + ext3 + + + Creates an "Extended Filesystem 3" image + file. This is the standard Linux journaling file system.IMAGE_CMD_ext3 = "genext2fs -b ${IMAGE_ROOTFS_SIZE} \ + -d ${IMAGE_ROOTFS} \ + ${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.ext3 \ + ${EXTRA_IMAGECMD}; \ +tune2fs -j ${DEPLOY_DIR_IMAGE}/tmp.gz/${IMAGE_NAME}.rootfs.ext3" + + The EXTRA_IMAGECMD variable for ext3 is + passed to genext2fs and is left empty by + default:EXTRA_IMAGECMD_ext3 = "" + + The IMAGE_ROOTS_SIZE variable is used to + specify the size of the ext3 image and is set to 64k by + default:IMAGE_ROOTFS_SIZE_ext3 = "65536" + + + ext2.gz @@ -153,7 +178,8 @@ Creates a version of the ext2 filesystem image compressed with gzip. - IMAGE_CMD_ext2.gz = "mkdir ${DEPLOY_DIR_IMAGE}/tmp.gz; \ + IMAGE_CMD_ext2.gz = "rm -rf ${DEPLOY_DIR_IMAGE}/tmp.gz && \ +mkdir ${DEPLOY_DIR_IMAGE}/tmp.gz; \ genext2fs -b ${IMAGE_ROOTFS_SIZE} -d ${IMAGE_ROOTFS} \ ${DEPLOY_DIR_IMAGE}/tmp.gz/${IMAGE_NAME}.rootfs.ext2 \ ${EXTRA_IMAGECMD}; \ @@ -163,8 +189,8 @@ mv ${DEPLOY_DIR_IMAGE}/tmp.gz/${IMAGE_NAME}.rootfs.ext2.gz \ rmdir ${DEPLOY_DIR_IMAGE}/tmp.gz" The EXTRA_IMAGECMD variable for ext2.gz is - passed to genext2fs and is not used by - default. + passed to genext2fs and is left empty by + default:EXTRA_IMAGECMD_ext2.gz = "" The IMAGE_ROOTS_SIZE variable is used to specify the size of the ext2 image and is set to 64k by @@ -174,6 +200,36 @@ rmdir ${DEPLOY_DIR_IMAGE}/tmp.gz" + + ext3.gz + + + Creates a version of the ext3 filesystem image compressed with + gzip. + + IMAGE_CMD_ext3.gz = "rm -rf ${DEPLOY_DIR_IMAGE}/tmp.gz && \ +mkdir ${DEPLOY_DIR_IMAGE}/tmp.gz; \ +genext2fs -b ${IMAGE_ROOTFS_SIZE} -d ${IMAGE_ROOTFS} \ + ${DEPLOY_DIR_IMAGE}/tmp.gz/${IMAGE_NAME}.rootfs.ext3 \ + ${EXTRA_IMAGECMD}; \ +tune2fs -j ${DEPLOY_DIR_IMAGE}/tmp.gz/${IMAGE_NAME}.rootfs.ext3; \ +gzip -f -9 ${DEPLOY_DIR_IMAGE}/tmp.gz/${IMAGE_NAME}.rootfs.ext3; \ +mv ${DEPLOY_DIR_IMAGE}/tmp.gz/${IMAGE_NAME}.rootfs.ext3.gz \ + ${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.ext3.gz; \ +rmdir ${DEPLOY_DIR_IMAGE}/tmp.gz" + + The EXTRA_IMAGECMD variable for ext3.gz is + passed to genext2fs and is left empty by + default:EXTRA_IMAGECMD_ext3.gz = "" + + The IMAGE_ROOTS_SIZE variable is used to + specify the size of the ext2 image and is set to 64k by + default: + + IMAGE_ROOTFS_SIZE_ext3.gz = "65536" + + + squashfs @@ -193,10 +249,12 @@ rmdir ${DEPLOY_DIR_IMAGE}/tmp.gz" ${EXTRA_IMAGECMD} -noappend" The EXTRA_IMAGECMD variable for squashfs is - passed to mksquashfs and by default is used - specify the endianess and block size of the filesystem: + passed to mksquashfs and is left empty by + default:EXTRA_IMAGECMD_squashfs = "" - EXTRA_IMAGECMD_squashfs = "-le -b 16384" + This was not always empty, prior to 2007/05/02 the + EXTRA_IMAGECMD variable for squashfs specified + the endianess and block size of the filesystem:EXTRA_IMAGECMD_squashfs = "-le -b 16384" @@ -220,10 +278,12 @@ rmdir ${DEPLOY_DIR_IMAGE}/tmp.gz" ${EXTRA_IMAGECMD} -noappend" The EXTRA_IMAGECMD variable for squashfs is - passed to mksquashfs-lzma and by default is used - specify the endianess and block size of the filesystem: + passed to mksquashfs-lzma and is left empty by + default:EXTRA_IMAGECMD_squashfs-lzma = "" - EXTRA_IMAGECMD_squashfs-lzma = "-le -b 16384" + This was not always empty, prior to 2007/05/02 the + EXTRA_IMAGECMD variable for squashfs specified + the endianess and block size of the filesystem:EXTRA_IMAGECMD_squashfs-lzma = "-le -b 16384" @@ -231,8 +291,7 @@ rmdir ${DEPLOY_DIR_IMAGE}/tmp.gz" tar - Creates a bzip2 compressed .tar - archive. + Creates a .tar archive. IMAGE_CMD_tar = "cd ${IMAGE_ROOTFS} && \ tar -jcvf ${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.tar.bz2 ." @@ -271,6 +330,31 @@ rmdir ${DEPLOY_DIR_IMAGE}/tmp.gz" supported for tar.bz2 images. + + + cpio + + + Creates a .cpio archive:IMAGE_CMD_cpio = "cd ${IMAGE_ROOTFS} && \ + (find . | cpio -o -H newc >${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.cpio)" + + The EXTRA_IMAGECMD variable in not + supported for cpio images. + + + + + cpio.gz + + + Creates a gzip compressed .cpio + archive.IMAGE_CMD_cpio.gz = cd ${IMAGE_ROOTFS} && \ + (find . | cpio -o -H newc | gzip -c -9 >${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.cpio.gz)" + + The EXTRA_IMAGECMD variable in not + supported for cpio.gz images. + + The above built in list of image types is defined in the bitbake -- cgit 1.2.3-korg