path: root/doc/book-enea-linux-user-guide/doc/using_enea_linux.xml

<?xml version="1.0" encoding="ISO-8859-1"?>
<chapter id="using_enealinux">
  <title>Using Enea Linux</title>

  <section id="build_enealinux">
    <title>Building Enea Linux</title>

    <para>Enea Linux is made available as sources, allowing for the building of
    various Enea Linux artifacts detailed in the following sections.</para>

    <section id="build_images">
      <title>Building the images</title>

      <para>Build Enea Linux images using the following steps:</para>

      <procedure>
        <step>
          <para>Set the $MACHINE/&lt;machine&gt; variable to the target you
          need, e.g. <literal>intel-corei7-64</literal>.</para>
        </step>

        <step>
          <para>Clone Enea Linux sources using Repo tool. Please refer to
          <xref linkend="getting_sources" /> for more details.</para>

          <programlisting>$ mkdir enea-linux
$ cd enea-linux
$ repo init -u git@git.enea.com:linux/manifests/el_manifests-standard.git \
    -b refs/tags/Enea_Linux_8.2 -m $MACHINE/default.xml
$ repo sync</programlisting>
        </step>

        <step>
          <para>Source the build environment</para>

          <programlisting>$ cd poky
$ TEMPLATECONF=meta-el-standard/conf/template.&lt;machine&gt; \
. ./oe-init-build-env &lt;build_dir&gt;</programlisting>

          <para>Sourcing the build environment is needed every time a new shell
          is used. However, sourcing using the <literal>TEMPLATECONF</literal>
          is only needed the first time around. After the first time, it is
          enough to source the build directory created before.</para>

          <note>
            <para>The build directory may reside on an NFS mount, but the
            <literal>TMPDIR</literal>
            (<literal>&lt;build_dir&gt;/tmp</literal>) may not. Either build
            all on a local disk, or update <literal>TMPDIR</literal> in
            <literal>conf/local.conf</literal> to point to a local
            disk.</para>
          </note>
        </step>

        <step>
          <para>Build an Enea Linux image</para>

          <programlisting># You have already initiated the build environment and are in the &lt;build_dir&gt;
$ bitbake &lt;enea-image-name&gt; 
$ cd &lt;build_dir&gt;/tmp/deploy/images/&lt;target&gt;/  # Here are the build binaries</programlisting>

          <note>
            <para>Some builds have restrictions on the length of the path
            name. If you get a build error indicating that the length is too
            long, you need to move your build to obtain a shorter path.</para>
          </note>

          <para>Generated images are by default saved in
          <literal><literal>&lt;build_dir&gt;/tmp/deploy/images/&lt;target&gt;</literal></literal>,
          where <literal>&lt;build_dir&gt;</literal> by default is the current
          working directory. Images are created for emulation on host or for
          booting a physical target, according to how the build environment
          was set up before running bitbake.</para>

          <para>Depending on the number of processors and cores, the amount of
          RAM, the speed of your internet connection and other factors, the
          build process can take several hours the first time you run it.
          Subsequent builds run much faster since parts of the build are
          cached.</para>

          <note>
            <para>Make sure that the user running the build has access to the
            Git repositories on git.enea.com. The build process fetches
            information from git.enea.com so the user running the build shall
            have the ssh key properly configured. Please refer to <xref
            linkend="getting_sources" /> for more details on how to get access
            to Enea Linux sources.</para>
          </note>
        </step>
      </procedure>
    </section>

    <section id="build_sdk">
      <title>Building the SDK</title>

      <para>If you want to rebuild a cross-compilation toolchain to be used by
      in application development, do the following:</para>

      <procedure>
        <step>
          <para>Clone Enea Linux sources using the Repo tool. Please refer to
          <xref linkend="getting_sources" /> for more details on how to do
          this.</para>

          <programlisting>$ mkdir enea-linux
$ cd enea-linux
$ repo init -u git@git.enea.com:linux/manifests/el_manifests-standard.git \
    -b refs/tags/Enea_Linux_8.2 -m $MACHINE/default.xml
$ repo sync</programlisting>
        </step>

        <step>
          <para>Source the build environment</para>

          <programlisting>$ cd poky 
