path: root/distribution/elbe-usage/pres_elbe-usage_en.tex

\input{configpres}

\title{ELBE - Embedded Linux Build Environment}
\maketitle

\subsection{ELBE usage}

\begin{frame}
\frametitle{What is ELBE?}
ELBE is a Debian based system to generate root-filesystems for embedded devices
\end{frame}

\begin{frame}[fragile]
\frametitle{How to install ELBE}
\begin{verbatim}
# On a Debian based system
$ echo 'deb http://debian.linutronix.de/elbe \
wheezy main' >> /etc/apt/sources.list
$ aptitude install elbe
\end{verbatim}
Or get the latest source from github:
\begin{verbatim}
git clone https://github.com/Linutronix/elbe.git
\end{verbatim}
\end{frame}

\begin{frame}
\frametitle{Overview}
\begin{itemize}
\item The Elbe system consists of the program elbe which is implemented in Python
\item Similar to git, it can be called with several sub commands
\item An Elbe project consists of an xml file that describes the project
\end{itemize}
\end{frame}

\begin{frame}
\frametitle{Documentation}
\begin{itemize}
\item Have a look at /usr/share/doc/elbe/
\item Please read /usr/share/doc/elbe/elbeoverview-en.html
\item There are man pages e.g. 'man elbe', 'man elbe-create', \dots
\end{itemize}
\end{frame}

\begin{frame}
\frametitle{How ELBE works}
\begin{figure}[h]
\centering
\includegraphics[width=10cm]{images/elbe-process.png}
\end{figure}
\end{frame}

\begin{frame}
\frametitle{How ELBE works}
\begin{figure}[h]
\centering
\includegraphics[width=10cm]{images/emu-process.png}
\end{figure}
\end{frame}

\begin{frame}
\frametitle{The ELBE workflow}
\begin{enumerate}
\item Create a XML file
\item Create a project based on that XML file
\item Change to the project directory an run make
\end{enumerate}
\end{frame}

\begin{frame}[fragile]
\frametitle{command overview}
Create a new project:
\begin{verbatim}
$ elbe create \
	--directory /home/user/example example.xml
\end{verbatim}
\end{frame}

\begin{frame}[fragile]
\frametitle{start build}
\begin{verbatim}
$ cd /home/user/example
$ ls -a
.  ..  .elbe-in  Makefile
$ make
\end{verbatim}
.elbe-in contains the files needed inside the virtual build machine
\end{frame}

\begin{frame}[fragile]
\frametitle{generated files}
\begin{verbatim}
$ ls -a
.             elbe-report.txt  sdcard.img
..            install.iso      source.xml
buildenv.img  licence.txt      .stamps
.elbe-gen     Makefile         validation.txt
.elbe-in      rootfs.tar.gz
\end{verbatim}
\end{frame}

\begin{frame}
\frametitle{buildenv.img}
\begin{itemize}
\item Qemu HD image containing a complete Debian system
\item was used to generate the RFS for the target
\item can be used as build environment for own applications
\end{itemize}
\end{frame}

\begin{frame}
\frametitle{.elbe-gen}
\begin{itemize}
\item files generated by the Makefile
\item including the modified initrd that contains the debian-installer
\item and a list containing the files that are copied from the buildenv to the
host PC
\end{itemize}
\end{frame}

\begin{frame}
\frametitle{elbe-report.txt}
\begin{itemize}
\item logfile of the build process in asciidoc format
\item 'asciidoc elbe-report.txt' generates a html file
\end{itemize}
\end{frame}

\begin{frame}
\frametitle{install.iso}
\begin{itemize}
\item ISO image that contains all used packages
\item the --skip-cds parameter of 'elbe create' can be used to skip the
  generation of the image
\item the --build-source parameter of 'elbe create' can be used to also generate
  a cdrom image that contains all Debian source packages
\item All mirrors configured in an elbe XML file can be replaced by an ISO image
  using the command 'elbe setcdrom'
\end{itemize}
\end{frame}

\begin{frame}
\frametitle{licence.txt}
\begin{itemize}
\item contains the licence text of all used debian packages
\end{itemize}
\end{frame}

