The quickest and most robust way to solve a problem is often to incorporate an existing solution. In project terms - why implement a new feature if we can find an implementation and just integrate it into ours? The answer, usually, is that there's no reason - integrating externally-available functionality is at the heart of much of what we've done in sipXecs, but there are some rules and some processes to be followed to keep it from being disruptive to others and/or harmful to the project.

...

The

...

The following outlines the steps you should take when incorporating an external dependency to ensure that you don't disrupt the work of other developers or the construction of release builds and ISO images.

Component Organization

The top level directory when you check out sipXecs has directories for components, along with a few files that control how those components relate to each other. Mostly, when adding a dependency, you're going to be either adding something to be used by some component or adding an entire standalone component.

Autoconf test for dependency

...

...

The traditional instructions for how to build and open source project from source are to

1. download the source tarball
2. unpack it
3. cd into the directory it creates
4. run configure
5. run make all install

We'd like those instructions to work for sipXecs (a goal we have not really achieved, since to begin with we don't create a single source tarball for everything). We would also would like it to be true that it's easy to get started one step earlier by checking out from the source control system. In order to achieve this, we need to automate as much as possible of the checking for dependencies. We use the GNU build system (see box at right) as our top level build framework, so if you add a dependency, you must add checks to the the files that control the build.

...

25%
Info
This wiki page is not going to attempt to do a full tutorial on autoconf or the other tools we use - for more complete documentation, see the GNU Build System.

configure.ac and the config directory

...

If there is no pre-packaged test for your dependency, you need to write one. You can either should create it in a file config/component.m4, or just edit it into config/general.m4 (for external components) or config/sipXecs.m4 (for other sipXecs components). then include that file in your configure.ac.

Here is a simple test:

...

# ================ NET SNMP ================
AC_DEFUN([CHECK_FOO],
[
    AC_MSG_CHECKING([for foo includes ])
    include_path="$includedir $prefix/include /usr/include /usr/local/include"
    include_check="foo/foo.h"

    foundpath=""
    for dir in $include_path ; do
        if test -f "$dir/$include_check";
        then
            foundpath=$dir;
            break;

fi;
    done
    if test x_$foundpath = x_; then
       AC_MSG_ERROR('$include_check' not found)
    else
       AC_MSG_RESULT($foundpath/$include_check)
    fi
])

This code defines the CHECK_FOO test macro; it is written in the m4 macro language, which when processed generates a shell script code fragment that is incorporated into the configure script.

The AC_MSG_CHECKING macro causes configure to print a progress message about what it is looking for - this message does not get a newline at the end.

The for loop checks in a series of directories for the foo/foo.h include file. The search list should be chosen to look in all the places the target file might be on different platforms, including those installed from rpm (or equivalent) packages or from source. In this case, all the choices were ones that will be in the default search path for include files, so no manipulation of the path is needed. There are a number of examples in config/general.m4 that do more elaborate searches and set variables used by other parts of the build.

The AC_MSG_RESULT macro causes configure to print a success message about where it found the file.

The AC_MSG_ERROR macro causes configure to print a failure message, and aborts configure.

Once you have the test macro defined, you just need to add an invocation of it to the configure.ac file at the top of any component that requires it:

...

Update ISO package definitions

...

...

Update the Express Development Environment (EDE)

See Express Development Environment Setup for information on the EDE. Making sure that it is updated will keep many of the sipXecs developers from bugging you when you break their builds.