$ TEMPLATECONF=meta-el-standard/conf/template.&lt;machine&gt; \
. ./oe-init-build-env &lt;build_dir&gt;</programlisting>

          <para>Sourcing the build environment is needed everytime a new shell
          is used. However, sourcing using the <literal>TEMPLATECONF</literal>
          is only needed the first time around. Afterwards it is enough to
          source the build directory created before.</para>

          <note>
            <para>The build directory may reside on an NFS mount, but the
            <literal>TMPDIR</literal>
            (<literal>&lt;build_dir&gt;/tmp</literal>) may not. Either build
            all on a local disk, or update <literal>TMPDIR</literal> in 
            <literal>conf/local.conf</literal> to point to a local disk.</para>
          </note>
        </step>

        <step>
          <para>Build an Enea Linux SDK</para>

          <programlisting># You have already initiated the build environment and are in the &lt;build_dir&gt;
$ bitbake &lt;enea-image-name&gt; -c populate_sdk_ext 
$ cd &lt;build_dir&gt;/tmp/deploy/sdk/  # Here is the SDK installer script</programlisting>

          <note>
            <para>Some builds have restrictions on the length of the path
            name. If you get a build error indicating that the length is too
            long, you need to move your build to obtain a shorter path.</para>
          </note>

          <para>The generated SDK installer script is by default saved in
          <literal>&lt;build_dir&gt;/tmp/deploy/sdk</literal>, where
          <literal>&lt;build_dir&gt;</literal> by default is the current
          working directory.</para>

          <para>Depending on the number of processors and cores, the amount of
          RAM, the speed of your internet connection and other factors, the
          build process can take several hours the first time you run it.
          Subsequent builds run much faster since parts of the build are
          cached.</para>

          <para>For more details on how to install and use the SDK, please
          refer to <xref linkend="install_el_sdk" />.</para>
        </step>
      </procedure>
    </section>
  </section>

  <section id="boot_enealinux">
    <title>Booting Enea Linux</title>

    <para>Regardless whether you decide to use the pre-built images or if you
    choose to build your own, the end result should be similar. Once you have
    the artifacts availalbe, you may proceed to booting Enea Linux on
    target.</para>

    <para>Enea Linux supports multiple booting methods which will be
    described in the following sections.</para>

    <section id="enea-linux-x86-pxe">
      <title>Booting via PXE</title>

      <para>Below is an example of how to boot Enea Linux on a target
      supporting PXE. The PXE boot is handled by the target BIOS.</para>

      <para>This requires the setup of DHCP, TFTP and NFS servers on the host.
      The DHCP server contains a configuration for the target, found via the
      target MAC address, and refers to the TFTP server for the boot image and
      to the NFS server for the root file system.</para>

      <para>For the DHCP server, in addition to the general configuration, the
      DHCPD configuration should contain an entry for the target with the
      following information:</para>

      <itemizedlist spacing="compact">
        <listitem>
          <para>Host name.</para>
        </listitem>

        <listitem>
          <para>MAC hardware ethernet address (also available in the TFTP
          configuration).</para>
        </listitem>

        <listitem>
          <para>IP address (assuming a fixed IP address is used).</para>
        </listitem>

        <listitem>
          <para>The TFTP server shall be defined as
          <literal>next-server</literal>.</para>
        </listitem>

        <listitem>
          <para>The relative path in the TFTP server to the PXE file
          <filename>pxelinux.0</filename>.</para>
        </listitem>

        <listitem>
          <para>The NFS server IP address and the path to the rootfs on the
          NFS server, defined as <literal>option root-path</literal>.</para>
        </listitem>
      </itemizedlist>

      <para>Example of a DHCP server configuration:</para>

      <programlisting>host intel-corei7-64_host {
    hardware ethernet 01:00:25:90:c8:c5:98;
    fixed-address     192.168.1.38;
    next-server       192.168.2.10;
    filename          "intel-corei7-64_tftp/pxelinux.0";
    option root-path  "192.168.2.20:/export/intel-corei7-64_rootfs";
}</programlisting>

      <para>For the TFTP server, the TFTP path to the target's <filename>pxelinux.0</filename>
        file is given in the DHCP Configuration. Examples of files included in the
      TFTP subdirectory indicated by the DHCP configuration are:</para>

      <programlisting>pxelinux.0
