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, wh