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.
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.
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.
|UROM Image Creator
|Disabled by default
Lua is an embeddable scripting language, which is used here to specify the configuration rules.
wxWidgets is a cross-platform C++ GUI framework.
It's recommended to try the full installation first. If it fails for some reason, you may step down to a less complete environment.
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.2To 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 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.
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.
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/
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.
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.
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.
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
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.
To create any binaries for our AVR or ARM target system, we need to install the related cross toolchain.
For the 8-bit AVR platform use
sudo apt-get install binutils-avr gcc-avr avr-libc avrdude
Unfortunately there is no official binary package available. You may try to build the toolchain from the official sources.
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: *** No rule to make target `httpdopt.o', needed by `libnutpro.a'. Stop. make: 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.
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
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
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.
Castrop-Rauxel, 21st of June 2009