vesamenu.c32
boot/device01/bzImage                          (bootable image file)
pxelinux.cfg/01-00-25-90-c8-c5-98              (Configuration file)</programlisting>

      <para>One configuration file has the same name as the target's MAC
      address (but with hyphens instead of a colon). This configuration file
      contains a pointer to the bootable image and also a list of command line
      arguments to append when the image is started. The same NFS path to the
      root file system is both in the DHCP and the TFTP configuration.</para>

      <para>Example of a configuration file:</para>

      <programlisting>default vesamenu.c32
prompt 0
timeout 100

label device01
  menu label ^EneaLinuxNFS
  menu default
  kernel boot/device01/bzImage
  <emphasis role="bold">append</emphasis> root=/dev/nfs nfsmount=192.168.2.20:/export/intel-corei7-64_rootfs ip=dhcp
                                                            console=ttyS0,115200</programlisting>

      <para><emphasis role="bold">NFS server</emphasis>: The NFS server shall
      contain an unpacked root file system in the path indicated both in the
      DHCP and in the TFTP configuration.</para>

      <para>After configuring the servers, copy files from the build directory
      into the correctly configured paths:</para>

      <orderedlist spacing="compact">
        <listitem>
          <para>Ensure the target is not already running an OS, otherwise the
          target might attempt to change files on the root file system while
          it is populated with new files.</para>
        </listitem>

        <listitem>
          <para>Copy <filename>pxelinux.0</filename> and
          <filename>vesamenu.c32</filename> from the build directory, e.g.
          from
          <filename>&lt;build_dir&gt;tmp/work/corei7-64-enea-linux/syslinux/6.04-pre2-r0/image/usr/share/syslinux/</filename>.</para>
        </listitem>

        <listitem>
          <para>Copy <filename>bzImage</filename> from
          <filename>&lt;build_dir&gt;/tmp/deploy/images/&lt;target&gt;/</filename>.</para>
        </listitem>

        <listitem>
          <para>Populate the root file system in the NFS directory by
          unpacking <filename>enea-image-standard-intel-corei7-64.tar.gz</filename>
          found at
          <filename>&lt;build_dir&gt;/tmp/deploy/images/&lt;target&gt;/</filename>.</para>
        </listitem>
      </orderedlist>

      <para>Boot the target by:</para>

      <orderedlist>
        <listitem>
          <para>Use the BIOS or boot setup to select PXE boot, if not already
          selected.</para>
        </listitem>

        <listitem>
          <para>Reboot the target.</para>
        </listitem>
      </orderedlist>

      <para>The boot setup menu is usually launched by pressing F12 or ESC
      during BIOS power up tests. Look up the manufacturer's documentation for
      your board model to find the appropriate key.</para>
    </section>

    <section id="boot_from_ram">
      <title>Boot from RAM</title>

      <para>This example requires that a TFTP server is set up at IP address
      <literal>&lt;tftp_server_ip&gt;</literal>, and that the server stores
      the Enea Linux image files, kernel image, device tree blob and root
      filesystem, in <literal>/tftpboot/&lt;download_directory&gt;.</literal>
      Please refer to <xref linkend="prebuiltprereq" /> for more details on
      how to install and configure the TFTP server.</para>

      <para>Once you have that in place, run the following commands on the
      target:</para>

      <programlisting>## set tftp server IP
U-Boot&gt; setenv serverip &lt;tftp_server_ip&gt;

## tftp the image files on the target machine
U-Boot&gt; tftpboot 0x01000000 Image  
U-Boot&gt; tftpboot 0x02000000 Image-bcm2837-rpi-3-b.dtb 
U-Boot&gt; tftpboot 0x03000000 enea-image-standard-raspberrypi3-64.ext2.gz.u-boot

## add any other bootargs values if necessary 
U-Boot&gt; setenv bootargs "8250.nr_uarts=1 root=/dev/ram rw ramdisk_size=500000 ip=dhcp \
console=ttyS0,115200"

