/* $Id$ */ /* * Copyright (C) 2008-2009 Teluu Inc. (http://www.teluu.com) * Copyright (C) 2003-2008 Benny Prijono * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with this program; if not, write to the Free Software * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA */ #ifndef __PJ_DOXYGEN_H__ #define __PJ_DOXYGEN_H__ /** * @file doxygen.h * @brief Doxygen's mainpage. */ /*////////////////////////////////////////////////////////////////////////// */ /* INTRODUCTION PAGE */ /** * @mainpage Welcome to PJLIB! * * @section intro_sec What is PJLIB * * PJLIB is an Open Source, small footprint framework library written in C for * making scalable applications. Because of its small footprint, it can be used * in embedded applications (we hope so!), but yet the library is also aimed for * facilitating the creation of high performance protocol stacks. * * PJLIB is released under GPL terms. * * @section download_sec Download * * PJLIB and all documentation can be downloaded from * http://www.pjsip.org. * * * @section how_to_use_sec About This Documentation * * This document is generated directly from PJLIB source file using * \a doxygen (http://www.doxygen.org). Doxygen is a great (and free!) * tools for generating such documentation. * * * @subsection find_samples_subsec How to Read This Document * * This documentation is laid out more to be a reference guide instead * of tutorial, therefore first time users may find it difficult to * grasp PJLIB by reading this document alone. * * However, we've tried our best to make this document easy to follow. * For first time users, we would suggest that you follow these steps * when reading this documentation: * * - continue reading this introduction chapter. At the end of this * chapter, you'll find section called \ref pjlib_fundamentals_sec * which should guide you to understand basic things about PJLIB. * * - find information about specific features that you want to use * in PJLIB. Use the Module Index to find out about all * features in PJLIB (if you're browsing the HTML documentation, * click on the \a Module link on top of the page, or if you're * reading the PDF documentation, click on \a Module \a Documentation * on the navigation pane on the left). * * @subsection doc_organize_sec How To's * * Please find below links to specific tasks that you probably * want to do: * * - How to Build PJLIB *\n * Please refer to \ref pjlib_build_sys_pg page for more information. * * - How to Use PJLIB in My Application *\n * Please refer to \ref configure_app_sec for more information. * * - How to Port PJLIB *\n * Please refer to \ref porting_pjlib_pg page. * * - Where to Read Samples Documentation *\n * Most of the modules provide link to the corresponding sample file. * Alternatively, to get the list of all examples, you can click on * Related Pages on the top of HTML document or on * PJLIB Page Documentation on navigation pane of your PDF reader. * * - How to Submit Code to PJLIB Project *\n * Please read \ref pjlib_coding_convention_page before submitting * your code. Send your code as patch against current Subversion tree * to the appropriate mailing list. * * * @section features_sec Features * * @subsection open_source_feat It's Open Source! * * PJLIB is currently released on GPL license, but other arrangements * can be made with the author. * * @subsection extreme_portable_feat Extreme Portability * * PJLIB is designed to be extremely portable. It can run on any kind * of processors (16-bit, 32-bit, or 64-bit, big or little endian, single * or multi-processors) and operating systems. Floating point or no * floating point. Multi-threading or not. * It can even run in environment where no ANSI LIBC is available. * * Currently PJLIB is known to run on these platforms: * - Win32/x86 (Win95/98/ME, NT/2000/XP/2003, mingw). * - arm, WinCE and Windows Mobile. * - Linux/x86, (user mode and as kernel module(!)). * - Linux/alpha * - Solaris/ultra. * - MacOS X/powerpc * - RTEMS (x86 and powerpc). * * And efforts is under way to port PJLIB on: * - Symbian OS * * * @subsection small_size_feat Small in Size * * One of the primary objectives is to have library that is small in size for * typical embedded applications. As a rough guidance, we aim to keep the * library size below 100KB for it to be considered as small. * As the result, most of the functionalities in the library can be tailored * to meet the requirements; user can enable/disable specific functionalities * to get the desired size/performance/functionality balance. * * For more info, please see @ref pj_config. * * * @subsection big_perform_feat Big in Performance * * Almost everything in PJLIB is designed to achieve the highest possible * performance out of the target platform. * * * @subsection no_dyn_mem No Dynamic Memory Allocations * * The central idea of PJLIB is that for applications to run as fast as it can, * it should not use \a malloc() at all, but instead should get the memory * from a preallocated storage pool. There are few things that can be * optimized with this approach: * * - \a alloc() is a O(1) operation. * - no mutex is used inside alloc(). It is assumed that synchronization * will be used in higher abstraction by application anyway. * - no \a free() is required. All chunks will be deleted when the pool is * destroyed. * * The performance gained on some systems can be as high as 30x speed up * against \a malloc() and \a free() on certain configurations, but of * course your mileage may vary. * * For more information, see \ref PJ_POOL_GROUP * * * @subsection os_abstract_feat Operating System Abstraction * * PJLIB has abstractions for features that are normally not portable * across operating systems: * - @ref PJ_THREAD *\n * Portable thread manipulation. * - @ref PJ_TLS *\n * Storing data in thread's private data. * - @ref PJ_MUTEX *\n * Mutual exclusion protection. * - @ref PJ_SEM *\n * Semaphores. * - @ref PJ_ATOMIC *\n * Atomic variables and their operations. * - @ref PJ_CRIT_SEC *\n * Fast locking of critical sections. * - @ref PJ_LOCK *\n * High level abstraction for lock objects. * - @ref PJ_EVENT *\n * Event object. * - @ref PJ_TIME *\n * Portable time manipulation. * - @ref PJ_TIMESTAMP *\n * High resolution time value. * - etc. * * * @subsection ll_network_io_sec Low-Level Network I/O * * PJLIB has very portable abstraction and fairly complete set of API for * doing network I/O communications. At the lowest level, PJLIB provides: * * - @ref PJ_SOCK *\n * A highly portable socket abstraction, runs on all kind of * network APIs such as standard BSD socket, Windows socket, Linux * \b kernel socket, PalmOS networking API, etc. * * - @ref pj_addr_resolve *\n * Portable address resolution, which implements #pj_gethostbyname(). * * - @ref PJ_SOCK_SELECT *\n * A portable \a select() like API (#pj_sock_select()) which can be * implemented with various back-end. * * * * @subsection timer_mgmt_sec Timer Management * * A passive framework for managing timer, see @ref PJ_TIMER for more info. * There is also function to retrieve high resolution timestamp * from the system (see @ref PJ_TIMESTAMP). * * * @subsection data_struct_sec Various Data Structures * * Various data structures are provided in the library: * * - @ref PJ_PSTR * - @ref PJ_ARRAY * - @ref PJ_HASH * - @ref PJ_LIST * - @ref PJ_RBTREE * * * @subsection exception_sec Exception Construct * * A convenient TRY/CATCH like construct to propagate errors, which by * default are used by the @ref PJ_POOL_GROUP "memory pool" and * the lexical scanner in pjlib-util. The exception * construct can be used to write programs like below: * * 
 *    #define SYNTAX_ERROR  1
 *
 *    PJ_TRY {
 *       msg = NULL;
 *       msg = parse_msg(buf, len);
 *    }
 *    PJ_CATCH ( SYNTAX_ERROR ) {
 *       .. handle error ..
 *    }
 *    PJ_END;
 *