\begin{frame}
\frametitle{rootfs.tar.gz, sdcard.img}
\begin{itemize}
\item Images or archives containing the target RFS
\item The 'target' section in the XML file describes which image and archive
  files are created; the 'fstab' section describes their content.
\end{itemize}
\end{frame}

\begin{frame}
\frametitle{source.xml}
\begin{itemize}
\item based on the XML file given to 'elbe create'
\item added a 'fullpkgs' section containing informations about all installed
  packages and their version
\item added a 'sources\_list' section that contains the used mirrors
\item added a 'apt\_prefs' section that contains the pinning settings
\item added a 'elbe\_version' section that contains the version number of
  the elbe tool that generated the file
\end{itemize}
\end{frame}

\begin{frame}
\frametitle{.stamps}
\begin{itemize}
\item status information used by the Makefile
\end{itemize}
\end{frame}

\begin{frame}
\frametitle{validation.txt}
\begin{itemize}
\item if elbe create was called with a XML file containing a 'fullpkgs' section
  the file contains informations if a package version differs
\item if a package in the 'pkg-list' was not found on one of the mirrors this
  will be logged in this file
\end{itemize}
\end{frame}

\begin{frame}[fragile]
\frametitle{Using the VM}
\begin{verbatim}
$ make run
\end{verbatim}
A Qemu with the buildenv.img will be started.
\end{frame}

\begin{frame}[fragile]
\frametitle{The ELBE XML format}
/usr/share/doc/elbe/examples/ contains a couple of examples that can be used
as templates for an own project:
\begin{verbatim}
$ ls /usr/share/doc/elbe/examples/
amd64-example.xml        beaglebone.xml
arm-complex-example.xml  i386-example.xml
arm-example.xml          ppc-example.xml
arm-wheezy-example.xml   x86-example.xml
\end{verbatim}
Take a look at the different modes and finetuning sections. Also various
iamge generation methods are used.
\end{frame}

\begin{frame}[fragile]
\frametitle{The ELBE XML format: Project setup}
\lstset{language=XML}
\begin{scriptsize}
\begin{lstlisting}
<project>
  <name>ARMexample</name>
  <version>08.15</version>
  <description>
    creates an UBI based target system without debian package management
    tools for version control and package build are added to the buildimage
  </description>
  <buildtype>armel</buildtype>
  ...
</project>
\end{lstlisting}
\end{scriptsize}
\end{frame}

\begin{frame}[fragile]
\frametitle{The ELBE XML format: Project setup}
\lstset{language=XML}
\begin{scriptsize}
\begin{lstlisting}
<project>
...
  <mirror>
    <primary_host>ftp.de.debian.org</primary_host>
    <primary_path>/debian</primary_path>
    <primary_proto>http</primary_proto>
    <url-list>
     <url>
      <binary>http://debian.linutronix.de/elbe wheezy main</binary>
      <source>http://debian.linutronix.de/elbe wheezy main</source>
     </url>
    </url-list>
  </mirror>
  <noauth />
...
</project>
\end{lstlisting}
\end{scriptsize}
\end{frame}

\begin{frame}[fragile]
\frametitle{The ELBE XML format: Project setup}
\lstset{language=XML}
\begin{scriptsize}
\begin{lstlisting}
<project>
...
  <suite>wheezy</suite>
  <buildimage>
    <kinitrd>elbe-bootstrap</kinitrd>
    <pkg-list>
      <pkg>build-essential</pkg>
      <pkg>debhelper</pkg>
      <pkg>git</pkg>
    </pkg-list>
  </buildimage>
</project>
\end{lstlisting}
\end{scriptsize}
\end{frame}

