diff options
Diffstat (limited to 'usermanual/reference')
| -rw-r--r-- | usermanual/reference/class_autotools.xml | 2 | ||||
| -rw-r--r-- | usermanual/reference/class_binconfig.xml | 2 | ||||
| -rw-r--r-- | usermanual/reference/class_distutils.xml | 2 | ||||
| -rw-r--r-- | usermanual/reference/class_image_ipkg.xml | 280 | ||||
| -rw-r--r-- | usermanual/reference/class_pkgconfig.xml | 2 | ||||
| -rw-r--r-- | usermanual/reference/class_rootfs_ipkg.xml | 216 | ||||
| -rw-r--r-- | usermanual/reference/class_update-alternatives.xml | 2 | ||||
| -rw-r--r-- | usermanual/reference/class_update-rc.d.xml | 2 | ||||
| -rw-r--r-- | usermanual/reference/image_types.xml | 2 |
9 files changed, 503 insertions, 7 deletions
diff --git a/usermanual/reference/class_autotools.xml b/usermanual/reference/class_autotools.xml index fd6c36da8e..a14b6d6ee8 100644 --- a/usermanual/reference/class_autotools.xml +++ b/usermanual/reference/class_autotools.xml @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8"?> -<section> +<section id="autotools_class" xreflabel="autotools class"> <title>autotools class</title> <para>Autotools is one of the most commonly seen configuration methods for diff --git a/usermanual/reference/class_binconfig.xml b/usermanual/reference/class_binconfig.xml index 27eafa16f9..bf6290039d 100644 --- a/usermanual/reference/class_binconfig.xml +++ b/usermanual/reference/class_binconfig.xml @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8"?> -<section> +<section id="binconfig_class" xreflabel="binconfig class"> <title>binconfig class</title> <para>The binconfig class is for packages that install diff --git a/usermanual/reference/class_distutils.xml b/usermanual/reference/class_distutils.xml index 96be6f6884..f2a2ec8957 100644 --- a/usermanual/reference/class_distutils.xml +++ b/usermanual/reference/class_distutils.xml @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8"?> -<section> +<section id="distutils_class" xreflabel="distutils class"> <title>distutils class</title> <para>Distutils is a standard python system for building and installing diff --git a/usermanual/reference/class_image_ipkg.xml b/usermanual/reference/class_image_ipkg.xml new file mode 100644 index 0000000000..c81a76da2f --- /dev/null +++ b/usermanual/reference/class_image_ipkg.xml @@ -0,0 +1,280 @@ +<?xml version="1.0" encoding="UTF-8"?> +<section id="image_ipkg_class" xreflabel="image_ipkg class"> + <title>image_ipkg class</title> + + <para>The image_ipkg class is used to generate images containing a root + filesystem, as generate by the <xref linkend="rootfs_ipkg_class" /> class, + for use on the target device. This could be a <emphasis>jffs2</emphasis> + image to be written into flash on the target device for example. In addition + it also configures the ipkg feeds (where to get updates from) in the root + filesystem and is able to generate multiple different image types.</para> + + <para>Summary of actions performed by the <emphasis>image_ipkg</emphasis> + class:</para> + + <orderedlist> + <listitem> + <para>Inherits the <xref linkend="rootfs_ipkg_class" /> in order to + bring in the functionality required to generate a root filesystem image + from a set of ipkg's that will be suitable for included in the + image(s);</para> + </listitem> + + <listitem> + <para>Sets <command>BUILD_ALL_DEPS = "1"</command> to force 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 determine 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>Call into <xref linkend="rootfs_ipkg_class" /> to install all of + the required components into the root filesystem;</para> + </listitem> + + <listitem> + <para>Configures the ipkg feed information in the root filesystem for + the <command>FEED_URIS</command>;</para> + </listitem> + + <listitem> + <para>Run any image per-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>Run 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 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 /dev 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.</para> + + <para>Default: <command>""</command></para> + </listitem> + </varlistentry> + + <varlistentry> + <term>IMAGE_POSTPROCESS_COMMAND</term> + + <listitem> + <para>Additional commands to run after processing the image.</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 modify existing types and creating new types is + provided in the <xref linkend="image_types" /> section.</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> + </variablelist> + + <section> + <title>Special node handling (fakeroot)</title> + + <para>Special nodes, such as /dev nodes, and files with special + permissions, such as suid files, are handled via the fakeroot system. This + means that when you view the contents of the root filesystem these device + appear to be created incorrectly:</para> + + <para>While these devices do not appear correctly on disk, fakeroot keeps + track of what they should be and when generating images it will provide + the proper files to the commands (such as tar) which are processing the + root filesystem. Note that for this to work all of the commands related to + generating the image must be run under fakeroot. This is the remove for + the IMAGE_PREPROCESS_COMMAND and IMAGE_POSTPROCESS_COMMAND variables - + these variables are processed while still under the fakeroot + process.</para> + </section> + + <section> + <title>Device (/dev) nodes</title> + + <para>There are two variables that can be defined for creating device + nodes. The newer version supports multiple device node tables and searches + for the specified files along ${BBPATH} so that relative file names may be + used.</para> + + <para>The following example from machine/titan.conf 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 /dev/SC{0,1,2} nodes + which are required for the SH processors on board SCI and SCIF + serial ports. On the titan 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 fro creating the /dev/sm0 and + /dev/sm0p{0,1,2} devices nodes for the block driver and associated + partitions that is used to managed the flash on the titan board. + </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 + IMAGE_FSTYPES variable. A full description of the available image types, + options of the images and details on creating new image types is provided + in the <xref linkend="image_types" /> section.</para> + </section> + + <section> + <title>Package feeds (feed_uris)</title> + + <para>Package feeds are used by the ipkg command to determine where to + retrieve updates and new packages from.</para> + + <para>Multiple feeds are support. Each is provided with a feed name and + the URL which will contain the packages. The following example shows the + addition of two feeds, one called <emphasis>base</emphasis> and one called + <emphasis>updates</emphasis>:</para> + + <para><screen>FEED_URIS += " \ + base##http://oe.example.com/releases/${DISTRO_VERSION}/feed/base \ + updates##http://oe.example.com/releases/${DISTRO_VERSION}/feed/updates"</screen></para> + </section> +</section>
\ No newline at end of file diff --git a/usermanual/reference/class_pkgconfig.xml b/usermanual/reference/class_pkgconfig.xml index 9040bc5c44..08df975b84 100644 --- a/usermanual/reference/class_pkgconfig.xml +++ b/usermanual/reference/class_pkgconfig.xml @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8"?> -<section> +<section id="pkgconfig_class" xreflabel="pkgconfig class"> <title>pkgconfig class</title> <para>The pkgconfig class is for packages that install diff --git a/usermanual/reference/class_rootfs_ipkg.xml b/usermanual/reference/class_rootfs_ipkg.xml new file mode 100644 index 0000000000..095c3278be --- /dev/null +++ b/usermanual/reference/class_rootfs_ipkg.xml @@ -0,0 +1,216 @@ +<?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 packages that + would need to be included in the root filesystem of the target + device.</para> + + <para>This class is normally not useddirectly, but instead used from + the<xref linkend="image_ipkg_class" /> which creates disk images from a set + of <command>.ipkg</command> files.</para> + + <para>Summary of actions performed by the <emphasis>rootfs_ipkg</emphasis> + class:</para> + + <orderedlist> + <listitem> + <para>Erase an existing root filesyste 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>Install locale related .ipkg packages;</para> + </listitem> + + <listitem> + <para>Install 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>remote_init_link</command>;</para> + </listitem> + + <listitem> + <para>Adds the rootfs task to run after the do_install 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>IPKG_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} + ${IPKG_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 fakeroot, so + any permissions, special devices files etc will be remember by fakeroot by + lost once the class has completed. This is why the + <command>ROOTFS_POSTPROCESS_COMMAND</command> is useful - it performs it's + actions while under the control of fakeroot. The class also provides a + function real_do_rootfs which is executed without fakeroot - this is used + from other classes, such as <xref linkend="image_ipkg_class" />, to perform + the functionality of this class under the control of it's own fakeroot + process so that it can perform additional actions under the control of + fakeroot in addition to that performed by the rootfs_ipkg class.</para> +</section>
\ No newline at end of file diff --git a/usermanual/reference/class_update-alternatives.xml b/usermanual/reference/class_update-alternatives.xml index 21d2c9c2ca..4e8f64a32d 100644 --- a/usermanual/reference/class_update-alternatives.xml +++ b/usermanual/reference/class_update-alternatives.xml @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8"?> -<section> +<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 diff --git a/usermanual/reference/class_update-rc.d.xml b/usermanual/reference/class_update-rc.d.xml index 11eed9ae4a..c29501fe59 100644 --- a/usermanual/reference/class_update-rc.d.xml +++ b/usermanual/reference/class_update-rc.d.xml @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8"?> -<section> +<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 diff --git a/usermanual/reference/image_types.xml b/usermanual/reference/image_types.xml index 2f6b29849a..3ccfe9c4e0 100644 --- a/usermanual/reference/image_types.xml +++ b/usermanual/reference/image_types.xml @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8"?> -<section> +<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 |