* * Please see @ref PJ_EXCEPT for more information. * * * @subsection logging_sec Logging Facility * * PJLIB @ref PJ_LOG consists of macros to write logging information to * some output device. Some of the features of the logging facility: * * - the verbosity can be fine-tuned both at compile time (to control * the library size) or run-time (to control the verbosity of the * information). * - output device is configurable (e.g. stdout, printk, file, etc.) * - log decoration is configurable. * * See @ref PJ_LOG for more information. * * * @subsection guid_gen_sec Random and GUID Generation * * PJLIB provides facility to create random string * (#pj_create_random_string()) or globally unique identifier * (see @ref PJ_GUID). * * * * @section configure_app_sec Configuring Application to use PJLIB * * @subsection pjlib_compil_sec Building PJLIB * * Follow the instructions in \ref pjlib_build_sys_pg to build * PJLIB. * * @subsection pjlib_compil_app_sec Building Applications with PJLIB * * Use the following settings when building applications with PJLIB. * * @subsubsection compil_inc_dir_sec Include Search Path * * Add this to your include search path ($PJLIB is PJLIB root directory): * 
 *   $PJLIB/include
 *
* * @subsubsection compil_inc_file_sec Include PJLIB Header * * To include all PJLIB headers: * \verbatim #include \endverbatim * * Alternatively, you can include individual PJLIB headers like this: * \verbatim #include #include \endverbatim * * * @subsubsection compil_lib_dir_sec Library Path * * Add this to your library search path: * 
 *   $PJLIB/lib
 *
* * Then add the appropriate PJLIB library to your link specification. For * example, you would add \c libpj-i386-linux-gcc.a when you're building * applications in Linux. * * * @subsection pjlib_fundamentals_sec Principles in Using PJLIB * * Few things that you \b MUST do when using PJLIB, to make sure that * you create trully portable applications. * * @subsubsection call_pjlib_init_sec Call pj_init() * * Before you do anything else, call \c pj_init(). This would make sure that * PJLIB system is properly set up. * * @subsubsection no_ansi_subsec Do NOT Use ANSI C * * Contrary to popular teaching, ANSI C (and LIBC) is not the most portable * library in the world, nor it's the most ubiquitous. For example, LIBC * is not available in Linux kernel. Also normally LIBC will be excluded * from compilation of RTOSes to reduce size. * * So for maximum portability, do NOT use ANSI C. Do not even try to include * any other header files outside . Stick with the functionalities * provided by PJLIB. * * * @subsubsection string_rep_subsubsec Use pj_str_t instead of C Strings * * PJLIB uses pj_str_t instead of normal C strings. You SHOULD follow this * convention too. Remember, ANSI string-h is not always available. And * PJLIB string is faster! * * @subsubsection mem_alloc_subsubsec Use Pool for Memory Allocations * * You MUST NOT use \a malloc() or any other memory allocation functions. * Use PJLIB @ref PJ_POOL_GROUP instead! It's faster and most portable. * * @subsection logging_subsubsec Use Logging for Text Display * * DO NOT use for text output. Use PJLIB @ref PJ_LOG instead. * * * @section porting_pjlib_sec0 Porting PJLIB * * Please see \ref porting_pjlib_pg page on more information to port * PJLIB to new target. * * @section enjoy_sec Enjoy Using PJLIB! * * We hope that you find PJLIB usefull for your application. If you * have any questions, suggestions, critics, bug fixes, or anything * else, we would be happy to hear it. * * Enjoy using PJLIB! * * Benny Prijono < bennylp at pjsip dot org > */ /*////////////////////////////////////////////////////////////////////////// */ /* CODING CONVENTION */ /** * @page pjlib_coding_convention_page Coding Convention * * Before you submit your code/patches to be included with PJLIB, you must * make sure that your code is compliant with PJLIB coding convention. * This is very important! Otherwise we would not accept your code. * * @section coding_conv_editor_sec Editor Settings * * The single most important thing in the whole coding convention is editor * settings. It's more important than the correctness of your code (bugs will * only crash the system, but incorrect tab size is mental!). * * Kindly set your editor as follows: * - tab size to \b 8. * - indentation to \b 4. * * With \c vi, you can do it with: * 
 *  :se ts=8
 *  :se sts=4
 *
* * You should replace tab with eight spaces. * * @section coding_conv_detail_sec Coding Style * * Coding style MUST strictly follow K&R style. The rest of coding style * must follow current style. You SHOULD be able to observe the style * currently used by PJLIB from PJLIB sources, and apply the style to your * code. If you're not able to do simple thing like to observe PJLIB * coding style from the sources, then logic dictates that your ability to * observe more difficult area in PJLIB such as memory allocation strategy, * concurrency, etc is questionable. * * @section coding_conv_comment_sec Commenting Your Code * * Public API (e.g. in header files) MUST have doxygen compliant comments. * */ /*////////////////////////////////////////////////////////////////////////// */ /* BUILDING AND INSTALLING PJLIB */ /** * @page pjlib_build_sys_pg Building, and Installing PJLIB * * @section build_sys_install_sec Build and Installation * * \note * The most up-to-date information on building and installing PJLIB * should be found in the website, under "Getting Started" document. * More over, the new PJLIB build system is now based on autoconf, * so some of the information here might not be relevant anymore * (although most still are, since the autoconf script still use * the old Makefile system as the backend). * * @subsection build_sys_install_win32_sec Visual Studio * * The PJLIB Visual Studio workspace supports the building of PJLIB * for Win32 target. Although currently only the Visual Studio 6 Workspace is * actively maintained, developers with later version of Visual Studio * can easily imports VS6 workspace into their IDE. * * To start building PJLIB projects with Visual Studio 6 or later, open * the \a workspace file in the corresponding \b \c build directory. You have * several choices on which \a dsw file to open: \verbatim $PJPROJECT/pjlib/build/pjlib.dsw $PJPROJECT/pjsip/build/pjsip.dsw ..etc \endverbatim * * The easiest way is to open pjsip_apps.dsw file in \b \c $PJPROJECT/pjsip-apps/build * directory, and build pjsua project or the samples project. * However this will not build the complete projects. * For example, the PJLIB test is not included in this workspace. * To build the complete projects, you must * open and build each \a dsw file in \c build directory in each * subprojects. For example, to open the complete PJLIB workspace, open * pjlib.dsw in $PJPROJECT/pjlib/build directory. * * * @subsubsection config_site_create_vc_sec Create config_site.h * * The file $PJPROJECT/pjlib/include/pj/config_site.h * is supposed to contain configuration that is specific to your site/target. * This file is not part of PJLIB, so you must create it yourself. Normally * you just need to create a blank file. * * The reason why it's not included in PJLIB is so that you would not accidently * overwrite your site configuration. * * If you fail to do this, Visual C will complain with error like: * * "fatal error C1083: Cannot open include file: 'pj/config_site.h': No such file * or directory". * * @subsubsection build_vc_subsubsec Build the Projects * * Just hit the build button! * * * @subsection build_sys_install_unix_sec Make System * * For other targets, PJLIB provides a rather comprehensive build system * that uses GNU \a make (and only GNU \a make will work). * Currently, the build system supports building * PJLIB for these targets: * - i386/Win32/mingw * - i386/Linux * - i386/Linux (kernel) * - alpha/linux * - sparc/SunOS * - etc.. * * * @subsubsection build_req_sec Requirements * * In order to use the \c make based build system, you MUST have: * * - GNU make *\n * The Makefiles heavily utilize GNU make commands which most likely * are not available in other \c make system. * - bash shell is recommended. *\n * Specificly, there is a command "echo -n" which may not work * in other shells. This command is used when generating dependencies * (make dep) and it's located in * $PJPROJECT/build/rules.mak. * - ar, ranlib from GNU binutils *\n * In your system has different ar or ranlib (e.g. they * may have been installed as gar and granlib), then * either you create the relevant symbolic links, or modify * $PJPROJECT/build/cc-gcc.mak and rename ar and * ranlib to the appropriate names. * - gcc to generate dependency. *\n * Currently the build system uses "gcc -MM" to generate build * dependencies. If gcc is not desired to generate dependency, * then either you don't run make dep, or edit * $PJPROJECT/build/rules.mak to calculate dependency using * your prefered method. (And let me know when you do so so that I can * update the file. :) ) * * @subsubsection build_overview_sec Building the Project * * Generally, steps required to build the PJLIB are: * \verbatim $ cd /home/user/pjproject $ ./configure $ touch pjlib/include/pj/config_site.h $ make dep $ make \endverbatim * * The above process will build all static libraries and all applications. * * \note the configure script is not a proper autoconf script, * but rather a simple shell script to detect current host. This script * currently does not support cross-compilation. * * \note For Linux kernel target, there are additional steps required, which * will be explained in section \ref linux_kern_target_subsec. * * @subsubsection build_mak_sec Cross Compilation * * For cross compilation, you will need to edit the \c build.mak file in * \c $PJPROJECT root directory manually. Please see README-configure file * in the root directory for more information. * * For Linux kernel target, you are also required to declare the following * variables in this file: * - \c KERNEL_DIR: full path of kernel source tree. * - \c KERNEL_ARCH: kernel ARCH options (e.g. "ARCH=um"), or leave blank * for default. * - \c PJPROJECT_DIR: full path of PJPROJECT source tree. * * Apart from these, there are also additional steps required to build * Linux kernel target, which will be explained in \ref linux_kern_target_subsec. * * @subsubsection build_dir_sec Files in "build" Directory * * The *.mak files in \c $PJPROJECT/build directory are used to specify * the configuration for the specified compiler, target machine target * operating system, and host options. These files will be executed * (included) by \a make during building process, depending on the values * specified in $PJPROJECT/build.mak file. * * Normally you don't need to edit these files, except when you're porting * PJLIB to new target. * * Below are the description of some files in this directory: * * - rules.mak: contains generic rules always included during make. * - cc-gcc.mak: rules when gcc is used for compiler. * - cc-vc.mak: rules when MSVC compiler is used. * - host-mingw.mak: rules for building in mingw host. * - host-unix.mak: rules for building in Unix/Posix host. * - host-win32.mak: rules for building in Win32 command console * (only valid when VC is used). * - m-i386.mak: rules when target machine is an i386 processor. * - m-m68k.mak: rules when target machine is an m68k processor. * - os-linux.mak: rules when target OS is Linux. * - os-linux-kernel.mak: rules when PJLIB is to be build as * part of Linux kernel. * - os-win32.mak: rules when target OS is Win32. * * * @subsubsection config_site_create_sec Create config_site.h * * The file $PJPROJECT/pjlib/include/pj/config_site.h * is supposed to contain configuration that is specific to your site/target. * This file is not part of PJLIB, so you must create it yourself. * * The reason why it's not included in PJLIB is so that you would not accidently * overwrite your site configuration. * * * @subsubsection invoking_make_sec Invoking make * * Normally, \a make is invoked in \c build directory under each project. * For example, to build PJLIB, you would invoke \a make in * \c $PJPROJECT/pjlib/build directory like below: * \verbatim $ cd pjlib/build $ make \endverbatim * * Alternatively you may invoke make in $PJPROJECT * directory, to build all projects under that directory (e.g. * PJLIB, PJSIP, etc.). * * * @subsubsection linux_kern_target_subsec Linux Kernel Target * * \note * BUILDING APPLICATIONS IN LINUX KERNEL MODE IS A VERY DANGEROUS BUSINESS. * YOU MAY CRASH THE WHOLE OF YOUR SYSTEM, CORRUPT YOUR HARDISK, ETC. PJLIB * KERNEL MODULES ARE STILL IN EXPERIMENTAL PHASE. DO NOT RUN IT IN PRODUCTION * SYSTEMS OR OTHER SYSTEMS WHERE RISK OF LOSS OF DATA IS NOT ACCEPTABLE. * YOU HAVE BEEN WARNED. * * \note * User Mode Linux (UML) provides excellent way to experiment with Linux * kernel without risking the stability of the host system. See * http://user-mode-linux.sourceforge.net for details. * * \note * I only use UML to experiment with PJLIB kernel modules. * I wouldn't be so foolish to use my host Linux machine to experiment * with this. * * \note * You have been warned. * * For building PJLIB for Linux kernel target, there are additional steps required. * In general, the additional tasks are: * - Declare some more variables in build.mak file (this * has been explained in \ref build_mak_sec above). * - Perform these two small modifications in kernel source tree. * * There are two small modification need to be applied to the kernel tree. * * 1. Edit Makefile in kernel root source tree. * * Add the following lines at the end of the Makefile in your * $KERNEL_SRC dir: \verbatim script: $(SCRIPT) \endverbatim * * \note Remember to replace spaces with tab in the Makefile. * * The modification above is needed to capture kernel's \c $CFLAGS and * \c $CFLAGS_MODULE which will be used for PJLIB's compilation. * * 2. Add Additional Exports. * * We need the kernel to export some more symbols for our use. So we declare * the additional symbols to be exported in extra-exports.c file, and add * a this file to be compiled into the kernel: * * - Copy the file extra-exports.c from pjlib/src/pj * directory to $KERNEL_SRC/kernel/ directory. * - Edit Makefile in that directory, and add this line * somewhere after the declaration of that variable: \verbatim obj-y += extra-exports.o \endverbatim * * To illustrate what have been done in your kernel source tree, below * is screenshot of my kernel source tree _after_ the modification. * \verbatim [root@vpc-linux linux-2.6.7]# pwd /usr/src/linux-2.6.7 [root@vpc-linux linux-2.6.7]# [root@vpc-linux linux-2.6.7]# [root@vpc-linux linux-2.6.7]# tail Makefile endif # skip-makefile FORCE: .PHONY: script script: $(SCRIPT) [root@vpc-linux linux-2.6.7]# [root@vpc-linux linux-2.6.7]# [root@vpc-linux linux-2.6.7]# head kernel/extra-exports.c #include #include EXPORT_SYMBOL(sys_select); EXPORT_SYMBOL(sys_epoll_create); EXPORT_SYMBOL(sys_epoll_ctl); EXPORT_SYMBOL(sys_epoll_wait); EXPORT_SYMBOL(sys_socket); [root@vpc-linux linux-2.6.7]# [root@vpc-linux linux-2.6.7]# [root@vpc-linux linux-2.6.7]# head -15 kernel/Makefile # # Makefile for the linux kernel. # obj-y = sched.o fork.o exec_domain.o panic.o printk.o profile.o \ exit.o itimer.o time.o softirq.o resource.o \ sysctl.o capability.o ptrace.o timer.o user.o \ signal.o sys.o kmod.o workqueue.o pid.o \ rcupdate.o intermodule.o extable.o params.o posix-timers.o \ kthread.o obj-y += extra-exports.o obj-$(CONFIG_FUTEX) += futex.o obj-$(CONFIG_GENERIC_ISA_DMA) += dma.o [root@vpc-linux linux-2.6.7]# \endverbatim * * Then you must rebuild the kernel. * If you fail to do this, you won't be able to insmod pjlib. * * \note You will see a lots of warning messages during pjlib-test compilation. * The warning messages complain about unresolved symbols which are defined * in pjlib module. You can safely ignore these warnings. However, you can not * ignore warnings about non-pjlib unresolved symbols. * * * @subsection makefile_explained_sec Makefile Explained * * The \a Makefile for each project (e.g. PJLIB, PJSIP, etc) should be * very similar in the contents. The Makefile is located under \c build * directory in each project subdir. * * @subsubsection pjlib_makefile_subsec PJLIB Makefile. * * Below is PJLIB's Makefile: * * \include build/Makefile * * @subsubsection pjlib_os_makefile_subsec PJLIB os-linux.mak. * * Below is file os-linux.mak file in * $PJPROJECT/pjlib/build directory, * which is OS specific configuration file for Linux target that is specific * for PJLIB project. For \b global OS specific configuration, please see * $PJPROJECT/build/os-*.mak. * * \include build/os-linux.mak * */ /*////////////////////////////////////////////////////////////////////////// */ /* PORTING PJLIB */ /** * @page porting_pjlib_pg Porting PJLIB * * \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. * * * @section new_arch_sec 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 \ref porting_os_sec. * * 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 := $(CC_DEF)PJ_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 
 *      ...
 *
* - done. Build PJLIB with: * 
 *      $ cd $PJPROJECT/pjlib/build
 *      $ make dep
 *      $ make clean
 *      $ make
 *
* * @section porting_os_sec 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). * * @subsection new_compat_os_h_file_sec 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. * * @subsection modify_config_h_file_sec Modify config.h * * Then modify file include/pj/config.h to include * this file accordingly (e.g. when macro PJ_XOS is * defined): * \verbatim ... #elif defined(PJ_XOS) # include #else #... \endverbatim * * @subsection new_target_mak_file_sec 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 \c CFLAGS section: * \verbatim # # $PJPROJECT/build/os-xos.mak: # export OS_CFLAGS := $(CC_DEF)PJ_XOS=1 export OS_CXXFLAGS := export OS_LDFLAGS := export OS_SOURCES := \endverbatim * * * @subsection new_target_prj_mak_file_sec 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: \verbatim # # 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 \endverbatim * * @subsection new_target_src_sec 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 \c errno and * \c 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 * \c 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. * * @subsection new_target_build_file_sec 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. * * @subsection new_target_edit_vs_new_file_sec 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. */ #endif /* __PJ_DOXYGEN_H__ */