## Start boot sequence
U-Boot&gt; booti 0x01000000 0x03000000 0x02000000</programlisting>
    </section>

    <section id="boot_from_sd">
      <title>Boot from SD card</title>

      <para>Copy the
      <filename>enea-image-standard-raspberrypi3-64.rpi-sdimg</filename> image
      to the SD card using the Linux dd tool or Win32DiskImager in Windows,
      and insert it into the RPi. The Raspberry Pi will not start without a
      properly formatted SD Card, containing the bootloader, kernel image and
      rootfs.</para>

      <para>Below you can find two methods of how to format an SD Card:</para>

      <itemizedlist>
        <listitem>
          <para><emphasis role="bold">Format and copy images to the SD card
          using the Linux dd command line</emphasis></para>

          <para>The <command>dd</command> command copies a file, converting
          the format of the data in the process, according to the operands
          specified:</para>

          <programlisting>sudo dd bs=4M if=enea-image-standard-sdk-raspberrypi3-64.rpi-sdimg of=/dev/sdg</programlisting>

          <note>
            <para>Use <command>dd</command> cautiously - improper usage or
            entering the wrong values could inadvertently wipe, destroy, or
            overwrite the data on your hard drive.</para>
          </note>
        </listitem>

        <listitem>
          <para><emphasis role="bold">Format the SD card using the
          Win32DiskImager program</emphasis></para>

          <orderedlist>
            <listitem>
              <para>Download and unzip <ulink
              url="https://sourceforge.net/projects/win32diskimager/">Win32DiskImager</ulink></para>
            </listitem>

            <listitem>
              <para>Run <filename>Win32DiskImager.exe</filename>.</para>
            </listitem>

            <listitem>
              <para>Select the drive of your SD card.</para>
            </listitem>

            <listitem>
              <para>Select the image
              <filename>enea-image-standard-raspberrypi3-64.rpi-sdimg</filename>.</para>
            </listitem>

            <listitem>
              <para>Click "Write" and wait for the write to complete.</para>
            </listitem>

            <listitem>
              <para>Exit the imager and eject the SD Card.</para>
            </listitem>

            <listitem>
              <para>Plug the card into your Raspberry Pi.</para>
            </listitem>
          </orderedlist>

          <note>
            <para>Be careful to select the correct drive. If you choose the
            wrong one you may destroy your HDD data. If you are using an SD
            Card slot and can't see the drive in the Win32DiskImager window,
            try using an affordable external adapter in a USB slot.</para>
          </note>
        </listitem>
      </itemizedlist>
    </section>
  </section>

  <section id="custom_enealinux">
    <title>Customizing Enea Linux</title>

    <section id="layers_adaptations">
      <title>Layers and Adaptations</title>

      <para>Bitbake allows a modular approach of Metadata, by building images
      for the layers listed in the conf/bblayers.conf file from your build
      directory.</para>

      <para>To avoid polluting the build with unnecessary packages, before
      adding a new layer, it is recommended to check if the Metadata you need
      is already available in the enabled layers, in which case, for the
      intended configuration, it may require less modification.</para>

      <para>To ease further use of the layer, try to follow as many best
      practices as possible when creating it:</para>

      <itemizedlist>
        <listitem>
          <para>Use names starting with the meta prefix (although this is not
          a requirement)</para>
        </listitem>
      </itemizedlist>

      <itemizedlist>
        <listitem>
          <para>Place your layer under poky</para>
        </listitem>
      </itemizedlist>

      <itemizedlist>
        <listitem>
          <para>Isolate different customizations by layer</para>
        </listitem>
      </itemizedlist>

      <itemizedlist>
        <listitem>
          <para>Assign the layer to a repository (to easily have access to
          maintenance)</para>
        </listitem>
      </itemizedlist>

      <para>To enable a layer, its top path must be specified in the
      <filename>BBLAYERS</filename> variable, as follows:</para>

      <programlisting># POKY_BBLAYERS_CONF_VERSION is increased each time build/conf/bblayers.conf
# changes incompatibly
POKY_BBLAYERS_CONF_VERSION = "2"

BBPATH = "${TOPDIR}"
BBFILES ?= ""

