Restructuring Getting Started chapter in the User's Guide and fixing minor bugs in several other sections and documents

6 files changed, 1042 insertions, 3 deletions

diff --git a/doc/book-enea-linux-release-info/doc/known_bugs_and_limitations.xml b/doc/book-enea-linux-release-info/doc/known_bugs_and_limitations.xml
index 9fda0a9..2f7a41d 100644
--- a/doc/book-enea-linux-release-info/doc/known_bugs_and_limitations.xml
+++ b/doc/book-enea-linux-release-info/doc/known_bugs_and_limitations.xml
@@ -2,7 +2,7 @@
 <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
 <chapter id="bugs-limitations">
-  <title>Known Problems in This Release</title>
+  <title>Known Problems in this Release</title>
 
   <para>Open source projects are continuously working on correcting reported
   problems. Corrections to bugs detected by Enea are submitted upstream, and
diff --git a/doc/book-enea-linux-user-guide/doc/application_development.xml b/doc/book-enea-linux-user-guide/doc/application_development.xml
index c8ee28c..3458d39 100644
--- a/doc/book-enea-linux-user-guide/doc/application_development.xml
+++ b/doc/book-enea-linux-user-guide/doc/application_development.xml
@@ -15,7 +15,7 @@
     applications as usual and get them compiled for your target. Below you see
     how to cross-compile from the command line. If Eclipse is installed, you
     can also cross-compile your code from the Eclipse IDE. For more details,
-    see <xref linkend="enea-linux-eclipse-cross-compile" />.</para>
+    see <xref linkend="crosscomp" />.</para>
 
     <orderedlist>
       <listitem>
diff --git a/doc/book-enea-linux-user-guide/doc/book.xml b/doc/book-enea-linux-user-guide/doc/book.xml
index f449974..6e131b3 100644
--- a/doc/book-enea-linux-user-guide/doc/book.xml
+++ b/doc/book-enea-linux-user-guide/doc/book.xml
@@ -12,7 +12,9 @@
   <xi:include href="../../s_docbuild/template/docsrc_common/bookinfo_userdoc.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />

   <xi:include href="preface.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />

   <xi:include href="introduction.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />

-  <xi:include href="getting_started.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />

+  <xi:include href="prerequisites_and_requirements.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />

+  <xi:include href="getting_enea_linux.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />

+  <xi:include href="using_enea_linux.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />

   <xi:include href="application_development.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />

   <xi:include href="using_eclipse.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />

   <xi:include href="troubleshooting.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />

