Ethernut Home Hardware Firmware Tools Download Community
Search | Legals | Deutsch

Nut/OS Development on Debian   [Logo]

Currently there's no binary package available for Debian. Thus, you need to build the Nut/OS development environment from the source package.

This document will explain, how to install all tools you need to create Nut/OS applications on a Debian Linux PC. In general, this should also work for other Unix-like operating systems, including Mac OS X.

Short Version

If you are an experienced user and refuse to read lengthy descriptions, then you may try the following command sequence:

sudo apt-get install automake autoconf
sudo apt-get install libtool
sudo apt-get install build-essential
sudo apt-get install doxygen doxygen-doc graphviz
sudo apt-get install lua5.1 liblua5.1-0 liblua5.1-0-dev
sudo apt-get install libgtk2.0-dev
sudo apt-get install libqtcore4 libqtgui4 libqt4-dev
mkdir ~/ethernut
cd ~/ethernut
tar xzf ethernut-5.0.5.tar.gz
ln -s ethernut-5.0.5 nut
cd nut/
sudo make install

Next install the cross compiler toolchain for your target system. For AVR boards this is simple:

sudo apt-get install binutils-avr gcc-avr avr-libc avrdude

For ARM based target boards we recommend the arm-eCross-eabi toolchain provided by thermotemp embedded systems.

For other targets you can build the toolchain from the source code. Several resources are available in the Internet to help with this.

When done, start the Configurator...

cd ~/ethernut/
qnutconf &

and follow the Nut/OS Software Manual.


Before delving into the details of the installation, we will give a first overview.

The following GNU tools are required to configure and build a minimal Nut/OS development environment:

Furthermore, you need a so called cross toolchain, which allows us to create binaries on a Linux host, which will later run on our target board. When developing for 8-bit AVR, we need

while for 32-bit ARM development the following tools are recommended

You have the choice to install different options of the development environment. Depending on this, additional tools may be required, as shown in the following table.