\begin{frame}[fragile]
\frametitle{The ELBE XML format: Defining a target}
\lstset{language=XML}
\begin{scriptsize}
\begin{lstlisting}
<target>
   <hostname>myARM</hostname>
   <domain>tec.linutronix.de</domain>
   <passwd>foo</passwd>
   <console>ttyS0,115200</console>
   <package>
     <tar>
       <name>nfsroot.tar.gz</name>
     </tar>
   </package>
   <finetuning>
    <rm>usr/share/doc</rm>  <!-- remove from target   -->
    <rm>/usr/share/doc</rm> <!-- remove from buildenv -->
   </finetuning>
   <pkg-list>
     <pkg>bash</pkg>
   </pkg-list>
 </target>
\end{lstlisting}
\end{scriptsize}
\end{frame}


\begin{frame}
\frametitle{ELBE modes}
\begin{itemize}
\item norecommend (can be combined with any of the other modes):
  Don't install recommended packages
\item default: target is a copy of the buildenv
\item diet: Only copy files referenced in the package management.
  Only use this for small and simple root filesystems!
\item setsel: The resulting image will just contain dpkg.
  This mode offers a finegrained control on which packages should be installed
\item tighten: ignore dependencies, this is useful for very minimalistic busybox
  based systems. Normally setsel mode should be used.
\end{itemize}
\end{frame}

\begin{frame}[fragile]
\frametitle{ELBE modes: Example}
\lstset{language=XML}
\begin{scriptsize}
\begin{lstlisting}
<target>
...
  <diet />
  <norecommend />
  <pkg-list>
          <pkg>bash</pkg>
  </pkg-list>
...
</target>
\end{lstlisting}
\end{scriptsize}
\end{frame}

\begin{frame}[fragile]
\frametitle{elbe-setsel usage}
\begin{enumerate}
\item Create package list:
\begin{verbatim}
hostpc$ make run-con
# remove all pkgs not wanted on the target
target$ dpkg --purge vim-nox libxml2-dev
# export installed package list
target$ dpkg --get-selections > selections.list
# copy list to hostpc
target$ scp selections.list 10.0.2.2:/tmp
\end{verbatim}
\item Import the package list to your xml file:
\begin{verbatim}
hostpc$ elbe setsel rfs.xml /tmp/selections.list
\end{verbatim}
\end{enumerate}
\end{frame}

\begin{frame}[fragile]
\frametitle{Using a CDROM}
\begin{itemize}
\item Each ELBE build will create a CD-ROM image with the packages
  needed for an elbe image build.
\item this ISO image can be used for future builds:
\end{itemize}
\begin{verbatim}
$ elbe setcdrom rfs.xml \
/home/user/elbe-test/install.iso
\end{verbatim}
This command removes all configured mirrors and additional urls from the XML
file and sets the given ISO image as the only mirror.
\end{frame}

\begin{frame}[fragile]
\frametitle{elbe-chg\_archive}
It is possible to include an archive into the xml file, that is unpacked into
the target RFS before and after the finetuning step:
\begin{verbatim}
$ mkdir archive/testd
$ cd archive
$ echo 'port = 1234' > archive/testd/myconfig
$ tar cjf ../archive.tar.bz2 *
$ cd ..
$ elbe chg_archive <xmlfile> archive.tar.bz2
\end{verbatim}
NOTE: The file must be a bzip2 compressed tar (.tar.bz2)
\end{frame}

\begin{frame}[fragile]
\frametitle{elbe-get\_archive}
It is also possible to extract an archive from an XML file:
\begin{verbatim}
$ elbe get_archive <xmlfile> <archive>
\end{verbatim}
\end{frame}

\begin{frame}[fragile]
\frametitle{elbe-show}
The elbe show command prints out some textual information about an
ELBE xml file:
\begin{verbatim}
$ elbe show --verbose arm-example.xml
== arm-example.xml: ARMexample - version 08.15 ==
Debian suite: wheezy/armel
[...]
\end{verbatim}
The '--verbose' parameter shows more informations, like the complete package
list.
\end{frame}

\begin{frame}[fragile]
\frametitle{elbe-xsdtoasciidoc}
Create an asciidoc documentation from an annotated XML Schema file
\begin{verbatim}
# Create asciidoc format
$ elbe xsdtoasciidoc --output=myasciidoc dbsfed.xsd
# Create HTML doc
$ asciidoc myasciidoc
\end{verbatim}
This is used to create the documentation of the ELBE XML schema.
\end{frame}