BBLAYERS ?= " \
  /path/to/poky/meta \
  /path/to/poky/meta-el-common \
  /path/to/poky/meta-el-standard \
  /path/to/poky/meta-enea-bsp-common \
  /path/to/poky/meta-enea-bsp-x86 \
  /path/to/poky/meta-openembedded/meta-oe \
  /path/to/poky/meta-openembedded/meta-networking \
  /path/to/poky/meta-openembedded/meta-filesystems \
  /path/to/poky/meta-openembedded/meta-python \
  /path/to/poky/meta-poky \
  /path/to/poky/meta-&lt;layer&gt; \
  "</programlisting>

      <para>Before adding an extra layer, please keep in mind that the order
      of layers is important (due to BitBake parsing conf/layer.conf as
      specified in <filename>BBLAYERS</filename>). To add an extra layer, you
      can modify the <filename>build/conf/bblayers.conf</filename> file in the
      source code editor you prefer, as described above, or use one of the
      specially designed Yocto tools.</para>

      <para>To do such, you can simply modify the build/conf/bblayers.conf
      file in the source code editor you prefer, as described above, or use
      one of the specially designed Yocto tools.</para>

      <para>For instance, in addition to the above, the Yocto Bitbake layers
      utility ensures a very useful checking of some basic layer requirements.
      Bitbake layers are available, as most of the BitBake tools, when
      sourcing oe-init-build-env. Therefore, to enable a custom meta layer,
      you should simply run the following from the build directory:</para>

      <programlisting>bitbake-layers add-layer &lt;meta-layer&gt;</programlisting>

      <para>If the specified layer doesn't contain a
      <filename>conf/layer.conf</filename> file, you should add one with the
      needed configuration. Also, to make sure the layer insertion is done in
      the right metadata, the utility looks for the bblayers.conf
      configuration file in the corresponding path, which should be satisfied
      if running the command from the generated build directory.</para>

      <para>For further information on this or on other utilities belonging to
      the same suite, run:</para>

      <programlisting>bitbake-layers -h</programlisting>

      <para>As a result, <filename>BBLAYERS</filename> shall be extended with
      the bsp-layer/s layer for your target and any other additional layer/s.
      For details on how to do this, see the <ulink
      url="http://www.yoctoproject.org/docs/3.1/dev-manual/dev-manual.html#understanding-and-creating-layers">Yocto
      3.1 Dev Manual, section "Understanding and Creating Layers".</ulink> If
      needed replace the Yocto version.</para>

      <para>Layers can be added when you initialize the build environment. The
      layers required for each target are specified in the build commands in
      the Enea Linux distribution's Release Information.</para>

      <para>Each Enea Linux customer is advised to add a custom layer for
      customer-specific additions and customizations, instead of modifying
      existing layers.</para>

      <para>The recommended way to modify a package is to edit directly in the
      recipe file. Utilizing the devshell, <literal>bitbake -c devshell
      &lt;image_name&gt;</literal>, when constructing or modifying recipes is
      really handy when experimenting, but do not forget to make the final
      updates directly in the recipe file. It is difficult to keep track of
      exactly what in the user environment is "dirty" and not in sync with
      current recipes. Therefore, always make sure to <literal>bitbake -c
      clean &lt;image_name&gt;</literal> after finishing up a devshell
      session, and adapt recipes accordingly to ensure a shareable and
      repeatable build environment.</para>
    </section>

    <section id="add_recipe">
      <title>Adding a Recipe</title>

      <para>Study the <ulink
      url="https://www.yoctoproject.org/docs/3.1/dev-manual/dev-manual.html#new-recipe-single-c-file-package-hello-world">Hello
      World recipe</ulink> in the Yocto Project Development Manual. If needed
      replace the example version (3.1) with the Yocto version in your Enea
      Linux distribution.</para>
    </section>

    <section id="config_pkg_recipes">
      <title>Configuring Packages via Recipes</title>

      <para>The default configuration produces a standard Linux installation,
      but it is often desirable to configure specific packages in more detail.
      Different packages implement their configuration in different ways, and
      there is no single method that is valid for all packages. As always, in
      a collaborative development environment, the developer should make sure
      that the recipes in the custom layer are upgraded accordingly when a
      reconfiguration of a specific package is done.</para>

      <para>In subsequent sections you find examples on how to configure some
      common packages.</para>

      <section id="linux_kern">
        <title>The Linux Kernel</title>

        <para>The Linux kernel provides a vast array of configuration options,
        managed using its own configuration system. The kernel package can be
        supplied from different providers, and this example uses the
        virtual/kernel package name to refer to the kernel used in the
        build:</para>

        <programlisting>$ bitbake -c menuconfig virtual/kernel</programlisting>

        <note>
          <para>menuconfig requires Ncurses. If the terminal that pops up
          immediately closes instead of showing the menuconfig interface,
          check that the Ncurses development library is installed.</para>
        </note>

        <para>First build the kernel:</para>

        <programlisting>$ bitbake -f -c compile -c install -c deploy virtual/kernel</programlisting>

        <para>Then build the whole distribution:</para>

        <programlisting>$ bitbake enea-image-&lt;name&gt;</programlisting>
      </section>

      <section id="busybox">
        <title>Busybox</title>

        <para>Busybox uses the same configuration system as the Linux kernel
        and is therefore invoked similarly. In contrast to the kernel, there
        is generally only one variant of busybox in a distribution and we can
        therefore refer to it by the package name alone:</para>

        <programlisting>$ bitbake -c menuconfig busybox</programlisting>
      </section>
    </section>

    <section id="build_com_licenses">
      <title>Building with Commercial Licenses</title>

      <note>
        <para>Adding commercial-licensed packages might pose distribution
        problems due to license agreements or patents.</para>
      </note>

      <para>Commercial-licensed packages are not provided with Enea Linux.
      Depending on your use case, you might need to extend the initial image
      with more packages by adding recipes and updating the image definition,
      always in accordance with the license conditions. To succeed with
      building the customized image, you might need to solve dependencies by
      adding even more packages.</para>

      <para>Below is an example with steps on how to add a package with a
      commercial license. The configuration is updated in two places and the
      recipes are selected for the packages and any dependencies.</para>

      <note>
        <para>This is only an illustrating example, the exact configuration
        may differ between different packages. Some packages could require
        other defines added to local.conf and some packages might need an
        added <filename>DEPENDS</filename> in the *.inc file, or other
        particular changes.</para>
      </note>

      <itemizedlist>
        <listitem>
          <para>Append the package name to the
          <filename>IMAGE_INSTALL</filename> definition, used in the recipe
          corresponding to the image you will build, as in one of the examples
          below:</para>

          <orderedlist>
            <listitem>
              <para>If you need the package in a set of images, to avoid
              defining it in each recipe, add the following line to
              <filename>IMAGE_INSTALL</filename> in
              <filename>meta-el-common/images/enea-image-common.inc</filename></para>

              <programlisting>  package_name \</programlisting>
            </listitem>

            <listitem>
              <para>If you have specific images in which you need the package,
              add the following line in the corresponding recipes in
              meta-el-&lt;profile&gt;/images/enea-image-&lt;profile&gt;.bb</para>

              <programlisting>  IMAGE_INSTALL += " \
          package_name \
          "</programlisting>
            </listitem>
          </orderedlist>
        </listitem>

        <listitem>
          <para>Add the required license to the
          <filename>LICENSE_FLAGS_WHITELIST</filename> definition. This can be
          done by adding script lines in the corresponding
          scripts/conf_setup.sh file, which appends
          <filename>LICENSE_FLAGS_WHITELIST +=
          "&lt;suitable-license&gt;</filename> to
          <filename>conf/local.conf.</filename></para>
        </listitem>

        <listitem>
          <para>To mitigate the build errors caused by packages with
          commercial licenses, you might also need to append the generic
          license <filename>LICENSE_FLAGS_WHITELIST += "commercial"</filename>
          in the same way as above.</para>
        </listitem>

        <listitem>
          <para>Select the needed recipes for the packages and add these to
          the build configuration.</para>
        </listitem>

        <listitem>
          <para>Select the needed recipes to resolve dependencies for the new
          packages and add these to the build configuration.</para>
        </listitem>
      </itemizedlist>

      <para>More information about recipes can be found here:</para>

      <itemizedlist>
        <listitem>
          <para><ulink
          url="http://git.openembedded.org/">http://git.openembedded.org/</ulink></para>
        </listitem>
      </itemizedlist>

      <itemizedlist>
        <listitem>
          <para><ulink
          url="https://wiki.yoctoproject.org/wiki/Building_your_own_recipes_from_first_principles">https://wiki.yoctoproject.org/wiki/Building_your_own_recipes_from_first_principles</ulink></para>
        </listitem>
      </itemizedlist>

      <itemizedlist>
        <listitem>
          <para><ulink
          url="http://www.yoctoproject.org/docs/current/dev-manual/dev-manual.html#new-recipe-writing-a-new-recipe">http://www.yoctoproject.org/docs/current/dev-manual/dev-manual.html#new-recipe-writing-a-new-recipe</ulink></para>
        </listitem>
      </itemizedlist>
    </section>
  </section>

  <section id="install_el_sdk">
    <title>Installing the Enea Linux SDK</title>

    <para>Before cross-compiling applications for your target, you need to
    install the Software Development Kit (SDK) - which contains the
    cross-compilation toolchain - and set up the cross-compilation environment
    on your host. The toolchain for each supported target contains a 64-bit
    library for gcc. The toolchain and the environment-setup script are
    wrapped together inside a toolchain installer in the form of a shell
    script.</para>

    <para>The cross-compilation toolchain is packaged as follows:</para>

    <itemizedlist>
      <listitem>
        <para>The &lt;target&gt; toolchain contains the lib64 (64-bit)
        library.</para>
      </listitem>

      <listitem>
        <para>The &lt;target&gt; installer has an environment-setup script
        which will select the lib64 to be used by gcc. This way, a 64-bit
        application can be cross-compiled.</para>
      </listitem>
    </itemizedlist>

    <para>Do as in the example below to install the SDK and set up the
    cross-compilation environment:</para>

    <orderedlist>
      <listitem>
        <para>The fastest alternative is to use a precompiled
        cross-compilation toolchain installer for your host and target.</para>

        <para>Please refer to the Release Information document, in section 1.1
        Provided Contents, for more details on where to find the pre-compiled
        SDK installer.</para>
      </listitem>

      <listitem>
        <para>Run the installer to unpack the cross-compilation toolchain and
        the environment-setup script:</para>

        <programlisting>$ chmod 770 enea-*-toolchain-&lt;version&gt;.sh
