From f8b811b951def89677e6c38d04f653d79885de4d Mon Sep 17 00:00:00 2001
From: Manuel Traut <manut@linutronix.de>
Date: Fri, 3 Jan 2014 17:07:59 +0100
Subject: update to elbe v0.5.5-git

Signed-off-by: Manuel Traut <manut@linutronix.de>
---
 distribution/elbe-usage/pres_elbe-usage_en.tex | 393 ++++++++++++++++---------
 1 file changed, 248 insertions(+), 145 deletions(-)

(limited to 'distribution/elbe-usage/pres_elbe-usage_en.tex')

diff --git a/distribution/elbe-usage/pres_elbe-usage_en.tex b/distribution/elbe-usage/pres_elbe-usage_en.tex
index 8e37ad5..7965509 100644
--- a/distribution/elbe-usage/pres_elbe-usage_en.tex
+++ b/distribution/elbe-usage/pres_elbe-usage_en.tex
@@ -15,7 +15,7 @@ ELBE is a Debian based system to generate root-filesystems for embedded devices
 \begin{verbatim}
 # On a Debian based system
 $ echo 'deb http://debian.linutronix.de/elbe \
-squeeze main' >> /etc/apt/sources.list
+wheezy main' >> /etc/apt/sources.list
 $ aptitude install elbe
 \end{verbatim}
 Or get the latest source from github:
@@ -25,7 +25,7 @@ git clone https://github.com/Linutronix/elbe.git
 \end{frame}
 
 \begin{frame}
-\frametitle{ELBE: Overview}
+\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
@@ -34,10 +34,11 @@ git clone https://github.com/Linutronix/elbe.git
 \end{frame}
 
 \begin{frame}
-\frametitle{ELBE: Documentation}
+\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}
 
@@ -60,50 +61,151 @@ git clone https://github.com/Linutronix/elbe.git
 \begin{frame}
 \frametitle{The ELBE workflow}
 \begin{enumerate}
-\item Create an XML file
+\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{ELBE: command overview}
+\frametitle{command overview}
 Create a new project:
 \begin{verbatim}
-elbe create \
+$ elbe create \
 	--directory /home/user/example example.xml
 \end{verbatim}
 \end{frame}
 
 \begin{frame}[fragile]
-\frametitle{ELBE: start build}
+\frametitle{start build}
 \begin{verbatim}
-cd /home/user/example
-# Note: the next step might take a while
-make
+$ 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{ELBE: Using the VM}
+\frametitle{generated files}
 \begin{verbatim}
-cd /home/user/example
-make run
-# or (without graphics)
-make run-con
+$ 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:
+/usr/share/doc/elbe/examples/ contains a couple of examples that can be used
+as templates for an own project:
 \begin{verbatim}
-$ ls -1 /usr/share/doc/elbe/examples/
-amd64-example.xml
-arm-complex-example.xml.gz 
-arm-example.xml
-i386-example.xml
+$ 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]
@@ -114,7 +216,12 @@ i386-example.xml
 <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}
@@ -128,30 +235,17 @@ i386-example.xml
 <project>
 ...
   <mirror>
-    <primary_host>debian.tu-bs.de</primary_host>
+    <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 squeeze main</binary>
+      <binary>http://debian.linutronix.de/elbe wheezy main</binary>
+      <source>http://debian.linutronix.de/elbe wheezy main</source>
      </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}
@@ -165,29 +259,15 @@ i386-example.xml
 \begin{lstlisting}
 <project>
 ...
+  <suite>wheezy</suite>
   <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>
+    <kinitrd>elbe-bootstrap</kinitrd>
     <pkg-list>
+      <pkg>build-essential</pkg>
+      <pkg>debhelper</pkg>
+      <pkg>git</pkg>
     </pkg-list>
   </buildimage>
-...
 </project>
 \end{lstlisting}
 \end{scriptsize}
@@ -209,62 +289,30 @@ i386-example.xml
      </tar>
    </package>
    <finetuning>
+    <rm>usr/share/doc</rm>  <!-- remove from target   -->
+    <rm>/usr/share/doc</rm> <!-- remove from buildenv -->
    </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!
+\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}
 
@@ -277,7 +325,6 @@ i386-example.xml
 ...
   <diet />
   <norecommend />
-
   <pkg-list>
           <pkg>bash</pkg>
   </pkg-list>
@@ -288,15 +335,21 @@ i386-example.xml
 \end{frame}
 
 \begin{frame}[fragile]
-\frametitle{ELBE command overview: elbe-setsel}
+\frametitle{elbe-setsel usage}
 \begin{enumerate}
 \item Create package list:
 \begin{verbatim}