\begin{frame}[fragile]
\frametitle{elbe-checkupdates}
Use a source.xml file to check if there are updates available for an existing
image:
\begin{verbatim}
$ elbe check_updates source.xml
checking /home/user/rfs/build-release/source.xml
armel
Reading package lists... Done
Building dependency tree... Done
Reading package lists... Done
Building dependency tree... Done
adduser 3.113+nmu1 != 3.113+nmu3
1 updates required
\end{verbatim}
This can be used e.g. as cronjob to get notifications if updates are availabe.

Than the person responsible for updates can decide what needs to be done.
\end{frame}

\begin{frame}[fragile]
\frametitle{elbe-diff}
compares to RFS trees and suggests commands to update the archive tar and a
'finetuning' section:
\begin{verbatim}
$ sudo elbe diff rfs rfs-modified
suggesting:

<rm>/etc/init.d/mountall-bootclean.sh</rm>
<rm>/etc/init.d/bootmisc.sh</rm>
tar rf archive.tar -C build/rfs /sbin/dhclient-script
tar rf archive.tar -C build/rfs /etc/init.d/mountfstab.sh
\end{verbatim}
This can be used if a (nfsroot) filesystem was modified and these modifications
should be included in an ELBE XML file.
\end{frame}

\begin{frame}[fragile]
\frametitle{elbe-validate}
validates the xmlfile provided, and prints out errors:
\begin{verbatim}
$ elbe validate rfs.xml
rfs.xml:101 error Element 'type': [facet 'enumeration'] The value 'ext5' is
not an element of the set {'ext2', 'ext3', 'ext4', 'xfs', 'ubifs', 'tmpfs',
'debugfs', 'configfs', 'proc', 'sysfs', 'vfat'}.
rfs.xml:101 error Element 'type': 'ext5' is not a valid value of the atomic
type '{https://www.linutronix.de/projects/Elbe}fs_type'.
validation failed
\end{verbatim}
\dots there is an typo in the XML file line 105: ext5 instead of ext4
\end{frame}


\begin{frame}[fragile]
\frametitle{Creating UBI images}
\lstset{language=XML}
\begin{scriptsize}
\begin{lstlisting}
<images>
  <mtd>
    <name>linux.img</name>                  1
    <nr>0</nr>
    <size>60MB</size>
    <ubivg>
      <label>nand</label>
      <miniosize>2048</miniosize>
      <maxlogicaleraseblockcount>1533</maxlogicaleraseblockcount>
      <logicaleraseblocksize>126976</logicaleraseblocksize>
      <physicaleraseblocksize>128KiB</physicaleraseblocksize>
      <ubi>
        <type>static</type>
        <label>kernel</label>
        <id>0</id>
        <size>4MiB</size>
        <binary>/boot/vmlinuz</binary>
      </ubi>
      <ubi>
        <type>dynamic</type>
        <label>rfs</label>
        <id>1</id>
        <size>26MiB</size>
      </ubi>
  </mtd>
 </images>
\end{lstlisting}
\end{scriptsize}
\end{frame}

\begin{frame}[fragile]
\frametitle{Creating UBI images}
\lstset{language=XML}
\begin{scriptsize}
\begin{lstlisting}
 <fstab>
  <bylabel>
  <label>rfs</label>
  <mountpoint>/</mountpoint>
  <fs>
    <type>ubifs</type>
    <mkfs>-x lzo</mkfs>
  </fs>
  </bylabel>
 </fstab>
\end{lstlisting}
\end{scriptsize}
\end{frame}

\begin{frame}
\frametitle{BETA: elbe buildchroot}
This may replace 'elbe create; cd build; make' in the future, if reproducability
is not that important:
\begin{lstlisting}
sudo elbe buildchroot -t build-chroot -o buildchroot.log -n myrfs \
--skip-validation --skip-cdrom --debug --buildtype=armel
\end{lstlisting}
Testing and feedback is welcome!
\end{frame}

\input{tailpres}