Building WebbotLib using Ant.


Who should use this document?

This document will be of use to advanced users of WebbotLib.

This will be mostly relevant to people who are testing patches, updates, etc or generally helping in the development of WebbotLib.
It may also be useful for users who need to split their project into multiple source files as it is complicated to link pre-compiled version of WebbotLib with multiple source files. (WebbotLib pre-complied libraries can be used in this way but using Ant is simpler.)
It will also be useful background reading for anyone who is already using WebbotLib successfully.

What does this do?

The instructions in this document explain how to build the WebbotLib libraries from source code.
WebbotLib  already comes with pre-built libraries so there is no reason to do this unless you are doing something non standard.

If you are new to WebbotLib do your self a favor and stop reading. Use WebbotLib in the normal way as documented in the PDF included with WebbotLib.

What this document does NOT do.

This document does not explain how to use WebbotLib. That information is in the .pdf file in the WebbotLib archive.
This document does not contain information on uploading compiled code to an AVR.

This document will presume you have read and understand WebbotLib's official documentation. It will also presume you are already using WebbotLib in the normal (ie, documented in the manual) way.

This document is not intended so you can roll your own WebbotLib libraries for release. That is best left to the existing Sourceforge page.

What is Apache Ant?

From the manual:
"Apache Ant is a Java-based build tool. In theory, it is kind of like make, without make's wrinkles."

In the context of WebbotLib, Ant is used to invoke GCC and associated tools to build the WebbotLib source files into a single library which can be included in your project.
Ant keeps track of source file changes and build times to make sure the finished library is up to date without having to rebuild everything.
This has allowed the author of WebbotLib to work on awesome coding rather than maintaining Makefiles.

Installing Apache Ant.


As Ant is Java based and run from the command line it should install and run the same on any system.
I will presume for the duration of this document the user is installing the latest (at the time of writing) stable version of Ant: 1.8.
Ant 1.8.* will run with jdk1.4 or higher installed on your system.
Ant will aso run on many Open Source Java runtimes. The author is happily using OpenJDK 6 for example.


First check if JDK is installed on your system and which version.
To check Java Version on windows launch a command prompt and enter "java -version".
This will give the version info. eg:

C:\> java -version

java version "1.6.0_11"
Java(TM) SE Runtime Environment (build 1.6.0_11-b03)
Java HotSpot(TM) Client VM (build 11.0-b16, mixed mode, sharing)

You want version 1.4 or higher.

Next download and install Apache Ant.

If you dont have Java, or its not on the runtime path, then you will get the "java is not recoginzed as internal or external command...." message when you try to run Ant.


First use your package manager to verify you have a reasonably up to date version of JDK on your system.

On any Debian based system (Ubuntu, etc) do the following:

$ dpkg --get-selections | grep jdk
openjdk-6-jdk                    install
openjdk-6-jre                    install
openjdk-6-jre-headless       install
openjdk-6-jre-lib                install

Open JDK 6 is fine.

Sun Java 6 JDK is probably better but either will do.

In the unlikely event you have something older on your system use your package manager to upgrade.


Next, use your package manager to install ant.

On my system it was as simple as:

$ sudo apt-get install ant

That's it. The default config worked fine.


*** Need Volunteer for this bit. Please contact me if you can fill in the deatails. mrdunk(at)***

Using Ant to build WebbotLib.

1. Unpack a fresh copy of WebbotLib to a working directory.
2. Change to that directory.
3. Check for the existence of build.xml. This is Ant's equivalent of a Make file.
4. You are now ready to run Ant.
For the first time it's probably worth running it with the "clean" target first which will scrub the old version of WebbotLib and build it all again from scratch.

$ ant clean

Buildfile: build.xml

   [delete] Deleting directory /home/duncan/Geek_projects/avr_projects/WebbotLib/ant



Total time: 2 seconds

Now build WebbotLib libraries again.

$ ant

Buildfile: build.xml


     [echo] Compiling for target = atmega8 to libWebbot-ATMega8.a
    [mkdir] Created dir: /home/duncan/Geek_projects/avr_projects/WebbotLib/ant/atmega8
    [mkdir] Created dir: /home/duncan/Geek_projects/avr_projects/WebbotLib/ant/atmega8/Sensors
    [mkdir] Created dir: /home/duncan/Geek_projects/avr_projects/WebbotLib/ant/atmega8/Sensors/Voltage
    [mkdir] Created dir: /home/duncan/Geek_projects/avr_projects/WebbotLib/ant/atmega8/Sensors/Voltage/Phidget
    [mkdir] Created dir: /home/duncan/Geek_projects/avr_projects/WebbotLib/ant/atmega8/Sensors/Temperature
    [mkdir] Created dir: /home/duncan/Geek_projects/avr_projects/WebbotLib/ant/atmega8/Sensors/Temperature/Phidget
    [mkdir] Created dir: /home/duncan/Geek_projects/avr_..................etc.

