View source for Documents/Development on Debian Sarge

<div id="content">

= Nut/OS Development on Debian Sarge [[File:debian-logo.png|[Logo]]] =

<br />
<br />
<br />
'''THIS DOCUMENT IS OUTDATED. A more recent version is available [[Documents/Development on Debian|here]].'''<br />
<br />
<br />
<br />
<br />


Currently there's no up-to-date package available for Debian. Thus, you need to build the Nut/OS Development Environment from the source package. Most required minimum versions of all required tools may not be available in the Debian stable tree. We generally used testing, but be warned, that mixing stable and testing releases on your system may introduce unforeseen problems.

You have the choice to build..

* ...the full installation including the Nut/OS Configurator GUI or
* ...the command line installation including the Nut/OS Configurator command line tool or
* ...the minimal installation without the Nut/OS Configurator

Both versions of the Configurator, the GUI type and the command line tool require Lua, an extension programming language. The GUI version additionally requires GTK+ and wxWidgets, a cross-platform C++ GUI framework.

You can also choose to include or exclude the API Documentation from the build process. This documentation is created from comment lines within the source files by using Doxygen and GraphViz.

It's recommended to try the full installation first. If it fails for some reason, you may step down to a less complete installation.

== Full Installation ==

=== GNU Compiler Collection ===

First check, that at least the following versions of the GNU Compilers are available.

<pre class="coding">$ gcc --version
gcc (GCC) 3.3.5
$ g++ --version
g++ (GCC) 3.3.5                  
                  </pre>
Previous versions may work, but haven't been tested.
=== GNU Autotools ===

Next you need to make sure to have the current version of the GNU autotools installed.

<pre class="coding">$ autoconf --version
autoconf (GNU Autoconf) 2.59
$ automake --version
automake (GNU automake) 1.9.5
                  </pre>
To upgrade, use
<pre class="coding">$ apt-get install autoconf
  1 http://ftp.de.debian.org testing/main autoconf 2.59a-3 [381kB]
                  </pre>
and
<pre class="coding">$ apt-get install automake1.9
  1 http://ftp.de.debian.org testing/main autotools-dev 20050422.1 [55,9kB]
  2 http://ftp.de.debian.org testing/main automake1.9 1.9.5-1 [505kB]
                  </pre>
=== GTK+ Development Package ===

As mentioned above, the Configurator's GUI is based on wxWidgets, which uses GTK+ on Linux systems. Use

<pre class="coding">$ apt-get install libgtk2.0-dev
  1 http://ftp.de.debian.org testing/main libglib2.0-dev 2.6.4-1 [469kB]
  2 http://ftp.de.debian.org testing/main libatk1.0-dev 1.8.0-4 [95,4kB]
  3 http://ftp.de.debian.org testing/main libexpat1-dev 1.95.8-3 [126kB]
  4 http://ftp.de.debian.org testing/main zlib1g-dev 1:1.2.2-4 [488kB]
  5 http://ftp.de.debian.org testing/main libfreetype6-dev 2.1.7-2.4 [695kB]
  6 http://ftp.de.debian.org testing/main libfontconfig1-dev 2.3.1-2 [398kB]
  7 http://ftp.de.debian.org testing/main x-dev 4.3.0.dfsg.1-12 [213kB]
  8 http://ftp.de.debian.org testing/main libxext-dev 4.3.0.dfsg.1-12.0.1 [244kB]
  9 http://ftp.de.debian.org testing/main libxi-dev 4.3.0.dfsg.1-12.0.1 [228kB]
 10 http://ftp.de.debian.org testing/main libxv-dev 4.3.0.dfsg.1-12.0.1 [187kB]
 11 http://ftp.de.debian.org testing/main xlibs-static-dev 4.3.0.dfsg.1-12.0.1 [851kB]
 12 http://ftp.de.debian.org testing/main libx11-dev 4.3.0.dfsg.1-12.0.1 [1355kB]
 13 http://ftp.de.debian.org testing/main render-dev 0.8-4 [25,1kB]
 14 http://ftp.de.debian.org testing/main libxrender-dev 0.8.3-7 [28,2kB]
 15 http://ftp.de.debian.org testing/main libxft-dev 2.1.7-1 [66,3kB]
 16 http://ftp.de.debian.org testing/main libpango1.0-dev 1.8.1-1 [284kB]
 17 http://ftp.de.debian.org testing/main libgtk2.0-dev 2.6.4-1 [7235kB]
                  </pre>