Module Provisions Additional Requirements Exclude with
Nut/OS Sources
  • Target selection via shell script
  • Configurable by editing C header files
  • Tool for creating simple file system images
  • None Always enabled
    CLI Configurator
  • Multiple build and application trees
  • Automated script based target configuration
  • Batch build
  • Lua 5.1 libraries
    UROM Image Creator
  • Creates simple filesystem images
  • C compiler
  • --disable-crurom
    GUI Configurator
    wxWidgets version
  • Easy to use configuration interface
  • Multiple build and application trees
  • Automated script based target configuration
  • Lua 5.1 libraries
  • wxWidgets 2.9 libraries
  • GNU C++ compiler
  • --disable-nutconf
    GUI Configurator
    Qt version
  • Easy to use configuration interface
  • Multiple build and application trees
  • Automated script based target configuration
  • Lua 5.1 libraries
  • Qt4 libraries
  • GNU C++ compiler
  • --disable-qnutconf
    GUI Discoverer
    wxWidgets version
  • Scans local and remote networks for Nut/OS nodes
  • Remote configuration of Nut/OS nodes
  • wxWidgets 2.9.3 libraries
  • GNU C++ compiler
  • --disable-nutdisc
    GUI Discoverer
    Qt version
  • Scans local networks for Nut/OS nodes
  • Remote configuration of Nut/OS nodes
  • Qt4 libraries
  • GNU C++ compiler
  • Disabled by default
    API Reference
  • HTML document created from source code
  • Doxygen 1.4 or later
  • GraphViz 2.2 or later
  • --disable-html-docs

    Lua is an embeddable scripting language, which is used here to specify the configuration rules.

    wxWidgets is a cross-platform C++ GUI framework.

    Doxygen and GraphViz are used to automatically create a Nut/OS API reference from the C source files.

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

    Full Installation

    Build Essentials

    Most Debian distributions offer to install all basic tools for building Linux applications in one step:

    sudo apt-get install build-essential

    If that doesn't work for you, we will show below, how to install them separately.

    Check the version of the GNU Compiler Collection installed on your PC. Note, that this compiler is needed to create binaries, which will run on Linux. Code for AVR or ARM targets is created by the cross compiler, which will be installed later.

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

    Actually the version is not critical. Previous versions should work fine. Typically, newer releases of the GNU compiler are more strict about code compliance and may emit warnings or even error messages.

    To install or upgrade, use

    sudo apt-get install gcc g++

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

    $ autoconf --version
    autoconf (GNU Autoconf) 2.63
    $ automake --version
    automake (GNU automake) 1.10.2
    To install or upgrade, use
    sudo apt-get install automake autoconf


    The recent configuration of the Nut/OS tools requires at least wxWidgets version 2.9.3. It will definitely not work with earlier versions. At the time of this writing this version is not available as a binary package. You have to build it from the sources. This is a bit time consuming, but works straightforward.

    First, make sure that you have installed the GCC toolchain and the GTK 2.0 libraries.

    sudo apt-get install build-essential libgtk2.0-dev

    Next, you can download and unpackk the wxWidgets 2.9.3 source code.

    wget -r -nd
    tar xjf wxWidgets-2.9.3.tar.bz2

    To avoid later problems with shared libraries and other features, we prefer to build a very basic version. However, shared libraries and unicode builds may work for you. In any case, we recommend to create a build directory first.

    cd wxWidgets-2.9.3/
    mkdir build-GTK
    cd build-GTK
    ../configure --with-gtk --disable-debug --disable-shared --disable-unicode

    Building the libraries is done in a second step. Be prepared that this takes at least several minutes.


    As usual, the binaries are finally installed with

    sudo make install
    sudo ldconfig

    You may now test the installation by trying the AUI sample.

    cd ../samples/aui
    make -f makefile.unx

    The last command should open a sample application window with dockable toolbars. This means the wxWidgets installation is working.


    The Nut/OS Discoverer is based on a wxWidgets extension called wxPropertyGrid. For earlier versions of wxWidgets it was required to install it separately. Now it has become part of the official wxWidgets distribution. Nevertheless, we keep the related installation instructions for archival purposes.

    Like most wxWidgets extensions, wxPropertyGrid is available in source code and must be applied to the wxWidgets source code package.

    Create a temporary directory and change to it.

    mkdir ~/propgrid
    cd ~/propgrid

    Next download and unpack the source code archive in that directory.

    tar xzf wxpropgrid-1.4.5-src.tar.gz

    Now run the standard command sequence to apply wxPropertyGrid to your wxWidgets source tree.

    cd propgrid/
    ./configure --disable-share
    sudo make install

    This should install the package in /usr/include/wx-2.8/wx or /usr/local/include/wx-2.8/wx. On our machine this didn't work properly. The wxPropertyGrid extension had been installed in /usr/local/include/wx/propgrid/ instead. Moving it manually to the right place helped.

    mv /usr/local/include/wx/propgrid/ /usr/local/include/wx-2.8/wx/propgrid/


    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.

    The Nut/OS Configurator had been tested with Lua 5.1 and may still run with either Lua 5.0 or even later versions. However, the configure script that is currently provided, will not accept anything else but version 5.1. Use the following command to install the binaries:

    sudo apt-get install lua5.1 liblua5.1-0 liblua5.1-0-dev

    If it worked you can skip the rest of this chapter and continue with installing Doxygen and GraphViz.

    If no binary package is available for your Linux distribution, which is most unlikely by the way, you can build Lua from the source. The following explanation had been written some time ago for the version 5.0, when Lua was not as widespread as it is today. It may be of some help.

    Download lua-5.0.3.tar.gz from and unpack it.

    tar xzf lua-5.0.3.tar.gz
    cd lua-5.0.3/

    The Lua source archive doesn't provide a configure script. Instead it comes with a prepared Makefile, which includes another 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.

    Building and installing is done in the usual way:

    sudo make install

    Doxygen And GraphViz

    For creating the Nut/OS API Reference Document, we need to install Doxygen and GraphViz.

    sudo apt-get install doxygen doxygen-doc graphviz

    If something fails here: No big deal. The documents are also available online.


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

    It is highly recommended to create a project directory first and then download the latest ethernut-x.y.z.tar.bz2 (or tar.gz) from the download section into this directory.

    mkdir ~/ethernut
    cd ~/ethernut
    tar xzf ethernut-5.0.5.tar.gz

    We may later upgrade to a new version or we may concurrently work with different versions. Thus, it is most convenient to create a symbolic link before starting the configure script.

    ln -s ethernut-5.0.5 nut
    cd nut/

    Carefully check the output, specially the following lines:

    checking for doxygen... true
    checking for dot... true
    configure: nutconf tools enabled
    configure: nutconfgui is enabled
    configure: nutdisc enabled

    If anything hasn't been enabled, refer to the addtional requirements given in the table in the first chapter of this document and make sure that they had been properly installed. However, even if not all requirements are fulfilled, you can still continue. But not all features of the development environment will be available.

    The next command will build tools and documentation and will take several minutes to finish.


    If the build fails because of wxWidgets, try

    ./configure --disable-nutconf --disable-nutdisc
    make clean

    This will only build the Qt and the command line versions of the Configurator.

    By default

    sudo make install

    should install five executables

    in a global directory, typically /usr/local/bin/.

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

    Install the same packages as described in the full installation, but completely skip the wxWidget part.

    After downloading and unpacking Nut/OS source code package, configure it with two additional parameters.

    cd ~/ethernut/nut/
    ./configure --disable-nutconf-gui --disable-html-docs
    sudo make install

    Minimal Installation

    Even if all fails, there is still hope: Try the bare minimum! In fact you can simply use the raw unpacked sources.

    Create a project directory and download the latest ethernut-x.y.z.tar.bz2 (or tar.gz) from the download section into this directory.

    mkdir ~/ethernut
    cd ~/ethernut
    wget -N

    When downloaded, unpack the Ethernut source package.

    tar xzf ethernut-5.0.5.tar.gz

    Now create a symbolic link to the unpacked sources, change to this new directory and run nutsetup to configure Nut/OS for your target board.

    ln -s ethernut-5.0.5 nut
    cd nut/

    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 UNIX, it will also create some wrapper header files in directory include/.

    After this, everything is ready to build Nut/OS in the source tree. We will explain this later.

    However, some applications, e.g. basemon or httpd require crurom to build an UROM file system image. Try

    ./configure --disable-nutconf-tools --disable-html-docs
    sudo make install

    Even if this fails, you can still build most application samples.

    Cross Toolchain

    To create any binaries for our AVR or ARM target system, we need to install the related cross toolchain.

    AVR Toolchain

    For the 8-bit AVR platform use

    sudo apt-get install binutils-avr gcc-avr avr-libc avrdude

    ARM Toolchain

    Unfortunately there is no official binary package available. You may try to build the toolchain from the official sources.

    Nut/OS Libraries

    The way we build Nut/OS libraries depends on the tools, which are available from the installation described above.

    Using the Configurator GUI

    Change to the Ethernut project directory and start the Configurator.

    cd ~/ethernut/

    Now follow the Nut/OS Software Manual to build Nut/OS and the related sample applications.

    Using the Configurator CLI

    Change to the Ethernut project directory and enter the following command to display the usage help for the Configurator's command line interface.

    cd ~/ethernut/
    nutconfigure -?
    Usage: nutconfigure OPTIONS ACTIONS
    -a<dir>  application directory (./nutapp)
    -b<dir>  build directory (./nutbld)
    -c<file> configuration file (./nut/conf/ethernut21b.conf)
    -i<dir>  first include path ()
    -j<dir>  last include path ()
    -l<dir>  library directory ()
    -m<type> target platform (avr-gcc)
    -p<type> programming adapter (avr-dude)
    -q       quiet (verbose)
    -s<dir>  source directory (./nut)
    -r<file> repository (./nut/conf/repository.nut)

    The document Nut/OS development for purists explains the whole process.

    Building in the Source Tree

    Today, building in the source tree is seldom used, currently not maintained and considered broken.

    With the minimal installation it is necessary to build Nut/OS libraries and applications directly in the source tree. It is assumed, that you already ran the nutsetup script to configure Nut/OS for a specific target board.

    Change to the subdirectory lib within the source tree and run make.

    cd ~/ethernut/nut/lib/
    make clean install

    Although simple, most developers prefer to use the Configurator nowadays. Therefore, building in the source tree is not always properly maintained. If your build fails, it is probably caused by a missing or outdated source file entry in the related Makefile. You can easily fix this by updating the Makefile with a text editor. Just make sure that your editor will preserve tabs. We will give an example.

    The build for Ethernut 2.1 fails with the following error:

    make[1]: *** No rule to make target `httpdopt.o', needed by `libnutpro.a'.  Stop.
    make[1]: Leaving directory `/home/harald/ethernut/ethernut-4.7.3/pro'
    make: *** [install] Error 2

    Change to the directory where the problem occured (remember that we use the symbolic link nut) and load the Makefile into an editor.

    cd ~/ethernut/nut/pro/
    vi Makefile

    We can see, that httpdopt.c is in the Makefile, but no such file exists in the current directory. Instead a file named httpopt.c (without letter d) exists. After correcting the Makefile, the error is gone.

    Applications are build in the source tree in a similar way.

    cd ~/ethernut/nut/app/events/
    make clean all

    Getting Nut/OS from Subversion

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

    mkdir ~/ethernut
    cd ~/ethernut
    svn co ethernut-4.8
    ln -s ethernut-4.8 nut
    cd nut

    If you want to try the latest code, use:

    cd ~/ethernut
    svn co ethernut-trunk
    ln -s ethernut-trunk nut
    cd nut

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


    The CVS repository will never contain any 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, reconf will fail. To fix this, run

    automake --add-missing

    and then run ./reconf again. We are now ready to configure, build and install the Nut/OS tools.

    sudo make install

    To keep up with the latest changes, use the following commands.

    cd ~/ethernut/nut
    svn update

    Related Links
    Devel section of Debian software packages in the testing distribution.
    How to setup the GNU Arm toolchain on (K)Ubuntu Linux (in lax German).
    Quick and dirty hack to bundle crosstool output into .tgz and .deb packages.
    Commercially supported toolchain (may not be suitable for Nut/OS yet).
    GCC ARM Improvement Project.
    Nut/OS development on Red Hat Enterprise Linux 4 (RHEL4).
    Ethernut Setup with Gentoo.
    BTnut Development Tools - Linux Installation.

    Nut/OS on Debian Etch
    Some additional notes in the NutWiki.

    Good luck,
    Harald Kipp

    Castrop-Rauxel, 21st of June 2009