diff --git a/doc/book-enea-linux-user-guide/doc/getting_enea_linux.xml b/doc/book-enea-linux-user-guide/doc/getting_enea_linux.xml
new file mode 100644
index 0000000..772d8e3
--- /dev/null
+++ b/doc/book-enea-linux-user-guide/doc/getting_enea_linux.xml
@@ -0,0 +1,156 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<chapter>
+  <title id="gettingel">Getting Enea Linux</title>
+
+  <para>Enea Linux is available as both pre-built binary images and source
+  code. Both serve a specific purpose and each have their advantages. However,
+  using the pre-built binary images allows for getting up and running faster.
+  Please refer to the sections below for details on how to get Enea Linux as
+  pre-built binary images or source code.</para>
+
+  <section id="gettingbin">
+    <title>Getting Pre-Built Binaries</title>
+
+    <para>Enea Linux pre-built binaries are available for download on <ulink
+    url="https://portal.enea.com/login/?redirect_to=https%3A%2F%2Fportal.enea.com%2F">Enea
+    Download Portal</ulink>. Log in using the credentials provided. Using the
+    menu, browse to the <emphasis role="bold">Linux</emphasis> section. You
+    will now have access to the <emphasis role="bold">Files</emphasis> section
+    and the <emphasis role="bold">Online Documentation</emphasis>
+    section.</para>
+
+    <para>The Files section lists each Enea Linux distribution, one for each
+    version and profile, as a separate download package. Clicking on the name
+    of the distribution will open a new page, which presents further details
+    about the content of the release and a list of downloadable archives, one
+    for each hardware target included in the release. Each archive provides
+    the following content:</para>
+
+    <itemizedlist>
+      <listitem>
+        <para><emphasis>images</emphasis> directory - this directory includes
+        the binary image files needed to boot the target with Enea Linux. This
+        includes the kernel, the root file system, device tree, etc.</para>
+      </listitem>
+
+      <listitem>
+        <para><emphasis>sdk</emphasis> directory - this directory includes the
+        installer for the SDK.</para>
+      </listitem>
+
+      <listitem>
+        <para><emphasis>deb</emphasis> directory - this directory contains all
+        the packages included in the distribution in deb format, which can be
+        installed using the package manager.</para>
+      </listitem>
+    </itemizedlist>
+
+    <para>For faster downloads, each archive is mirrored in several places,
+    geographically. Choose the archive in the region closest to you.</para>
+
+    <para>The Documentation section lists all the documents delivered with the
+    release.</para>
+  </section>
+
+  <section id="gettingsources">
+    <title>Getting the Sources</title>
+
+    <para>Enea Linux sources are available for cloning from a set of Git
+    repositories on <ulink url="https://git.enea.com">git.enea.com</ulink>.
+    Since Enea Linux requires multiple repositories, Google Repo tool is used
+    in order to manage configurations and make the cloning step simpler.
+    Google Repo tool uses files, known as manifests, which store a list of
+    tuples (repository URL, version). The Repo tool is then used to traverse
+    the list of tuples in the manifest file and clone the specified versions
+    of each repository. See <ulink
+    url="https://code.google.com/p/git-repo/">https://code.google.com/p/git-repo/</ulink>
+    for more info.</para>
+
+    <section id="getting-source-code-step-one">
+      <title>Get access to git.enea.com</title>
+
+      <para>In order to get access to git.enea.com, a ssh key is required for
+      Git authentication. If you don't already have such a key, follow the
+      steps below to generate one:</para>
+
+      <orderedlist>
+        <listitem>
+          <para>Generate the ssh key pair:</para>
+
+          <programlisting>$ ssh-keygen -t rsa</programlisting>
+
+          <para>When asked for a password, just press Enter. This will create
+          two files in the .ssh directory in your home directory.</para>
+
+          <programlisting>id_rsa
+id_rsa.pub</programlisting>
+        </listitem>
+
+        <listitem>
+          <para>Copy the public key into an authorized_keys file:</para>
+
+          <programlisting>$ cat id_rsa.pub &gt;&gt; authorized_keys</programlisting>
+        </listitem>
+      </orderedlist>
+
+      <para>Once these steps are done and you have a valid ssh key pair, send
+      the public key, <emphasis>id_rsa.pub</emphasis>, via email to
+      <email>mailto:git_support@list.enea.se</email> in order to get access to
+      <ulink url="https://git.enea.com">git.enea.com</ulink>.</para>
+    </section>
+
+    <section id="getting-source-code-step-two">
+      <title>Get Sources</title>
+
+      <para>To use the Repo tool to download the sources for Enea Linux, do
+      the following:</para>
+
+      <orderedlist>
+        <listitem>
+          <para>Make sure that the repo tool is installed. If not, do the
+          following: <remark>Below is include of ID
+          "eltf-getting-repo-install-command" from
+          eltf_params_updated.xml</remark></para>
+
+          <xi:include href="../../book-enea-linux-release-info/doc/eltf_params_updated.xml"
+                      xmlns:xi="http://www.w3.org/2001/XInclude"
+                      xpointer="element(eltf-getting-repo-install-command/1)" />
+        </listitem>
+
+        <listitem>
+          <para>Define the <filename>MACHINE</filename> from one of the
+          targets listed here:<remark>Below is the "machine_list"
+          programlisting in machine_list_generated.xml created by the make
+          system by extracting from the manifest</remark><itemizedlist>
+              <listitem>
+                <para>raspberrypi3-64</para>
+              </listitem>
+            </itemizedlist></para>
+        </listitem>
+
+        <listitem>
+          <para>Then use the repo command below:</para>
+
+          <xi:include href="../../book-enea-linux-release-info/doc/eltf_params_updated.xml"
+                      xmlns:xi="http://www.w3.org/2001/XInclude"
+                      xpointer="element(eltf-repo-cloning-enea-linux/1)" />
+        </listitem>
+      </orderedlist>
+
+      <para>Once the source code is downloaded, the current directory will
+      contain a <filename>README</filename> file with instructions on how to
+      build the distro and boot the machine you choose. .</para>
+
+      <para>It's not necessary to explicitly clone the manifest repository
+      since that is done automatically by the repo tool. To see the current
+      manifest, use the following command:</para>
+
+      <programlisting>$ repo manifest</programlisting>
+
+      <remark>The UG should be updated with instructions on how to add
+      customizations. That section should also contain more info about the
+      manifest: the manifest templates, using a branch instead of the tag EL6,
+      etc. When this is done a reference from here should be added.</remark>
+    </section>
+  </section>
+</chapter>
\ No newline at end of file
diff --git a/doc/book-enea-linux-user-guide/doc/prerequisites_and_requirements.xml b/doc/book-enea-linux-user-guide/doc/prerequisites_and_requirements.xml
new file mode 100644
index 0000000..d560eb6
--- /dev/null
+++ b/doc/book-enea-linux-user-guide/doc/prerequisites_and_requirements.xml
@@ -0,0 +1,101 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<chapter>
+  <title id="prereq">Prerequisites and Requirements</title>
+
+  <para>Building Enea Linux or compiling applications requires that your git
+  environment be setup properly and for certain packages to be installed on
+  your Linux development host. The following chapter details the
+  configurations needed on the build environment in order to properly use Enea
+  Linux.</para>
+
+  <section id="gitconfig">
+    <title>Git Configuration</title>
+
+    <para>If you intend to get Enea Linux sources and build Enea Linux
+    yourself, you will need Git installed in your build environemtn. Please
+    refer to <ulink
+    url="https://git-scm.com/book/en/v2/Getting-Started-First-Time-Git-Setup">Getting
+    Started - First-Time Git Setup</ulink>, for more details on how to set up
+    your git environment correctly, including how to set your identity using
+    the following commands:</para>
+
+    <programlisting>$ git config --global user.name "John Doe"
+$ git config --global user.email johndoe@example.com</programlisting>
+  </section>
+
+  <section id="hostpackages">
+    <title>Host Packages</title>
+
+    <para>In order to work with Enea Linux, you need a set of tools installed
+    on the build machine, depending on the scenario you use. The following
+    chapters will describe what tools to install on the build machine.</para>
+
+    <section id="prebuiltprereq">
+      <title>Using Pre-Build Binaries</title>
+
+      <para>Using the pre-built binaries, you can get up and running more
+      quickly. Since building is not required, there are not a lot of packaes
+      and tools that need to be installed but a few are still required:</para>
+
+      <itemizedlist>
+        <listitem>
+          <para>wget - for downloading the Enea Linux binaries</para>
+        </listitem>
+
+        <listitem>
+          <para>tar - for decompressing the Enea Linux release</para>
+        </listitem>
+
+        <listitem>
+          <para>tftpboot server - for deploying Enea Linux on target</para>
+        </listitem>
+
+        <listitem>
+          <para>NFS server - in case you want to mount the root file system
+          over NFS</para>
+        </listitem>
+      </itemizedlist>
+    </section>
+
+    <section id="hostprereqpackages">
+      <title>Required Packages for the Host Development System</title>
+
+      <para>Building Enea Linux requires a set of packages to be installed on
+      your Linux development host. The list of required packages is described
+      in the <ulink
+      url="https://www.yoctoproject.org/docs/2.3/ref-manual/ref-manual.html#required-packages-for-the-host-development-system">Yocto
+      Project reference manual</ulink>.</para>
+    </section>
+  </section>
+
+  <section id="sysshell_config">
+    <title>Default Shell Configuration</title>
+
+    <para>Before installing Enea Linux, make sure that
+    <filename>bash</filename> is the default shell.</para>
+
+    <para><emphasis role="bold">To verify the default system
+    shell</emphasis></para>
+
+    <itemizedlist>
+      <listitem>
+        <para>If your system runs Ubuntu, use list to verify if
+        <filename>/usr/bin</filename> is a symbolic link to <emphasis
+        role="bold">bash</emphasis>:</para>
+
+        <programlisting># ls -l /bin/sh
+lrwxrwxrwx 1 root root 4 2012-03-02 11:53 /bin/sh -&gt; bash</programlisting>
+      </listitem>
+
+      <listitem>
+        <para>Optionally, in case the link points to <literal>dash</literal>,
+        change it through the following steps:</para>
+
+        <programlisting># ls -l /bin/sh
+lrwxrwxrwx 1 root root 4 2012-03-02 11:53 /bin/sh -&gt; dash
+# sudo dpkg-reconfigure dash
+Use dash as the default system shell (/bin/sh)? No</programlisting>
+      </listitem>
+    </itemizedlist>
+  </section>
+</chapter>
\ No newline at end of file
diff --git a/doc/book-enea-linux-user-guide/doc/using_enea_linux.xml b/doc/book-enea-linux-user-guide/doc/using_enea_linux.xml
new file mode 100644
index 0000000..a880500
--- /dev/null
+++ b/doc/book-enea-linux-user-guide/doc/using_enea_linux.xml
@@ -0,0 +1,780 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<chapter id="usingenealinux">
+  <title>Using Enea Linux</title>
+
+  <section id="buildingenealinux">
+    <title>Building Enea Linux</title>
+
+    <para>Enea Linux is made available as sources as well. This allows
+    building various Enea Linux artifacts and this is detailed in the
+    following sections:</para>
+
+    <section>
+      <title>Building the images</title>
+
+      <para>Build Enea Linux images using the following steps:</para>
+
+      <procedure>
+        <step>
+          <para>Clone Enea Linux sources using Repo tool. Please refer to
+          chapter 3.2 in the current documebt for more details on how to do
+          this.</para>
+
+          <programlisting>$ mkdir enea-linux
+$ cd enea-linux
+$ export MACHINE=&lt;machine&gt;
+$ repo init -u git@git.enea.com:linux/manifests/el_manifests-standard.git \
+    -b refs/tags/Enea_Linux_7.0 -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>
+
+          <note>
+            <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>
+
+          <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 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 or
+          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="gettingsources" /> for more details on how to get access
+            to Enea Linux sources.</para>
+          </note>
+        </step>
+      </procedure>
+    </section>
+
+    <section>
+      <title>Building the SDK</title>
+
+      <para>If you want to rebuild a cross-compilation toolchain to be used by
+      in application development, use the following steps:</para>
+
+      <procedure>
+        <step>
+          <para>Clone Enea Linux sources using Repo tool. Please refer to
+          <xref linkend="gettingsources" /> for more details on how to do
+          this.</para>
+
+          <programlisting>$ mkdir enea-linux
+$ cd enea-linux
+$ export MACHINE=&lt;machine&gt;
+$ repo init -u git@git.enea.com:linux/manifests/el_manifests-standard.git \
+    -b refs/tags/Enea_Linux_7.0 -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>
+
+          <note>
+            <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>
+
+          <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 TMPDIR in conf/local.conf to point
+            to a local disk.</para>
+          </note>
+        </step>
+
+        <step>
+          <para>Build 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; -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>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 or
+          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="bootingenealinux">
+    <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 so those will be
+    described in the following sections.</para>
+
+    <section>
+      <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>
+      <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><filename>enea-image-standard-raspberrypi3-64.rpi-sdimg</filename></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-&lt;arch&gt; \
+  /path/to/poky/meta-fsl-&lt;arch&gt; \
+  /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/2.3/dev-manual/dev-manual.html#understanding-and-creating-layers">Yocto
+      2.3 Dev Manual, section &lt;Understanding and Creating
+      Layers&gt;</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/2.3/dev-manual/dev-manual.html#new-recipe-single-c-file-package-hello-world"><ulink
+      url="https://www.yoctoproject.org/docs/2.3/dev-manual/dev-manual.html#new-recipe-single-c-file-package-hello-world">Hello
+      World recipe</ulink></ulink> in the Yocto Project Development Manual. If
+      needed replace the example version (2.3) 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>
+        <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-aarch64-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) or, if Eclipse is installed, Cross-Compiling from Eclipse
+    (5.4.1).</para>
+  </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 2.3 document <ulink
+    url="http://www.yoctoproject.org/docs/2.3/mega-manual/mega-manual.html">Yocto
+    Project Mega Manual</ulink>. If needed replace the Yocto version in the
+    link.</para>
+
+    <section id="apt_pktmgmt">
+      <title>APT Package Management (DEB Packages)</title>
+
+      <para>Enea Linux provides DEB packages on <ulink
+      url="http://linux.enea.com/EneaLinux7.0/">linux.enea.com</ulink> site,
+      in directory
+      <literal><literal>&lt;release&gt;/&lt;target&gt;/deb</literal>/</literal>.</para>
+
+      <para>The application for performing runtime package management of DEB
+      packages on the target is called <filename>apt-get</filename>.</para>
+
+      <para>Use the <literal>apt-get</literal> command to install, upgrade, or
+      remove packages. Before using any apt-get options that require network
+      access, please check that the network is configured and working
+      properly.</para>
+
+      <para>The <literal>apt-get</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>apt-get update</literal> to fetch information from
+        the new repository:</para>
+
+        <programlisting># apt-get update</programlisting>
+      </section>
+
+      <section id="apt_install">
+        <title>Installing</title>
+
+        <para>DEB packages typically have file names like
+        foo-1.0.1-r0.0_arm64.deb 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># apt-get install foo</programlisting>
+
+        <para>The <literal>apt-get install</literal> command will install one
+        or more packages in the system.</para>
+      </section>
+
+      <section id="apt_upgrade">
+        <title>Upgrading</title>
+
+        <para>The <literal>apt-get upgrade</literal> command will upgrade one
+        or more packages which are currently installed in the system. If no
+        packages are given, all installed packages will be checked.</para>
+
+        <programlisting># apt-get upgrade foo</programlisting>
+      </section>
+
+      <section id="apt_rm">
+        <title>Removing</title>
+
+        <para>The <literal>apt-get remove</literal> command will remove one or
+        more packages which are currently installed in the system.
+        Example:</para>
+
+        <programlisting># apt-get remove ptest-runner
+Reading package lists... Done
+Building dependency tree
+Reading state information... Done
+The following packages were automatically installed and are no longer required:
+  libc6-dbg libc6-dev libc6-extra-nss libc6-thread-db libcidn1
+  linux-libc-headers-dev
+Use 'apt autoremove' to remove them.
+The following packages will be REMOVED:
+  ptest-runner
+0 upgraded, 0 newly installed, 1 to remove and 0 not upgraded.
+After this operation, 0 B of additional disk space will be used.
+Do you want to continue? [Y/n] y
+(Reading database ... 5766 files and directories currently installed.)
+Removing ptest-runner (2.0.2+git0+6d2872116c-r0.0) ...
+</programlisting>
+      </section>
+
+      <section id="pmsearching">
+        <title>Searching</title>
+
+        <para>The <literal>apt-cache search</literal> allows searching for the
+        given expressions in the name, summary and description of known
+        packages. Example:</para>
+
+        <programlisting># apt-cache search ptest-runner
+ptest-runner - A C program to run all installed ptests
+ptest-runner-dbg - A C program to run all installed ptests - Debugging files
+ptest-runner-dev - A C program to run all installed ptests - Development files</programlisting>
+      </section>
+    </section>
+  </section>
+</chapter>
\ No newline at end of file