-dpkg --get-selections > selections.list
+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}
-elbe setsel <xmlfile> selections.list
+hostpc$ elbe setsel rfs.xml /tmp/selections.list
 \end{verbatim}
 \end{enumerate}
 \end{frame}
@@ -304,56 +357,57 @@ elbe setsel <xmlfile> selections.list
 \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
+\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}
-\end{frame}
-
-\begin{frame}[fragile]
-\frametitle{ELBE command overview: elbe-setcdrom}
 \begin{verbatim}
-$ elbe setcdrom mysqueeze.xml \
+$ 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.
+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:
+\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}
-elbe chg_archive <xmlfile> archive.tar.bz2
+$ 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 command overview: elbe-get\_archive}
+\frametitle{elbe-get\_archive}
 It is also possible to extract an archive from an XML file:
 \begin{verbatim}
-elbe get_archive <xmlfile> <archive>
+$ 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:
+\frametitle{elbe-show}
+The elbe show command prints out some textual information about an
+ELBE xml file:
 \begin{verbatim}
-$ elbe show arm-example.xml 
+$ elbe show --verbose arm-example.xml
 == arm-example.xml: ARMexample - version 08.15 ==
-Debian suite: squeeze/armel
+Debian suite: wheezy/armel
 [...]
 \end{verbatim}
+The '--verbose' parameter shows more informations, like the complete package
+list.
 \end{frame}
 
 \begin{frame}[fragile]
-\frametitle{ELBE command overview: elbe-xsdtoasciidoc}
+\frametitle{elbe-xsdtoasciidoc}
 Create an asciidoc documentation from an annotated XML Schema file
 \begin{verbatim}
 # Create asciidoc format
@@ -361,8 +415,62 @@ $ 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}
@@ -404,15 +512,6 @@ $ asciidoc myasciidoc
 \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>
@@ -420,17 +519,21 @@ $ asciidoc myasciidoc
     <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}
+
+\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}
-- 
cgit v1.2.3


From 515da1c9119646ea3c100c918839f0ac933332c7 Mon Sep 17 00:00:00 2001
From: Manuel Traut <manut@linutronix.de>
Date: Tue, 7 Jan 2014 08:21:05 +0100
Subject: remove BETA from elbe buildchroot

..and call it sth. like proof of concept

Signed-off-by: Manuel Traut <manut@linutronix.de>
---
 distribution/elbe-usage/pres_elbe-usage_en.tex | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)

(limited to 'distribution/elbe-usage/pres_elbe-usage_en.tex')

diff --git a/distribution/elbe-usage/pres_elbe-usage_en.tex b/distribution/elbe-usage/pres_elbe-usage_en.tex
index 7965509..b605f81 100644
--- a/distribution/elbe-usage/pres_elbe-usage_en.tex
+++ b/distribution/elbe-usage/pres_elbe-usage_en.tex
@@ -525,10 +525,9 @@ validation failed
 \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{frame}[fragile]
+\frametitle{Future? elbe buildchroot}
+Something like this may be used in the future:
 \begin{lstlisting}
 sudo elbe buildchroot -t build-chroot -o buildchroot.log -n myrfs \
 --skip-validation --skip-cdrom --debug --buildtype=armel
-- 
cgit v1.2.3


From d7da5da17cad611293c655860b9656d4156eaa1f Mon Sep 17 00:00:00 2001
From: Manuel Traut <manut@linutronix.de>
Date: Tue, 7 Jan 2014 11:23:29 +0100
Subject: elbe-usage: include elbe pkgdiff

Signed-off-by: Manuel Traut <manut@linutronix.de>
---
 distribution/elbe-usage/pres_elbe-usage_en.tex | 12 ++++++++++++
 1 file changed, 12 insertions(+)

(limited to 'distribution/elbe-usage/pres_elbe-usage_en.tex')

diff --git a/distribution/elbe-usage/pres_elbe-usage_en.tex b/distribution/elbe-usage/pres_elbe-usage_en.tex
index b605f81..452d678 100644
--- a/distribution/elbe-usage/pres_elbe-usage_en.tex
+++ b/distribution/elbe-usage/pres_elbe-usage_en.tex
@@ -455,6 +455,18 @@ 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-pkgdiff}
+compares to RFS trees and displays the difference of the installed packages
+\begin{verbatim}
+$ sudo elbe pkgdiff `pwd`/rfs `pwd`/rfs-modified
+-<pkg>firmware-ivtv</pkg>
+-<pkg>firmware-ipw2x00</pkg>
+\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:
-- 
cgit v1.2.3

