Building Linux, *nix, *BSD, and MacOS X Targets with GNU Build Systems

1. Using in your applications

3.1 Supported Targets

The new, autoconf based GNU build system can be used to build the libraries/applications for the following targets:

• Linux/uC-Linux (i386, Opteron, Itanium, MIPS, PowerPC, etc.),
• MacOS X (PowerPC),
• mingw (i386),
• FreeBSD and maybe other BSD's (i386, Opteron, etc.),
• RTEMS with cross compilation (ARM, powerpc),
• etc.

3.2 Requirements

In order to use PJ's GNU build system, these typical GNU tools are needed:

• GNU make (other make will not work),
• GNU binutils for the target, and
• GNU gcc for the target.

In addition, the following libraries are optional, but they will be used if they are present:

• ALSA header files/libraries (optional) if ALSA support is wanted.
• OpenSSL header files/libraries (optional) if TLS support is wanted.

The build system is known to work on the following hosts:

• Linux, many types of distributions.
• MacOS X 10.2
• mingw (Win2K, XP)
• FreeBSD (must use gmake instead of make)

Building Win32 applications with Cygwin is currently not supported by the autoconf script (there are some conflicts with Windows headers), but one can still use the old configure script by calling ./configure-legacy. More over, cross-compilations might also work with Cygwin using this build system.

3.3 Running configure Using Default Settings

Run "./configure" without any options to let the script detect the appropriate settings for the host:

$ cd pjproject $ ./configure ...

Notes:

The default settings build the libraries in "release" mode, with default CFLAGS set to "-O2". To change the default CFLAGS, we can use the usual "./configure CFLAGS='-g'" construct.

Features Customization

With the new autoconf based build system, most configuration/customization can be specified as configure arguments. The list of customizable features can be viewed by running "./configure --help" command:

$ cd pjproject $ ./configure --help ... Optional Features: --disable-floating-point Disable floating point where possible --disable-sound Exclude sound (i.e. use null sound) --disable-small-filter Exclude small filter in resampling --disable-large-filter Exclude large filter in resampling --disable-g711-plc Exclude G.711 Annex A PLC --disable-speex-aec Exclude Speex Acoustic Echo Canceller/AEC --disable-g711-codec Exclude G.711 codecs from the build --disable-l16-codec Exclude Linear/L16 codec family from the build --disable-gsm-codec Exclude GSM codec in the build --disable-speex-codec Exclude Speex codecs in the build --disable-ilbc-codec Exclude iLBC codec in the build --disable-tls Force excluding TLS support (default is autodetected based on OpenSSL availability) ... Configuring Debug Version and Other Customizations

The configure script accepts standard customization, which details can be obtained by executing ./configure --help.

Below is an example of specifying CFLAGS in configure:

$ ./configure CFLAGS="-O3 -DNDEBUG -msoft-float -fno-builtin" ... Configuring TLS Support

By default, TLS support is configured based on the availability of OpenSSL header files and libraries. If OpenSSL is available at the default include and library path locations, TLS will be enabled by the configure script.

You can explicitly disable TLS support by giving the configure script --disable-tls option.

3.4 Cross Compilation

Cross compilation should be supported, using the usual autoconf syntax:

$ ./configure --host=arm-elf-linux ...

Since cross-compilation is not tested as often as the "normal" build, please watch for the ./configure output for incorrect settings (well ideally this should be done for normal build too).

Please refer to Porting Guide for further information about porting PJ software.

3.5 Running make

Once the configure script completes successfully, start the build process by invoking these commands:

$ cd pjproject $ make dep $ make

Note:

gmake may need to be specified instead of make for some hosts, to invoke GNU make instead of the native make.

Description of all make targets supported by the Makefile's:

all

The default (or first) target to build the libraries/binaries.

dep, depend

Build dependencies rule from the source files.

clean

Clean the object files for current target, but keep the output library/binary files intact.

distclean, realclean

Remove all generated files (object, libraries, binaries, and dependency files) for current target.

Note:

make can be invoked either in the top-level PJ directory or in build directory under each project to build only the particular project.

3.6 Build Customizations

Build features can be customized by specifying the options when running ./configure as described in Running Configure above.