$ ./enea-*-toolchain-&lt;version&gt;.sh</programlisting>

        <para>When prompted, select to install the SDK in the desired
        directory, referred to as &lt;sdkdir&gt;. The default path where the
        SDK will be installed, will be shown in the prompt. The installer
        unpacks the environment setup script in &lt;sdkdir&gt; and the
        toolchain under &lt;sdkdir&gt;/sysroots.</para>

        <note>
          <para>Choose a unique directory for each toolchain. Installing a
          second toolchain of any type (buildtools toolchain or
          cross-compilation toolchain) in the same directory as a previously
          installed one will break the $PATH variable of the first one.</para>
        </note>
      </listitem>

      <listitem>
        <para>Setup the toolchain environment for your target by sourcing the
        environment-setup script:</para>

        <programlisting>$ . &lt;sdkdir&gt;/environment-setup-&lt;arch&gt;-enea-linux</programlisting>

        <para>Example:</para>

        <programlisting>$ . /opt/enea/environment-setup-corei7-64-enea-linux</programlisting>
      </listitem>
    </orderedlist>

    <para>Once the cross-compilation toolchain is in place and the environment
    set up, you can proceed with Cross-Compiling Applications from Command
    Line (4.1) </para>

    <section id="boot_qemux86">
      <title>Building and booting Enea Linux on QEMU x86</title>

      <para>Build an Enea Linux image from the SDK to run on QEMU x86:</para>

      <programlisting>$ cd &lt;sdkdir&gt;/workspace
