Note: Since version 0.5.8, PJLIB build system is now based on autoconf, so most of the time we shouldn't need to apply the tweakings below to get PJLIB working on a new platform. However, since the autoconf build system still uses the old Makefile build system, the information below may still be useful for reference.

Porting to New CPU Architecture

Below is step-by-step guide to add support for new CPU architecture. This sample is based on porting to Alpha architecture; however steps for porting to other CPU architectures should be pretty similar.

Also note that in this example, the operating system used is Linux. Should you wish to add support for new operating system, then follow the next section Porting to New Operating System Target.

Step-by-step guide to port to new CPU architecture:

decide the name for the new architecture. In this case, we choose alpha.

edit file $PJPROJECT/build.mak, and add new section for the new target:

        #
        # Linux alpha, gcc
        #
        export MACHINE_NAME := alpha
        export OS_NAME := linux
        export CC_NAME := gcc
        export HOST_NAME := unix

create a new file $PJPROJECT/build/m-alpha.mak. Alternatively create a copy from other file in this directory. The contents of this file will look something like:
```
        export M_CFLAGS := -DPJ_M_ALPHA=1
        export M_CXXFLAGS :=
        export M_LDFLAGS :=
        export M_SOURCES :=
      
```
create a new file $PJPROJECT/pjlib/include/pj/compat/m_alpha.h. Alternatively create a copy from other header file in this directory. The contents of this file will look something like:
```
        #define PJ_HAS_PENTIUM          0
        #define PJ_IS_LITTLE_ENDIAN     1
        #define PJ_IS_BIG_ENDIAN        0
      
```

edit pjlib/include/pj/config.h. Add new processor configuration in this header file, like follows:

        ...
        #elif defined (PJ_M_ALPHA) && PJ_M_ALPHA != 0
        #   include <pj/compat/m_alpha.h>
        ...

done. Build PJLIB with:

        $ cd $PJPROJECT/pjlib/build
        $ make dep
        $ make clean
        $ make

Porting to New Operating System Target

This section will try to give you rough guideline on how to port PJLIB to a new target. As a sample, we give the target a name tag, for example xos (for X OS).

Create New Compat Header File

You'll need to create a new header file include/pj/compat/os_xos.h. You can copy as a template other header file and edit it accordingly.

Modify config.h

Then modify file include/pj/config.h to include this file accordingly (e.g. when macro PJ_XOS is defined):

 ...
 #elif defined(PJ_XOS)
 #  include <pj/compat/os_xos.h>
 #else
 #...

Create New Global Make Config File

Then you'll need to create global configuration file that is specific for this OS, i.e. os-xos.mak in $PJPROJECT/build directory.

At very minimum, the file will normally need to define PJ_XOS=1 in the CFLAGS section:

#
# $PJPROJECT/build/os-xos.mak:
#
export OS_CFLAGS   := $(CC_DEF)PJ_XOS=1
export OS_CXXFLAGS := 
export OS_LDFLAGS  :=
export OS_SOURCES  :=

Create New Project's Make Config File

Then you'll need to create xos-specific configuration file for PJLIB. This file is also named os-xos.mak, but its located in pjlib/build directory. This file will specify source files that are specific to this OS to be included in the build process.

Below is a sample:

#
# pjlib/build/os-xos.mak:
#  XOS specific configuration for PJLIB.
#
export PJLIB_OBJS +=    os_core_xos.o \
                        os_error_unix.o \
                        os_time_ansi.o
export TEST_OBJS +=     main.o
export TARGETS      =   pjlib pjlib-test

Create and Edit Source Files

You'll normally need to create at least these files:

os_core_xos.c: core OS specific functionality.
os_timestamp_xos.c: how to get timestamp in this OS.

Depending on how things are done in your OS, you may need to create these files:

os_error_*.c: how to manipulate OS error codes. Alternatively you may use existing os_error_unix.c if the OS has errno and strerror() function.
ioqueue_*.c: if the OS has specific method to perform asynchronous I/O. Alternatively you may use existing ioqueue_select.c if the OS supports select() function call.
sock_*.c: if the OS has specific method to perform socket communication. Alternatively you may use existing sock_bsd.c if the OS supports BSD socket API, and edit include/pj/compat/socket.h file accordingly.

You will also need to check various files in include/pj/compat/xxx.h, to see if they're compatible with your OS.

Build The Project

After basic building blocks have been created for the OS, then the easiest way to see which parts need to be fixed is by building the project and see the error messages.

Editing Existing Files vs Creating New File

When you encounter compatibility errors in PJLIB during porting, you have three options on how to fix the error:

edit the existing *.c file, and give it #ifdef switch for the new OS, or
edit include/pj/compat/*.h instead, or
create a totally new file.

Basicly there is no strict rule on which approach is the best to use, however the following guidelines may be used:

if the file is expected to be completely different than any existing file, then perhaps you should create a completely new file. For example, file os_core_xxx.c will normally be different for each OS flavour.
if the difference can be localized in include/compat header file, and existing #ifdef switch is there, then preferably you should edit this include/compat header file.
if the existing *.c file has #ifdef switch, then you may add another #elif switch there. This normally is used for behaviors that are not totally different on each platform.
other than that above, use your own judgement on whether to edit the file or create new file etc.