In addition, additional CFLAGS and LDFLAGS options can be put in user.mak file in PJ root directory (this file may need to be created if it doesn't exist). Below is a sample of user.mak file contents:

export CFLAGS += -msoft-float -fno-builtin export LDFLAGS +=

Using in your applications

Getting_Started_Using

Regardless of the build system being used, the following tasks are normally needed to be done in order to build application to use PJSIP and PJMEDIA:

1. Put these include directories in the include search path:
   • pjlib/include
   • pjlib-util/include
   • pjnath/include
   • pjmedia/include
   • pjsip/include
2. Put these library directories in the library search path:
   • pjlib/lib
   • pjlib-util/lib
   • pjnath/lib
   • pjmedia/lib
   • pjsip/lib

3.

Include the relevant PJ header files in the application source file. For example, using these would include ALL APIs exported by PJ:

#include <pjlib.h> #include <pjlib-util.h> #include <pjnath.h> #include <pjsip.h> #include <pjsip_ua.h> #include <pjsip_simple.h> #include <pjsua-lib/pjsua.h> #include <pjmedia.h> #include <pjmedia-codec.h>

(Note: the documentation of the relevant libraries should say which header files should be included to get the declaration of the APIs).

4.

Declare the OS macros.

• For Windows applications built with Visual Studio, we need to declare PJ_WIN32=1 macro in the project settings (declaring the macro in the source file may not be sufficient).
• For Windows Mobile applications build with Visual C++, we need to declare PJ_WIN32_WINCE=1 macro in the project settings.
• For GNU build system/autoconf based build system, we need to declare PJ_AUTOCONF=1 macro when compiling the applications.

(Note: the old PJ build system requires declaring the target processor with PJ_M_XXX=1 macro, but this has been made obsolete. The target processor will be detected from compiler's predefined macro by pjlib/config.h file).

5.

Link with the appropriate PJ libraries. The following libraries will need to be included in the library link specifications:

pjlib

Base library used by all libraries.

pjlib-util

Auxiliary library containing scanner, XML, STUN, MD5, getopt, etc, used by the SIP and media stack.

pjnath

NAT helper library (STUN, TURN, ICE).

pjsip

SIP core stack library.

pjsip-ua

SIP user agent library containing INVITE session, call transfer, client registration, etc.

pjsip-simple

SIP SIMPLE library for base event framework, presence, instant messaging, etc.

pjsua

High level SIP UA library, combining SIP and media stack into high-level easy to use API.

pjmedia

The media framework.

pjmedia-codec

Container library for various codecs such as GSM, Speex, and iLBC.

Note: the actual library names will be appended with the target name and the build configuration. For example:

For Visual Studio builds

The actual library names will look like pjlib-i386-win32-vc6-debug.lib, pjlib-i386-win32-vc6-release.lib, etc., depending on whether we are building the Debug or Release version of the library.

An easier way to link with the libraries is to include PJ project files in the workspace, and to configure project dependencies so that the application depends on the PJ libraries. This way, we don't need to manually add each PJ libraries to the input library file specification, since VS will automatically link the dependency libraries with the application.

For Windows Mobile builds

Unfortunately the PJ libraries built for Windows Mobile will not be placed in the usual lib directory, but rather under the output directory under build/wince-evc4 project directory.

An easier way to link with the libraries is to include PJ project files in the workspace, and to configure project dependencies so that the application depends on the PJ libraries. This way, we don't need to manually add each PJ libraries to the input library file specification, since VS will automatically link the dependency libraries with the application.

For GNU builds

Use the template Makefile below (as described in Building Application using PJSIP with GNU Tools): # Modify this to point to the PJSIP location. PJBASE=/home/myself/pjproject-0.5.10.2

include $(PJBASE)/build.mak

CC = $(APP_CC) LDFLAGS = $(APP_LDFLAGS) LDLIBS = $(APP_LDLIBS) CFLAGS = $(APP_CFLAGS) CPPFLAGS= ${CFLAGS}

# If your application is in a file named myapp.cpp or myapp.c # this is the line you will need to build the binary. all: myapp

myapp: myapp.cpp

$(CC) -o $@ $< $(CPPFLAGS) $(LDFLAGS) $(LDLIBS)

clean:

rm -f myapp.o myapp

6.

Link with system spesific libraries:

Windows

Add (among other things): wsock32.lib, ws2_32.lib, ole32.lib, dsound.lib

Linux, *nix, *BSD

Add (among other things): '-lpthread -lm' (at least). If you use the template Makefile above, these would have been added by PJ.

MacOS X

Add (among other things): '-framework CoreAudio? -lpthread -lm'. If you use the template Makefile above, these would have been added by PJ.