Documents/Development on Debian Sarge

From Nutwiki
Revision as of 16:11, 13 July 2017 by Harald (Talk | contribs) (Nut/OS Development on Debian Sarge [Logo])

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Nut/OS Development on Debian Sarge [Logo]

THIS DOCUMENT IS OUTDATED. A more recent version is available here.

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.

$ gcc --version
gcc (GCC) 3.3.5
$ g++ --version
g++ (GCC) 3.3.5                  

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.

$ autoconf --version
autoconf (GNU Autoconf) 2.59
$ automake --version
automake (GNU automake) 1.9.5

To upgrade, use

$ apt-get install autoconf
  1 testing/main autoconf 2.59a-3 [381kB]


$ apt-get install automake1.9
  1 testing/main autotools-dev 20050422.1 [55,9kB]
  2 testing/main automake1.9 1.9.5-1 [505kB]

GTK+ Development Package

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

$ apt-get install libgtk2.0-dev
  1 testing/main libglib2.0-dev 2.6.4-1 [469kB]
  2 testing/main libatk1.0-dev 1.8.0-4 [95,4kB]
  3 testing/main libexpat1-dev 1.95.8-3 [126kB]
  4 testing/main zlib1g-dev 1:1.2.2-4 [488kB]
  5 testing/main libfreetype6-dev 2.1.7-2.4 [695kB]
  6 testing/main libfontconfig1-dev 2.3.1-2 [398kB]
  7 testing/main x-dev 4.3.0.dfsg.1-12 [213kB]
  8 testing/main libxext-dev 4.3.0.dfsg.1-12.0.1 [244kB]
  9 testing/main libxi-dev 4.3.0.dfsg.1-12.0.1 [228kB]
 10 testing/main libxv-dev 4.3.0.dfsg.1-12.0.1 [187kB]
 11 testing/main xlibs-static-dev 4.3.0.dfsg.1-12.0.1 [851kB]
 12 testing/main libx11-dev 4.3.0.dfsg.1-12.0.1 [1355kB]
 13 testing/main render-dev 0.8-4 [25,1kB]
 14 testing/main libxrender-dev 0.8.3-7 [28,2kB]
 15 testing/main libxft-dev 2.1.7-1 [66,3kB]
 16 testing/main libpango1.0-dev 1.8.1-1 [284kB]
 17 testing/main libgtk2.0-dev 2.6.4-1 [7235kB]

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 and

$ 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

Due to several problems with shared libraries we prefer to build the static ones only. Anyway, shared libraries may work for you. Now type

$ make
  ...lots of output lines, finally ending with...
  ranlib lib/libwx_gtk2_xrc-2.8.a
  (test -d utils/wxrc && cd utils/wxrc && 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'

and, as root

# 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.


To check the installtion, try

$ cd samples
$ make
$ cd aui
$ ./auidemo

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 and

$ gzip -d downloads/lua-5.0.2.tar.gz
$ tar xf downloads/lua-5.0.2.tar
$ cd lua-5.0.2/                  

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

$ make

and, after it finished without error, become a root user and type

# 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

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.

$ apt-get install doxygen doxygen-doc graphviz
  1 testing/main doxygen 1.4.2-3 [1349kB]
  2 testing/main doxygen-doc 1.4.2-3 [1100kB]
  3 testing/main graphviz 2.2.1-1 [971kB]

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 and

$ 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.

The next command will take a quite long time to finish.

$ 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

Now change to the root user and type

$ make install

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

$ apt-get install gcc-avr
  1 testing/main binutils-avr 2.15-3 [2336kB]
  2 testing/main gcc-avr 1:3.4.3-2 [3170kB]
$ apt-get install avr-libc
  1 testing/main avr-libc 1:1.2.3-3 [1298kB]

Now you should be able to run the Configurator

$ cd ~/ethernut-4.3.1/                  
$ nutconf                  

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.

$ cd ethernut-4.3.1/
$ ./configure --disable-nutconf-gui
$ make
$ make install

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

$ cd ethernut-4.3.1/
$ nutconfigure -bnutbld-13g-gcc -cnut/conf/ethernut13g.conf -lnutbld-13g-gcc/lib \
-mavr-gcc create-buildtree

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.

$ cd nutbld-13g-gcc/
$ make install

In case you want to build another set of libraries for the GameBoy Advance, use

$ 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

In order to create an application tree for the Ethernut 1.3 board, which uses the libraries from the build tree created previously, use

$ nutconfigure -anutapp-13g-gcc -b../../nutbld-13g-gcc -cnut/conf/ethernut13g.conf \
-lnutbld-13g-gcc/lib -mavr-gcc create-apptree
$ echo "# Ethernut 1.3" >nutapp-13g-gcc/

The second command is required to destroy the default 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

$ cd ethernut-4.3.1/
$ ./configure --disable-nutconf-tools
$ make
$ make install

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:

$ cd ethernut-4.3.1/
$ ./configure --disable-nutconf-tools --disable-html-docs
$ make
$ make install

The latest release of the API documentation is also available online at 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.

$ cd ethernut-4.3.1/nut/
$ ./nutsetup

The nutsetup script will create a file named 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

$ cd lib/
$ make install

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.

$ cd ethernut-4.3.1/nut/app/httpd
$ make

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.

$ cvs login
$ cvs -z3 co nut

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

$ automake --add-missing

A script named reconf had been prepared to run the autotools. Run it.

$ ./reconf

We are now ready to configure, make and install the Nut/OS development environment.

$ ./configure
$ make
$ make install

Related Links

Contains a collection of links.

Debian Packages
Devel section of Debian software packages in the testing distribution.

Good luck,
Harald Kipp
Herne, 5th of August 2005