diff options
| author | Michael 'Mickey' Lauer <mickey@vanille-media.de> | 2009-02-25 01:47:30 +0100 |
|---|---|---|
| committer | Michael 'Mickey' Lauer <mickey@vanille-media.de> | 2009-02-25 01:47:30 +0100 |
| commit | 25b51d32c982a6767f3d4a88dec12f70c8c8f875 (patch) | |
| tree | 206e94d12d2fda511c5b383adfec3684829703a1 /docs/usermanual/reference | |
| parent | 6d76191b2021518d2f1ea00c20a1ec3151d93069 (diff) | |
docs: import usermanual from org.openembedded.documentation.
org.openembedded.documentation is deprecated now; please do all updates here!
Diffstat (limited to 'docs/usermanual/reference')
| -rw-r--r-- | docs/usermanual/reference/.mtn2git_empty | 0 | ||||
| -rw-r--r-- | docs/usermanual/reference/class_autotools.xml | 153 | ||||
| -rw-r--r-- | docs/usermanual/reference/class_binconfig.xml | 46 | ||||
| -rw-r--r-- | docs/usermanual/reference/class_distutils.xml | 48 | ||||
| -rw-r--r-- | docs/usermanual/reference/class_image.xml | 358 | ||||
| -rw-r--r-- | docs/usermanual/reference/class_pkgconfig.xml | 39 | ||||
| -rw-r--r-- | docs/usermanual/reference/class_rootfs_ipkg.xml | 215 | ||||
| -rw-r--r-- | docs/usermanual/reference/class_siteinfo.xml | 180 | ||||
| -rw-r--r-- | docs/usermanual/reference/class_update-alternatives.xml | 241 | ||||
| -rw-r--r-- | docs/usermanual/reference/class_update-rc.d.xml | 133 | ||||
| -rw-r--r-- | docs/usermanual/reference/dirs_install.xml | 198 | ||||
| -rw-r--r-- | docs/usermanual/reference/dirs_staging.xml | 169 | ||||
| -rw-r--r-- | docs/usermanual/reference/fakeroot.xml | 186 | ||||
| -rw-r--r-- | docs/usermanual/reference/image_types.xml | 385 | ||||
| -rw-r--r-- | docs/usermanual/reference/var_section.xml | 704 | ||||
| -rw-r--r-- | docs/usermanual/reference/var_src_uri.xml | 692 |
16 files changed, 3747 insertions, 0 deletions
diff --git a/docs/usermanual/reference/.mtn2git_empty b/docs/usermanual/reference/.mtn2git_empty new file mode 100644 index 0000000000..e69de29bb2 --- /dev/null +++ b/docs/usermanual/reference/.mtn2git_empty 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 @@ +<?xml version="1.0" encoding="UTF-8"?> +<section id="autotools_class" xreflabel="autotools class"> + <title>autotools class</title> + + <para>Autotools is one of the most commonly seen configuration methods for + applications. Anything that uses the standard <command>./configure; make; + make install</command> 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.</para> + + <para>The autotools class takes care of all of the details for you. It + defines appropriate tasks for <emphasis>configure</emphasis>, + <emphasis>compile</emphasis>, <emphasis>stage</emphasis> and + <emphasis>install</emphasis>. At it's simplest adding an inherit for the + autotools class is all that is required. The netcat recipe for example + is:<screen>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 autotools</screen>The 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 <command>EXTRA_OECONF</command> variable. This example from the lftp + recipe shows several extra options being passed to the configure + script:<screen>EXTRA_OECONF = "--disable-largefile --disable-rpath --with-included-readline=no"</screen>If + you define your own tasks for <emphasis>configure</emphasis>, + <emphasis>compile</emphasis>, <emphasis>stage</emphasis> or + <emphasis>install</emphasis> (via <command>do_<taskname></command>) + 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 <command>do_<task>_append</command> or + <command>do_<task>_prepend</command> methods. The following example + from the conserver recipe shows some additional items being + installed:<screen># 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 +}</screen></para> + + <section> + <title>oe_runconf / autotools_do_configure</title> + + <para>Autotools generates a configuration method called + <command>oe_runconf</command> which runs the actual configure script, and + a method called <command>autotools_do_configure</command> which generates + the configure file (runs automake and autoconf) and then calls + <command>oe_runconf</command>. The generated method for the + <emphasis>configure</emphasis> task, <command>do_configure</command>, just + calls the <command>autotools_do_configure</command> method.</para> + + <para>It is sometimes desirable to implement your own + <command>do_configure</command> method, where additional configuration is + required or where you wish to inhibit the running of automake and + autoconf, and then manually call <command>oe_runconf</command>.</para> + + <para>The following example from the ipacct recipe shows an example of + avoiding the use of automake/autoconf:<screen>do_configure() { + oe_runconf +}</screen>Sometimes manual manipulations of the autotools files is required + prior to calling autoconf/automake. In this case you can defined your own + <command>do_configure</command> method which performs the required actions + and then calls <command>autotools_do_configure</command>.</para> + </section> + + <section> + <title>Presetting autoconf variables (the site file)</title> + + <para>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.</para> + + <para>Autoconf uses site files as definied in the + <command>CONFIG_SITE</command> 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 <xref linkend="siteinfo_class" /> (the class + responsbile for setting the variable) section.</para> + + <para>There are some things that you should keep in mind about the caching + of configure tests:</para> + + <orderedlist> + <listitem> + <para>Check the other site files to see if there any entries for the + application you are attempting to build.</para> + + <para>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.</para> + </listitem> + + <listitem> + <para>Sometimes the same cache value is used by multiple + applications.</para> + + <para>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.</para> + </listitem> + + <listitem> + <para>Not all values can be stored in the cache</para> + + <para>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.</para> + </listitem> + </orderedlist> + + <para>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:<screen>ac_cv_sys_restartable_syscalls=yes</screen>and + conditionally setting the value of the variable:<screen>ac_cv_uchar=${ac_cv_uchar=no}</screen>The + conditional version is using shell syntax to say "<emphasis>only set this + to the specified value if it is not currently set</emphasis>". 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.</para> + + <note> + <para>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.</para> + </note> + + <para>It is possible to disable the use of the cached values from the site + file by clearing the definition of <command>CONFIG_SITE</command> 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:<screen># Cancel the site stuff - it's set for db3 and destroys the +# configure. +CONFIG_SITE = "" +do_configure() { + oe_runconf +}</screen></para> + </section> +</section>
\ 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 @@ +<?xml version="1.0" encoding="UTF-8"?> +<section id="binconfig_class" xreflabel="binconfig class"> + <title>binconfig class</title> + + <para>The binconfig class is for packages that install + <command><pkg>-config</command> 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.</para> + + <para>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 <emphasis>stage</emphasis> task.</para> + + <para>The actions performed by the binconfig class are:</para> + + <orderedlist> + <listitem> + <para>Copies the <command><x>-config</command> script from the + package into <command>${STAGING_BINDIR} </command>directory;</para> + </listitem> + + <listitem> + <para>If the package is not native then it modifies the contents of the + <command><x>-config</command> script in the staging area to ensure + that all the paths in the script refer to the staging area;</para> + </listitem> + + <listitem> + <para>If the package is native then + the<command><x>-config</command> script is renamed to + <command><x>-config-native</command> to ensure that the native and + non-native versions do not interfere with each other.</para> + </listitem> + </orderedlist> + + <para>A package is considered to be native if it also inherits the native + class.</para> + + <para>The class will search in source directory, <command>${S}</command>, + and all it's subdirectories, for files that end in + <command>-config</command> and process them as described above. All that is + required to use the class is the addition of binconfig in an inherit + statement:</para> + + <para><screen>inherit autotools binconfig</screen></para> +</section>
\ 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 @@ +<?xml version="1.0" encoding="UTF-8"?> +<section id="distutils_class" xreflabel="distutils class"> + <title>distutils class</title> + + <para>Distutils is a standard python system for building and installing + modules. The <emphasis>distutils</emphasis> class is used to automate the + building of python modules that use the distutils system.</para> + + <para>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:<screen>python setup.py build +python setup.py install</screen></para> + + <para>The <emphasis>distutils</emphasis> class will perform the build and + install actions on the <command>setup.py</command> 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:</para> + + <orderedlist> + <listitem> + <para>Adds python-native to <command>DEPENDS</command> 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.</para> + </listitem> + + <listitem> + <para>Adds python-core to <command>RDEPENDS</command> 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 + <command>RDEPENDS</command>.</para> + </listitem> + </orderedlist> + + <para>The following example from the <emphasis>moin</emphasis> recipe shows + how simple this can make a python package:<screen>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 distutils</screen>The header, source location and the inherit are all + that is required.</para> +</section>
\ 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 @@ +<?xml version="1.0" encoding="UTF-8"?> +<section id="image_class" xreflabel="image class"> + <title>image class</title> + + <para>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 <xref linkend="rootfs_ipkg_class" />, for use on the target device. This + could be a <emphasis>jffs2</emphasis> 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.</para> + + <para>Summary of the actions performed by the + <emphasis>image_ipkg</emphasis> class:</para> + + <orderedlist> + <listitem> + <para>Inherits the rootfs class for the appropriate package type, + typically <xref linkend="rootfs_ipkg_class" />, 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;</para> + </listitem> + + <listitem> + <para>Sets <command>BUILD_ALL_DEPS = "1"</command> to force the + dependency system to build all packages that are listed in the + <command>RDEPENDS</command> and/or <command>RRECOMENDS</command> of the + packages to be installed;</para> + </listitem> + + <listitem> + <para>Determines the name of the image device tables or table + (<command>IMAGE_DEVICE_TABLES/IMAGE_DEVICE_TABLE</command>) which will + be used to describe the device nodes to create in + <command>/dev</command> directory in the root filesystem;</para> + </listitem> + + <listitem> + <para>Erases the contents of any existing root filesystem image, + <command>${IMAGE_ROOTFS}</command>;</para> + </listitem> + + <listitem> + <para>If devfs is not being used then the <command>/dev</command> + directory, <command>${IMAGE_ROOTFS}/dev</command>, will be created and + then populated with the device nodes described by the image device table + or tables (using "<command>makedevs -r ${IMAGE_ROOTFS} -D + <table></command>" for each device table);</para> + </listitem> + + <listitem> + <para>Calls into <xref linkend="rootfs_ipkg_class" /> to install all of + the required packages into the root filesystem;</para> + </listitem> + + <listitem> + <para>Configures the ipkg feed information in the root filesystem + (using <command>FEED_URIS</command> and <command>FEED_DEPLOYDIR_BASE_URI</command>);</para> + </listitem> + + <listitem> + <para>Runs any image pre-processing commands as specified via + <command>${IMAGE_PREPROCESS_COMMAND}</command>;</para> + </listitem> + + <listitem> + <para>Calls <command>bbimage</command> on the root filesystem for each + required image type, as specified via + <command>${IMAGE_FSTYPES}</command>, to generate the actual filesystem + images;</para> + </listitem> + + <listitem> + <para>Runs any image post-processing commands, as specified via + <command>${IMAGE_POSTPROCESS_COMMAND}</command>.</para> + </listitem> + </orderedlist> + + <para>The following variables may be used to control some of the behaviour + of this class (remember we use <xref linkend="rootfs_ipkg_class" /> to build + the filesystem image, so look at the variables defined by that class as + well):</para> + + <variablelist> + <varlistentry> + <term>USE_DEVFS</term> + + <listitem> + <para>Indicates if the image will be using devfs, the device + filesystem, or not. If devfs is being used then no + <command>/dev</command> directory will be required in the image. Set + to <command>"1"</command> 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.</para> + + <para>Default: <command>"0"</command></para> + </listitem> + </varlistentry> + + <varlistentry> + <term>IMAGE_DEVICE_TABLES</term> + + <listitem> + <para>Specifies one, or more, files containing a list of the device + nodes that should be created in the <command>/dev</command> directory + of the image. Each file is searched for via the + <command>${BBPATH}</command> 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 <command>IMAGE_DEVICE_TABLE</command> is set + then this variable is ignored.</para> + + <para>Example: <command>IMAGE_DEVICE_TABLES = + "files/device_table-minimal.txt files/device_table_add-sci.txt + device_table_add-sm.txt"</command></para> + + <para>Default: + <command>"files/device_table-minimal.txt"</command></para> + </listitem> + </varlistentry> + + <varlistentry> + <term>IMAGE_DEVICE_TABLE</term> + + <listitem> + <para>Specifies the file that lists the device nodes that should be + created in the <command>/dev </command>directory of the image. This + needs to be an absolute filename and so should be specified relative + to <command>${BBPATH}</command>. Only a single device table is + supported. Use <command>IMAGE_DEVICE_TABLES</command> instead if you + want to use multiple device tables.</para> + + <para>Default: <command>""</command></para> + </listitem> + </varlistentry> + + <varlistentry> + <term>IMAGE_PREPROCESS_COMMAND</term> + + <listitem> + <para>Additional commands to run prior to processing the image. Note + that these command run within the same <xref linkend="fakeroot" /> + instance as the rest of this class.</para> + + <para>Default: <command>""</command></para> + </listitem> + </varlistentry> + + <varlistentry> + <term>IMAGE_POSTPROCESS_COMMAND</term> + + <listitem> + <para>Additional commands to run after processing the image. Note that + these command run within the same <xref linkend="fakeroot" /> instance + as the rest of this class.</para> + + <para>Default: <command>""</command></para> + </listitem> + </varlistentry> + + <varlistentry> + <term>IMAGE_FSTYPES</term> + + <listitem> + <para>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 <xref linkend="image_types" /> section. + This variable is set to a space seperated list of image types to + generate.</para> + + <para>Example: <command>"jffs2 tar.gz"</command></para> + + <para>Default: <command>"jffs2"</command></para> + </listitem> + </varlistentry> + + <varlistentry> + <term>FEED_URIS</term> + + <listitem> + <para>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.</para> + + <para>Example: <command>FEED_URIS = + "example##http://dist.example.com/ipkg-titan-glibc/"</command></para> + + <para>Default: <command>""</command></para> + </listitem> + </varlistentry> + + <varlistentry> + <term>FEED_DEPLOYDIR_BASE_URI</term> + + <listitem> + <para>If set, configures local testing feeds using OE package deploy dir + contents. The value is URL, corresponding to the ipk deploy dir.</para> + + <para>Example: <command>FEED_DEPLOYDIR_BASE_URI = + "http://192.168.2.200/bogofeed/"</command></para> + + <para>Default: <command>""</command></para> + </listitem> + </varlistentry> + </variablelist> + + <section> + <title>Special node handling (fakeroot)</title> + + <para>Special nodes, such as <command>/dev</command> nodes, and files with + special permissions, such as suid files, are handled via the <xref + linkend="fakeroot" /> system. This means that when you view the contents + of the root filesystem these device appear to be created + incorrectly:</para> + + <para>The <command>IMAGE_PREPROCESS_COMMAND</command> and + <command>IMAGE_POSTPROCESS_COMMAND</command> variables will be processed + within the same <xref linkend="fakeroot" /> instance as the rest of the + rest of this class.</para> + </section> + + <section> + <title>Device (/dev) nodes</title> + + <para>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 <command>${BBPATH}</command> so that + relative file names may be used.</para> + + <para>The following example from <command>machine/titan.conf</command> + shows the use of multiple device tables:</para> + + <para><screen># 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" +</screen></para> + + <para>It uses the standard minimal device tables but adds some additional + items which are not normally needed:</para> + + <variablelist> + <varlistentry> + <term>files/device_table-minimal.txt</term> + + <listitem> + <para>This is the standard minimal set of device nodes.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>files/device_table_add-sci.txt</term> + + <listitem> + <para>This contains details for creating the + <command>/dev/SC{0,1,2}</command> 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.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>device_table_add-sm.txt</term> + + <listitem> + <para>This contains details for creating the + <command>/dev/sm0</command> and <command>/dev/sm0p{0,1,2}</command> + devices nodes for the block driver, and the associated partitions, + that are used to manage the on board flash on the titan + hardware.</para> + </listitem> + </varlistentry> + </variablelist> + + <para>Prior to support for multiple device tables this would have required + the creation of a titan specific device table.</para> + </section> + + <section> + <title>Image types</title> + + <para>The type of filesystem images to create are specified via the + <command>IMAGE_FSTYPES</command> variable. A full description of the + available image types, options of the images and details on creating new + image types is provided in the <xref linkend="image_types" /> + section.</para> + </section> + + <section> + <title>Package feeds</title> + + <para>"Package feed", or feed for short, is a term used by <command>ipkg</command> + 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 <command>Packages</command> or + <command>Packages.gz</command> if compressed. Multiple feeds are supported.</para> + + <para>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.</para> + + <section> + <title>Method 1: Using existing feed</title> + <para>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: +<screen>FEED_URIS = " \ + base##http://oe.example.com/releases/${DISTRO_VERSION}/feed/base \ + updates##http://oe.example.com/releases/${DISTRO_VERSION}/feed/updates"</screen> + + 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.</para> + </section> + + <section> + <title>Method 2: Using OE deploy directory as a feed (development only)</title> + <para>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).</para> + <para>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: +<screen> +FEED_DEPLOYDIR_BASE_URI = "http://192.168.2.200/bogofeed" +</screen> + Now you need to setup local HTTP server to actually export that directory. For Apache it can be: +<screen> +<![CDATA[ +Alias /bogofeed ${DEPLOY_DIR} + +<Directory ${DEPLOY_DIR}> + Options Indexes FollowSymLinks + Order deny,allow + Allow from 192.168.2.0/24 +</Directory> +]]> +</screen> + Replace ${DEPLOY_DIR} with the full path of deploy directory (last components of its path will be + <command>deploy/ipk</command>).</para> + <para>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). + </para> + + </section> + + </section> +</section>
\ 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 @@ +<?xml version="1.0" encoding="UTF-8"?> +<section id="pkgconfig_class" xreflabel="pkgconfig class"> + <title>pkgconfig class</title> + + <para>The pkgconfig class is for packages that install + <command><pkg>.pc</command> files. These files provide information + about the build settings for the package vwhich are then made available by + the <command>pkg-config</command> command.</para> + + <para>Since the contents of the <command>.pc</command> 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 <emphasis>stage</emphasis> + task.</para> + + <para>The actions performed by the pkgconfig class are:</para> + + <orderedlist> + <listitem> + <para>Copies the <command><x>.pc</command> files into the + <command>${PKG_CONFIG_PATH}</command> directory;</para> + </listitem> + + <listitem> + <para>If the package is not native then it modifies the contents of the + <command><x>.pc</command> file in the + <command>${PKG_CONFIG_PATH}</command> area to ensure that all the paths + in the script refer to the staging area;</para> + </listitem> + </orderedlist> + + <para>A package is considered to be native if it also inherits the native + class.</para> + + <para>The class will search the source directory, <command>${S}</command>, + and all it's subdirectories, for files that end in <command>.pc</command> + (it will ignore those that end in <command>-uninstalled.pc)</command> and + process them as described above. All that is required to use the class is + the addition of pkgconfig in an inherit statement:<screen>inherit autotools pkgconfig</screen></para> +</section>
\ 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 @@ +<?xml version="1.0" encoding="UTF-8"?> +<section id="rootfs_ipkg_class" xreflabel="rootfs_ipkg class"> + <title>rootfs_ipkg class</title> + + <para>The <emphasis>rootf_ipk</emphasis> 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.</para> + + <para>This class is normally not used directly, but instead used from the + <xref linkend="image_class" /> which creates images from a set of package + (typically <command>.ipkg</command>) files.</para> + + <para>Summary of actions performed by the <emphasis>rootfs_ipkg</emphasis> + class:</para> + + <orderedlist> + <listitem> + <para>Erase any existing root filesystem image by deleting the entire + contents of <command>${IMAGE_ROOTFS}</command>;</para> + </listitem> + + <listitem> + <para>Creates the device node directory, + <command>${IMAGE_ROOTFS}/dev</command>;</para> + </listitem> + + <listitem> + <para>Determines which packages to install in order to provide the + locales that have been requested;</para> + </listitem> + + <listitem> + <para>Configures ipkg to allow it to be used locally to install into the + root filesystem <command>${IMAGE_ROOTFS}</command>;</para> + </listitem> + + <listitem> + <para>Installs locale related .ipkg packages;</para> + </listitem> + + <listitem> + <para>Installs the list of requested <command>.ipkg</command> packages, + <command>${IPKG_INSTALL}</command>;</para> + </listitem> + + <listitem> + <para>Creates ipkg's arch.conf as + <command>${IMAGE_ROOTFS}/etc/ipkg/arch.conf</command>;</para> + </listitem> + + <listitem> + <para>Runs any preinst and postinst scripts that were specified by the + installed .ipkg packages;</para> + </listitem> + + <listitem> + <para>Creates the system configuration directory + <command>${IMAGE_ROOTFS}/${sysconfdir}</command> (that is the + <command>/etc</command> directory on the target);</para> + </listitem> + + <listitem> + <para>Runs and custom post-processing commands, as described by + <command>${ROOTFS_POSTPROCESS_COMMAND}</command>;</para> + </listitem> + + <listitem> + <para>Verifies that all the ipkg's were installed correctly and reports + an error if they were not;</para> + </listitem> + + <listitem> + <para>Makes available a set of functions which may be used by callers of + the class: <command>zap_root_password</command>, + <command>create_etc_timestamp</command> and + <command>remove_init_link</command>;</para> + </listitem> + + <listitem> + <para>Adds the rootfs task to run after the <emphasis>install</emphasis> + task <command>"addtask rootfs before do_build and + do_install"</command>.</para> + </listitem> + </orderedlist> + + <para>The following variables may be used to control some of the behaviour + of this class:</para> + + <variablelist> + <varlistentry> + <term>IPKG_INSTALL</term> + + <listitem> + <para>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.</para> + + <para>Default: empty</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>ROOTFS_POSTPROCESS_COMMAND</term> + + <listitem> + <para>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 <command>zImage</command> kernel image + or to edit the ipkg configuration for example.</para> + + <para>Default: empty</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>PACKAGE_ARCH</term> + + <listitem> + <para>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.</para> + + <para>Default: <command>"all any noarch ${TARGET_ARCH} + ${PACKAGE_EXTRA_ARCHS} ${MACHINE}"</command></para> + </listitem> + </varlistentry> + + <varlistentry> + <term>IMAGE_LINGUAS</term> + + <listitem> + <para>Specifies which locales should be installed. This is often set + to <command>""</command> to indicate that no locales will be + installed.</para> + + <para>Default: <command>"de-de fr-fr en-gb"</command></para> + </listitem> + </varlistentry> + + <varlistentry> + <term>EXTRA_IMAGEDEPENDS</term> + + <listitem> + <para>A list of dependencies, this is appended to + <command>DEPENDS</command>. This is typically used to ensure that any + commands that are called by + <command>ROOTFS_POSTPROCESS_COMMAND</command> are actually built by + the system prior to being called.</para> + + <para>Default: empty</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>BUILDNAME</term> + + <listitem> + <para>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.</para> + + <para>Default: <command>'date +%Y%m%d%H%M'</command></para> + </listitem> + </varlistentry> + + <varlistentry> + <term>IMAGE_ROOTFS</term> + + <listitem> + <para>The path to the root of the filesystem image. You can use this + when you need to explicitly refer to the root filesystem + directory.</para> + + <para>Default: <command>IMAGE_ROOTFS = + "${TMPDIR}/rootfs"</command></para> + </listitem> + </varlistentry> + + <varlistentry> + <term>DEPLOY_DIR</term> + + <listitem> + <para>The base deploy dir. Used to find the directory containing the + ipkg files.</para> + + <para>Default: <command>DEPLOY_DIR = + "${TMPDIR}/deploy"</command></para> + </listitem> + </varlistentry> + + <varlistentry> + <term>DEPLOY_DIR_IPK</term> + + <listitem> + <para>The directory in which to search for the ipkg files that are to + be installed in the root filesystem.</para> + + <para>Default: <command>DEPLOY_DIR_IPK = + "${DEPLOY_DIR}/ipk"</command></para> + </listitem> + </varlistentry> + </variablelist> + + <para>Note that the entire process is run under the control of <xref + linkend="fakeroot" /> in order to handle device files, uids and gids. The + <command>ROOTFS_POSTPROCESS_COMMAND</command> is useful due to the fact that + it runs within the same <xref linkend="fakeroot" /> instance as the rest of + this class.</para> + + <para>The class also provides a function <command>real_do_rootfs</command> + which is executed without <xref linkend="fakeroot" /> and therefore can be + used from other classes, such as <xref linkend="image_class" />, that + are already running under the control of <xref linkend="fakeroot" />.</para> +</section>
\ 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 @@ +<?xml version="1.0" encoding="UTF-8"?> +<section id="siteinfo_class" xreflabel="siteinfo class"> + <title>siteinfo class</title> + + <para>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 <xref linkend="autotools_class" />. Full site + information for your target can be determined by looking at the table in the + class implementation found in the + <command>classes/siteinfo.bbclass</command> file. A typical entry contains + the name of the target and a list of site information for the + target:<screen> "sh4-linux": "endian-little bit-32 common-glibc sh-common",</screen>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 <command>"common"</command> + entry is automatically added to the end of each of the definitions during + processing.</para> + + <para>The class makes available three variables based on the information + provided for a target:</para> + + <variablelist> + <varlistentry> + <term>SITEINFO_ENDIANESS</term> + + <listitem> + <para>Defines the endianess of the target as either + <command>"le"</command> (little endian) or <command>"be"</command> + (big endian). The target must list either + <command>endian-little</command> or <command>endian-big</command> in + it's site information.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>SITEINFO_BITS</term> + + <listitem> + <para>Defines the bitsize of the target as either + <command>"32"</command> or <command>"64"</command>. The target must + list either <command>bit-32</command> or <command>bit-64</command> in + it's site information.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>CONFIG_SITE</term> + + <listitem> + <para>Defines the site files to be used by autoconf. This is a space + separated list of one or more site files for the target.</para> + </listitem> + </varlistentry> + </variablelist> + + <para>A typical use for the <command>SITEINFO_ENDIANESS</command> and + <command>SITEINFO_BITS</command> variables is to provide configuration + within a recipe based on their values. The following example from the + <emphasis>openssl</emphasis> 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 + <command>SITEINFO_ENDIANESS</command> variable. Note that use of the + <emphasis>base_conditional</emphasis> method (see the <xref + linkend="recipes_advanced_python" /> section) to select a value conditional + on the endianess setting:</para> + + <para><screen> # Additional flag based on target endiness (see siteinfo.bbclass) + CFLAG="${CFLAG} ${@base_conditional('SITEINFO_ENDIANESS', 'le', '-DL_ENDIAN', '-DB_ENDIAN', d)}"</screen></para> + + <section> + <title>CONFIG_SITE: The autoconf site files</title> + + <para>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.</para> + + <para>Which site files are used is determined via the + <command>CONFIG_SITE</command> definition which is calculated via the + siteinfo class. Typically the following site files will be checked for, + and used in the order found:</para> + + <variablelist> + <varlistentry> + <term>endian-(big|little)</term> + + <listitem> + <para>Either <command>endian-big</command> or + <command>endian-little</command> 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.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>bit-(32|64)</term> + + <listitem> + <para>Either <command>bit-32</command> or <command>bit-64</command> + 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.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>common-(libc|uclibc)</term> + + <listitem> + <para>Either <command>common-libc</command> or + <command>common-uclibc</command> 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.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><arch>-common</term> + + <listitem> + <para>A common site file for the target architecture. For i386, + i485, i586 and i686 this would be <command>x86-common</command>, for + sh3 and sh4 this would be <command>sh-common</command> and for + various arm targets this would be + <command>arm-common</command>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>common</term> + + <listitem> + <para>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.</para> + </listitem> + </varlistentry> + </variablelist> + + <para>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 <command>CONFIG_SITE</command> variable. The + following directories are checked:</para> + + <variablelist> + <varlistentry> + <term>org.openembedded.dev/packages/<packagename>/site-<version>/</term> + + <listitem> + <para>This directory is for site files which are specific to a + particular version (where version is the PV of the package) of a + package.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>org.openembedded.dev/packages/<packagename>/site/</term> + + <listitem> + <para>This directory is for site files which are specific to a + particular package, but apply to all versions of the package.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>org.openembedded.dev/site/</term> + + <listitem> + <para>This directory is for site files that are common to all + packages. Originally this was the only site file directory that was + supported.</para> + </listitem> + </varlistentry> + </variablelist> + </section> +</section>
\ 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 @@ +<?xml version="1.0" encoding="UTF-8"?> +<section id="update-alternatives_class" xreflabel="update-alternatives class"> + <title>update-alternatives class</title> + + <para>Some commands are available from multiple sources. As an example we + have <command>/bin/sh</command> available from <emphasis>busybox</emphasis> + and from <emphasis>bash</emphasis>. 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.</para> + + <para>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.</para> + + <para>In the following sections we'll use the <command>/bin/ping</command> + command as an example. This command is available as a basic version from + busybox and as a more advanced version from iputils.</para> + + <section> + <title>Naming of the alternative commands</title> + + <para>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.</para> + + <para>For the <command>/bin/ping</command> case this means that neither + busybox nor iputils should actually install a command called + <command>/bin/ping</command>. Instead we see that the iputils recipe + installs it's version of ping as + <command>/bin/ping.iputils</command>:<screen>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} + ... +}</screen></para> + + <para>If you were to look at the busybox recipe you would see that it also + doesn't install a command called <command>/bin/ping</command>, instead it + installs it's command as <command>/bin/busybox</command>.</para> + + <para>The important point to note is that neither package is installing an + actual <command>/bin/ping</command> target command.</para> + </section> + + <section> + <title>How alternatives work</title> + + <para>Before proceeding lets take a look at how alternatives are handled. + If we have a base image that includes only busybox then look at + <command>/bin/ping</command> we see that it is a symlink to + busybox:</para> + + <para><screen>root@titan:/etc# ls -l /bin/ping +lrwxrwxrwx 1 root root 7 May 3 2006 /bin/ping -> busybox</screen></para> + + <para>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.</para> + + <para>If the iputils version of ping is now installed and we look at the + <command>/bin/ping</command> command again we see that it has been changed + to a symlink pointing at the iputils version of ping - + <command>/bin/ping.iptils</command>:</para> + + <para><screen>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</screen></para> + + <para>The iputils version is considered to be the more fully featured + version of ping and is therefore the default when both versions are + installed.</para> + + <para>What happens if the iputils-ping package is removed now? The symlink + should be changed to point back at the busybox version:</para> + + <para><screen>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</screen></para> + + <para>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.</para> + </section> + + <section> + <title>The update-alternatives command</title> + + <para>Available alternatives need to be registered with the alternatives + system. This is handled by the <command>update-alternatives</command> + command. The help from the command shows it's usage options:<screen>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. +</screen></para> + + <para>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.</para> + + <para>The iputils recipe actual codes this directly (rather than using the + class) so we can see an example of the command being called:<screen>pkg_postinst_${PN}-ping () { + update-alternatives --install ${base_bindir}/ping ping ping.${PN} 100 +} +pkg_prerm_${PN}-ping () { + update-alternatives --remove ping ping.${PN} +}</screen></para> + + <para>In both cases the name that the alternatives are registered against, + <command>"ping"</command>, is passed in and the path to the iputils + version of the command, <command>"ping.${PN}"</command>. For the install + case the actual command name (where the symlink will be made from) and a + priority value are also supplied.</para> + </section> + + <section> + <title>Priority of the alternatives</title> + + <para>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:<screen> update-alternatives --install ${base_bindir}/ping ping ping.${PN} 100</screen></para> + + <para>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.</para> + </section> + + <section> + <title>Tracking of the installed alternatives</title> + + <para>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: <screen>root@titan:/etc# cat /usr/lib/ipkg/alternatives/ping +/bin/ping +busybox 50 +ping.iputils 100</screen>If we remove iputils-ping, then we see that + alternatives file is updated to reflect this: <screen>root@titan:/etc# cat /usr/lib/ipkg/alternatives/ping +/bin/ping +busybox 50 +root@titan:/etc#</screen></para> + + <para>The file lists the command first, and then each of the available + alternatives and their relative priorities.</para> + </section> + + <section> + <title>Using the update-alternatives class</title> + + <para>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.</para> + + <para>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:</para> + + <para><screen>inherit autotools update-alternatives + +ALTERNATIVE_NAME = "java" +ALTERNATIVE_PATH = "${bindir}/jamvm" +ALTERNATIVE_LINK = "${bindir}/java" +ALTERNATIVE_PRIORITY = "10" +</screen></para> + + <para>where the variables to be specified are:</para> + + <variablelist> + <varlistentry> + <term>ALTERNATIVE_NAME [Required]</term> + + <listitem> + <para>The name that the alternative is registered against and needs + to be the same for all alternatives registering this command.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>ALTERNATIVE_PATH [Required]</term> + + <listitem> + <para>The path of the installed alternative. (This was iputils.ping + in the example used previously).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>ALTERNATIVE_LINK [Optional]</term> + + <listitem> + <para>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: <command>"${bindir}/${ALTERNATIVE_NAME}"</command></para> + </listitem> + </varlistentry> + + <varlistentry> + <term>ALTERNATIVE_PRIORITY [Optional]</term> + + <listitem> + <para>The priority of this alternative. The alternative with the + highest valued priority will be selected as the default. The default + value is: <command>"10"</command>.</para> + </listitem> + </varlistentry> + </variablelist> + + <para>The actual postinst and postrm commands that are registered by the + class are:<screen>update_alternatives_postinst() { + update-alternatives --install ${ALTERNATIVE_LINK} ${ALTERNATIVE_NAME} ${ALTERNATIVE_PATH} ${ALTERNATIVE_PRIORITY} +} + +update_alternatives_postrm() { + update-alternatives --remove ${ALTERNATIVE_NAME} ${ALTERNATIVE_PATH} +}</screen></para> + </section> +</section>
\ 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 @@ +<?xml version="1.0" encoding="UTF-8"?> +<section id="update-rc-d_class" xreflabel="update-rc.d class"> + <title>update-rc.d class</title> + + <para>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 <command>/etc/init.d</command> that can be + used to start and stop the service.</para> + + <para>The following examples show a service being manually stopped and + started using it's init script:<screen>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#</screen>The update-rc.d class takes care of the following + automatically:</para> + + <orderedlist> + <listitem> + <para>Registers the service with the system during postinst so it will + be automatically started on boot;</para> + </listitem> + + <listitem> + <para>Stops the service during prerm so it will no longer be running + after being removed;</para> + </listitem> + + <listitem> + <para>Unregisters the service during prerm so there will be no attempts + to start the removed service during boot;</para> + </listitem> + + <listitem> + <para>Adds a build and run time dependency on the update-rc.d package + which it uses to register and unregister the services.</para> + </listitem> + </orderedlist> + + <para>Usage is very simple, as shown by this example from dropbear:<screen>INITSCRIPT_NAME = "dropbear" +INITSCRIPT_PARAMS = "defaults 10" + +inherit autotools update-rc.d</screen></para> + + <para>where the variables are:</para> + + <variablelist> + <varlistentry> + <term>INITSCRIPT_NAME</term> + + <listitem> + <para>The name of the init script, which the package will have + installed into /etc/init.d</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>INITSCRIPT_PARAMS</term> + + <listitem> + <para>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.)</para> + </listitem> + </varlistentry> + </variablelist> + + <para>The help from update-rc.d shows show the required parameters:<screen>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#</screen>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.</para> + + <section> + <title>Multiple update-rc.d packages</title> + + <para>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:<screen># 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</screen> The variables that need to be declared + are:</para> + + <variablelist> + <varlistentry> + <term>INITSCRIPT_PACKAGES</term> + + <listitem> + <para>The names of each package which includes an init + script.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>INITSCRIPT_NAME_x</term> + + <listitem> + <para>The same meaning as INITSCRIPT_NAME, but for the package x. + This would be repeated for each package that includes an init + script.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>INITSCRIPT_PARAMS_x</term> + + <listitem> + <para>The same meaning as INITSCRIPT_PARAMS, but for the package x. + This would be repeated for each package that includes an init + script.</para> + </listitem> + </varlistentry> + </variablelist> + </section> +</section>
\ 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 @@ +<?xml version="1.0" encoding="UTF-8"?> +<section id="directories_installation" xreflabel="Installation directories"> + <title>Directories: Installation variables</title> + + <para>The following table provides a list of the variables that are used to + control the directories into which files are installed.</para> + + <para>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:<screen># Indicate that the default files are configuration files +CONFFILES_${PN} = "${sysconfdir}/default/quagga" +CONFFILES_${PN}-watchquagga = "${sysconfdir}/default/watchquagga"</screen></para> + + <para>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, <emphasis role="bold">D</emphasis>. The following + example from the quagga recipe shows some addition files being manually + installed from within the recipe itself:<screen>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</screen></para> + + <informaltable> + <tgroup cols="3"> + <thead> + <row> + <entry>Variable name</entry> + + <entry>Definition</entry> + + <entry>Typical value</entry> + </row> + </thead> + + <tbody> + <row> + <entry>prefix</entry> + + <entry>/usr</entry> + + <entry>/usr</entry> + </row> + + <row> + <entry>base_prefix</entry> + + <entry align="right"><emphasis>(empty)</emphasis></entry> + + <entry align="right"><emphasis>(empty)</emphasis></entry> + </row> + + <row> + <entry>exec_prefix</entry> + + <entry>${base_prefix}</entry> + + <entry align="right"><emphasis>(empty)</emphasis></entry> + </row> + + <row> + <entry>base_bindir</entry> + + <entry>${base_prefix}/bin</entry> + + <entry>/bin</entry> + </row> + + <row> + <entry>base_sbindir</entry> + + <entry>${base_prefix}/sbin</entry> + + <entry>/sbin</entry> + </row> + + <row> + <entry>base_libdir</entry> + + <entry>${base_prefix}/lib</entry> + + <entry>/lib</entry> + </row> + + <row> + <entry>datadir</entry> + + <entry>${prefix}/share</entry> + + <entry>/usr/share</entry> + </row> + + <row> + <entry>sysconfdir</entry> + + <entry>/etc</entry> + + <entry>/etc</entry> + </row> + + <row> + <entry>localstatedir</entry> + + <entry>/var</entry> + + <entry>/var</entry> + </row> + + <row> + <entry>infodir</entry> + + <entry>${datadir}/info</entry> + + <entry>/usr/share/info</entry> + </row> + + <row> + <entry>mandir</entry> + + <entry>${datadir}/man</entry> + + <entry>/usr/share/man</entry> + </row> + + <row> + <entry>docdir</entry> + + <entry>${datadir}/doc</entry> + + <entry>/usr/share/doc</entry> + </row> + + <row> + <entry>servicedir</entry> + + <entry>/srv</entry> + + <entry>/srv</entry> + </row> + + <row> + <entry>bindir</entry> + + <entry>${exec_prefix}/bin</entry> + + <entry>/usr/bin</entry> + </row> + + <row> + <entry>sbindir</entry> + + <entry>${exec_prefix}/sbin</entry> + + <entry>/usr/sbin</entry> + </row> + + <row> + <entry>libexecdir</entry> + + <entry>${exec_prefix}/libexec</entry> + + <entry>/usr/libexec</entry> + </row> + + <row> + <entry>libdir</entry> + + <entry>${exec_prefix}/lib</entry> + + <entry>/usr/lib</entry> + </row> + + <row> + <entry>includedir</entry> + + <entry>${exec_prefix}/include</entry> + + <entry>/usr/include</entry> + </row> + + <row> + <entry>palmtopdir</entry> + <entry>${libdir}/opie</entry> + <entry>/usr/lib/opie</entry> + </row> + + <row> + <entry>palmqtdir</entry> + <entry>${palmtopdir}</entry> + <entry>/usr/lib/opie</entry> + </row> + + </tbody> + </tgroup> + </informaltable> + + <para></para> +</section> 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 @@ +<?xml version="1.0" encoding="UTF-8"?> +<section id="directories_staging" xreflabel="Staging directories"> + <title>Directories: Staging variables</title> + + <para>The following table provides a list of the variables that are used to + control the directories into which files are staged.</para> + + <para>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.</para> + + <para>There are two common situations in which you will need to directly + refer to the staging directories:</para> + + <orderedlist> + <listitem> + <para>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 + <emphasis>configure</emphasis> task.</para> + </listitem> + + <listitem> + <para>In the <emphasis>stage</emphasis> task for libraries to specify + where to install the headers and libraries.</para> + </listitem> + </orderedlist> + + <para>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 <emphasis>oe_libinstall</emphasis> helper function for installation + of the libraries:<screen>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}/ +}</screen></para> + + <para>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:<screen>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"</screen>The following table lists the available + variables for referring to the staging area:</para> + + <informaltable> + <tgroup cols="2"> + <colspec colnum="0" colwidth="1*" /> + + <colspec colnum="1" colwidth="1*" /> + + <thead> + <row> + <entry>Directory</entry> + + <entry>Definition</entry> + </row> + </thead> + + <tbody> + <row> + <entry>STAGING_DIR</entry> + + <entry>${TMPDIR}/staging</entry> + </row> + + <row> + <entry>STAGING_BINDIR</entry> + + <entry>${STAGING_DIR}/${HOST_SYS}/bin</entry> + </row> + + <row> + <entry>STAGING_BINDIR_CROSS</entry> + + <entry>${STAGING_DIR}/${BUILD_SYS}/bin/${HOST_SYS}</entry> + </row> + + <row> + <entry>STAGING_BINDIR_NATIVE</entry> + + <entry>${STAGING_DIR}/${BUILD_SYS}/bin</entry> + </row> + + <row> + <entry>STAGING_LIBDIR</entry> + + <entry>${STAGING_DIR}/${HOST_SYS}/lib</entry> + </row> + + <row> + <entry>STAGING_INCDIR</entry> + + <entry>${STAGING_DIR}/${HOST_SYS}/include</entry> + </row> + + <row> + <entry>STAGING_DATADIR</entry> + + <entry>${STAGING_DIR}/${HOST_SYS}/share</entry> + </row> + + <row> + <entry>STAGING_LOADER_DIR</entry> + + <entry>${STAGING_DIR}/${HOST_SYS}/loader</entry> + </row> + + <row> + <entry>STAGING_FIRMWARE_DIR</entry> + + <entry>${STAGING_DIR}/${HOST_SYS}/firmware</entry> + </row> + + <row> + <entry>STAGING_PYDIR</entry> + + <entry>${STAGING_DIR}/lib/python2.4</entry> + </row> + + <row> + <entry>STAGING_KERNEL_DIR</entry> + + <entry>${STAGING_DIR}/${HOST_SYS}/kernel</entry> + </row> + + <row> + <entry>PKG_CONFIG_PATH</entry> + + <entry>${STAGING_LIBDIR}/pkgconfig</entry> + </row> + + <row> + <entry>QTDIR</entry> + + <entry>${STAGING_DIR}/${HOST_SYS}/qt2</entry> + </row> + + <row> + <entry>QPEDIR</entry> + + <entry>${STAGING_DIR}/${HOST_SYS}</entry> + </row> + + <row> + <entry>OPIEDIR</entry> + + <entry>${STAGING_DIR}/${HOST_SYS}</entry> + </row> + </tbody> + </tgroup> + </informaltable> + + <para></para> + + <para></para> +</section>
\ 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 @@ +<?xml version="1.0" encoding="UTF-8"?> +<section id="fakeroot" xreflabel="fakeroot"> + <title>fakeroot (device node handling)</title> + + <para>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 <xref linkend="rootfs_ipkg_class" /> + for root filesystem creation and by the <xref linkend="image_class" /> + 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.</para> + + <para>In particular fakeroot deals with:</para> + + <itemizedlist> + <listitem> + <para>Device nodes; and</para> + </listitem> + + <listitem> + <para>Ownership and group (uid & gid) management.</para> + </listitem> + </itemizedlist> + + <section> + <title>How fakeroot works</title> + + <para>First of all we'll look at an example of how the fakeroot process + works when used manually.</para> + + <para>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:<screen>~%> mknod hdc b 22 0 +mknod: `hdc': Operation not permitted</screen>Yet the <xref + linkend="image_class" /> is able to create device nodes and include + them in the final images, all without the need to have root + privileges.</para> + + <para>Let's try and create that node again, this time we'll run the + commands from within a fakeroot process:<screen>~%> ./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 +~#></screen>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 + <emphasis>"yes, this file exists and these are it's + properties"</emphasis>. We'll talk more about how fakeroot actually works + in a minute.</para> + + <para>In this case <command>hdc</command> is the cd-rom drive, so let's + try and actually mount the cd-rom:<screen>~#> 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 +~#></screen>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.</para> + + <para>If we exit the fakeroot process and then look at the device node + this is what we see:<screen>~#> exit +~%> ls -l hdc +brw------- 1 user user 22, 0 Aug 18 13:20 hdc +~#></screen></para> + + <para>Note that it isn't a device node at all, just an empty file owned by + the current user!</para> + + <para>So what exactly is fakeroot doing? It's using + <command>LD_PRELOAD</command> 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:</para> + + <orderedlist> + <listitem> + <para>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;</para> + </listitem> + + <listitem> + <para>It remembers the fact that mknod was called by root and it + remembers the properties of the device node;</para> + </listitem> + + <listitem> + <para>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.</para> + </listitem> + </orderedlist> + + <para>When we tried to run mount we received the error <command>"ERROR: + ld.so: object 'libfakeroot.so.0' from LD_PRELOAD cannot be preloaded: + ignored."</command>. This is due to the fact that mount is an suid root + binary, and for security reasons <command>LD_PRELOAD</command> is disabled + on suid binaries.</para> + + <para>There are some very important points to remember when dealing with + fakeroot:</para> + + <orderedlist> + <listitem> + <para>All information regarding devices nodes, uid and gids will be + lost when fakeroot exists;</para> + </listitem> + + <listitem> + <para>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;</para> + </listitem> + + <listitem> + <para>Any suid binaries will not interact with fakeroot;</para> + </listitem> + + <listitem> + <para>Any static binaries will not interact with fakeroot;</para> + </listitem> + </orderedlist> + </section> + + <section> + <title>Root filesystem, images and fakeroot</title> + + <para>Many people have been confused by the generated root filesystem not + containing any valid device nodes. This is in fact the expected + behaviour.</para> + + <para>When you look at a generated root filesystem you'll notice that the + device nodes all appear to be incorrectly created:<screen>~%> 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 +~%></screen>These are empty files and not device nodes at all.</para> + + <para>If we look in the image files generated from that root filesystem + then everything is actually ok:<screen>~%> 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 +~%></screen>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.</para> + + <para><emphasis role="bold">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).</emphasis></para> + </section> + + <section> + <title>Recipes and fakeroot</title> + + <para>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 + <command>do_install</command> method for the <emphasis>install</emphasis> + task:<screen>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} + ...</screen>can be modified to run within a fakeroot environment by + prefixing the method name with fakeroot:<screen><emphasis role="bold">fakeroot</emphasis> 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} + ...</screen></para> + </section> +</section>
\ 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 @@ +<?xml version="1.0" encoding="UTF-8"?> +<section id="image_types" xreflabel="image types"> + <title>Image types</title> + + <para>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 <xref linkend="image_class" /> section for details on how image + generation is configured.</para> + + <para>The final root file system will consist of all of the files located in + image root filesystem directory, <command>${IMAGE_ROOTFS}</command>, which + is usually <command>tmp/rootfs</command> 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 <command>${IMAGE_ROOTFS}</command> directory but they + will be present in any images that are generated. This is due to + <emphasis><xref linkend="fakeroot" /> </emphasis>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 <command>.tar</command> archive, to ensure you have the + correct device nodes and any other special files.</para> + + <section> + <title>Defining images</title> + + <para>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.</para> + + <para>The variables that define an image type are:</para> + + <variablelist> + <varlistentry> + <term>IMAGE_CMD_<type></term> + + <listitem> + <para>Specifies the actual command that is run to generate an image + of the specified type.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>EXTRA_IMAGECMD_<type></term> + + <listitem> + <para>Used to pass additional command line arguments to the + <command>IMAGE_CMD</command> 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 + <command>IMAGE_CMD</command> definition to determine how these + options are being used.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>IMAGE_ROOTFS_SIZE_<type></term> + + <listitem> + <para>For those image types that generate a fixed size image this + variable is used to specify the required image size.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>IMAGE_DEPENDS_<type></term> + + <listitem> + <para>Lists the packages that the <command>IMAGE_CMD</command> + depends on. As an example the jffs2 filesystem creation depends on + <command>mkfs.jffs2</command> command which is part of the mtd + utilities and therefore depends on mtd-utils-native.</para> + </listitem> + </varlistentry> + </variablelist> + </section> + + <section> + <title>Available image types</title> + + <para>The following image types are built in to OpenEmbedded:</para> + + <variablelist> + <varlistentry> + <term>jffs2</term> + + <listitem> + <para>Creates jffs2 <emphasis>"Journaling flash file system + 2"</emphasis> images. This is a read/write, compressed filesystem + for mtd (flash) devices. It is not supported for block + devices.<screen>IMAGE_CMD_jffs2 = "mkfs.jffs2 \ + -x lzo \ + --root=${IMAGE_ROOTFS} \ + --faketime \ + --output=${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.jffs2 \ + ${EXTRA_IMAGECMD}"</screen></para> + + <para>The <command>EXTRA_IMAGECMD</command> variable for jffs2 + passed to <command>mkfs.jffs2</command> and is left empty by + default:<screen>EXTRA_IMAGECMD_jffs2 = ""</screen></para> + + <para>This was not always empty, prior to 2007/05/02 the + <command>EXTRA_IMAGECMD</command> variable for jffs2 was set to + enable padding, to define the endianess and to specify the block + size:<screen><emphasis>EXTRA_IMAGECMD_jffs2 = "--pad --little-endian --eraseblock=0x40000"</emphasis></screen></para> + </listitem> + </varlistentry> + + <varlistentry> + <term>cramfs</term> + + <listitem> + <para>Creates cramfs <emphasis>"Compression ROM file + system"</emphasis> 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.<screen>IMAGE_CMD_cramfs = "mkcramfs ${IMAGE_ROOTFS} \ + ${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.cramfs \ + ${EXTRA_IMAGECMD}"</screen></para> + + <para>The <command>EXTRA_IMAGECMD</command> variable for cramfs is + passed to <command>mkcramfs</command> and is left empty by + default:<screen>EXTRA_IMAGECMD_cramfs = ""</screen></para> + </listitem> + </varlistentry> + + <varlistentry> + <term>ext2</term> + + <listitem> + <para>Creates an <emphasis>"Extended Filesystem 2"</emphasis> image + file. This is the standard Linux non-journaling file system.<screen>IMAGE_CMD_ext2 = "genext2fs -b ${IMAGE_ROOTFS_SIZE} \ + -d ${IMAGE_ROOTFS} \ + ${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.ext2 \ + ${EXTRA_IMAGECMD}"</screen></para> + + <para>The <command>EXTRA_IMAGECMD</command> variable for ext2 is + passed to <command>genext2fs</command> and is left empty by + default:<screen>EXTRA_IMAGECMD_ext2 = ""</screen></para> + + <para>The <command>IMAGE_ROOTS_SIZE</command> variable is used to + specify the size of the ext2 image and is set to 64k by + default:<screen>IMAGE_ROOTFS_SIZE_ext2 = "65536"</screen></para> + </listitem> + </varlistentry> + + <varlistentry> + <term>ext3</term> + + <listitem> + <para>Creates an <emphasis>"Extended Filesystem 3"</emphasis> image + file. This is the standard Linux journaling file system.<screen>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"</screen></para> + + <para>The <command>EXTRA_IMAGECMD</command> variable for ext3 is + passed to <command>genext2fs</command> and is left empty by + default:<screen>EXTRA_IMAGECMD_ext3 = ""</screen></para> + + <para>The <command>IMAGE_ROOTS_SIZE</command> variable is used to + specify the size of the ext3 image and is set to 64k by + default:<screen>IMAGE_ROOTFS_SIZE_ext3 = "65536"</screen></para> + </listitem> + </varlistentry> + + <varlistentry> + <term>ext2.gz</term> + + <listitem> + <para>Creates a version of the ext2 filesystem image compressed with + <command>gzip</command>.</para> + + <para><screen>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"</screen></para> + + <para>The <command>EXTRA_IMAGECMD</command> variable for ext2.gz is + passed to <command>genext2fs</command> and is left empty by + default:<screen>EXTRA_IMAGECMD_ext2.gz = ""</screen></para> + + <para>The <command>IMAGE_ROOTS_SIZE</command> variable is used to + specify the size of the ext2 image and is set to 64k by + default:</para> + + <para><screen>IMAGE_ROOTFS_SIZE_ext2.gz = "65536"</screen></para> + </listitem> + </varlistentry> + + <varlistentry> + <term>ext3.gz</term> + + <listitem> + <para>Creates a version of the ext3 filesystem image compressed with + <command>gzip</command>.</para> + + <para><screen>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"</screen></para> + + <para>The <command>EXTRA_IMAGECMD</command> variable for ext3.gz is + passed to <command>genext2fs</command> and is left empty by + default:<screen>EXTRA_IMAGECMD_ext3.gz = ""</screen></para> + + <para>The <command>IMAGE_ROOTS_SIZE</command> variable is used to + specify the size of the ext2 image and is set to 64k by + default:</para> + + <para><screen>IMAGE_ROOTFS_SIZE_ext3.gz = "65536"</screen></para> + </listitem> + </varlistentry> + + <varlistentry> + <term>squashfs</term> + + <listitem> + <para>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.</para> + + <para>Squashfs uses gzip as its compression method.</para> + + <para><screen>IMAGE_CMD_squashfs = "mksquashfs ${IMAGE_ROOTFS} \ + ${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.squashfs \ + ${EXTRA_IMAGECMD} -noappend"</screen></para> + + <para>The <command>EXTRA_IMAGECMD</command> variable for squashfs is + passed to <command>mksquashfs</command> and is left empty by + default:<screen>EXTRA_IMAGECMD_squashfs = ""</screen></para> + + <para>This was not always empty, prior to 2007/05/02 the + <command>EXTRA_IMAGECMD</command> variable for squashfs specified + the endianess and block size of the filesystem:<screen><emphasis>EXTRA_IMAGECMD_squashfs = "-le -b 16384"</emphasis></screen></para> + </listitem> + </varlistentry> + + <varlistentry> + <term>squashfs-lzma</term> + + <listitem> + <para>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.</para> + + <para>Squashfs-lzma uses lzma as its compression method.</para> + + <para><screen>IMAGE_CMD_squashfs-lzma = "mksquashfs-lzma ${IMAGE_ROOTFS} \ + ${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.squashfs \ + ${EXTRA_IMAGECMD} -noappend"</screen></para> + + <para>The <command>EXTRA_IMAGECMD</command> variable for squashfs is + passed to <command>mksquashfs-lzma</command> and is left empty by + default:<screen>EXTRA_IMAGECMD_squashfs-lzma = ""</screen></para> + + <para>This was not always empty, prior to 2007/05/02 the + <command>EXTRA_IMAGECMD</command> variable for squashfs specified + the endianess and block size of the filesystem:<screen><emphasis>EXTRA_IMAGECMD_squashfs-lzma = "-le -b 16384"</emphasis></screen></para> + </listitem> + </varlistentry> + + <varlistentry> + <term>tar</term> + + <listitem> + <para>Creates a .tar archive.</para> + + <para><screen>IMAGE_CMD_tar = "cd ${IMAGE_ROOTFS} && \ + tar -cvf ${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.tar ."</screen></para> + + <para>The <command>EXTRA_IMAGECMD</command> variable in not + supported for tar images.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>tar.gz</term> + + <listitem> + <para>Creates a <command>gzip</command> compressed .tar + archive.</para> + + <para><screen>IMAGE_CMD_tar.gz = "cd ${IMAGE_ROOTFS} && \ + tar -zcvf ${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.tar.gz ."</screen></para> + + <para>The <command>EXTRA_IMAGECMD</command> variable in not + supported for .tar.gz images.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>tar.bz2</term> + + <listitem> + <para>Creates a <command>bzip2</command> compressed .tar + archive.</para> + + <para><screen>IMAGE_CMD_tar.bz2 = "cd ${IMAGE_ROOTFS} && \ + tar -jcvf ${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.tar.bz2 ."</screen></para> + + <para>The <command>EXTRA_IMAGECMD</command> variable in not + supported for tar.bz2 images.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>cpio</term> + + <listitem> + <para>Creates a .cpio archive:<screen>IMAGE_CMD_cpio = "cd ${IMAGE_ROOTFS} && \ + (find . | cpio -o -H newc >${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.cpio)"</screen></para> + + <para>The <command>EXTRA_IMAGECMD</command> variable in not + supported for cpio images.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>cpio.gz</term> + + <listitem> + <para>Creates a <command>gzip</command> compressed .cpio + archive.<screen>IMAGE_CMD_cpio.gz = cd ${IMAGE_ROOTFS} && \ + (find . | cpio -o -H newc | gzip -c -9 >${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.cpio.gz)"</screen></para> + + <para>The <command>EXTRA_IMAGECMD</command> variable in not + supported for cpio.gz images.</para> + </listitem> + </varlistentry> + </variablelist> + + <para>The above built in list of image types is defined in the bitbake + configuration file: + <command>org.openembedded.dev/conf/bitbake.conf</command>.</para> + </section> + + <section> + <title>Custom image types</title> + + <para>Custom image types can be created by defining the + <command>IMAGE_CMD</command> variable, and optionally the + <command>EXTRA_IMAGECMD</command>, <command>IMAGE_ROOTFS_SIZE</command> + and <command>IMAGE_DEPENDS</command> variables, for your new image + type.</para> + + <para>An example can be found in + <command>conf/machine/wrt54.conf</command> where it defines a new image + type, <emphasis>squashfs-lzma</emphasis>, 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):<screen>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"</screen></para> + </section> +</section> 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 @@ +<?xml version="1.0" encoding="UTF-8"?> +<section id="section_variable" xreflabel="SECTION variable"> + <title>SECTION variable: Package category</title> + + <para>Sections are a means for categorising packages into related groups to + enable users to find packages easier. The <command>SECTION</command> + 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.</para> + + <para>The default values for the section variables are:</para> + + <itemizedlist> + <listitem> + <para><command>SECTION = "base"</command></para> + </listitem> + + <listitem> + <para><command>SECTION_${PN}-doc = "doc"</command></para> + </listitem> + + <listitem> + <para><command>SECTION_${PN}-dev = "devel"</command></para> + </listitem> + </itemizedlist> + + <para>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.</para> + + <para>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.</para> + + <informaltable> + <tgroup cols="2"> + <colspec colwidth="1*" /> + + <colspec colwidth="3*" /> + + <tbody> + <row> + <entry>Section</entry> + + <entry>Description</entry> + </row> + + <row> + <entry>admin</entry> + + <entry></entry> + </row> + + <row> + <entry>base</entry> + + <entry>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.</entry> + </row> + + <row> + <entry>base/shell</entry> + + <entry>Shells such as bash, tcsh, ksh etc.</entry> + </row> + + <row> + <entry>bootloaders</entry> + + <entry>Bootloaders, which are the applications responsible for + loading the kernel from the appropriate location (disk, flash, + network, etc.) and starting it running.</entry> + </row> + + <row> + <entry>console</entry> + + <entry>Applications which run on the console. These require no GUI + related libraries or interfaces to run.</entry> + </row> + + <row> + <entry>console/editors</entry> + + <entry></entry> + </row> + + <row> + <entry>console/games</entry> + + <entry></entry> + </row> + + <row> + <entry>console/multimedia</entry> + + <entry></entry> + </row> + + <row> + <entry>console/network</entry> + + <entry></entry> + </row> + + <row> + <entry>console/scientific</entry> + + <entry></entry> + </row> + + <row> + <entry>console/telephony</entry> + + <entry></entry> + </row> + + <row> + <entry>console/tools</entry> + + <entry></entry> + </row> + + <row> + <entry>console/utils</entry> + + <entry></entry> + </row> + + <row> + <entry>devel</entry> + + <entry>Development related files. These include compilers, + libraries, headers, debuggers etc.</entry> + </row> + + <row> + <entry>devel/libs</entry> + + <entry></entry> + </row> + + <row> + <entry>devel/perl</entry> + + <entry></entry> + </row> + + <row> + <entry>devel/python</entry> + + <entry></entry> + </row> + + <row> + <entry>devel/rexx</entry> + + <entry></entry> + </row> + + <row> + <entry>devel/ruby</entry> + + <entry></entry> + </row> + + <row> + <entry>devel/scheme</entry> + + <entry></entry> + </row> + + <row> + <entry>devel/tcltk</entry> + + <entry></entry> + </row> + + <row> + <entry>doc</entry> + + <entry>Documentation, including man pages and sample configuration + files.</entry> + </row> + + <row> + <entry>e/apps</entry> + + <entry></entry> + </row> + + <row> + <entry>e/libs</entry> + + <entry></entry> + </row> + + <row> + <entry>e/utils</entry> + + <entry></entry> + </row> + + <row> + <entry>fonts</entry> + + <entry>Fonts that are not X11 or OPIE specific such as truetype + fonts.</entry> + </row> + + <row> + <entry>games</entry> + + <entry>Games.</entry> + </row> + + <row> + <entry>games/arcade</entry> + + <entry></entry> + </row> + + <row> + <entry>gpe</entry> + + <entry>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.</entry> + </row> + + <row> + <entry>gpe/applications</entry> + + <entry></entry> + </row> + + <row> + <entry>gpe/base</entry> + + <entry></entry> + </row> + + <row> + <entry>gpe/games</entry> + + <entry></entry> + </row> + + <row> + <entry>gpe/libs</entry> + + <entry>GPE runtime libraries. This does not include libraries used + for development - they should be included in the appropriate devel + section.</entry> + </row> + + <row> + <entry>gpe/multimedia</entry> + + <entry></entry> + </row> + + <row> + <entry>inputmethods</entry> + + <entry>inputmethods that are neither libs, nor solely for GPE/Opie or the console</entry> + </row> + + <row> + <entry>interpreters</entry> + + <entry></entry> + </row> + + <row> + <entry>kde</entry> + + <entry>KDE related applications.</entry> + </row> + + <row> + <entry>kde/devel</entry> + + <entry></entry> + </row> + + <row> + <entry>kernel</entry> + + <entry>Linux kernels.</entry> + </row> + + <row> + <entry>kernel/modules</entry> + + <entry>Linux kernel modules. This include out-of-tree kernel + modules.</entry> + </row> + + <row> + <entry>kernel/userland</entry> + + <entry></entry> + </row> + + <row> + <entry>libs</entry> + + <entry>Runtime libraries. This does not include libraries used for + development - they should be included in the appropriate devel + section.</entry> + </row> + + <row> + <entry>libs/inputmethods</entry> + + <entry></entry> + </row> + + <row> + <entry>libs/multimedia</entry> + + <entry></entry> + </row> + + <row> + <entry>libs/network</entry> + + <entry></entry> + </row> + + <row> + <entry>network</entry> + + <entry></entry> + </row> + + <row> + <entry>network/cms</entry> + + <entry></entry> + </row> + + <row> + <entry>network/misc</entry> + + <entry></entry> + </row> + + <row> + <entry>openmoko</entry> + + <entry>Anything related to openmoko.org</entry> + </row> + + <row> + <entry>openmoko/applications</entry> + + <entry></entry> + </row> + + <row> + <entry>openmoko/base</entry> + + <entry></entry> + </row> + + <row> + <entry>openmoko/examples</entry> + + <entry></entry> + </row> + + <row> + <entry>openmoko/libs</entry> + + <entry></entry> + </row> + + <row> + <entry>openmoko/pim</entry> + + <entry></entry> + </row> + + <row> + <entry>openmoko/tools</entry> + + <entry></entry> + </row> + + <row> + <entry>opie</entry> + + <entry>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.</entry> + </row> + + <row> + <entry>opie/applets</entry> + + <entry></entry> + </row> + + <row> + <entry>opie/applications</entry> + + <entry></entry> + </row> + + <row> + <entry>opie/base</entry> + + <entry></entry> + </row> + + <row> + <entry>opie/codecs</entry> + + <entry></entry> + </row> + + <row> + <entry>opie/datebook</entry> + + <entry></entry> + </row> + + <row> + <entry>opie/decorations</entry> + + <entry></entry> + </row> + + <row> + <entry>opie/fontfactories</entry> + + <entry></entry> + </row> + + <row> + <entry>opie/fonts</entry> + + <entry>OPIE specific fonts. General fonts, such as truetype fonts, + should be in the fonts section.</entry> + </row> + + <row> + <entry>opie/games</entry> + + <entry></entry> + </row> + + <row> + <entry>opie/help</entry> + + <entry></entry> + </row> + + <row> + <entry>opie/inputmethods</entry> + + <entry></entry> + </row> + + <row> + <entry>opie/libs</entry> + + <entry>OPIE runtime libraries. This does not include libraries used + for development - they should be included in the appropriate devel + section.</entry> + </row> + + <row> + <entry>opie/multimedia</entry> + + <entry></entry> + </row> + + <row> + <entry>opie/network</entry> + + <entry></entry> + </row> + + <row> + <entry>opie/pim</entry> + + <entry></entry> + </row> + + <row> + <entry>opie/security</entry> + + <entry></entry> + </row> + + <row> + <entry>opie/settings</entry> + + <entry></entry> + </row> + + <row> + <entry>opie/shell</entry> + + <entry></entry> + </row> + + <row> + <entry>opie/styles</entry> + + <entry></entry> + </row> + + <row> + <entry>opie/today</entry> + + <entry></entry> + </row> + + <row> + <entry>utils</entry> + + <entry></entry> + </row> + + <row> + <entry>x11</entry> + + <entry>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.</entry> + </row> + + <row> + <entry>x11/applications</entry> + + <entry>General applications.</entry> + </row> + + <row> + <entry>x11/base</entry> + + <entry>Core X11 applications.</entry> + </row> + + <row> + <entry>x11/data</entry> + + <entry></entry> + </row> + + <row> + <entry>x11/fonts</entry> + + <entry>X11 specific fonts. General fonts, such as truetype fonts, + should be in the fonts section.</entry> + </row> + + <row> + <entry>x11/games</entry> + + <entry>Games.</entry> + </row> + + <row> + <entry>x11/gnome</entry> + + <entry>Core gnome applications.</entry> + </row> + + <row> + <entry>x11/gnome/libs</entry> + + <entry>Gnome runtime libraries. This does not include libraries used + for development - they should be included in the appropriate devel + section.</entry> + </row> + + <row> + <entry>x11/graphics</entry> + + <entry>Applications which manipulate, display, edit, print etc. + images, photos, diagrams etc.</entry> + </row> + + <row> + <entry>x11/libs</entry> + + <entry>X11 runtime libraries. This does not include libraries used + for development - they should be included in the appropriate devel + section.</entry> + </row> + + <row> + <entry>x11/multimedia</entry> + + <entry>Multimedia applications.</entry> + </row> + + <row> + <entry>x11/network</entry> + + <entry></entry> + </row> + + <row> + <entry>x11/office</entry> + + <entry>Office and productivity applications.</entry> + </row> + + <row> + <entry>x11/scientific</entry> + + <entry>Scientific applications.</entry> + </row> + + <row> + <entry>x11/utils</entry> + + <entry></entry> + </row> + + <row> + <entry>x11/wm</entry> + + <entry>Window managers.</entry> + </row> + </tbody> + </tgroup> + </informaltable> + + <para>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.</para> + + <informaltable> + <tgroup cols="2"> + <colspec colwidth="1*" /> + + <colspec colwidth="3*" /> + + <tbody> + <row> + <entry>Section</entry> + + <entry>Action</entry> + </row> + + <row> + <entry>apps</entry> + + <entry>Replace with appropriate section</entry> + </row> + + <row> + <entry>gui</entry> + + <entry>Replace with appropriate section</entry> + </row> + + <row> + <entry>media-gfx</entry> + + <entry>Replace with appropriate section</entry> + </row> + + <row> + <entry>multimedia</entry> + + <entry>Replace with appropriate section</entry> + </row> + + <row> + <entry>net</entry> + + <entry>Replace with network</entry> + </row> + + <row> + <entry>unknown</entry> + + <entry>Replace with appropriate section</entry> + </row> + + <row> + <entry>x11-misc</entry> + + <entry>Replace with appropriate section</entry> + </row> + </tbody> + </tgroup> + </informaltable> + + <para></para> +</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 @@ +<?xml version="1.0" encoding="UTF-8"?> +<section id="src_uri_variable" xreflabel="SRC_URI variable"> + <title>SRC_URI variable: Source code and patches</title> + + <para>All recipies need to contain a definition of + <command>SRC_URI</command>. 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.</para> + + <para>A typical <command>SRC_URI</command> contains a list of URL's, patches + and files as shown in this example from quagga:<screen>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"</screen>All source code and files will + be placed into the work directory, <command>${WORKDIR}</command>, for the + package. All patches will be placed into a <command>patches</command> + subdirectory of the package source directory, <command>${S}</command>, and + then automatically applied to the source.</para> + + <para>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, + <command>${DL_DIR}</command>, 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.</para> + + <para>Each URI supports a set of additional options. These options are + tag/value pairs of the form <command>"a=b"</command> 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:<screen>file://ospfd-no-opaque-lsa-fix.patch;patch=1;pnum=2</screen>The + supported methods for fetching source and files are:</para> + + <variablelist> + <varlistentry> + <term>http, https, ftps</term> + + <listitem> + <para>Used to download files and source code via the specified URL. + These are fetched from the specified location using wget.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>file</term> + + <listitem> + <para>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.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>cvs</term> + + <listitem> + <para>Used to download from a CVS repository.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>svn</term> + + <listitem> + <para>Used to download from a subversion repository.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>git</term> + + <listitem> + <para>Used to download from a git repository.</para> + </listitem> + </varlistentry> + </variablelist> + + <para>When source code is specified as a part of <command>SRC_URI</command> + it is unpacked into the work directory, <command>${WORKDIR}</command>. 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:</para> + + <variablelist> + <varlistentry> + <term>.tar</term> + + <listitem> + <para>Tar archives which will be extracted with <command>"tar x + --no-same-owner -f <srcfile>"</command>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>.tgz, .tar.gz, tar.Z</term> + + <listitem> + <para>Gzip compressed tar archives which will be extracted with + <command>"tar xz --no-same-owner -f <srcfile>"</command>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>.tbz, .tar.bz2</term> + + <listitem> + <para>Bzip2 compressed tar archives which will be extracted with + <command>"bzip2 -dc <srcfile> | tar x --no-same-owner -f + -"</command>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>.gz, .Z, .z</term> + + <listitem> + <para>Gzip compressed files which will be decompressed with + <command>"gzip -dc <srcfile> > + <dstfile>"</command>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>.bz2</term> + + <listitem> + <para>Bzip2 compressed files which will be decompressed with + <command>"bzip2 -dc <srcfile> > + <dstfile>"</command>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>.zip</term> + + <listitem> + <para>Zip archives which will be extracted with <command>"unzip -q + <srcfile>"</command>.</para> + </listitem> + </varlistentry> + </variablelist> + + <para>The downloading of the source files occurs in the + <emphasis>fetch</emphasis> task, the unpacking and copying to the work + directory occurs in the <emphasis>unpack</emphasis> task and the applying of + patches occurs in the <emphasis>patch</emphasis> task.</para> + + <section> + <title>http/https/ftp (wget)</title> + + <para>The wget fetcher handles http, https and ftp URLs.<screen>http://www.quagga.net/download/quagga-${PV}.tar.gz</screen></para> + + <para>Supported options:</para> + + <variablelist> + <varlistentry> + <term>md5sum</term> + + <listitem> + <para>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.</para> + </listitem> + </varlistentry> + </variablelist> + + <para>Related variables:</para> + + <variablelist> + <varlistentry> + <term>MIRRORS</term> + + <listitem> + <para>Mirrors define alternative locations to download source files + from. See the mirror section below for more information.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>DL_DIR</term> + + <listitem> + <para>The downloaded files will be placed in this directory with the + name exactly as supplied via the URI.</para> + </listitem> + </varlistentry> + </variablelist> + </section> + + <section> + <title>file: for patches and additional files</title> + + <para>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.</para> + + <para>The following example shows the specification of a patch + file:<screen>file://ospfd-no-opaque-lsa-fix.patch;patch=1</screen></para> + + <para>Patch files are be copied to the patches subdirectory of the source + directory, <command>${S}/patches</command>, and then applied from the + source directory. The patches are searched for along the path specified + via the file path variable, <command>${FILESPATH},</command> and if not + found the directory specified by the file directory variable, + <command>${FILEDIR}</command>, is also checked.</para> + + <para>The following example shows the specification of a non-patch file. + In this case it's an init script:<screen>file://quagga.init</screen>Non-patch + files are copied to the work directory, <command>${WORKDIR}</command>. 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 <emphasis>install</emphasis> task:<screen>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 <emphasis role="bold">${WORKDIR}/quagga.init</emphasis> ${D}${sysconfdir}/init.d/quagga +...</screen></para> + + <para>Supported options:</para> + + <variablelist> + <varlistentry> + <term>patch</term> + + <listitem> + <para>Used as <command>"patch=1"</command> to define this file as a + patch file. Patch files will be copied to + <command>${S}/patches</command> and then applied to source from + within the source directory, <command>${S}</command>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>pnum</term> + + <listitem> + <para>By default patches are applied with the <command>"-p + 1"</command> parameter, which strips off the first directory of the + pathname in the patches. This option is used to explicitly control + the value passed to <command>"-p"</command>. The most typical use is + when the patches are relative to the source directory already and + need to be applied using <command>"-p 0"</command>, in which case + the <command>"pnum=0"</command> option is supplied.</para> + </listitem> + </varlistentry> + </variablelist> + </section> + + <section> + <title>cvs</title> + + <para>The cvs fetcher is used to retrieve files from a CVS repository. + <screen> cvs://anonymous@cvs.sourceforge.net/cvsroot/linuxsh;module=linux;date=20051111</screen>A + cvs URI will retrieve the source from a cvs repository. Note that use of + the <emphasis>date=</emphasis> to specify a checkout for specified date. + It is preferable to use either a <emphasis>date=</emphasis> or a + <emphasis>tag=</emphasis> option to select a specific date and/or tag from + cvs rather than leave the checkout floating at the head revision.</para> + + <para>Supported options:</para> + + <variablelist> + <varlistentry> + <term>module</term> + + <listitem> + <para>The name of a module to retrieve. This is a required parameter + and there is no default value.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>tag</term> + + <listitem> + <para>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.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>date</term> + + <listitem> + <para>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 <command>"YYYYMMDD"</command>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>method</term> + + <listitem> + <para>The method used to access the repository. Common options are + <command>"pserver"</command> and <command>"ext"</command> (for cvs + over rsh or ssh). The default is + <command>"pserver"</command>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>rsh</term> + + <listitem> + <para>The rsh command to use with the <command>"ext"</command> + method. Common options are <command>"rsh"</command> or + <command>"ssh"</command>. The default is + <command>"rsh"</command>.</para> + </listitem> + </varlistentry> + </variablelist> + + <para>Related variables:<variablelist> + <varlistentry> + <term>CVS_TARBALL_STASH</term> + + <listitem> + <para>Used to specifies a location to search for pre-generated tar + archives to use instead of accessing cvs directly.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>CVSDIR</term> + + <listitem> + <para>The directory in which the cvs checkouts will be performed. + The default is <command>${DL_DIR}/cvs</command>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>DL_DIR</term> + + <listitem> + <para>A compressed tar archive of the retrieved files will be + placed in this directory. The archive name will be of the form: + <command>"<module>_<host>_<tag>_<date>.tar.gz"</command>. + Path separators in <command>module</command> will be replaced with + full stops.</para> + </listitem> + </varlistentry> + </variablelist></para> + </section> + + <section> + <title>svn</title> + + <para>The svn fetcher is used to retrieve files from a subversion + repository.</para> + + <para><screen> svn://svn.xiph.org/trunk;module=Tremor;rev=4573;proto=http</screen></para> + + <para>Supported options:</para> + + <variablelist> + <varlistentry> + <term>module</term> + + <listitem> + <para>The name of a module to retrieve. This is a required parameter + and there is no default value.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>rev</term> + + <listitem> + <para>The revision to retrieve. Revisions in subversion are integer + values.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>proto</term> + + <listitem> + <para>The method to use to access the repository. Common options are + <command>"svn"</command>, <command>"svn+ssh"</command>, + <command>"http"</command> and <command>"https"</command>. The + default is <command>"svn"</command>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>rsh</term> + + <listitem> + <para>The rsh command to use with using the + <command>"svn+ssh"</command> method. Common options are + <command>"rsh"</command> or <command>"ssh"</command>. The default is + <command>"ssh"</command>.</para> + </listitem> + </varlistentry> + </variablelist> + + <para>Related variables:<variablelist> + <varlistentry> + <term>SVNDIR</term> + + <listitem> + <para>The directory in which the svn checkouts will be performed.. + The default is <command>${DL_DIR}/svn</command>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>DL_DIR</term> + + <listitem> + <para>A compressed tar archive of the retrieved files will be + placed in this directory. The archive name will be of the form: + <command>"<module>_<host>_<path>_<revn>_<date>.tar.gz"</command>. + Path separators in <command>path</command> and + <command>module</command> will be replaced with full stops.</para> + </listitem> + </varlistentry> + </variablelist></para> + </section> + + <section> + <title>git</title> + + <para>The git fetcher is used to retrieve files from a git repository. + <screen> SRC_URI = "git://www.denx.de/git/u-boot.git;protocol=git;tag=${TAG}"</screen></para> + + <para>Supported options:</para> + + <variablelist> + <varlistentry> + <term>tag</term> + + <listitem> + <para>The tag to retrieve. The default is + <command>"master"</command>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>protocol</term> + + <listitem> + <para>The method to use to access the repository. Common options are + <command>"git"</command> and <command>"rsync"</command>. The default + is <command>"rsync"</command>.</para> + </listitem> + </varlistentry> + </variablelist> + + <para>Related variables</para> + + <para><variablelist> + <varlistentry> + <term>GITDIR</term> + + <listitem> + <para>The directory in which the git checkouts will be performed. + The default is <command>${DL_DIR}/git</command>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>DL_DIR</term> + + <listitem> + <para>A compressed tar archive of the retrieved files will be + placed in this directory. The archive name will be of the form: + <command>"git_<host><mpath>_<tag>.tar.gz"</command>. + Path separators in <command>host</command> will be replaced with + full stops.</para> + </listitem> + </varlistentry> + </variablelist></para> + </section> + + <section> + <title>Mirrors</title> + + <para>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.</para> + + <para>Default mirrors, along with their primary URL, include:</para> + + <variablelist> + <varlistentry> + <term>GNU_MIRROR</term> + + <listitem> + <para>ftp://ftp.gnu.org/gnu</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>DEBIAN_MIRROR</term> + + <listitem> + <para>ftp://ftp.debian.org/debian/pool</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>SOURCEFORGE_MIRROR</term> + + <listitem> + <para>http://heanet.dl.sourceforge.net/sourceforge</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>GPE_MIRROR</term> + + <listitem> + <para>http://handhelds.org/pub/projects/gpe/source</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>XLIBS_MIRROR</term> + + <listitem> + <para>http://xlibs.freedesktop.org/release</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>XORG_MIRROR</term> + + <listitem> + <para>http://xorg.freedesktop.org/releases</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>GNOME_MIRROR</term> + + <listitem> + <para>http://ftp.gnome.org/pub/GNOME/sources</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>FREEBSD_MIRROR</term> + + <listitem> + <para>ftp://ftp.freebsd.org/pub/FreeBSD</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>GENTOO_MIRROR</term> + + <listitem> + <para>http://distro.ibiblio.org/pub/linux/distributions/gentoo/distfiles</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>APACHE_MIRROR</term> + + <listitem> + <para>http://www.apache.org/dist</para> + </listitem> + </varlistentry> + </variablelist> + + <para>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:<screen>SRC_URI = "${SOURCEFORGE_MIRROR}/lex/flex-2.5.31.tar.bz2</screen></para> + + <para>You can manually define your mirrors if you wish to force the use of + a specific mirror by exporting the appropriate mirrors in + <command>local.conf</command> with them set to the local mirror:<screen>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"</screen></para> + + <para>Mirrors can be extended in individual recipes via the use of + <command>MIRRORS_prepend</command> or <command>MIRRORS_append</command>. + 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 + <command>"${GNU_MIRROR}/gcc/"</command> URI:<screen>MIRRORS_prepend () { + ${GNU_MIRROR}/gcc/ http://gcc.get-software.com/releases/ + ${GNU_MIRROR}/gcc/ http://mirrors.rcn.net/pub/sourceware/gcc/releases/ +}</screen></para> + </section> + + <section> + <title>Manipulating SRC_URI</title> + + <para>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 <command>SRC_URI_append</command> and/or + <command>SRC_URI_prepend</command> methods for adding additional URI's + based on the architecture or machine name.</para> + + <para>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 <command>SRC_URI</command>, but only for the + sh4 architecture. For other architectures it is ignored:<screen># Build fails on sh4 unless no-z-defs is defined +SRC_URI_append_sh4 = " file://no-z-defs.patch;patch=1"</screen></para> + </section> + + <section> + <title>Source distribution (src_distribute_local)</title> + + <para>In order to obtain a set of source files for a build you can use the + <emphasis>src_distribute_local</emphasis> 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.</para> + + <para>Enabling this option is as simple as activating the functionality by + including the required class in one of your configuration files:<screen>SRC_DIST_LOCAL = "copy" +INHERIT += "src_distribute_local"</screen></para> + + <para>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, <command>${SRC_DISTRIBUTEDIR}</command>, after + building.</para> + + <para>There are some options available to effect the option</para> + + <variablelist> + <varlistentry> + <term>SRC_DIST_LOCAL</term> + + <listitem> + <para>Specifies if the source files should be copied, symlinked or + moved and symlinked back. The default is + <command>"move+symlink"</command>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>SRC_DISTRIBUTEDIR</term> + + <listitem> + <para>Specifies the source distribution directory - this is why the + source files that was used for the build are placed. The default is + <command>"${DEPLOY_DIR}/sources"</command>.</para> + </listitem> + </varlistentry> + </variablelist> + + <para>The valid values for <command>SRC_DIST_LOCAL</command> are:</para> + + <variablelist> + <varlistentry> + <term>copy</term> + + <listitem> + <para>Copies the files to the downloaded sources directory into the + distribution directory.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>symlink</term> + + <listitem> + <para>Symlinks the files from the downloaded sources directory into + the distribution directory.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>move+symlink</term> + + <listitem> + <para>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.</para> + </listitem> + </varlistentry> + </variablelist> + </section> +</section>
\ No newline at end of file |