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 \
squeeze 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{ELBE: 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{ELBE: Documentation}
\begin{itemize}
\item Have a look at /usr/share/doc/elbe/
\item Please read /usr/share/doc/elbe/elbeoverview-en.html
\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 an 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{ELBE: command overview}
Create a new project:
\begin{verbatim}
elbe create \
	--directory /home/user/example example.xml
\end{verbatim}
\end{frame}

\begin{frame}[fragile]
\frametitle{ELBE: start build}
\begin{verbatim}
cd /home/user/example
# Note: the next step might take a while
make
\end{verbatim}
\end{frame}

\begin{frame}[fragile]
\frametitle{ELBE: Using the VM}
\begin{verbatim}
cd /home/user/example
make run
# or (without graphics)
make run-con
\end{verbatim}
\end{frame}

\begin{frame}[fragile]
\frametitle{The ELBE XML format}
/usr/share/doc/elbe/examples/ contains a couple of examples:
\begin{verbatim}
$ ls -1 /usr/share/doc/elbe/examples/
amd64-example.xml
arm-complex-example.xml.gz 
arm-example.xml
i386-example.xml
\end{verbatim}
\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>
...
</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>debian.tu-bs.de</primary_host>
    <primary_path>/debian</primary_path>
    <primary_proto>http</primary_proto>
    <url-list>
     <url>
      <binary>http://debian.linutronix.de/elbe squeeze main</binary>
     </url>
    </url-list>
  </mirror>
...
</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>
...
  <noauth />
  <suite>squeeze</suite>
...
</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>
...
  <buildimage>
    <arch>armel</arch>
    <size>20G</size>
    <mem>256</mem>
    <interpreter>qemu-system-arm</interpreter>
    <kinitrd>testrd</kinitrd>
    <console>ttyAMA0,115200n1</console>
    <machine>versatilepb</machine>
    <NIC>
      <model>smc91c111</model>
      <MAC>de:ad:be:ef:be:05</MAC>
    </NIC>
    <portforwarding>
      <forward>
         <proto>tcp</proto>
         <buildenv>22</buildenv>
         <host>5022</host>
      </forward>
    </portforwarding>
    <pkg-list>
    </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>
   </finetuning>
   <pkg-list>
     <pkg>build-essential</pkg>
     <pkg>bash</pkg>
     <pkg>less</pkg>
     <pkg>git</pkg>
     <pkg>debhelper</pkg>
     <pkg>nfs-common</pkg>
     <pkg>openssh-server</pkg>
   </pkg-list>
 </target>
\end{lstlisting}
\end{scriptsize}
\end{frame}

\begin{frame}[fragile]
\frametitle{The ELBE XML format: finetuning}
\lstset{language=XML}
\begin{scriptsize}
\begin{lstlisting}
<target>
...
  <finetuning>
    <rm>/usr/share/doc</rm>
    <mv path="/var">/var_ro</mv>
    <cp path=/copy/me>/my/name/on/target</mv>
  </finetuning>
...
</target>
\end{lstlisting}
\end{scriptsize}
\end{frame}

\begin{frame}[fragile]
\frametitle{The ELBE XML format: finetuning}
\lstset{language=XML}
\begin{scriptsize}
\begin{lstlisting}
<target>
...
  <finetuning>
    <command>cp /etc/passwd etc/ </command>
  </finetuning>
...
</target>
\end{lstlisting}
\end{scriptsize}
\end{frame}

\begin{frame}
\frametitle{ELBE modes}
\begin{itemize}
\item default
\item norecommend (can be combined with any of the other modes): Don't install recommended packages
\item setsel: The resulting image will just contain dpkg. This mode offers a finegrained control on which packages should be installed
\item diet: Only copy files referenced in the package management. Only use this for small and simple root filesystems!
\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 command overview: elbe-setsel}
\begin{enumerate}
\item Create package list:
\begin{verbatim}
dpkg --get-selections > selections.list
\end{verbatim}
\item Import the package list to your xml file:
\begin{verbatim}
elbe setsel <xmlfile> 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 package (which have been used for the installation): install.iso
\item You can use this ISO image for future builds:
\begin{verbatim}
<mirror>
<cdrom>/home/user/elbe-exmpl/install.iso</cdrom>
</mirror>
\end{verbatim}
\item You can also use the elbe-setcdrom command
\end{itemize}
\end{frame}

\begin{frame}[fragile]
\frametitle{ELBE command overview: elbe-setcdrom}
\begin{verbatim}
$ elbe setcdrom mysqueeze.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 command overview: elbe-chg\_archive}
It is possible to include an archive into the xml file, that is unpacked into the target root-filesystem after the finetuning step:
\begin{verbatim}
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 command overview: 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 command overview: elbe-show}
The elbe show command prints out some textual information about an ELBE xml file:
\begin{verbatim}
$ elbe show arm-example.xml 
== arm-example.xml: ARMexample - version 08.15 ==
Debian suite: squeeze/armel
[...]
\end{verbatim}
\end{frame}

\begin{frame}[fragile]
\frametitle{ELBE command overview: 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}
\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>data</label>
    <mountpoint>/opt</mountpoint>
    <fs>
      <type>ubifs</type>
      <mkfs>-x lzo</mkfs>
    </fs>
    <options>rw</options>
  </bylabel>
  <bylabel>
  <label>rfs</label>
  <mountpoint>/</mountpoint>
  <fs>
    <type>ubifs</type>
    <mkfs>-x lzo</mkfs>
  </fs>
  <options>ro</options>
  </bylabel>
  <bydev>
  <source>proc</source>
  <mountpoint>/proc</mountpoint>
  <fs>
    <type>proc</type>
  </fs>
  </bydev>
 </fstab>
\end{lstlisting}
\end{scriptsize}
\end{frame}
\input{tailpres}