Building WebbotLib using Ant.

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.

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.

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.

Pre-requisites.

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.

Windows.

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:


You want version 1.4 or higher.

Next download and install Apache Ant.
http://ant.apache.org/bindownload.cgi

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.

Linux.

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:

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:

That's it. The default config worked fine.

Mac.

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

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.



Now build WebbotLib libraries again.


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.



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





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.

$ ant clean Buildfile: build.xml clean-lib:    [delete] Deleting directory /home/duncan/Geek_projects/avr_projects/WebbotLib/ant clean-examples: BUILD FAILED /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