From 25b51d32c982a6767f3d4a88dec12f70c8c8f875 Mon Sep 17 00:00:00 2001 From: Michael 'Mickey' Lauer Date: Wed, 25 Feb 2009 01:47:30 +0100 Subject: docs: import usermanual from org.openembedded.documentation. org.openembedded.documentation is deprecated now; please do all updates here! --- docs/usermanual/reference/.mtn2git_empty | 0 docs/usermanual/reference/class_autotools.xml | 153 +++++ docs/usermanual/reference/class_binconfig.xml | 46 ++ docs/usermanual/reference/class_distutils.xml | 48 ++ docs/usermanual/reference/class_image.xml | 358 +++++++++++ docs/usermanual/reference/class_pkgconfig.xml | 39 ++ docs/usermanual/reference/class_rootfs_ipkg.xml | 215 +++++++ docs/usermanual/reference/class_siteinfo.xml | 180 ++++++ .../reference/class_update-alternatives.xml | 241 +++++++ docs/usermanual/reference/class_update-rc.d.xml | 133 ++++ docs/usermanual/reference/dirs_install.xml | 198 ++++++ docs/usermanual/reference/dirs_staging.xml | 169 +++++ docs/usermanual/reference/fakeroot.xml | 186 ++++++ docs/usermanual/reference/image_types.xml | 385 +++++++++++ docs/usermanual/reference/var_section.xml | 704 +++++++++++++++++++++ docs/usermanual/reference/var_src_uri.xml | 692 ++++++++++++++++++++ 16 files changed, 3747 insertions(+) create mode 100644 docs/usermanual/reference/.mtn2git_empty create mode 100644 docs/usermanual/reference/class_autotools.xml create mode 100644 docs/usermanual/reference/class_binconfig.xml create mode 100644 docs/usermanual/reference/class_distutils.xml create mode 100644 docs/usermanual/reference/class_image.xml create mode 100644 docs/usermanual/reference/class_pkgconfig.xml create mode 100644 docs/usermanual/reference/class_rootfs_ipkg.xml create mode 100644 docs/usermanual/reference/class_siteinfo.xml create mode 100644 docs/usermanual/reference/class_update-alternatives.xml create mode 100644 docs/usermanual/reference/class_update-rc.d.xml create mode 100644 docs/usermanual/reference/dirs_install.xml create mode 100644 docs/usermanual/reference/dirs_staging.xml create mode 100644 docs/usermanual/reference/fakeroot.xml create mode 100644 docs/usermanual/reference/image_types.xml create mode 100644 docs/usermanual/reference/var_section.xml create mode 100644 docs/usermanual/reference/var_src_uri.xml (limited to 'docs/usermanual/reference') diff --git a/docs/usermanual/reference/.mtn2git_empty b/docs/usermanual/reference/.mtn2git_empty new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/usermanual/reference/class_autotools.xml b/docs/usermanual/reference/class_autotools.xml new file mode 100644 index 0000000000..a9e1a5721a --- /dev/null +++ b/docs/usermanual/reference/class_autotools.xml @@ -0,0 +1,153 @@ + +
+ autotools class + + Autotools is one of the most commonly seen configuration methods for + applications. Anything that uses the standard ./configure; make; + make install sequence is using autotools. Usually the configure + script will support a large number of options to specify various + installation directories, to disable and/or enable various features and + options to specify search paths for headers and libraries. + + The autotools class takes care of all of the details for you. It + defines appropriate tasks for configure, + compile, stage and + install. At it's simplest adding an inherit for the + autotools class is all that is required. The netcat recipe for example + is:DESCRIPTION = "GNU Netcat" +HOMEPAGE = "http://netcat.sourceforge.net" +LICENSE = "GPLv2" +MAINTAINER = "Your name <yname@example.com>" +SECTION = "console/networking" +PR = "r1" + +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 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 + script:EXTRA_OECONF = "--disable-largefile --disable-rpath --with-included-readline=no"If + you define your own tasks for configure, + compile, stage or + install (via do_<taskname>) + then they will override the methods generated by the autotools class. If you + need to perform additional operations (rather than replacing the generated + operations) you can use the do_<task>_append or + do_<task>_prepend methods. The following example + from the conserver recipe shows some additional items being + installed:# Include the init script and default settings in the package +do_install_append () { + install -m 0755 -d ${D}${sysconfdir}/default ${D}${sysconfdir}/init.d + install -m 0644 ${WORKDIR}/conserver.default ${D}${sysconfdir}/default/conserver + install -m 0755 ${WORKDIR}/conserver.init ${D}${sysconfdir}/init.d/conserver +} + +
+ oe_runconf / autotools_do_configure + + Autotools generates a configuration method called + oe_runconf which runs the actual configure script, and + a method called autotools_do_configure which generates + the configure file (runs automake and autoconf) and then calls + oe_runconf. The generated method for the + configure task, do_configure, just + calls the autotools_do_configure method. + + It is sometimes desirable to implement your own + do_configure method, where additional configuration is + required or where you wish to inhibit the running of automake and + autoconf, and then manually call oe_runconf. + + The following example from the ipacct recipe shows an example of + avoiding the use of automake/autoconf:do_configure() { + oe_runconf +}Sometimes manual manipulations of the autotools files is required + prior to calling autoconf/automake. In this case you can defined your own + do_configure method which performs the required actions + and then calls autotools_do_configure. +
+ +
+ Presetting autoconf variables (the site file) + + 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. + + 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: + + + + Check the other site files to see if there any entries for the + application you are attempting to build. + + Sometimes entries are only updated for the target that the + developer has access to. If they exist for another target then it may + provide a good idea of what needs to be defined. + + + + Sometimes the same cache value is used by multiple + applications. + + This can have the side effect where a value added for one + application breaks the build of another. It is a very good idea to + empty the site file of all other values if you are having build + problems to ensure that none of the existing values are causing + problems. + + + + Not all values can be stored in the cache + + Caching of variables is defined by the author of the configure + script, so sometimes not all variables can be set via the cache. In + this case it often means resorting to patching the original configure + scripts to achieve the desired result. + + + + All site files are shell scripts which are run by autoconf and + therefore the syntax is the same as you would use in sh. There are two + current methods of settings variables that is used in the existing site + files. This include explicitly settings the value of the variable:ac_cv_sys_restartable_syscalls=yesand + conditionally setting the value of the variable:ac_cv_uchar=${ac_cv_uchar=no}The + conditional version is using shell syntax to say "only set this + to the specified value if it is not currently set". The + conditional version allows the variable to be set in the shell prior to + calling configure and it will then not be replaced by the value from the + site file. + + + 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() { + oe_runconf +} +
+
\ No newline at end of file diff --git a/docs/usermanual/reference/class_binconfig.xml b/docs/usermanual/reference/class_binconfig.xml new file mode 100644 index 0000000000..049f85e1f0 --- /dev/null +++ b/docs/usermanual/reference/class_binconfig.xml @@ -0,0 +1,46 @@ + +
+ binconfig class + + The binconfig class is for packages that install + <pkg>-config scripts that provide information about + the build settings for the package. It is usually provided by libraries and + then used by other packages to determine various compiler options. + + Since the script is used at build time it is required to be copied + into the staging area. All the actions performed by the class are appended + to the stage task. + + The actions performed by the binconfig class are: + + + + Copies the <x>-config script from the + package into ${STAGING_BINDIR} directory; + + + + If the package is not native then it modifies the contents of the + <x>-config script in the staging area to ensure + that all the paths in the script refer to the staging area; + + + + If the package is native then + the<x>-config script is renamed to + <x>-config-native to ensure that the native and + non-native versions do not interfere with each other. + + + + A package is considered to be native if it also inherits the native + class. + + The class will search in source directory, ${S}, + and all it's subdirectories, for files that end in + -config and process them as described above. All that is + required to use the class is the addition of binconfig in an inherit + statement: + + inherit autotools binconfig +
\ No newline at end of file diff --git a/docs/usermanual/reference/class_distutils.xml b/docs/usermanual/reference/class_distutils.xml new file mode 100644 index 0000000000..ddc9c721ab --- /dev/null +++ b/docs/usermanual/reference/class_distutils.xml @@ -0,0 +1,48 @@ + +
+ distutils class + + Distutils is a standard python system for building and installing + modules. The distutils class is used to automate the + building of python modules that use the distutils system. + + Any python package that requires the standard python commands to build + and install is using the distutils system and should be able to use this + class:python setup.py build +python setup.py install + + The distutils class will perform the build and + install actions on the setup.py provided by the package, + as required for building distutils packages, including setting all the + required parameters for cross compiling. It willl also perform the following + actions: + + + + Adds python-native to DEPENDS to ensure that + python is built and installed on the build host. This also ensure that + the version of python that is used during package creation matches the + version of python that will be installed on the target. + + + + Adds python-core to RDEPENDS to ensure that the + python-core is installed when this module is installed. Note that you + need to manually add any other python module dependencies to + RDEPENDS. + + + + The following example from the moin recipe shows + how simple this can make a python package:DESCRIPTION = "A full fledged WikiWiki system written in Python" +LICENSE = "GPL" +SECTION = "base" +PRIORITY = "optional" +MAINTAINER = "Your name <yname@example.com>" +PR = "r1" + +SRC_URI = "${SOURCEFORGE_MIRROR}/moin/moin-${PV}.tar.gz" + +inherit distutilsThe header, source location and the inherit are all + that is required. +
\ No newline at end of file diff --git a/docs/usermanual/reference/class_image.xml b/docs/usermanual/reference/class_image.xml new file mode 100644 index 0000000000..b591e9aae2 --- /dev/null +++ b/docs/usermanual/reference/class_image.xml @@ -0,0 +1,358 @@ + +
+ 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 + (using FEED_URIS and FEED_DEPLOYDIR_BASE_URI); + + + + 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: "" + + + + + FEED_DEPLOYDIR_BASE_URI + + + If set, configures local testing feeds using OE package deploy dir + contents. The value is URL, corresponding to the ipk deploy dir. + + Example: FEED_DEPLOYDIR_BASE_URI = + "http://192.168.2.200/bogofeed/" + + 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 + + "Package feed", or feed for short, is a term used by ipkg + package manager, commonly used in embedded systems, to name a package repository + holding packages. Structurally, a feed is a directory - local, or on HTTP of FTP server, - + holding packages and package descriptor file, named Packages or + Packages.gz if compressed. Multiple feeds are supported. + + OpenEmbedded has support to pre-configure feeds within generated images, + so once image is installed on a device, user can immediately install new software, + without the need to manually edit config files. There are several ways to pre-configure + feed support, described below. + +
+ Method 1: Using existing feed + If you already have the feed(s) set up and available via specific URL, they + can be added to the image using FEED_URIS variable: +FEED_URIS = " \ + base##http://oe.example.com/releases/${DISTRO_VERSION}/feed/base \ + updates##http://oe.example.com/releases/${DISTRO_VERSION}/feed/updates" + + FEED_URIS contains list of feed descriptors, separated by spaces, per + OE conventions. Each descriptor consists of feed name and feed URL, + joined with "##". Feed name is an identifier used by ipkg to distinguish + among the feeds. It can be arbitrary, just useful to the users to understood + which feed is used for one or another action. +
+ +
+ Method 2: Using OE deploy directory as a feed (development only) + OE internally maintains a feed-like collection of directories to create + images from packages. This package deployment directory however has structure internal to OE + and subject to change without notice. Thus, using it as feed directly is not recommended + (distributions which ignored this recommendation are known to have their feeds broken when + OE upgraded its internal mechanisms). + However, using deploy directory as feed directly may be beneficial during + development and testing, as it allows developers to easily install newly built packages + without many manual actions. To facilitate this, OE offers a way to prepare feed configs + for using deploy dir as such. To start with this, you first need to configure local + HTTP server to export a package deployment directory via HTTP. + Suppose you will export it via URL "http://192.168.2.200/bogofeed" (where 192.168.2.200 is the address + which will be reachable from the device). Add the following to your local.conf: + +FEED_DEPLOYDIR_BASE_URI = "http://192.168.2.200/bogofeed" + + Now you need to setup local HTTP server to actually export that directory. For Apache it can be: + + + Options Indexes FollowSymLinks + Order deny,allow + Allow from 192.168.2.0/24 + +]]> + + Replace ${DEPLOY_DIR} with the full path of deploy directory (last components of its path will be + deploy/ipk). + Now, every image built will automatically contain feed configs + for the deploy directory (as of time of writing, deploy directory is internally structured with + per-arch subdirectories; so, there several feed configs are being generated, one for each subdirectory). + + +
+ +
+
\ No newline at end of file diff --git a/docs/usermanual/reference/class_pkgconfig.xml b/docs/usermanual/reference/class_pkgconfig.xml new file mode 100644 index 0000000000..3cb5002df5 --- /dev/null +++ b/docs/usermanual/reference/class_pkgconfig.xml @@ -0,0 +1,39 @@ + +
+ pkgconfig class + + The pkgconfig class is for packages that install + <pkg>.pc files. These files provide information + about the build settings for the package vwhich are then made available by + the pkg-config command. + + Since the contents of the .pc files are used at + build time they need to be installed into the staging area. All the actions + performed by this class are appended to the stage + task. + + The actions performed by the pkgconfig class are: + + + + Copies the <x>.pc files into the + ${PKG_CONFIG_PATH} directory; + + + + If the package is not native then it modifies the contents of the + <x>.pc file in the + ${PKG_CONFIG_PATH} area to ensure that all the paths + in the script refer to the staging area; + + + + A package is considered to be native if it also inherits the native + class. + + The class will search the source directory, ${S}, + and all it's subdirectories, for files that end in .pc + (it will ignore those that end in -uninstalled.pc) and + process them as described above. All that is required to use the class is + the addition of pkgconfig in an inherit statement:inherit autotools pkgconfig +
\ No newline at end of file diff --git a/docs/usermanual/reference/class_rootfs_ipkg.xml b/docs/usermanual/reference/class_rootfs_ipkg.xml new file mode 100644 index 0000000000..b60adf8e70 --- /dev/null +++ b/docs/usermanual/reference/class_rootfs_ipkg.xml @@ -0,0 +1,215 @@ + +
+ rootfs_ipkg class + + The rootf_ipk class us used to create a root + filesystem for the target device from a set of .ipkg packages. The end + result is a directory containing all the files that need to be included in + 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 package + (typically .ipkg) files. + + Summary of actions performed by the rootfs_ipkg + class: + + + + Erase any existing root filesystem image by deleting the entire + contents of ${IMAGE_ROOTFS}; + + + + Creates the device node directory, + ${IMAGE_ROOTFS}/dev; + + + + Determines which packages to install in order to provide the + locales that have been requested; + + + + Configures ipkg to allow it to be used locally to install into the + root filesystem ${IMAGE_ROOTFS}; + + + + Installs locale related .ipkg packages; + + + + Installs the list of requested .ipkg packages, + ${IPKG_INSTALL}; + + + + Creates ipkg's arch.conf as + ${IMAGE_ROOTFS}/etc/ipkg/arch.conf; + + + + Runs any preinst and postinst scripts that were specified by the + installed .ipkg packages; + + + + Creates the system configuration directory + ${IMAGE_ROOTFS}/${sysconfdir} (that is the + /etc directory on the target); + + + + Runs and custom post-processing commands, as described by + ${ROOTFS_POSTPROCESS_COMMAND}; + + + + Verifies that all the ipkg's were installed correctly and reports + an error if they were not; + + + + Makes available a set of functions which may be used by callers of + the class: zap_root_password, + create_etc_timestamp and + remove_init_link; + + + + Adds the rootfs task to run after the install + task "addtask rootfs before do_build and + do_install". + + + + The following variables may be used to control some of the behaviour + of this class: + + + + IPKG_INSTALL + + + The list of packages which will be installed into the root + filesystem. This needs to be set in order for this class to perform + any useful work. + + Default: empty + + + + + ROOTFS_POSTPROCESS_COMMAND + + + Defines additional commands to run after processing of the root + filesystem. Could be used to change roots password, remove parts of + the install kernel such as the zImage kernel image + or to edit the ipkg configuration for example. + + Default: empty + + + + + PACKAGE_ARCH + + + Defines the list of architectures that are support by the target + platform. This is used to configure the arch settings for ipkg on the + target system. + + Default: "all any noarch ${TARGET_ARCH} + ${PACKAGE_EXTRA_ARCHS} ${MACHINE}" + + + + + IMAGE_LINGUAS + + + Specifies which locales should be installed. This is often set + to "" to indicate that no locales will be + installed. + + Default: "de-de fr-fr en-gb" + + + + + EXTRA_IMAGEDEPENDS + + + A list of dependencies, this is appended to + DEPENDS. This is typically used to ensure that any + commands that are called by + ROOTFS_POSTPROCESS_COMMAND are actually built by + the system prior to being called. + + Default: empty + + + + + BUILDNAME + + + The name of the build. This is either set by the distro + configuration (for released versions) or set to a date stamp which is + autogenerated by bitbake. + + Default: 'date +%Y%m%d%H%M' + + + + + IMAGE_ROOTFS + + + The path to the root of the filesystem image. You can use this + when you need to explicitly refer to the root filesystem + directory. + + Default: IMAGE_ROOTFS = + "${TMPDIR}/rootfs" + + + + + DEPLOY_DIR + + + The base deploy dir. Used to find the directory containing the + ipkg files. + + Default: DEPLOY_DIR = + "${TMPDIR}/deploy" + + + + + DEPLOY_DIR_IPK + + + The directory in which to search for the ipkg files that are to + be installed in the root filesystem. + + Default: DEPLOY_DIR_IPK = + "${DEPLOY_DIR}/ipk" + + + + + Note that the entire process is run under the control of in order to handle device files, uids and gids. The + ROOTFS_POSTPROCESS_COMMAND is useful due to the fact that + it runs within the same instance as the rest of + this class. + + The class also provides a function real_do_rootfs + which is executed without and therefore can be + used from other classes, such as , that + are already running under the control of . +
\ No newline at end of file diff --git a/docs/usermanual/reference/class_siteinfo.xml b/docs/usermanual/reference/class_siteinfo.xml new file mode 100644 index 0000000000..4d66e85e7c --- /dev/null +++ b/docs/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/docs/usermanual/reference/class_update-alternatives.xml b/docs/usermanual/reference/class_update-alternatives.xml new file mode 100644 index 0000000000..cd86e3e6ab --- /dev/null +++ b/docs/usermanual/reference/class_update-alternatives.xml @@ -0,0 +1,241 @@ + +
+ update-alternatives class + + Some commands are available from multiple sources. As an example we + have /bin/sh available from busybox + and from bash. The busybox version is better from a + size perspective, but limited in functionality, while the bash version is + much larger but also provides far more features. The alternatives system is + designed to handle the situation where two commands are provided by two, or + more, packages. It ensures that one of the alternatives is always the + currently selected one and ensures that there are no problems with + installing and/or removing the various alternatives. + + The update-alternatives class is used to register a command provided + by a package that may have an alternative implementation in a some other + package. + + In the following sections we'll use the /bin/ping + command as an example. This command is available as a basic version from + busybox and as a more advanced version from iputils. + +
+ Naming of the alternative commands + + When supplying alternative commands the target command itself is not + installed directly by any of the available alternatives. This is to ensure + that no package will replace files that were installed by one of the other + available alternative packages. The alternatives system will create a + symlink for the target command that points to the required + alternative. + + For the /bin/ping case this means that neither + busybox nor iputils should actually install a command called + /bin/ping. Instead we see that the iputils recipe + installs it's version of ping as + /bin/ping.iputils:do_install () { + install -m 0755 -d ${D}${base_bindir} ${D}${bindir} ${D}${mandir}/man8 + # SUID root programs + install -m 4755 ping ${D}${base_bindir}/ping.${PN} + ... +} + + If you were to look at the busybox recipe you would see that it also + doesn't install a command called /bin/ping, instead it + installs it's command as /bin/busybox. + + The important point to note is that neither package is installing an + actual /bin/ping target command. +
+ +
+ How alternatives work + + Before proceeding lets take a look at how alternatives are handled. + If we have a base image that includes only busybox then look at + /bin/ping we see that it is a symlink to + busybox: + + root@titan:/etc# ls -l /bin/ping +lrwxrwxrwx 1 root root 7 May 3 2006 /bin/ping -> busybox + + This is what is expected since the busybox version of ping is the + only one installed on the system. Note again that it is only a symlink and + not an actual command. + + If the iputils version of ping is now installed and we look at the + /bin/ping command again we see that it has been changed + to a symlink pointing at the iputils version of ping - + /bin/ping.iptils: + + root@titan:/etc# ipkg install iputils-ping +Installing iputils-ping (20020927-r2) to root... +Downloading http://nynaeve/ipkg-titan-glibc//iputils-ping_20020927-r2_sh4.ipk +Configuring iputils-ping +update-alternatives: Linking //bin/ping to ping.iputils +root@titan:/etc# ls -l /bin/ping +lrwxrwxrwx 1 root root 12 May 13 2006 /bin/ping -> ping.iputils + + The iputils version is considered to be the more fully featured + version of ping and is therefore the default when both versions are + installed. + + What happens if the iputils-ping package is removed now? The symlink + should be changed to point back at the busybox version: + + root@titan:/etc# ipkg remove iputils-ping +Removing package iputils-ping from root... +update-alternatives: Linking //bin/ping to busybox +root@titan:/etc# ls -l /bin/ping +lrwxrwxrwx 1 root root 7 May 13 2006 /bin/ping -> busybox + + This simple example shows that the alternatives system is taking + care of ensuring the symlink is pointing to the correct version of the + command without any special interaction from the end users. +
+ +
+ The update-alternatives command + + Available alternatives need to be registered with the alternatives + system. This is handled by the update-alternatives + command. The help from the command shows it's usage options:root@titan:/etc# update-alternatives --help +update-alternatives: help: + +Usage: update-alternatives --install <link> <name> <path> <priority> + update-alternatives --remove <name> <path> + update-alternatives --help +<link> is the link pointing to the provided path (ie. /usr/bin/foo). +<name> is the name in /usr/lib/ipkg/alternatives/alternatives (ie. foo) +<path> is the name referred to (ie. /usr/bin/foo-extra-spiffy) +<priority> is an integer; options with higher numbers are chosen. + + + During postinst the update-alternatives command needs to be called + with the install option and during postrm it needs to be called with the + remove option. + + The iputils recipe actual codes this directly (rather than using the + class) so we can see an example of the command being called:pkg_postinst_${PN}-ping () { + update-alternatives --install ${base_bindir}/ping ping ping.${PN} 100 +} +pkg_prerm_${PN}-ping () { + update-alternatives --remove ping ping.${PN} +} + + In both cases the name that the alternatives are registered against, + "ping", is passed in and the path to the iputils + version of the command, "ping.${PN}". For the install + case the actual command name (where the symlink will be made from) and a + priority value are also supplied. +
+ +
+ Priority of the alternatives + + So why did the alternatives system prefer the iputils version of + ping over the busybox version? It's because of the relative priorities of + the available alternatives. When iputils calls update-alternatives the + last parameter passed is a priority: update-alternatives --install ${base_bindir}/ping ping ping.${PN} 100 + + So iputils is specifying a priority of 100 and if you look at + busybox you'll see it specifies a priority of 50 for ping. The alternative + with the highest priority value is the one that update-alternatives will + select as the version to actual use. In this particular situation the + authors have selected a higher priority for iputils since it is the more + capable version of ping and would not normally be installed unless + explicitly requested. +
+ +
+ Tracking of the installed alternatives + + You can actually see which alternatives are available and what their + priority is on a target system. Here we have an example in which both + busybox and iptuils-ping packages are installed: root@titan:/etc# cat /usr/lib/ipkg/alternatives/ping +/bin/ping +busybox 50 +ping.iputils 100If we remove iputils-ping, then we see that + alternatives file is updated to reflect this: root@titan:/etc# cat /usr/lib/ipkg/alternatives/ping +/bin/ping +busybox 50 +root@titan:/etc# + + The file lists the command first, and then each of the available + alternatives and their relative priorities. +
+ +
+ Using the update-alternatives class + + Neither busybox nor iputils actually use the update-alternatives + class - they call the update-alternatives functions directly. They need to + call the command directly since they need to register multiple + alternatives and the class does not support this. The class can only be + used when you have only a single alternative to register. + + To use the class you need to inherent update-alternatives and then + define the name, path, link and priority as show in the following example + from the jamvm recipe: + + inherit autotools update-alternatives + +ALTERNATIVE_NAME = "java" +ALTERNATIVE_PATH = "${bindir}/jamvm" +ALTERNATIVE_LINK = "${bindir}/java" +ALTERNATIVE_PRIORITY = "10" + + + where the variables to be specified are: + + + + ALTERNATIVE_NAME [Required] + + + The name that the alternative is registered against and needs + to be the same for all alternatives registering this command. + + + + + ALTERNATIVE_PATH [Required] + + + The path of the installed alternative. (This was iputils.ping + in the example used previously). + + + + + ALTERNATIVE_LINK [Optional] + + + The name of the actual command. This is what the symlink will + be called and is the actual command that the use runs. The default + value is: "${bindir}/${ALTERNATIVE_NAME}" + + + + + ALTERNATIVE_PRIORITY [Optional] + + + The priority of this alternative. The alternative with the + highest valued priority will be selected as the default. The default + value is: "10". + + + + + The actual postinst and postrm commands that are registered by the + class are:update_alternatives_postinst() { + update-alternatives --install ${ALTERNATIVE_LINK} ${ALTERNATIVE_NAME} ${ALTERNATIVE_PATH} ${ALTERNATIVE_PRIORITY} +} + +update_alternatives_postrm() { + update-alternatives --remove ${ALTERNATIVE_NAME} ${ALTERNATIVE_PATH} +} +
+
\ No newline at end of file diff --git a/docs/usermanual/reference/class_update-rc.d.xml b/docs/usermanual/reference/class_update-rc.d.xml new file mode 100644 index 0000000000..2da9b0bf86 --- /dev/null +++ b/docs/usermanual/reference/class_update-rc.d.xml @@ -0,0 +1,133 @@ + +
+ update-rc.d class + + Services which need to be started during boot need to be registered + using the update-rc.d command. These services are required to have an init + script which is installed into /etc/init.d that can be + used to start and stop the service. + + The following examples show a service being manually stopped and + started using it's init script:root@titan:/etc# /etc/init.d/syslog stop +Stopping syslogd/klogd: stopped syslogd (pid 1551). +stopped klogd (pid 1553). +done +root@titan:/etc# /etc/init.d/syslog start +Starting syslogd/klogd: done +root@titan:/etc#The update-rc.d class takes care of the following + automatically: + + + + Registers the service with the system during postinst so it will + be automatically started on boot; + + + + Stops the service during prerm so it will no longer be running + after being removed; + + + + Unregisters the service during prerm so there will be no attempts + to start the removed service during boot; + + + + Adds a build and run time dependency on the update-rc.d package + which it uses to register and unregister the services. + + + + Usage is very simple, as shown by this example from dropbear:INITSCRIPT_NAME = "dropbear" +INITSCRIPT_PARAMS = "defaults 10" + +inherit autotools update-rc.d + + where the variables are: + + + + INITSCRIPT_NAME + + + The name of the init script, which the package will have + installed into /etc/init.d + + + + + INITSCRIPT_PARAMS + + + The parameters to pass to the update-rc.d call during + installation. Typically this will be the work default followed by + either single number or a pair of numbers representing the start/stop + sequence number (both are set to the same if only one number is + supplied.) + + + + + The help from update-rc.d shows show the required parameters:root@titan:/etc# update-rc.d -h +usage: update-rc.d [-n] [-f] [-r <root>] <basename> remove + update-rc.d [-n] [-r <root>] [-s] <basename> defaults [NN | sNN kNN] + update-rc.d [-n] [-r <root>] [-s] <basename> start|stop NN runlvl [runlvl] [...] . + -n: not really + -f: force + -r: alternate root path (default is /) + -s: invoke start methods if appropriate to current runlevel +root@titan:/etc#The start and stop sequence numbers need to ensure + that the the service is started at the appropriate time relative to other + services, such as waiting for any service that it depends on before starting + (networking for example). Unless the service is a system or security related + service it's better to be started as late as possible. + +
+ Multiple update-rc.d packages + + Defining multiple init scripts within the one recipe is also + supported. Note that each init script must be in it's own package. The + following example is from the quagga recipe:# Main init script starts all deamons +# Seperate init script for watchquagga +INITSCRIPT_PACKAGES = "${PN} ${PN}-watchquagga" +INITSCRIPT_NAME_${PN} = "quagga" +INITSCRIPT_PARAMS_${PN} = "defaults 15 85" +INITSCRIPT_NAME_${PN}-watchquagga = "watchquagga" +INITSCRIPT_PARAMS_${PN}-watchquagga = "defaults 90 10" + +inherit autotools update-rc.d The variables that need to be declared + are: + + + + INITSCRIPT_PACKAGES + + + The names of each package which includes an init + script. + + + + + INITSCRIPT_NAME_x + + + The same meaning as INITSCRIPT_NAME, but for the package x. + This would be repeated for each package that includes an init + script. + + + + + INITSCRIPT_PARAMS_x + + + The same meaning as INITSCRIPT_PARAMS, but for the package x. + This would be repeated for each package that includes an init + script. + + + +
+
\ No newline at end of file diff --git a/docs/usermanual/reference/dirs_install.xml b/docs/usermanual/reference/dirs_install.xml new file mode 100644 index 0000000000..75f85ac930 --- /dev/null +++ b/docs/usermanual/reference/dirs_install.xml @@ -0,0 +1,198 @@ + +
+ Directories: Installation variables + + The following table provides a list of the variables that are used to + control the directories into which files are installed. + + These variables can be used directly by the recipe to refer to paths + that will be used after the package is installed. For example, when specify + the location of configuration files you need to specify the location on the + target as show in the following example from quagga:# Indicate that the default files are configuration files +CONFFILES_${PN} = "${sysconfdir}/default/quagga" +CONFFILES_${PN}-watchquagga = "${sysconfdir}/default/watchquagga" + + When using these variables to actually install the components of a + package from within a bitbake recipe they should used relative to the + destination directory, D. The following + example from the quagga recipe shows some addition files being manually + installed from within the recipe itself:do_install () { + # Install init script and default settings + install -m 0755 -d ${D}${sysconfdir}/default ${D}${sysconfdir}/init.d ${D}${sysconfdir}/quagga + install -m 0644 ${WORKDIR}/quagga.default ${D}${sysconfdir}/default/quagga + + + + + + Variable name + + Definition + + Typical value + + + + + + prefix + + /usr + + /usr + + + + base_prefix + + (empty) + + (empty) + + + + exec_prefix + + ${base_prefix} + + (empty) + + + + base_bindir + + ${base_prefix}/bin + + /bin + + + + base_sbindir + + ${base_prefix}/sbin + + /sbin + + + + base_libdir + + ${base_prefix}/lib + + /lib + + + + datadir + + ${prefix}/share + + /usr/share + + + + sysconfdir + + /etc + + /etc + + + + localstatedir + + /var + + /var + + + + infodir + + ${datadir}/info + + /usr/share/info + + + + mandir + + ${datadir}/man + + /usr/share/man + + + + docdir + + ${datadir}/doc + + /usr/share/doc + + + + servicedir + + /srv + + /srv + + + + bindir + + ${exec_prefix}/bin + + /usr/bin + + + + sbindir + + ${exec_prefix}/sbin + + /usr/sbin + + + + libexecdir + + ${exec_prefix}/libexec + + /usr/libexec + + + + libdir + + ${exec_prefix}/lib + + /usr/lib + + + + includedir + + ${exec_prefix}/include + + /usr/include + + + + palmtopdir + ${libdir}/opie + /usr/lib/opie + + + + palmqtdir + ${palmtopdir} + /usr/lib/opie + + + + + + + +
diff --git a/docs/usermanual/reference/dirs_staging.xml b/docs/usermanual/reference/dirs_staging.xml new file mode 100644 index 0000000000..25f3685aad --- /dev/null +++ b/docs/usermanual/reference/dirs_staging.xml @@ -0,0 +1,169 @@ + +
+ Directories: Staging variables + + The following table provides a list of the variables that are used to + control the directories into which files are staged. + + Staging is used for headers, libraries and binaries that are generated + by packages and are to be used in the generation of other packages. For + example the libpcre recipe needs to make the include files and libraries for + the target available on the host for other applications that depend on + libpcre. So in addition to packaging these files up for use in the binary + package they are need to be installed in the staging are for use by other + packages. + + There are two common situations in which you will need to directly + refer to the staging directories: + + + + To specify where headers and libraries are to be found for + libraries that your package depends on. In some cases these will be + found automatically due to the default compiler settings used by OE, but + in other cases you will need to explicitly tell your package to look in + the staging area. This is more commonly needed with autoconf based + packages that check for the presence of a specific package during the + configure task. + + + + In the stage task for libraries to specify + where to install the headers and libraries. + + + + The following example from libpcre shows the installation of the + libraries and headers from the package into the staging area. Note the use + of the oe_libinstall helper function for installation + of the libraries:do_stage () { + oe_libinstall -a -so libpcre ${STAGING_LIBDIR} + oe_libinstall -a -so libpcreposix ${STAGING_LIBDIR} + install -m 0644 pcre.h ${STAGING_INCDIR}/ + install -m 0644 pcreposix.h ${STAGING_INCDIR}/ +} + + The following example from the flac recipe shows the location of the + ogg libraries and included before explicitly passed to the configured script + via EXTRA_OECONF so that it will correctly find ogg and enable support for + it:EXTRA_OECONF = "--disable-oggtest --disable-id3libtest \ + --with-ogg-libraries=${STAGING_LIBDIR} \ + --with-ogg-includes=${STAGING_INCDIR} \ + --without-xmms-prefix \ + --without-xmms-exec-prefix \ + --without-libiconv-prefix \ + --without-id3lib"The following table lists the available + variables for referring to the staging area: + + + + + + + + + + Directory + + Definition + + + + + + STAGING_DIR + + ${TMPDIR}/staging + + + + STAGING_BINDIR + + ${STAGING_DIR}/${HOST_SYS}/bin + + + + STAGING_BINDIR_CROSS + + ${STAGING_DIR}/${BUILD_SYS}/bin/${HOST_SYS} + + + + STAGING_BINDIR_NATIVE + + ${STAGING_DIR}/${BUILD_SYS}/bin + + + + STAGING_LIBDIR + + ${STAGING_DIR}/${HOST_SYS}/lib + + + + STAGING_INCDIR + + ${STAGING_DIR}/${HOST_SYS}/include + + + + STAGING_DATADIR + + ${STAGING_DIR}/${HOST_SYS}/share + + + + STAGING_LOADER_DIR + + ${STAGING_DIR}/${HOST_SYS}/loader + + + + STAGING_FIRMWARE_DIR + + ${STAGING_DIR}/${HOST_SYS}/firmware + + + + STAGING_PYDIR + + ${STAGING_DIR}/lib/python2.4 + + + + STAGING_KERNEL_DIR + + ${STAGING_DIR}/${HOST_SYS}/kernel + + + + PKG_CONFIG_PATH + + ${STAGING_LIBDIR}/pkgconfig + + + + QTDIR + + ${STAGING_DIR}/${HOST_SYS}/qt2 + + + + QPEDIR + + ${STAGING_DIR}/${HOST_SYS} + + + + OPIEDIR + + ${STAGING_DIR}/${HOST_SYS} + + + + + + + + +
\ No newline at end of file diff --git a/docs/usermanual/reference/fakeroot.xml b/docs/usermanual/reference/fakeroot.xml new file mode 100644 index 0000000000..5eb6a48eb0 --- /dev/null +++ b/docs/usermanual/reference/fakeroot.xml @@ -0,0 +1,186 @@ + +
+ fakeroot (device node handling) + + 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 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. + + In particular fakeroot deals with: + + + + Device nodes; and + + + + Ownership and group (uid & gid) management. + + + +
+ How fakeroot works + + First of all we'll look at an example of how the fakeroot process + works when used manually. + + If we attempt to create a device node as a normal non-root user then + 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 + them in the final images, all without the need to have root + privileges. + + Let's try and create that node again, this time we'll run the + commands from within a fakeroot process:~%> ./tmp/staging/x86_64-linux/bin/fakeroot +~#> mknod hdc b 22 0 +~#> ls -l hdc +brw------- 1 root root 22, 0 Aug 18 13:20 hdc +~#>So it looks like we have successfully managed to create a + device node, even though we did not have to give a password for the root + user. In reality this device node still doesn't exist, it just looks like + it exits. Fakeroot is lying to the shell process and telling it that + "yes, this file exists and these are it's + properties". We'll talk more about how fakeroot actually works + in a minute. + + In this case hdc is the cd-rom drive, so let's + try and actually mount the cd-rom:~#> mkdir disk +~#> mount hdc disk +ERROR: ld.so: object 'libfakeroot.so.0' from LD_PRELOAD cannot be preloaded: ignored. +mount: only root can do that +~#>So even though it appears we have root permissions, and that we + created a device node, you see that the system gives an error about + libfakeroot and about not being able to run mount because we are not + root. + + If we exit the fakeroot process and then look at the device node + this is what we see:~#> exit +~%> ls -l hdc +brw------- 1 user user 22, 0 Aug 18 13:20 hdc +~#> + + Note that it isn't a device node at all, just an empty file owned by + the current user! + + So what exactly is fakeroot doing? It's using + LD_PRELOAD to load a shared library into program which + replaces calls into libc, such as open and stat, and then returns + information to make it look like certain commands succeeded without + actually performing those commands. So when creating a device node + fakeroot will: + + + + Intercept the mknod system call and instead of creating a device + node it'll just create an empty file, owned by the user who run + fakeroot; + + + + It remembers the fact that mknod was called by root and it + remembers the properties of the device node; + + + + When a program, such as ls, calls stat on the file fakeroot + remembers that it was device node, owned by root, and modifies that + stat information to return this to ls. So ls sees a device node even + though one doesn't exist. + + + + When we tried to run mount we received the error "ERROR: + ld.so: object 'libfakeroot.so.0' from LD_PRELOAD cannot be preloaded: + ignored.". This is due to the fact that mount is an suid root + binary, and for security reasons LD_PRELOAD is disabled + on suid binaries. + + There are some very important points to remember when dealing with + fakeroot: + + + + All information regarding devices nodes, uid and gids will be + lost when fakeroot exists; + + + + None of the device nodes, uids or gids will appear on disk. + However if you tar up a directory from within fakeroot (for example), + all of these device, uids and gids will appear correctly in the tar + archive; + + + + Any suid binaries will not interact with fakeroot; + + + + Any static binaries will not interact with fakeroot; + + +
+ +
+ Root filesystem, images and fakeroot + + Many people have been confused by the generated root filesystem not + containing any valid device nodes. This is in fact the expected + behaviour. + + When you look at a generated root filesystem you'll notice that the + device nodes all appear to be incorrectly created:~%> ls -l tmp/rootfs/dev | grep ttySC +-rw-r--r-- 1 root root 0 Aug 16 13:07 ttySC0 +-rw-r--r-- 1 root root 0 Aug 16 13:07 ttySC1 +-rw-r--r-- 1 root root 0 Aug 16 13:07 ttySC2 +~%>These are empty files and not device nodes at all. + + If we look in the image files generated from that root filesystem + then everything is actually ok:~%> tar -ztvf tmp/deploy/images/titan-titan-20060816030639.rootfs.tar.gz | grep " ./dev/ttySC" +crw-r----- root/root 204,8 2006-08-16 13:07:12 ./dev/ttySC0 +crw-r----- root/root 204,9 2006-08-16 13:07:12 ./dev/ttySC1 +crw-r----- root/root 204,10 2006-08-16 13:07:12 ./dev/ttySC2 +~%>The images are created from within the same fakeroot process as + the creation of the root filesystem and therefore it correctly picks up + all of the special files and permissions from fakeroot. + + NOTE: This means that you cannot use the root + filesystem in tmp/rootfs directly on your target device. You need to use + the .tar.gz image and uncompress it, as root, in order to generate a root + filesystem which is suitable for use directly on the target (or as an NFS + root). +
+ +
+ Recipes and fakeroot + + Some applications require that you have root permissions to run + their installation routine, and this is another area where fakeroot can + help. In a recipe the method for a standard task, such as the + do_install method for the install + task:do_install() { + install -d ${D}${bindir} ${D}${sbindir} ${D}${mandir}/man8 \ + ${D}${sysconfdir}/default \ + ${D}${sysconfdir}/init.d \ + ${D}${datadir}/arpwatch + + oe_runmake install DESTDIR=${D} + oe_runmake install-man DESTDIR=${D} + ...can be modified to run within a fakeroot environment by + prefixing the method name with fakeroot:fakeroot do_install() { + install -d ${D}${bindir} ${D}${sbindir} ${D}${mandir}/man8 \ + ${D}${sysconfdir}/default \ + ${D}${sysconfdir}/init.d \ + ${D}${datadir}/arpwatch + + oe_runmake install DESTDIR=${D} + oe_runmake install-man DESTDIR=${D} + ... +
+
\ No newline at end of file diff --git a/docs/usermanual/reference/image_types.xml b/docs/usermanual/reference/image_types.xml new file mode 100644 index 0000000000..4ea174fd46 --- /dev/null +++ b/docs/usermanual/reference/image_types.xml @@ -0,0 +1,385 @@ + +
+ Image types + + One of the most commonly used outputs from a build is a filesystem + image containing the root filesystem for the target device. There are + 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 + generation is configured. + + The final root file system will consist of all of the files located in + image root filesystem directory, ${IMAGE_ROOTFS}, which + is usually tmp/rootfs in the build area. One important + difference between the images and the root file system directory is that any + files which can only be created by privileged users, such as device nodes, + will not appear in the ${IMAGE_ROOTFS} directory but they + will be present in any images that are generated. This is due to + system keeping track of + these special files and making them available when generating the image - + even though they do not appear in the root filesystem directory. For this + reason it is important to always create an actual image to use for testing, + even if it's just a .tar archive, to ensure you have the + correct device nodes and any other special files. + +
+ Defining images + + Each supported image type is defined via a set of variables. Each + variables has the name of the image type appended to indicate the settings + for that particular image type. The behaviour of the built in image types + can be changed by modifying these variables, and new types can be created + by defining these variables for the new type. + + The variables that define an image type are: + + + + IMAGE_CMD_<type> + + + Specifies the actual command that is run to generate an image + of the specified type. + + + + + EXTRA_IMAGECMD_<type> + + + Used to pass additional command line arguments to the + IMAGE_CMD without the need to redefine the entire + image command. This is often used to pass options such as endianess + and compression rations. You need to look at the + IMAGE_CMD definition to determine how these + options are being used. + + + + + IMAGE_ROOTFS_SIZE_<type> + + + For those image types that generate a fixed size image this + variable is used to specify the required image size. + + + + + IMAGE_DEPENDS_<type> + + + Lists the packages that the IMAGE_CMD + depends on. As an example the jffs2 filesystem creation depends on + mkfs.jffs2 command which is part of the mtd + utilities and therefore depends on mtd-utils-native. + + + +
+ +
+ Available image types + + The following image types are built in to OpenEmbedded: + + + + jffs2 + + + 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 \ + -x lzo \ + --root=${IMAGE_ROOTFS} \ + --faketime \ + --output=${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.jffs2 \ + ${EXTRA_IMAGECMD}" + + The EXTRA_IMAGECMD variable for jffs2 + passed to mkfs.jffs2 and is left empty by + default:EXTRA_IMAGECMD_jffs2 = "" + + 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" + + + + + cramfs + + + Creates cramfs "Compression ROM file + system" images. This is a read only compressed filesystem + which is used directly by decompressing files into RAM as they are + accessed. Files sizes are limited to 16MB, file system size is + limited to 256MB, only 8-bit uids and gids are supported, no hard + links are supported and no time stamps are supported.IMAGE_CMD_cramfs = "mkcramfs ${IMAGE_ROOTFS} \ + ${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.cramfs \ + ${EXTRA_IMAGECMD}" + + The EXTRA_IMAGECMD variable for cramfs is + passed to mkcramfs and is left empty by + default:EXTRA_IMAGECMD_cramfs = "" + + + + + ext2 + + + Creates an "Extended Filesystem 2" image + file. This is the standard Linux non-journaling file system.IMAGE_CMD_ext2 = "genext2fs -b ${IMAGE_ROOTFS_SIZE} \ + -d ${IMAGE_ROOTFS} \ + ${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.ext2 \ + ${EXTRA_IMAGECMD}" + + The EXTRA_IMAGECMD variable for ext2 is + 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 + default:IMAGE_ROOTFS_SIZE_ext2 = "65536" + + + + + 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 + + + Creates a version of the ext2 filesystem image compressed with + gzip. + + 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}; \ +gzip -f -9 ${DEPLOY_DIR_IMAGE}/tmp.gz/${IMAGE_NAME}.rootfs.ext2; \ +mv ${DEPLOY_DIR_IMAGE}/tmp.gz/${IMAGE_NAME}.rootfs.ext2.gz \ + ${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.ext2.gz; \ +rmdir ${DEPLOY_DIR_IMAGE}/tmp.gz" + + The EXTRA_IMAGECMD variable for ext2.gz is + 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 + default: + + IMAGE_ROOTFS_SIZE_ext2.gz = "65536" + + + + + 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 + + + Creates a squashfs image. This is a read only compressed + filesystem which is used directly with files uncompressed into RAM + as they are accessed. Files and filesystems may be up to 2^64 bytes + in size, full 32-bit uids and gids are stored, it detects duplicate + files and stores only a single copy, all meta-data is compressed and + big and little endian filesystems can be mounted on any + platform. + + Squashfs uses gzip as its compression method. + + IMAGE_CMD_squashfs = "mksquashfs ${IMAGE_ROOTFS} \ + ${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.squashfs \ + ${EXTRA_IMAGECMD} -noappend" + + The EXTRA_IMAGECMD variable for squashfs is + passed to mksquashfs and is left empty by + default:EXTRA_IMAGECMD_squashfs = "" + + 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" + + + + + squashfs-lzma + + + Creates a squashfs image using lzma compression instead of + gzip which is the standard squashfs compression type. This is a read + only compressed filesystem which is used directly with files + uncompressed into RAM as they are accessed. Files and filesystems + may be up to 2^64 bytes in size, full 32-bit uids and gids are + stored, it detects duplicate files and stores only a single copy, + all meta-data is compressed and big and little endian filesystems + can be mounted on any platform. + + Squashfs-lzma uses lzma as its compression method. + + IMAGE_CMD_squashfs-lzma = "mksquashfs-lzma ${IMAGE_ROOTFS} \ + ${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.squashfs \ + ${EXTRA_IMAGECMD} -noappend" + + The EXTRA_IMAGECMD variable for squashfs is + passed to mksquashfs-lzma and is left empty by + default:EXTRA_IMAGECMD_squashfs-lzma = "" + + 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" + + + + + tar + + + Creates a .tar archive. + + IMAGE_CMD_tar = "cd ${IMAGE_ROOTFS} && \ + tar -cvf ${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.tar ." + + The EXTRA_IMAGECMD variable in not + supported for tar images. + + + + + tar.gz + + + Creates a gzip compressed .tar + archive. + + IMAGE_CMD_tar.gz = "cd ${IMAGE_ROOTFS} && \ + tar -zcvf ${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.tar.gz ." + + The EXTRA_IMAGECMD variable in not + supported for .tar.gz images. + + + + + tar.bz2 + + + Creates a bzip2 compressed .tar + archive. + + IMAGE_CMD_tar.bz2 = "cd ${IMAGE_ROOTFS} && \ + tar -jcvf ${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.tar.bz2 ." + + The EXTRA_IMAGECMD variable in not + 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 + configuration file: + org.openembedded.dev/conf/bitbake.conf. +
+ +
+ Custom image types + + Custom image types can be created by defining the + IMAGE_CMD variable, and optionally the + EXTRA_IMAGECMD, IMAGE_ROOTFS_SIZE + and IMAGE_DEPENDS variables, for your new image + type. + + An example can be found in + conf/machine/wrt54.conf where it defines a new image + type, squashfs-lzma, for a squashfs filesystem using + lzma compression instead of the standard gzip compression (squashfs-lzma + is now a standard type, but the example still serves to show the + concept):IMAGE_DEPENDS_squashfs-lzma = "squashfs-tools-native" +IMAGE_CMD_squashfs-lzma = "mksquashfs-lzma ${IMAGE_ROOTFS} \ + ${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.squashfs-lzma \ + ${EXTRA_IMAGECMD} -noappend" +EXTRA_IMAGECMD_squashfs-lzma = "-root-owned -le" +
+
diff --git a/docs/usermanual/reference/var_section.xml b/docs/usermanual/reference/var_section.xml new file mode 100644 index 0000000000..96b746e56c --- /dev/null +++ b/docs/usermanual/reference/var_section.xml @@ -0,0 +1,704 @@ + +
+ SECTION variable: Package category + + Sections are a means for categorising packages into related groups to + enable users to find packages easier. The SECTION + variable is used to declare which section a package belongs to. The most + common use of the section information is in GUI based package management + applications. + + The default values for the section variables are: + + + + SECTION = "base" + + + + SECTION_${PN}-doc = "doc" + + + + SECTION_${PN}-dev = "devel" + + + + Note that each package generated by a recipe can have it's own section + and that by default documentation and development files are seperated out to + their own sections. + + The table of sections show the current usage of section information. + This is a recomendation only, althought it is recomended that any additions + or modifications be discusssed via the open embedded developer mailing list + first. + + + + + + + + + + Section + + Description + + + + admin + + + + + + base + + Base system files. These are applications which are expected + to be included as part of a base system and include things such as + init scripts, core utilities, standard system daemons etc. + + + + base/shell + + Shells such as bash, tcsh, ksh etc. + + + + bootloaders + + Bootloaders, which are the applications responsible for + loading the kernel from the appropriate location (disk, flash, + network, etc.) and starting it running. + + + + console + + Applications which run on the console. These require no GUI + related libraries or interfaces to run. + + + + console/editors + + + + + + console/games + + + + + + console/multimedia + + + + + + console/network + + + + + + console/scientific + + + + + + console/telephony + + + + + + console/tools + + + + + + console/utils + + + + + + devel + + Development related files. These include compilers, + libraries, headers, debuggers etc. + + + + devel/libs + + + + + + devel/perl + + + + + + devel/python + + + + + + devel/rexx + + + + + + devel/ruby + + + + + + devel/scheme + + + + + + devel/tcltk + + + + + + doc + + Documentation, including man pages and sample configuration + files. + + + + e/apps + + + + + + e/libs + + + + + + e/utils + + + + + + fonts + + Fonts that are not X11 or OPIE specific such as truetype + fonts. + + + + games + + Games. + + + + games/arcade + + + + + + gpe + + GPE GUI enviroment. For the anything that provides or uses + the GPE UI. Note that development and documentation related files + should be in the appropriate devel and doc section, not under + GPE. + + + + gpe/applications + + + + + + gpe/base + + + + + + gpe/games + + + + + + gpe/libs + + GPE runtime libraries. This does not include libraries used + for development - they should be included in the appropriate devel + section. + + + + gpe/multimedia + + + + + + inputmethods + + inputmethods that are neither libs, nor solely for GPE/Opie or the console + + + + interpreters + + + + + + kde + + KDE related applications. + + + + kde/devel + + + + + + kernel + + Linux kernels. + + + + kernel/modules + + Linux kernel modules. This include out-of-tree kernel + modules. + + + + kernel/userland + + + + + + libs + + Runtime libraries. This does not include libraries used for + development - they should be included in the appropriate devel + section. + + + + libs/inputmethods + + + + + + libs/multimedia + + + + + + libs/network + + + + + + network + + + + + + network/cms + + + + + + network/misc + + + + + + openmoko + + Anything related to openmoko.org + + + + openmoko/applications + + + + + + openmoko/base + + + + + + openmoko/examples + + + + + + openmoko/libs + + + + + + openmoko/pim + + + + + + openmoko/tools + + + + + + opie + + OPIE GUI enviroment. For the anything that provides or uses + the OPIE UI. Note that development and documentation related files + should be in the appropriate devel and doc section, not under + OPIE. + + + + opie/applets + + + + + + opie/applications + + + + + + opie/base + + + + + + opie/codecs + + + + + + opie/datebook + + + + + + opie/decorations + + + + + + opie/fontfactories + + + + + + opie/fonts + + OPIE specific fonts. General fonts, such as truetype fonts, + should be in the fonts section. + + + + opie/games + + + + + + opie/help + + + + + + opie/inputmethods + + + + + + opie/libs + + OPIE runtime libraries. This does not include libraries used + for development - they should be included in the appropriate devel + section. + + + + opie/multimedia + + + + + + opie/network + + + + + + opie/pim + + + + + + opie/security + + + + + + opie/settings + + + + + + opie/shell + + + + + + opie/styles + + + + + + opie/today + + + + + + utils + + + + + + x11 + + X11 GUI platform. For anything that provides or uses the X11 + UI and is not GPE. Note that development and documentation related + files should be in the appropriate devel and doc section, not under + X11. + + + + x11/applications + + General applications. + + + + x11/base + + Core X11 applications. + + + + x11/data + + + + + + x11/fonts + + X11 specific fonts. General fonts, such as truetype fonts, + should be in the fonts section. + + + + x11/games + + Games. + + + + x11/gnome + + Core gnome applications. + + + + x11/gnome/libs + + Gnome runtime libraries. This does not include libraries used + for development - they should be included in the appropriate devel + section. + + + + x11/graphics + + Applications which manipulate, display, edit, print etc. + images, photos, diagrams etc. + + + + x11/libs + + X11 runtime libraries. This does not include libraries used + for development - they should be included in the appropriate devel + section. + + + + x11/multimedia + + Multimedia applications. + + + + x11/network + + + + + + x11/office + + Office and productivity applications. + + + + x11/scientific + + Scientific applications. + + + + x11/utils + + + + + + x11/wm + + Window managers. + + + + + + The following tables lists some sections which may be in existing + recipes. These should not be used in new recipes and should be renamed when + updated existing recipes that use the specified sections. + + + + + + + + + + Section + + Action + + + + apps + + Replace with appropriate section + + + + gui + + Replace with appropriate section + + + + media-gfx + + Replace with appropriate section + + + + multimedia + + Replace with appropriate section + + + + net + + Replace with network + + + + unknown + + Replace with appropriate section + + + + x11-misc + + Replace with appropriate section + + + + + + +
diff --git a/docs/usermanual/reference/var_src_uri.xml b/docs/usermanual/reference/var_src_uri.xml new file mode 100644 index 0000000000..a9a2985a70 --- /dev/null +++ b/docs/usermanual/reference/var_src_uri.xml @@ -0,0 +1,692 @@ + +
+ SRC_URI variable: Source code and patches + + All recipies need to contain a definition of + SRC_URI. It determines what files and source code is + needed and where that source code should be obtained from. This includes + patches to be applied and basic files that are shipped as part of the + meta-data for the package. + + A typical SRC_URI contains a list of URL's, patches + and files as shown in this example from quagga:SRC_URI = "http://www.quagga.net/download/quagga-${PV}.tar.gz \ + file://ospfd-no-opaque-lsa-fix.patch;patch=1 \ + file://fix-for-lib-inpath.patch;patch=1 \ + file://quagga.init \ + file://quagga.default \ + file://watchquagga.init \ + file://watchquagga.default"All source code and files will + be placed into the work directory, ${WORKDIR}, for the + package. All patches will be placed into a patches + subdirectory of the package source directory, ${S}, and + then automatically applied to the source. + + Before downloading from a remote URI a check will be made to see if + what is to be retrieved is already present in the download source directory, + ${DL_DIR}, along with an associated md5 sum. If the + source is present in the downloaded sources directory and the md5 sum + matches that listed in the associated md5 sum file, then that version will + be used in preference to retrieving a new version . Any source that is + retrieved from a remote URI will be stored in the download source directory + and an appropriate md5 sum generated and stored alongside it. + + Each URI supports a set of additional options. These options are + tag/value pairs of the form "a=b" and are semi-colon + separated from each other and from the URI. The follow examples shows two + options being included, the patch and pnum options:file://ospfd-no-opaque-lsa-fix.patch;patch=1;pnum=2The + supported methods for fetching source and files are: + + + + http, https, ftps + + + Used to download files and source code via the specified URL. + These are fetched from the specified location using wget. + + + + + file + + + Used for files that are included locally in the meta-data. These + may be plain files, such as init scripts to be added to the final + package, or they may be patch files to be applied to other + source. + + + + + cvs + + + Used to download from a CVS repository. + + + + + svn + + + Used to download from a subversion repository. + + + + + git + + + Used to download from a git repository. + + + + + When source code is specified as a part of SRC_URI + it is unpacked into the work directory, ${WORKDIR}. The + unpacker recognises several archive and compression types and for these it + will decompress any compressed files and extract all of the files from + archives into the work directory. The supported types are: + + + + .tar + + + Tar archives which will be extracted with "tar x + --no-same-owner -f <srcfile>". + + + + + .tgz, .tar.gz, tar.Z + + + Gzip compressed tar archives which will be extracted with + "tar xz --no-same-owner -f <srcfile>". + + + + + .tbz, .tar.bz2 + + + Bzip2 compressed tar archives which will be extracted with + "bzip2 -dc <srcfile> | tar x --no-same-owner -f + -". + + + + + .gz, .Z, .z + + + Gzip compressed files which will be decompressed with + "gzip -dc <srcfile> > + <dstfile>". + + + + + .bz2 + + + Bzip2 compressed files which will be decompressed with + "bzip2 -dc <srcfile> > + <dstfile>". + + + + + .zip + + + Zip archives which will be extracted with "unzip -q + <srcfile>". + + + + + The downloading of the source files occurs in the + fetch task, the unpacking and copying to the work + directory occurs in the unpack task and the applying of + patches occurs in the patch task. + +
+ http/https/ftp (wget) + + The wget fetcher handles http, https and ftp URLs.http://www.quagga.net/download/quagga-${PV}.tar.gz + + Supported options: + + + + md5sum + + + If an md5sum is provided then the downloaded files will only + be considered valid if the md5sum of the downloaded file matches the + md5sum option provided. + + + + + Related variables: + + + + MIRRORS + + + Mirrors define alternative locations to download source files + from. See the mirror section below for more information. + + + + + DL_DIR + + + The downloaded files will be placed in this directory with the + name exactly as supplied via the URI. + + + +
+ +
+ file: for patches and additional files + + The file URI's are used to copy files, included as part of the + package meta data, into the work directory to be used when building the + package. Typical use of the file URI's is to specify patches that be + applied to the source and to provide additional files, such as init + scripts, to be included in the final package. + + The following example shows the specification of a patch + file:file://ospfd-no-opaque-lsa-fix.patch;patch=1 + + Patch files are be copied to the patches subdirectory of the source + directory, ${S}/patches, and then applied from the + source directory. The patches are searched for along the path specified + via the file path variable, ${FILESPATH}, and if not + found the directory specified by the file directory variable, + ${FILEDIR}, is also checked. + + The following example shows the specification of a non-patch file. + In this case it's an init script:file://quagga.initNon-patch + files are copied to the work directory, ${WORKDIR}. You + can access these files from within a recipe by referring to them relative + to the work directory. The following example, from the quagga recipe, + shows the above init script being included in the package by copying it + during the install task:do_install () { + # Install init script and default settings + install -m 0755 -d ${D}${sysconfdir}/default ${D}${sysconfdir}/init.d ${D}${sysconfdir}/quagga + install -m 0644 ${WORKDIR}/quagga.init ${D}${sysconfdir}/init.d/quagga +... + + Supported options: + + + + patch + + + Used as "patch=1" to define this file as a + patch file. Patch files will be copied to + ${S}/patches and then applied to source from + within the source directory, ${S}. + + + + + pnum + + + By default patches are applied with the "-p + 1" parameter, which strips off the first directory of the + pathname in the patches. This option is used to explicitly control + the value passed to "-p". The most typical use is + when the patches are relative to the source directory already and + need to be applied using "-p 0", in which case + the "pnum=0" option is supplied. + + + +
+ +
+ cvs + + The cvs fetcher is used to retrieve files from a CVS repository. + cvs://anonymous@cvs.sourceforge.net/cvsroot/linuxsh;module=linux;date=20051111A + cvs URI will retrieve the source from a cvs repository. Note that use of + the date= to specify a checkout for specified date. + It is preferable to use either a date= or a + tag= option to select a specific date and/or tag from + cvs rather than leave the checkout floating at the head revision. + + Supported options: + + + + module + + + The name of a module to retrieve. This is a required parameter + and there is no default value. + + + + + tag + + + The name of a cvs tag to retrieve. Releases are often tagged + with a specific name to allow easy access. Either a tag or a date + can be specified, but not both. + + + + + date + + + The date to retrieve. This requests that files as of the + specified date, rather then the current code or a tagged release. If + no date or tag options are specified, then the date is set to the + current date. The date is of any form accepted by cvs with the most + common format being "YYYYMMDD". + + + + + method + + + The method used to access the repository. Common options are + "pserver" and "ext" (for cvs + over rsh or ssh). The default is + "pserver". + + + + + rsh + + + The rsh command to use with the "ext" + method. Common options are "rsh" or + "ssh". The default is + "rsh". + + + + + Related variables: + + CVS_TARBALL_STASH + + + Used to specifies a location to search for pre-generated tar + archives to use instead of accessing cvs directly. + + + + + CVSDIR + + + The directory in which the cvs checkouts will be performed. + The default is ${DL_DIR}/cvs. + + + + + DL_DIR + + + A compressed tar archive of the retrieved files will be + placed in this directory. The archive name will be of the form: + "<module>_<host>_<tag>_<date>.tar.gz". + Path separators in module will be replaced with + full stops. + + + +
+ +
+ svn + + The svn fetcher is used to retrieve files from a subversion + repository. + + svn://svn.xiph.org/trunk;module=Tremor;rev=4573;proto=http + + Supported options: + + + + module + + + The name of a module to retrieve. This is a required parameter + and there is no default value. + + + + + rev + + + The revision to retrieve. Revisions in subversion are integer + values. + + + + + proto + + + The method to use to access the repository. Common options are + "svn", "svn+ssh", + "http" and "https". The + default is "svn". + + + + + rsh + + + The rsh command to use with using the + "svn+ssh" method. Common options are + "rsh" or "ssh". The default is + "ssh". + + + + + Related variables: + + SVNDIR + + + The directory in which the svn checkouts will be performed.. + The default is ${DL_DIR}/svn. + + + + + DL_DIR + + + A compressed tar archive of the retrieved files will be + placed in this directory. The archive name will be of the form: + "<module>_<host>_<path>_<revn>_<date>.tar.gz". + Path separators in path and + module will be replaced with full stops. + + + +
+ +
+ git + + The git fetcher is used to retrieve files from a git repository. + SRC_URI = "git://www.denx.de/git/u-boot.git;protocol=git;tag=${TAG}" + + Supported options: + + + + tag + + + The tag to retrieve. The default is + "master". + + + + + protocol + + + The method to use to access the repository. Common options are + "git" and "rsync". The default + is "rsync". + + + + + Related variables + + + + GITDIR + + + The directory in which the git checkouts will be performed. + The default is ${DL_DIR}/git. + + + + + DL_DIR + + + A compressed tar archive of the retrieved files will be + placed in this directory. The archive name will be of the form: + "git_<host><mpath>_<tag>.tar.gz". + Path separators in host will be replaced with + full stops. + + + +
+ +
+ Mirrors + + The support for mirror sites enables spreading the load over sites + and allows for downloads to occur even when one of the mirror sites are + unavailable. + + Default mirrors, along with their primary URL, include: + + + + GNU_MIRROR + + + ftp://ftp.gnu.org/gnu + + + + + DEBIAN_MIRROR + + + ftp://ftp.debian.org/debian/pool + + + + + SOURCEFORGE_MIRROR + + + http://heanet.dl.sourceforge.net/sourceforge + + + + + GPE_MIRROR + + + http://handhelds.org/pub/projects/gpe/source + + + + + XLIBS_MIRROR + + + http://xlibs.freedesktop.org/release + + + + + XORG_MIRROR + + + http://xorg.freedesktop.org/releases + + + + + GNOME_MIRROR + + + http://ftp.gnome.org/pub/GNOME/sources + + + + + FREEBSD_MIRROR + + + ftp://ftp.freebsd.org/pub/FreeBSD + + + + + GENTOO_MIRROR + + + http://distro.ibiblio.org/pub/linux/distributions/gentoo/distfiles + + + + + APACHE_MIRROR + + + http://www.apache.org/dist + + + + + When creating new recipes this mirrors should be used when you wish + to use one of the above sites by referring to the name of the mirror in + the URI, as show in this example from flex:SRC_URI = "${SOURCEFORGE_MIRROR}/lex/flex-2.5.31.tar.bz2 + + You can manually define your mirrors if you wish to force the use of + a specific mirror by exporting the appropriate mirrors in + local.conf with them set to the local mirror:export GNU_MIRROR = "http://www.planetmirror.com/pub/gnu" +export DEBIAN_MIRROR = "http://mirror.optusnet.com.au/debian/pool" +export SOURCEFORGE_MIRROR = "http://optusnet.dl.sourceforge.net/sourceforge" + + Mirrors can be extended in individual recipes via the use of + MIRRORS_prepend or MIRRORS_append. + Each entry in the list contains the mirror name on the left-hand side and + the URI of the mirror on the right-hand side. The following example from + libffi shows the addition of two URI for the + "${GNU_MIRROR}/gcc/" URI:MIRRORS_prepend () { + ${GNU_MIRROR}/gcc/ http://gcc.get-software.com/releases/ + ${GNU_MIRROR}/gcc/ http://mirrors.rcn.net/pub/sourceware/gcc/releases/ +} +
+ +
+ Manipulating SRC_URI + + Sometimes it is desirable to only include patches for a specific + architecture and/or to include different files based on the architecture. + This can be done via the SRC_URI_append and/or + SRC_URI_prepend methods for adding additional URI's + based on the architecture or machine name. + + In this example from glibc, the patch creates a configuration file + for glibc, which should only be used or the sh4 architecture. Therefore + this patch is appended to the SRC_URI, but only for the + sh4 architecture. For other architectures it is ignored:# Build fails on sh4 unless no-z-defs is defined +SRC_URI_append_sh4 = " file://no-z-defs.patch;patch=1" +
+ +
+ Source distribution (src_distribute_local) + + In order to obtain a set of source files for a build you can use the + src_distribute_local class. This will result in all + the files that were actually used during a build being made available in a + seperate directory and therefore they can be distributed with the + binaries. + + Enabling this option is as simple as activating the functionality by + including the required class in one of your configuration files:SRC_DIST_LOCAL = "copy" +INHERIT += "src_distribute_local" + + Now during a build each recipe which has a LICENSE that mandates + source availability, like the GPL, will be placed into the source + distribution directory, ${SRC_DISTRIBUTEDIR}, after + building. + + There are some options available to effect the option + + + + SRC_DIST_LOCAL + + + Specifies if the source files should be copied, symlinked or + moved and symlinked back. The default is + "move+symlink". + + + + + SRC_DISTRIBUTEDIR + + + Specifies the source distribution directory - this is why the + source files that was used for the build are placed. The default is + "${DEPLOY_DIR}/sources". + + + + + The valid values for SRC_DIST_LOCAL are: + + + + copy + + + Copies the files to the downloaded sources directory into the + distribution directory. + + + + + symlink + + + Symlinks the files from the downloaded sources directory into + the distribution directory. + + + + + move+symlink + + + Moves the files from the downloaded sources directory into the + distribution directory. Then creates a symlink in the download + sources directory to the moved files. + + + +
+
\ No newline at end of file -- cgit v1.2.3