Chapter 2. Building and Using openACN

Table of Contents

Setting Up A Build Directory
Other Target Specific Directories
Configuring OpenACN for your System and Application
user_opt.h
Building Using Make
Building Using Integrated Development Environments
Building openACN
Configuration and Customization
Compile Time Options

Setting Up A Build Directory

You should build your OpenACN code in a build directory, which may be either inside or outside the main source tree. All build specific details including options and makefile configuration should be confined within this build directory. This leaves the source tree untouched and allows you to set up builds for multiple targets alongside each other without them conflicting. There are several example build configurations in the source tree and copying one of these is a good way to start. By convention the build directory is called something like build-<processor>-<system> where <processor> is the processor you are cross compiling for, and <system> is the operating system and TCP/IP stack combination. e.g build-coldfire-uclinux or build-arm9-lwip. For builds which use a native compiler the processor should be given as native e.g. build-native-freebsd.

In the following, the root directory of your downloaded openacn sources (corresponding to SVN's trunk directory is called ACNROOT (if you followed the directions in the previous chapter, this will be actually be openacn) whilst the build directory you have created is called MYBUILD.

Other Target Specific Directories

There are a number of directories within the tree which contain target specific code. C code routines specific to a particular stack and OS are subdirectories within the ACNROOT/platform directory. Whilst these routines may be used for specific builds, they are generally applicable across a range of builds which use the same OS and/or stack.

Similarly there are subdirectories within the main include directory for headers specific to individual processor or processor family architectures. If building using Make, the appropriate directories are incorporated into the header file search path when compiling.

Configuring OpenACN for your System and Application

Before you can build OpenACN you need to do some basic configuration. This generally means creating and/or editing these files:

user_opt.h

Most options are set within a file called MYBUILD/include/user_opt.h. Copying one of the examples is a good way to start. For a full list of configuration options and documentation on what they do, look at ACNROOT/include/opt.h. You should not however edit ACNROOT/include/opt.h directly (unless you are adding new options in source code you plan to feed back into openACN).

Building Using Make

Make is a generic command line build system which works with any compiler and many other processing systems (e.g. for transforming this documentation from Docbook into HTML, PDF or other formats).

OpenACN is set up to be built with Gnu make. This open-source program is available on most common operating systems including Windows (both fully native or using the Cygwin environment), Macintosh, Linux and Unix. Other versions of Make vary wildly in their operation and syntax and may not work.

The configuration for your own build should go into MYBUILD/Makefile. This file is where you put build-specific configuration. It then includes ACNROOT/builddir.mk which provides defaults and rules applicable to all builds.

Items which you must define in MYBUILD/Makefile are:

ACNROOT

This is the path from your build directory to the openacn source directory. For example, if your build directory and the openacn directory are both within a common parent this would be:

ACNROOT:=../openacn
PLATFORMNAME

The Make variable PLATFORMNAME must be the same as the name of the subdirectory of ACNROOT/platform which includes platform dependent code for your operating system (if any) and stack e.g.

PLATFORMNAME:=linux    # Assume Linux's standard stack
COMPILER

This is a simple name identifying your compiler type which allows parts of the Makefiles defining compiler flags and mechanisms to work. Currently defined options are

visualc
gcc
bcc32

For example:

COMPILER:=visualc

Other optional definitions include your compiler command (compulsory if you are cross compiling, or if your compiler is not found by the default commands), the C preprocessor command (which is used by Make), and various other flags and options. Look at the makefiles in the sample build directories provided with the source for documentation.

C Compiler

Make will use the native C compiler by default (usually cc) If you are cross compiling, this is not what you want and you need to define the Make variable CC to be the command to start your compiler. e.g.

CC=/usr/bin/h8300-elf-gcc -ms
INCLUDEDIRS

Make variable INCLUDEDIRS is a space separated list of directories to search for header files. You can add directories to this list if necessary, for example to search for stack-specific headers. e.g.prog

INCLUDEDIRS:=../../lwip/src/include
CFLAGS

The Make variable contains flags and options for the C compiler. There is a default set defined in ACNROOT/builddir.mk but you can override them in your Makefile if desired. e.g. (for Borland bcc)

CFLAGS:=-6                  # Pentium pro level processor
CFLAGS+=-A                  # ANSI C
CFLAGS+=-b- -O2 -Oc -Ov -pm # Some optimization options

Building Using Integrated Development Environments

The use of IDEs is beyond the scope of this documentation at present. However, any good IDE will allow you to build within the directory structure given above. It should ensure that the following include directories are in the compiler's search path:

ACNROOT/include
ACNROOT/include/arch-<processor>
MYBUILD/include
ACNROOT/platform/<your-platform>

Building openACN

Assuming you are building with Make, once you have configured openACN you build it by simply typing make in a shell (in cmd.exe on Windows) from your build directory. For example if your build directory is bendilite/openacn/build-avr-uip:

Example 2.1. Building the code

$ cd bendilite/openacn/build-avr-uip
~/bendilite/openacn/build-avr-uip
$ make

If you type make in the ACNROOT directory. Make will attempt to make all the builds within this directory which may not be what you want!

Configuration and Customization

Compile Time Options

OpenACN has a wide variety of configuration options and is unlikely to fit a particular application without setting up some of these. The majority (all?) of configuration is done using compile time switches of the form:

#define CONFIG_SOME_OPTION 1
#define CONFIG_ANOTHER_OPTION 0
// etc.

These are all documented and default values provided in the include file opt.h. (do not edit opt.h).

Setting Options for Your Build

Do not edit opt.h in order to configure your implementation - opt.h provides a default value for each option and performs sanity checks such as ensuring you have not selected two operating systems in the same build. In order to build your own customized implementation you must create your own header file MYBUILD/include/user_opt.h.

opt.h only provides default values for options which have not been defined in user_opt.h so you need only define in user_opt.h, those options for which you do not want the default value. This means that throughout the rest of the source, every option has a defined value and for Boolean options, you must explicitly set them to FALSE (or 0) if that is what you want, rather than leaving them undefined.

Example 2.2. Defining config options in user_opt.h

/* correct way to exclude a boolean option */
#define CONFIG_SOME_OPTION FALSE

/* WRONG! opt.h will substitute a default value */
#undef CONFIG_OTHER_OPTION

Testing options in code

If you are writing or extending you code which needs to test configuration options, bear in mind that as seen above, every option has a defined value and an #ifdef test will always pass. Use a simple #if test instead.

Example 2.3. Testing options in C code

#if CONFIG_SOME_OPTION    /* Correct way to test a boolean option */
...
#endif
 
#ifdef CONFIG_OTHER_OPTION   /* WRONG! Test always passes */
...
#endif
 
#if defined(CONFIG_THIRD_OPTION)   /* WRONG! Test always passes */
...
#endif

Summary of Compile Time Configuration Mechanism

  • Options are documented with default values in opt.h

  • Local customization is done in user_opt.h which must be created for each build

  • Each option always has a defined value - booleans are TRUE or FALSE (never undefined)

SourceForge.net Logo