$ devtool build-image enea-image-standard 
$ devtool runqemu kvm enea-image-standard nographic slirp  </programlisting>
    </section>
  </section>

  <section id="pkg_mg">
    <title>Using Package Management</title>

    <para>A Package Management System (PMS) can be used to customize your
    image in a consistent way, e.g. to install, upgrade, or delete packages
    considering the dependencies. The package management systems supported by
    Enea Linux are described in this section. More information about PMS can
    be found in the Yocto 3.1 document <ulink
    url="http://www.yoctoproject.org/docs/3.1/mega-manual/mega-manual.html">Yocto
    Project Mega Manual</ulink>. If needed replace the Yocto version in the
    link.</para>

    <section id="rpm_pktmgmt">
      <title>RPM Package Management (RPM Packages)</title>

<!--      <para>Enea Linux provides RPM packages on <ulink
      url="http://linux.enea.com/EneaLinux8.0/">linux.enea.com</ulink> site,
      in directory
      <literal><literal>&lt;release&gt;/&lt;target&gt;/rpm</literal>/</literal>.</para>
-->
      <para>The application for performing runtime package management of RPM
      packages on the target is called <filename>rpm</filename>.</para>

      <para>Use the <literal>rpm</literal> command to install, upgrade, or
      remove packages. Before using any rpm options that require network
      access, please check that the network is configured and working
      properly.</para>

      <para>The <literal>rpm</literal> command is by default included in
      Enea Linux images.</para>

      <!--<section id="apt_config">
        <title>Configuring</title>

        <para>APT relies on the concept of repositories in order to find
        packages and resolve dependencies.</para>

        <para>Any number of additional repositories can be added to APT's
        configuration files (.list extension) located in sources.list.d
        directory (e.g:
        <filename>/etc/apt/sources.list.d/repos.list</filename>) and then be
        queried by APT.</para>

        <programlisting># touch /etc/apt/sources.list.d/repos.list
