wiki:Getting-Started/Autoconf

Version 17 (modified by ismangil, 12 years ago) (diff)

--

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

  1. Supported Targets
  2. Requirements
    1. Tools and development libraries
    2. Video Support (for 2.0 and above)
    3. Host requirements
  3. Running configure
    1. Using Default Settings
    2. Features Customization
    3. Configuring Debug Version and Other Customizations
    4. Configuring TLS Support
  4. Cross Compilation
  5. Running make
  6. Build Customizations
  7. Optional: Installing PJSIP
  8. Next: Using pjsip libraries in your applications

Supported Targets

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

Requirements

Tools and development libraries

In order to use PJSIP'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.

Video Support (for 2.0 and above)

The following components are needed for video:

  1. Linux: Video4Linux2 (v4l2) development library.
  2. Mac OS X: You might have an old libbz2 for older system, in that case it has to be rebuild (needed by ffmpeg H.264 support)
  3. SDL version 1.3 (contained in SDL version 2.0).
    • Note that this is the newer and not yet released SDL library, hence most likely it won't be installed by default on your system. You can download the SDL 2.0 source snapshot or from the Mercurial repository from http://www.libsdl.org/hg.php.
    • SDL 1.3 is under SDL sub-directory of SDL 2.0.
  4. ffmpeg development library. We tested with ffmpeg version ranging from 0.5.1 (from circa 2009) to 0.10.
    • Note that for H.264 support, you need newer releases (October 2011 onwards), and it needs libz too.
    • Build with at least:
      $ ./configure --enable-shared --disable-static --enable-memalign-hack
                            # add other options if needed, e.g: optimization, install dir, search path 
                            # particularly CFLAGS and LDFLAGS for x264
                            # to enable H264, add "--enable-gpl --enable-libx264"
      $ make && make install
      
  5. Optional for H.264: libx264. We tested with the latest from git (as of October 2011):
    $ ./configure --enable-static      # add options if needed, e.g: optimization, install dir, search path
    $ make && make install-lib-static  # default install dir is /usr/local
    
  6. Optional: Qt development SDK for building the video GUI sample. We tested with version 4.6 or later.
    • without this you can still enjoy video with pjsua console application

Host requirements

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.

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.

Configure with Video Support

Add this to your config_site.h:

#define PJMEDIA_HAS_VIDEO	1

Video requirements will be detected by the configure script. Pay attention to the following output (the sample below was taken on a Mac):

...
Using SDL prefix... /Users/pjsip/Desktop/opt
checking SDL availability..... 1.3.0
Using ffmpeg prefix... /Users/pjsip/Desktop/opt
checking for pkg-config... no
checking for python... python pkgconfig.py
checking ffmpeg packages...  libavformat libavcodec libswscale libavutil
checking for v4l2_open in -lv4l2... no
...

The above output shows the SDL version detected, 1.3.0 in this case, and the ffmpeg packages found (libavformat, libavcodec, etc.). Note that for this particular build, alternative locations (prefixes) are specified for both SDL and ffmpeg with --with-sdl and -with-ffmpeg options respectively.

Note on ffmpeg libraries dependencies:

The pkg-config tool is used to detect the correct compilation settings and library dependency for the ffmpeg packages. The pkg-config is not installed by default on Mac, as the output above shows, hence we use the alternate pkgconfig.py script. You need to have Python installed to run this script of course, and the configure script detects its availability automatically. If Python is not available, you will need to supply the correct CFLAGS and LDFLAGS manually prior to running configure so that it is able to detect ffmpeg libraries.

For example, if ffmpeg was built with x264 and mp3 encoder support, you will need to pass additional "-lx264 -lmp3lame" flags when linking libavformat. With manual checking in the configure script, the AC_CHECK_LIB(avformat) would not be able to detect that it needs to add "-lx264 -lmp3lame" as the dependency, hence you need to put this in the LDFLAGS prior to running configure.

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)
--disable-sdl           Disable SDL (default: not disabled)
--disable-ffmpeg        Disable ffmpeg (default: not disabled)
--disable-v4l2          Disable Video4Linux2 (default: not disabled)

...

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.

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.

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:

allThe default (or first) target to build the libraries/binaries.
dep, dependBuild dependencies rule from the source files.
cleanClean the object files for current target, but keep the output library/binary files intact.
distclean, realcleanRemove 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.

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 +=

Optional: Installing PJSIP

Run make install to install the header and library files to the target directory. The default target directory can be customized by specifying --prefix=DIR option to configure script.

$ make install

Next: Using pjsip libraries in your applications

Follow the steps described in building applications with GNU tools You can also go to Video User's Guide for video usage instructions for pjsip version 2.x.