Nut/OS Development on Debian

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
wget http://www.ethernut.de/arc/ethernut-5.0.5.tar.gz
tar xzf ethernut-5.0.5.tar.gz
ln -s ethernut-5.0.5 nut
cd nut/
./configure
make
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.

Requirements

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:

C compiler 4.1 or later
Binutils 2.18 or later
Autoconf 2.61
Automake 1.10

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

GNU Compiler Collection for AVR
GNU Binary Utilities for AVR
AVRDUDE programmer software

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

GNU Compiler Collection for ARM
GNU Binary Utilities for ARM
OpenOCD for JTAG programming and debugging

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 (mandatory)	Target selection via shell script Configurable by editing C header files Tool for creating simple file system images	None	Always enabled
CLI Configurator (recommended)	Multiple build and application trees Automated script based target configuration Batch build	Lua 5.1 libraries
UROM Image Creator (recommended)	Creates simple filesystem images	C compiler	--disable-crurom
GUI Configurator wxWidgets version (optional)	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 (optional)	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 (optional)	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 (optional)	Scans local networks for Nut/OS nodes Remote configuration of Nut/OS nodes	Qt4 libraries GNU C++ compiler	Disabled by default
API Reference (optional)	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

wxWidgets

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 http://tenet.dl.sourceforge.net/project/wxwindows/2.9.3/wxWidgets-2.9.3.tar.bz2
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.

make

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
./auidemo

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

wxPropertyGrid

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.

wget http://ovh.dl.sourceforge.net/sourceforge/wxpropgrid/wxpropgrid-1.4.5-src.tar.gz
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
make
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/

Lua

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 www.lua.org 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:

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

Nut/OS

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
wget http://www.ethernut.de/arc/ethernut-5.0.5.tar.gz
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/
./configure

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.

make

If the build fails because of wxWidgets, try

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

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

By default

sudo make install

should install five executables

crurom, UROM file system creator
nutconfigure, Nut/OS Configurator for the command line
qnutconf, full fledged Nut/OS Configurator GUI, based on Qt4
nutconf, same as above, but based on wxWidgets
nutdisc, Nut/OS Discoverer

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
make
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 http://www.ethernut.de/arc/ethernut-5.0.5.tar.gz

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/
./nutsetup

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 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
make
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/
nutconf

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
OPTIONS:
-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)
ACTIONS:
create-buildtree
create-apptree

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 https://ethernut.svn.sourceforge.net/svnroot/ethernut/branches/nut-4_8-branch ethernut-4.8
ln -s ethernut-4.8 nut
cd nut

If you want to try the latest code, use:

cd ~/ethernut
svn co https://ethernut.svn.sourceforge.net/svnroot/ethernut/trunk ethernut-trunk
ln -s ethernut-trunk nut
cd nut

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

./reconf

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.

./configure
make
sudo make install

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

cd ~/ethernut/nut
svn update