Lots more output removed...

...........................dir: /home/duncan/Geek_projects/avr_projects/WebbotLib/ant/atmega328p/RFTransceiver
    [mkdir] Created dir: /home/duncan/Geek_projects/avr_projects/WebbotLib/ant/atmega328p/RFTransceiver/Hope
    [mkdir] Created dir: /home/duncan/Geek_projects/avr_projects/WebbotLib/ant/atmega328p/Storage
    [apply] /home/duncan/Geek_projects/avr_projects/WebbotLib/RFTransceiver/Hope/RF12.c:43: warning: ‘rf12_init’ defined but not used
    [apply] avr-ar: creating ./libWebbot-ATMega328P.a


Total time: 1 minute 20 seconds

As you can see (Total time: 1 minute 20 seconds), it takes quite a while the first time.

An alternative, less time consuming way is to build only the part of WebbotLib you require.
To see the various build targets use the -projecthelp flag.

$ ant -projecthelp
Buildfile: build.xml

Main targets:

 ATMega1280      ATMega1280 library
 ATMega168       ATMega168 library
 ATMega2560      ATMega2560 library
 ATMega2561      ATMega2561 library
 ATMega32        ATMega32 library
 ATMega328P      ATMega328P library
 ATMega640       ATMega640 library
 ATMega8         ATMega8 library
 build-lib       Make all libraries
 clean           clean everything
 clean-examples  Clean the examples
 clean-lib       Clean the library
 examples        Examples
 make-example    internal use only
 makeone         internal use only
 release         Create release
Default target: build-lib

You can then build only the target you need for your model of AVR.
In the following example only the library for the ATMega2561 is being built (saving you time).

$ ant ATMega2561
Buildfile: build.xml


     [echo] Compiling for target = atmega2561 to libWebbot-ATMega2561.a
    [mkdir] Created dir: /home/duncan/Geek_projects/avr_projects/WebbotLib/ant/atmega2561
    [mkdir] Created dir: /home/duncan/Geek_projects/avr_projects/WebbotLib/ant/atmega2561/Sensors
    [mkdir] Created dir: /home/duncan/Geek_projects/avr_projects/WebbotLib/ant/atmega2561/Sensors/Voltage
    [mkdir] Created dir: /home  ..................etc.

Lots more output removed...

............................................................  rojects/WebbotLib/ant/atmega2561/RFTransceiver/Hope
    [mkdir] Created dir: /home/duncan/Geek_projects/avr_projects/WebbotLib/ant/atmega2561/Storage
    [apply] /home/duncan/Geek_projects/avr_projects/WebbotLib/RFTransceiver/Hope/RF12.c:43: warning: ‘rf12_init’ defined but not used
    [apply] avr-ar: creating ./libWebbot-ATMega2561.a

Total time: 14 seconds

Although Ant is designed to track changes in files and only rebuild libraries if source files have changed Ant is actually being invoked in a non-standard way due to the fact there is not a avr-gcc plugin.
As a result if you change an H file then ant doesn't know all the C files that include it and so probably rebuilds nothing.
In short, if you don't know what you are doing (which if you are reading this is probably the case) it is best to rebuild everything every time you make changes to your source files.

So its actually a good idea to do an 'ant clean' followed by either 'ant' or 'ant ATMegaXXX' to make sure that everything is rebuilt completely.


All well and good but what when things go wrong?

It's worth viewing the contents of build.xml.
Everything in there is nice formated XML so you can view it in a web browser or in a text editor.

Have a look at the <target> tags.
Earlier when you did an "$ ant clean" the <target name="clean" description="clean everything" depends="clean-lib, clean-examples"> rule was invoked.
Take particular notice of the depends= section. These dependencies point to more <target > tags which will also be run.

Ant's default action is set here: <project name="My Project" default="build-lib" basedir=".">
The default="build-lib" section sends ant to the <target name="build-lib"> section if you don't specify one your self.

Most problems are fairly straight forward. Ant is just invoking other command line tools so look for familiar debug output from them.
Any problems i have seen so far are related to incorrect filenames or paths.

$ ant clean
Buildfile: build.xml

   [delete] Deleting directory /home/duncan/Geek_projects/avr_projects/WebbotLib/ant


/home/duncan/Geek_projects/avr_projects/WebbotLib/build.xml:25: Directory does not exist:/home/duncan/Geek_projects/avr_projects/WebbotLib/examples

Total time: 0 seconds

Can be fixed by simply adding the missing ./examples directory.

Good luck!


Good stuff by Dunk. His

Good stuff by Dunk. His final comment about the missing 'examples' directory happens coz I personally have lots of examples which I don't actually ship with the release. They are just there for me to test new versions.