to install the development package of the GTK+ 2.0 library. At least on our system a large number of additional packages are installed or replaced.
=== wxWidgets Libraries ===

Now we are ready to install wxWidgets. At the time of this writing there was no Debian package available. Thus we install it from the sources. Download wxGTK-2.8.0.tar.gz from [http://www.wxwidgets.org/ www.wxwidgets.org] and

<pre class="coding">$ tar xzf wxGTK-2.8.0.tar.gz
$ cd wxGTK-2.8.0/
$ mkdir build-gtk2-ansi-static
$ cd build/
$ ../configure --disable-shared
Configured wxWidgets 2.8.0 for `i686-pc-linux-gnu'

  Which GUI toolkit should wxWidgets use?                 GTK+ 2
  Should wxWidgets be compiled into single library?       no
  Should wxWidgets be compiled in debug mode?             no
  Should wxWidgets be linked as a shared library?         no
  Should wxWidgets be compiled in Unicode mode?           no
  What level of wxWidgets compatibility should be enabled?
                                       wxWidgets 2.4      no
                                       wxWidgets 2.6      yes
  Which libraries should wxWidgets use?
                                       jpeg               builtin
                                       png                builtin
                                       regex              sys
                                       tiff               builtin
                                       zlib               sys
                                       odbc               no
                                       expat              sys
                                       libmspack          no
                                       sdl                no
                                       gnomeprint         no
                  </pre>
Due to several problems with shared libraries we prefer to build the static ones only. Anyway, shared libraries may work for you. Now type
<pre class="coding">$ make
  ...lots of output lines, finally ending with...
  ranlib lib/libwx_gtk2_xrc-2.8.a
  (test -d utils/wxrc &amp;&amp; cd utils/wxrc &amp;&amp; make all) || true
  make[1]: Entering directory `/home/harald/wxGTK-2.8.0/build/utils/wxrc'
  ../.././bk-deps g++ -c -o wxrc_wxrc.o -D__WXGTK__     -I../../../utils/wxrc  -DwxUSE_GUI=0 \
  -DGTK_NO_CHECK_CASTS -I../../lib/wx/include/gtk2-ansi-release-static-2.8 \
  -I../../../include -DXTHREADS -pthread -I/usr/include/gtk-2.0 -I/usr/lib/gtk-2.0/include \
  -I/usr/X11R6/include -I/usr/include/atk-1.0 -I/usr/include/pango-1.0 -I/usr/include/freetype2 \
  -I/usr/include/glib-2.0 -I/usr/lib/glib-2.0/include -D_FILE_OFFSET_BITS=64 -D_LARGE_FILES \
  -D_LARGEFILE_SOURCE=1 -O2 -pthread -Wall -Wno-ctor-dtor-privacy ../../../utils/wxrc/wxrc.cpp
  g++ -o wxrc wxrc_wxrc.o -pthread   -L/usr/X11R6/lib    -L../../lib   -lwx_base_xml-2.8 \
  -lexpat -lwx_base-2.8   -lwxtiff-2.8 -lwxjpeg-2.8 -lwxpng-2.8 -pthread -L/usr/X11R6/lib \
  -lz -ldl -lm
  make[1]: Leaving directory `/home/harald/wxGTK-2.8.0/build/utils/wxrc'
                  </pre>
and, as root
<pre class="coding"># make install
 ...after some output the result is...
 ------------------------------------------------------

 The installation of wxWidgets is finished.  On certain
 platforms (e.g. Linux) you'll now have to run ldconfig
 if you installed a shared library and also modify the
 LD_LIBRARY_PATH (or equivalent) environment variable.

 wxWidgets comes with no guarantees and doesn't claim
 to be suitable for any purpose.

 Read the wxWidgets Licence on licencing conditions.

 ------------------------------------------------------
                  </pre>
To check the installtion, try

<pre class="coding">$ cd samples
$ make
$ cd aui
$ ./auidemo
                  </pre>
The last command should open a sample application window with dockable toolbars. This means the wxWidgets installation is working.
=== Lua Language ===

In the next step we are going to install the Lua language, which is used later by the Nut/OS Configurator to parse the configuration files. Although there may be readily build binary packages, it is recommended to build from the source. Download lua-5.0.2.tar.gz from [http://www.lua.org www.lua.org] and

<pre class="coding">$ gzip -d downloads/lua-5.0.2.tar.gz
$ tar xf downloads/lua-5.0.2.tar
$ cd lua-5.0.2/                  
                  </pre>
The Lua source archive doesn't provide a configure script. Instead it comes with a prepared Makefile, which includes a file named config. This file allows to modify several build options. On our system the original file worked fine, but you may at least have a look to the contents. To build the Lua tools and libraries, type
<pre class="coding">$ make
                  </pre>
and, after it finished without error, become a root user and type
<pre class="coding"># make install
...
 cp bin/* /usr/local/bin
 cp include/*.h /usr/local/include
 cp lib/*.a /usr/local/lib
 cp doc/*.1 /usr/local/man/man1
                  </pre>
=== Doxygen And GraphViz ===

The Nut/OS API Documentation will be build automatically from the source code. For this we need to install

* Doxygen 1.4.1 or later
* GraphViz 2.2.1 or later

Luckily, Debian binary packages are available.
<pre class="coding">$ apt-get install doxygen doxygen-doc graphviz
  1 http://ftp.de.debian.org testing/main doxygen 1.4.2-3 [1349kB]
  2 http://ftp.de.debian.org testing/main doxygen-doc 1.4.2-3 [1100kB]
  3 http://ftp.de.debian.org testing/main graphviz 2.2.1-1 [971kB]
                  </pre>
On Windows we have had several problems with all Doxygen versions above 1.4.1, but nothing really important. Some duplicate entries may be created or the structure of the contents may not appear as intended. In general all versions upto 1.4.4 create a usable documentation.
=== Installing Nut/OS ===

No we got everything on our system to install the Nut/OS source package. Well, in fact the AVR or ARM toolchain is missing to build the Nut/OS libraries and sample applications. But these are build later with the Nut/OS Configurator and therefore the platform specific toolchains are not yet required.

Download ethernut-4.3.1.tar.bz2 from http://www.ethernut.de and

<pre class="coding">$ bzip2 -d ethernut-4.3.1.tar.bz2
$ tar xf ethernut-4.3.1.tar.bz2
$ cd ethernut-4.3.1/
$ ./configure
  ====================================================================
    Your Nut/OS development environment has been configured.
    After running make and make install, you may...
    ... run nutconf or nutconfigure to set up a Nut/OS build tree.
    ... or run ./nutsetup to set up the environment for building
        Nut/OS in the source tree.
  ====================================================================
                  </pre>
The next command will take a quite long time to finish.

<pre class="coding">$ make
...after a long time...
  g++  -g -O2 -o nutconf  nutconf-nutconf.o nutcomponent.o nutconf-appoptdlg.o \
  nutconf-bldoptdlg.o nutconf-configitem.o nutconf-configtree.o nutconf-enumeditctrl.o \
  nutconf-iconinfo.o nutconf-iconlist.o nutconf-infowindow.o nutconf-inteditctrl.o \
  nutconf-mainframe.o nutconf-nutconfdoc.o nutconf-nutconfhint.o nutconf-nutconfview.o \
  nutconf-propertylist.o nutconf-repoptdlg.o nutconf-scrolledtree.o nutconf-settings.o \
  nutconf-settingsdlg.o nutconf-splitscroll.o nutconf-texteditctrl.o nutconf-tooloptdlg.o \
  nutconf-treecomp.o nutconf-treeitemdata.o nutconf-utils.o nutconf-valuewindow.o \
  -llua -llualib -L/usr/local/lib -pthread   -L/usr/X11R6/lib  /usr/local/lib/libwx_gtk2_xrc-2.8.a \
  /usr/local/lib/libwx_gtk2_qa-2.8.a /usr/local/lib/libwx_gtk2_html-2.8.a \
  /usr/local/lib/libwx_gtk2_adv-2.8.a /usr/local/lib/libwx_gtk2_core-2.8.a \
  /usr/local/lib/libwx_base_xml-2.8.a /usr/local/lib/libwx_base_net-2.8.a \
  /usr/local/lib/libwx_base-2.8.a -Wl,--export-dynamic -pthread -lgtk-x11-2.0 \
  -lgdk-x11-2.0 -latk-1.0 -lgdk_pixbuf-2.0 -lpangoxft-1.0 -lpangox-1.0 -lpango-1.0 \
  -lgobject-2.0 -lgmodule-2.0 -lgthread-2.0 -lglib-2.0 -lXinerama -lXxf86vm -lexpat \
  -lwxtiff-2.8 -lwxjpeg-2.8 -lwxpng-2.8 -lz -ldl -lm
                  </pre>
Now change to the root user and type
<pre class="coding">$ make install
                  </pre>
This should install the three executables
* crurom, UROM file system creator
* nutconfigure, Nut/OS Configurator for the command line
* nutconf, full fledged Nut/OS Configurator GUI

in /usr/local/bin/.
=== Building Nut/OS ===

As a final step we have to install the proper GCC toolchain to cross compile Nut/OS libraries and applications on Linux.

For the AVR platform use

<pre class="coding">$ apt-get install gcc-avr
  1 http://ftp.de.debian.org testing/main binutils-avr 2.15-3 [2336kB]
  2 http://ftp.de.debian.org testing/main gcc-avr 1:3.4.3-2 [3170kB]
$ apt-get install avr-libc
  1 http://ftp.de.debian.org testing/main avr-libc 1:1.2.3-3 [1298kB]
                  </pre>
Now you should be able to run the Configurator
<pre class="coding">$ cd ~/ethernut-4.3.1/                  
$ nutconf                  
                  </pre>
and follow the [[../../pdf/enswm28e.pdf|Nut/OS Software Manual]] to build Nut/OS and the related sample applications.
== Installation With Command Line Tools Only ==

In case you experience problems with GTK+ or wxWidgets, or simply refuse to use GUI tools for building embedded applications, you can install a reduced version. Beside GUI gimmicks, you won't miss anything.

Install the same packages as described in the full installation, except

* GTK+ Development Package
* wxWidgets Libraries

After downloading and unpacking ethernut-4.3.1.tar.bz2, configure the package with an additional option.

<pre class="coding">$ cd ethernut-4.3.1/
$ ./configure --disable-nutconf-gui
$ make
$ make install
                  </pre>
Now you can consult the [[../../pdf/enswm28e.pdf|Nut/OS Software Manual]] about how to build the Nut/OS libraries and sample applications. Except, the GUI Configurator will not be available and separate build trees or sample directories have to be created on the command line.

=== Using nutconfigure ===

To create a build tree for Ethernut 1.3 Rev-G, you may use

<pre class="coding">$ cd ethernut-4.3.1/
$ nutconfigure -bnutbld-13g-gcc -cnut/conf/ethernut13g.conf -lnutbld-13g-gcc/lib \
-mavr-gcc create-buildtree
                  </pre>
This will read the configuration file nut/conf/ethernut13g.conf, create a new directory nutbld-13g-gcc/ with all required Makefiles and specify nutbld-13g-gcc/lib/ as the target directory for the libraries. Now change to the build tree and use make to build the libraries for Ethernut 1.3.
<pre class="coding">$ cd nutbld-13g-gcc/
$ make install
                  </pre>
In case you want to build another set of libraries for the GameBoy Advance, use

<pre class="coding">$ cd ethernut-4.3.1/
$ nutconfigure -bnutbld-gba-gcc -cnut/conf/gbaxport2.conf -lnutbld-gba-gcc/lib \
-marm-gcc create-buildtree
$ cd nutbld-gba-gcc/
$ make install
                  </pre>
In order to create an application tree for the Ethernut 1.3 board, which uses the libraries from the build tree created previously, use

<pre class="coding">$ nutconfigure -anutapp-13g-gcc -b../../nutbld-13g-gcc -cnut/conf/ethernut13g.conf \
-lnutbld-13g-gcc/lib -mavr-gcc create-apptree
$ echo &quot;# Ethernut 1.3&quot; &gt;nutapp-13g-gcc/UserConf.mk
                  </pre>
The second command is required to destroy the default UserConf.mk. That's because nutconfigure will create one for Ethernut 2 by default. These board versions are equipped with different Ethernet Controller Chips and applications are typically build for one specific chip only to save program space.
The [[../../pdf/enswm28e.pdf|Nut/OS Software Manual]] will further explain how to build a few sample applications and run them on Ethernut or any other compatible hardware.

== Minimum Installation ==

Some people experience problems with installing Lua, which is also required by the command line based Configurator. You still need

* GNU Compiler Collection 3.3.5 or above
* AVR or ARM Toolchain
* Doxygen 1.4.1 and GraphViz 2.2.1 or later

To completely exclude the Configurator, configure Nut/OS with
<pre class="coding">$ cd ethernut-4.3.1/
$ ./configure --disable-nutconf-tools
$ make
$ make install
                  </pre>
This will still build the crurom utility and the API documentation. In case of problems with Doxygen or GraphViz, the latter can be excluded from the build as well:
<pre class="coding">$ cd ethernut-4.3.1/
$ ./configure --disable-nutconf-tools --disable-html-docs
$ make
$ make install
                  </pre>
The latest release of the API documentation is also available online at www.ethernut.de.
With the minimum installation it is quite difficult to create your Nut/OS libraries in a separate build tree. As long as you are developing for a specific single target, this is no big loss though. You can still build Nut/OS libraries in the source tree.

<pre class="coding">$ cd ethernut-4.3.1/nut/
$ ./nutsetup
                  </pre>
The nutsetup script will create a file named UserConf.mk used by make and will create a link of Makedefs, Makerules, app/Makedefs and app/Makerules to the platform specific files. For the AVR platform the link will point to Makedefs.avr-gcc, Makerules.avr-gcc, app/Makedefs.avr-gcc and app(Makerules.avr-gcc resp. For the Nut/OS emulation on the UNIX, it will also create a few additional header files in include/. Now type
<pre class="coding">$ cd lib/
$ make install
                  </pre>
The last command will build all required Nut/OS libraries in a platform specific subdirectory of lib/. You can finally change to one of the subdirectories in app/ and create one of the sample applications.
<pre class="coding">$ cd ethernut-4.3.1/nut/app/httpd
$ make
                  </pre>
Several applications, like the one chosen here, require the crurom utility. This is a quite simple application. Even if the whole Nut/OS configuration fails somehow, you should be able to create this tool manually. You'll find the sources in tools/crurom.
== Getting Nut/OS From CVS ==

Instead of downloading the source package, you may retrieve the latest updates from the CVS repository.

<pre class="coding">$ cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/ethernut login
$ cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/ethernut co nut</pre>
Simply press enter when prompted for a password.
The CVS repository will not contain files, which can be created locally. This is also true for some default files used by automake. Thus, after checking out the module for the first time, enter

<pre class="coding">$ automake --add-missing</pre>
A script named reconf had been prepared to run the autotools. Run it.
<pre class="coding">$ ./reconf</pre>
We are now ready to configure, make and install the Nut/OS development environment.

<pre class="coding">$ ./configure
$ make
$ make install</pre>
== Related Links ==

[http://www.ethernut.de/nutwiki NutWiki]<br />
Contains a collection of links.

[http://packages.debian.org/testing/devel Debian Packages]<br />
Devel section of Debian software packages in the testing distribution.

<br />
<br />

Good luck,<br />
Harald Kipp<br />
Herne, 5th of August 2005


</div>