- 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
- 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
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
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.
Then modify file
include/pj/config.h to include this file accordingly (e.g. when macro
PJ_XOS is defined):
# include <pj/compat/os_xos.h>
Create New Global Make Config File
Then you'll need to create global configuration file that is specific for this OS, i.e.
At very minimum, the file will normally need to define
PJ_XOS=1 in the
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:
# XOS specific configuration for PJLIB.
export PJLIB_OBJS += os_core_xos.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
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/*.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
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.