# echo "deb [trusted=yes]  http://server-address/path/to/the/package/directory ./" | \
tee -a /etc/apt/sources.list.d/repos.list</programlisting>

        <para>Run <literal>createrepo --><!--update path_to_repo</literal> to fetch information from
        the new repository:</para>

        <programlisting># createrepo --><!--update repo</programlisting>
      </section>-->

      <section id="rpm_preparation">
      	<title>Preparation</title>

	<para>RPM packages need to first be downloaded on target. 
	<programlisting># wget https://rpmfind.net/linux/fedora/linux/development/rawhide/Everything/
aarch64/os/Packages/v/vim-common-8.1.2120-1.fc32.aarch64.rpm</programlisting>
	They can be copied either from public maintained repositories or from locally maintained collections of useful RPMs. 
	<programlisting># wget http://linux.enea.com/RPM/aarch64/vim-common-7.4.481-r0.0.aarch64.rpm</programlisting>
	</para>

	<para>
	RPM is also identifying and checking for package dependencies. It warns if the package can not be installed correctly and lists what needs to be done.
	</para>

      </section>

      <section id="rpm_install">
        <title>Installing</title>
     
        <para>RPM packages typically have file names like
        foo-1.0.1-r0.0_arm64.rpm The file name includes the package name
        (foo), version (1.0.1), revison (r0.0), and architecture (arm64). To
        install a package, log in as root and type the following command at a
        shell prompt:</para>

        <programlisting># rpm -i vim-common-8.1.1017-r0.0.aarch64.rpm
user.notice [RPM][351]: Transaction ID 5d836e00 started
user.notice [RPM][351]: install vim-common-8.1.1017-r0.0.aarch64: success
user.notice [RPM][351]: install vim-common-8.1.1017-r0.0.aarch64: success
user.notice [RPM][351]: Transaction ID 5d836e00 finished: 0</programlisting>

      </section>

      <section id="rpm_upgrade">
        <title>Upgrading</title>

        <para>The <literal>rpm -U</literal> command will upgrade one
        or more packages which are currently installed in the system.
	</para>

        <programlisting># rpm -U vim-common-8.1.1518-r0.0.aarch64.rpm
user.notice [RPM][346]: Transaction ID 5d836d54 started
user.notice [RPM][346]: erase vim-common-8.1.1017-r0.0.aarch64: success
user.notice [RPM][346]: install vim-common-8.1.1518-r0.0.aarch64: success
user.notice [RPM][346]: erase vim-common-8.1.1017-r0.0.aarch64: success
user.notice [RPM][346]: install vim-common-8.1.1518-r0.0.aarch64: success
user.notice [RPM][346]: Transaction ID 5d836d54 finished: 0</programlisting>
      </section>

      <section id="rpm_rm">
        <title>Removing</title>

        <para>The <literal>rpm -e</literal> command will remove the
	package which is currently installed in the system.
        Example:</para>

        <programlisting># rpm -e vim-common
user.notice [RPM][350]: Transaction ID 5d836dc9 started
user.notice [RPM][350]: erase vim-common-8.1.1518-r0.0.aarch64: success
user.notice [RPM][350]: erase vim-common-8.1.1518-r0.0.aarch64: success
user.notice [RPM][350]: Transaction ID 5d836dc9 finished: 0
</programlisting>
      </section>

      <section id="rpm_searching">
        <title>Searching</title>

        <para>The <literal>rpm -q</literal> allows searching for the
        given expressions in the name, summary and description of known
        packages. Example:</para>

        <programlisting># rpm -q vim-common
vim-common-8.1.1017-r0.0.aarch64</programlisting>
      </section>
    </section>
  </section>
</chapter>