How to compile an external module in C++ for Yate

You've created an external module for Yate, and you want to keep it as a separate project, not in the main branch of Yate, for future development. Your purpose is to compile your module with Yate packages, so others can used on different platforms. Bellow you can find some ideas for doing that.

Install Yate

To use an external module you need to have Yate already installed. This can be done in two ways:

• Yate is installed from SVN source, the needed headers files are obtained in this way
• Development packages for Yate including headers and shared libraries (typically this is called yate-devel but depends on distribution).

Compile an external module

When compiling an external module, it is recommended to have autogen.sh. This way, the build system will detect if the Yate headers are correctly installed, and their paths. When running autogen.sh an executable file is produced, configure from configure.ac. Then configure is run and Makefile is produced using Makefile.in.

So, to start using the Yate's build system with your software package it is recommended to write the files bellow.

Write configure.ac

This file is process with autoconf to produce a configure script.
It contains tests that check for conditions that are likely to differ on different platforms. The tests are made by actually invoke autoconf macros.

Typical layout:

• AC_INIT(package, version) - perform initialization and verification - sets the name of the package (name of the external module) and its version.
• package information
• program checks
• library checks
• type checks
• structure checks
• compiler characteristics checks
• library functions check
• system service checks
• AC_CONFIG_FILES([... Makefile])
• AC_OUTPUT

For Yate's detection the following parameters are required:

Parameter name	Command line	Parameter semnification	Result
YATE_VER	yate-config --version 2>/dev/null	Yate version	4.2.1
YATE_INC	yate-config --c-all 2>/dev/null	Yate headers location	-fno-check-new -fno-exceptions -fPIC -DHAVE_GCC_FORMAT_CHECK -DHAVE_BLOCK_RETURN -I/usr/local/include/yate
YATE_LIB	yate-config --ld-nostrip 2>/dev/null	linker options	-export-dynamic -shared -Wl,--unresolved-symbols=ignore-in-shared-libs -lyate
YATE_STR	yate-config --ld-strip 2>/dev/null	linker options	-Wl,--retain-symbols-file,/dev/null
YATE_MOD	yate-config --modules 2>/dev/null	Yate modules path	/usr/local/lib/yate
YATE_SCR	yate-config --scripts 2>/dev/null	Yate scripts path	/usr/local/share/yate/scripts
YATE_SKN	yate-config --skins 2>/dev/null	Yate skins path	/usr/local/share/yate/skins
YATE_CFG	yate-config --config 2>/dev/null	Yate configuration files path	/usr/local/etc/yate

If Yate version couldn't be found an error must be given to the user so that he will Know that something is wrong with installation of Yate.

For the above variables use AC_SUBST to create an output variable.

Write Makefile.in

This file holds the make rules for a Yate module

A typical makefile contains lines of the following types:

• Variable Definitions - these lines define values for variables.
  

For example:

# override DESTDIR at install time to prefix the install directory
DESTDIR :=
# override DEBUG at compile time to enable full debug or remove it all
DEBUG :=
# use "gcc" to compile source files.
CC  := @CC@ -Wall
CXX := @CXX@ -Wall
# Compiler flags go here.
CFLAGS = -O3 @YATE_INC@
# Linker flags go here. Currently there aren't any, but if we'll switch to
# code optimization, we might add "-s" here to strip debug info and symbols.
LDFLAGS =
# Defining a list of generated object files.
OBJS = file1.o file2.o
YATELIBS:= @YATE_LIB@ -ldl -lpthread
MODSTRIP:= @YATE_STR@
# program executable file name.
PROGS:= name_module.yate
INCFILES:= file1.h file2.h
# yate directories paths
confdir:= @YATE_CFG@
moddir := @YATE_MOD@
scrdir := @YATE_SCR@
skndir := @YATE_SKN@

• Dependency Rules - these lines define under what conditions a given file (or a type of file) needs to be re-compiled, and how to compile it.

Rules for compiling, cleaning, debugging, installing and uninstalling module with Yate must be written, for that the above variables can be used. For that use a .PHONY target rule for improving performance, avoid conflict names. This allows you to use it when call make from command line (e.g. make debug). Example:

.PHONY: all debug ddebug xdebug ndebug
# rule to compile everything
all: $(PROGS)
debug:
   $(MAKE) all DEBUG=-g3 MODSTRIP=
ddebug:
   $(MAKE) all DEBUG='-g3 -DDEBUG' MODSTRIP=
xdebug:
   $(MAKE) all DEBUG='-g3 -DXDEBUG' MODSTRIP=
ndebug:
   $(MAKE) all DEBUG='-g0 -DNDEBUG'

See also

• http://code.google.com/p/yate-datacard/