← Back to branch summary

~ubuntu-branches/ubuntu/wily/sflphone/wily

« back to all changes in this revision

Viewing changes to daemon/libs/pjproject-2.2.1/pjlib/include/pj/doxygen.h

  • Committer: Package Import Robot
  • Author(s): Francois Marier, Francois Marier, Mark Purcell
  • Date: 2014-10-18 15:08:50 UTC
  • mfrom: (1.1.12)
  • mto: This revision was merged to the branch mainline in revision 29.
  • Revision ID: package-import@ubuntu.com-20141018150850-2exfk34ckb15pcwi
Tags: 1.4.1-0.1
http://bugs.debian.org/759576
http://bugs.debian.org/741130
[ Francois Marier ]
* Non-maintainer upload
* New upstream release (closes: #759576, #741130)
  - debian/rules +PJPROJECT_VERSION := 2.2.1
  - add upstream patch to fix broken TLS support
  - add patch to fix pjproject regression

[ Mark Purcell ]
* Build-Depends:
  - sflphone-daemon + libavformat-dev, libavcodec-dev, libswscale-dev,
  libavdevice-dev, libavutil-dev
  - sflphone-gnome + libclutter-gtk-1.0-dev

Show diffs side-by-side

added added

removed removed

Lines of Context:
daemon/libs/pjproject-2.2.1/pjlib/include/pj/doxygen.h
 
1
/* $Id: doxygen.h 3553 2011-05-05 06:14:19Z nanang $ */
 
2
/* 
 
3
 * Copyright (C) 2008-2011 Teluu Inc. (http://www.teluu.com)
 
4
 * Copyright (C) 2003-2008 Benny Prijono <benny@prijono.org>
 
5
 *
 
6
 * This program is free software; you can redistribute it and/or modify
 
7
 * it under the terms of the GNU General Public License as published by
 
8
 * the Free Software Foundation; either version 2 of the License, or
 
9
 * (at your option) any later version.
 
10
 *
 
11
 * This program is distributed in the hope that it will be useful,
 
12
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 
13
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 
14
 * GNU General Public License for more details.
 
15
 *
 
16
 * You should have received a copy of the GNU General Public License
 
17
 * along with this program; if not, write to the Free Software
 
18
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA 
 
19
 */
 
20
#ifndef __PJ_DOXYGEN_H__
 
21
#define __PJ_DOXYGEN_H__
 
22
 
 
23
/**
 
24
 * @file doxygen.h
 
25
 * @brief Doxygen's mainpage.
 
26
 */
 
27
 
 
28
/*////////////////////////////////////////////////////////////////////////// */
 
29
/*
 
30
        INTRODUCTION PAGE
 
31
 */
 
32
 
 
33
/**
 
34
 * @mainpage Welcome to PJLIB!
 
35
 *
 
36
 * @section intro_sec What is PJLIB
 
37
 *
 
38
 * PJLIB is an Open Source, small footprint framework library written in C for 
 
39
 * making scalable applications. Because of its small footprint, it can be used
 
40
 * in embedded applications (we hope so!), but yet the library is also aimed for
 
41
 * facilitating the creation of high performance protocol stacks.
 
42
 *
 
43
 * PJLIB is released under GPL terms.
 
44
 *
 
45
 * @section download_sec Download
 
46
 *
 
47
 * PJLIB and all documentation can be downloaded from 
 
48
 * http://www.pjsip.org.
 
49
 *
 
50
 *
 
51
 * @section how_to_use_sec About This Documentation
 
52
 *
 
53
 * This document is generated directly from PJLIB source file using
 
54
 * \a doxygen (http://www.doxygen.org). Doxygen is a great (and free!) 
 
55
 * tools for generating such documentation.
 
56
 *
 
57
 *
 
58
 * @subsection find_samples_subsec How to Read This Document
 
59
 *
 
60
 * This documentation is laid out more to be a reference guide instead
 
61
 * of tutorial, therefore first time users may find it difficult to
 
62
 * grasp PJLIB by reading this document alone.
 
63
 *
 
64
 * However, we've tried our best to make this document easy to follow.
 
65
 * For first time users, we would suggest that you follow these steps
 
66
 * when reading this documentation:
 
67
 *
 
68
 *  - continue reading this introduction chapter. At the end of this
 
69
 *    chapter, you'll find section called \ref pjlib_fundamentals_sec
 
70
 *    which should guide you to understand basic things about PJLIB.
 
71
 *
 
72
 *  - find information about specific features that you want to use
 
73
 *    in PJLIB. Use the <b>Module Index</b> to find out about all 
 
74
 *    features in PJLIB (if you're browsing the HTML documentation,
 
75
 *    click on the \a Module link on top of the page, or if you're
 
76
 *    reading the PDF documentation, click on \a Module \a Documentation
 
77
 *    on the navigation pane on the left).
 
78
 *
 
79
 * @subsection doc_organize_sec How To's
 
80
 *
 
81
 * Please find below links to specific tasks that you probably
 
82
 * want to do:
 
83
 *
 
84
 *  - <b>How to Build PJLIB</b>
 
85
 *\n
 
86
 * Please refer to \ref pjlib_build_sys_pg page for more information.
 
87
 *
 
88
 *  - <b>How to Use PJLIB in My Application</b>
 
89
 *\n
 
90
 * Please refer to \ref configure_app_sec for more information.
 
91
 *
 
92
 *  - <b>How to Port PJLIB</b>
 
93
 *\n
 
94
 * Please refer to \ref porting_pjlib_pg page.
 
95
 *
 
96
 *  - <b>Where to Read Samples Documentation</b>
 
97
 *\n
 
98
 * Most of the modules provide link to the corresponding sample file.
 
99
 * Alternatively, to get the list of all examples, you can click on 
 
100
 * <b>Related Pages</b> on the top of HTML document or on 
 
101
 * <b>PJLIB Page Documentation</b> on navigation pane of your PDF reader.
 
102
 *
 
103
 *  - <b>How to Submit Code to PJLIB Project</b>
 
104
 *\n
 
105
 * Please read \ref pjlib_coding_convention_page before submitting
 
106
 * your code. Send your code as patch against current Subversion tree
 
107
 * to the appropriate mailing list.
 
108
 *
 
109
 *
 
110
 * @section features_sec Features
 
111
 *
 
112
 * @subsection open_source_feat It's Open Source!
 
113
 *
 
114
 * PJLIB is currently released on GPL license, but other arrangements
 
115
 * can be made with the author.
 
116
 *
 
117
 * @subsection extreme_portable_feat Extreme Portability
 
118
 *
 
119
 * PJLIB is designed to be extremely portable. It can run on any kind
 
120
 * of processors (16-bit, 32-bit, or 64-bit, big or little endian, single
 
121
 * or multi-processors) and operating systems. Floating point or no
 
122
 * floating point. Multi-threading or not.
 
123
 * It can even run in environment where no ANSI LIBC is available. 
 
124
 *
 
125
 * Currently PJLIB is known to run on these platforms:
 
126
 *  - Win32/x86 (Win95/98/ME, NT/2000/XP/2003, mingw).
 
127
 *  - arm, WinCE and Windows Mobile.
 
128
 *  - Linux/x86, (user mode and as <b>kernel module</b>(!)).
 
129
 *  - Linux/alpha
 
130
 *  - Solaris/ultra.
 
131
 *  - MacOS X/powerpc
 
132
 *  - RTEMS (x86 and powerpc).
 
133
 *
 
134
 * And efforts is under way to port PJLIB on:
 
135
 *  - Symbian OS
 
136
 *
 
137
 *
 
138
 * @subsection small_size_feat Small in Size
 
139
 *
 
140
 * One of the primary objectives is to have library that is small in size for
 
141
 * typical embedded applications. As a rough guidance, we aim to keep the 
 
142
 * library size below 100KB for it to be considered as small.
 
143
 * As the result, most of the functionalities in the library can be tailored
 
144
 * to meet the requirements; user can enable/disable specific functionalities
 
145
 * to get the desired size/performance/functionality balance.
 
146
 *
 
147
 * For more info, please see @ref pj_config.
 
148
 *
 
149
 *
 
150
 * @subsection big_perform_feat Big in Performance
 
151
 *
 
152
 * Almost everything in PJLIB is designed to achieve the highest possible
 
153
 * performance out of the target platform. 
 
154
 *
 
155
 *
 
156
 * @subsection no_dyn_mem No Dynamic Memory Allocations
 
157
 *
 
158
 * The central idea of PJLIB is that for applications to run as fast as it can,
 
159
 * it should not use \a malloc() at all, but instead should get the memory 
 
160
 * from a preallocated storage pool. There are few things that can be 
 
161
 * optimized with this approach:
 
162
 *
 
163
 *  - \a alloc() is a O(1) operation.
 
164
 *  - no mutex is used inside alloc(). It is assumed that synchronization 
 
165
 *    will be used in higher abstraction by application anyway.
 
166
 *  - no \a free() is required. All chunks will be deleted when the pool is 
 
167
 *    destroyed.
 
168
 *
 
169
 * The performance gained on some systems can be as high as 30x speed up
 
170
 * against \a malloc() and \a free() on certain configurations, but of
 
171
 * course your mileage may vary. 
 
172
 *
 
173
 * For more information, see \ref PJ_POOL_GROUP
 
174
 *
 
175
 * 
 
176
 * @subsection os_abstract_feat Operating System Abstraction
 
177
 *
 
178
 * PJLIB has abstractions for features that are normally not portable 
 
179
 * across operating systems: 
 
180
 *  - @ref PJ_THREAD
 
181
 *\n
 
182
 *    Portable thread manipulation.
 
183
 *  - @ref PJ_TLS
 
184
 *\n
 
185
 *    Storing data in thread's private data.
 
186
 *  - @ref PJ_MUTEX
 
187
 *\n
 
188
 *    Mutual exclusion protection.
 
189
 *  - @ref PJ_SEM
 
190
 *\n
 
191
 *    Semaphores.
 
192
 *  - @ref PJ_ATOMIC
 
193
 *\n
 
194
 *    Atomic variables and their operations.
 
195
 *  - @ref PJ_CRIT_SEC
 
196
 *\n
 
197
 *    Fast locking of critical sections.
 
198
 *  - @ref PJ_LOCK
 
199
 *\n
 
200
 *    High level abstraction for lock objects.
 
201
 *  - @ref PJ_EVENT
 
202
 *\n
 
203
 *    Event object.
 
204
 *  - @ref PJ_TIME
 
205
 *\n
 
206
 *    Portable time manipulation.
 
207
 *  - @ref PJ_TIMESTAMP
 
208
 *\n
 
209
 *    High resolution time value.
 
210
 *  - etc.
 
211
 *
 
212
 *
 
213
 * @subsection ll_network_io_sec Low-Level Network I/O
 
214
 *
 
215
 * PJLIB has very portable abstraction and fairly complete set of API for
 
216
 * doing network I/O communications. At the lowest level, PJLIB provides:
 
217
 *
 
218
 *  - @ref PJ_SOCK
 
219
 *\n
 
220
 *    A highly portable socket abstraction, runs on all kind of
 
221
 *    network APIs such as standard BSD socket, Windows socket, Linux
 
222
 *    \b kernel socket, PalmOS networking API, etc.
 
223
 *
 
224
 *  - @ref pj_addr_resolve
 
225
 *\n
 
226
 *    Portable address resolution, which implements #pj_gethostbyname().
 
227
 *
 
228
 *  - @ref PJ_SOCK_SELECT
 
229
 *\n
 
230
 *    A portable \a select() like API (#pj_sock_select()) which can be
 
231
 *    implemented with various back-end.
 
232
 *
 
233
 *
 
234
 *
 
235
 * @subsection timer_mgmt_sec Timer Management
 
236
 *
 
237
 * A passive framework for managing timer, see @ref PJ_TIMER for more info.
 
238
 * There is also function to retrieve high resolution timestamp
 
239
 * from the system (see @ref PJ_TIMESTAMP).
 
240
 *
 
241
 *
 
242
 * @subsection data_struct_sec Various Data Structures
 
243
 *
 
244
 * Various data structures are provided in the library:
 
245
 *
 
246
 *  - @ref PJ_PSTR
 
247
 *  - @ref PJ_ARRAY
 
248
 *  - @ref PJ_HASH
 
249
 *  - @ref PJ_LIST
 
250
 *  - @ref PJ_RBTREE
 
251
 *
 
252
 *
 
253
 * @subsection exception_sec Exception Construct
 
254
 *
 
255
 * A convenient TRY/CATCH like construct to propagate errors, which by
 
256
 * default are used by the @ref PJ_POOL_GROUP "memory pool" and 
 
257
 * the lexical scanner in pjlib-util. The exception
 
258
 * construct can be used to write programs like below:
 
259
 *
 
260
 * <pre>
 
261
 *    #define SYNTAX_ERROR  1
 
262
 *
 
263
 *    PJ_TRY {
 
264
 *       msg = NULL;
 
265
 *       msg = parse_msg(buf, len);
 
266
 *    }
 
267
 *    PJ_CATCH ( SYNTAX_ERROR ) {
 
268
 *       .. handle error ..
 
269
 *    }
 
270
 *    PJ_END;
 
271
 * </pre>
 
272
 *
 
273
 * Please see @ref PJ_EXCEPT for more information.
 
274
 *
 
275
 *
 
276
 * @subsection logging_sec Logging Facility
 
277
 *
 
278
 * PJLIB @ref PJ_LOG consists of macros to write logging information to
 
279
 * some output device. Some of the features of the logging facility:
 
280
 *
 
281
 *  - the verbosity can be fine-tuned both at compile time (to control
 
282
 *    the library size) or run-time (to control the verbosity of the
 
283
 *    information).
 
284
 *  - output device is configurable (e.g. stdout, printk, file, etc.)
 
285
 *  - log decoration is configurable.
 
286
 *
 
287
 * See @ref PJ_LOG for more information.
 
288
 *
 
289
 *
 
290
 * @subsection guid_gen_sec Random and GUID Generation
 
291
 *
 
292
 * PJLIB provides facility to create random string 
 
293
 * (#pj_create_random_string()) or globally unique identifier
 
294
 * (see @ref PJ_GUID).
 
295
 *
 
296
 *
 
297
 *
 
298
 * @section configure_app_sec Configuring Application to use PJLIB
 
299
 *
 
300
 * @subsection pjlib_compil_sec Building PJLIB
 
301
 *
 
302
 * Follow the instructions in \ref pjlib_build_sys_pg to build
 
303
 * PJLIB.
 
304
 *
 
305
 * @subsection pjlib_compil_app_sec Building Applications with PJLIB
 
306
 *
 
307
 * Use the following settings when building applications with PJLIB.
 
308
 *
 
309
 * @subsubsection compil_inc_dir_sec Include Search Path
 
310
 *
 
311
 * Add this to your include search path ($PJLIB is PJLIB root directory):
 
312
 * <pre>
 
313
 *   $PJLIB/include
 
314
 * </pre>
 
315
 *
 
316
 * @subsubsection compil_inc_file_sec Include PJLIB Header
 
317
 *
 
318
 * To include all PJLIB headers:
 
319
 * \verbatim
 
320
    #include <pjlib.h>
 
321
   \endverbatim
 
322
 *
 
323
 * Alternatively, you can include individual PJLIB headers like this:
 
324
 * \verbatim
 
325
     #include <pj/log.h>
 
326
     #include <pj/os.h>
 
327
  \endverbatim
 
328
 *
 
329
 *
 
330
 * @subsubsection compil_lib_dir_sec Library Path
 
331
 *
 
332
 * Add this to your library search path:
 
333
 * <pre>
 
334
 *   $PJLIB/lib
 
335
 * </pre>
 
336
 *
 
337
 * Then add the appropriate PJLIB library to your link specification. For
 
338
 * example, you would add \c libpj-i386-linux-gcc.a when you're building
 
339
 * applications in Linux.
 
340
 *
 
341
 *
 
342
 * @subsection pjlib_fundamentals_sec Principles in Using PJLIB
 
343
 *
 
344
 * Few things that you \b MUST do when using PJLIB, to make sure that
 
345
 * you create trully portable applications.
 
346
 *
 
347
 * @subsubsection call_pjlib_init_sec Call pj_init()
 
348
 *
 
349
 * Before you do anything else, call \c pj_init(). This would make sure that
 
350
 * PJLIB system is properly set up.
 
351
 *
 
352
 * @subsubsection no_ansi_subsec Do NOT Use ANSI C
 
353
 *
 
354
 * Contrary to popular teaching, ANSI C (and LIBC) is not the most portable
 
355
 * library in the world, nor it's the most ubiquitous. For example, LIBC
 
356
 * is not available in Linux kernel. Also normally LIBC will be excluded
 
357
 * from compilation of RTOSes to reduce size.
 
358
 *
 
359
 * So for maximum portability, do NOT use ANSI C. Do not even try to include
 
360
 * any other header files outside <include/pj>. Stick with the functionalities
 
361
 * provided by PJLIB. 
 
362
 *
 
363
 *
 
364
 * @subsubsection string_rep_subsubsec Use pj_str_t instead of C Strings
 
365
 *
 
366
 * PJLIB uses pj_str_t instead of normal C strings. You SHOULD follow this
 
367
 * convention too. Remember, ANSI string-h is not always available. And
 
368
 * PJLIB string is faster!
 
369
 *
 
370
 * @subsubsection mem_alloc_subsubsec Use Pool for Memory Allocations
 
371
 *
 
372
 * You MUST NOT use \a malloc() or any other memory allocation functions.
 
373
 * Use PJLIB @ref PJ_POOL_GROUP instead! It's faster and most portable.
 
374
 *
 
375
 * @subsection logging_subsubsec Use Logging for Text Display
 
376
 *
 
377
 * DO NOT use <stdio.h> for text output. Use PJLIB @ref PJ_LOG instead.
 
378
 *
 
379
 *
 
380
 * @section porting_pjlib_sec0 Porting PJLIB
 
381
 *
 
382
 * Please see \ref porting_pjlib_pg page on more information to port
 
383
 * PJLIB to new target.
 
384
 *
 
385
 * @section enjoy_sec Enjoy Using PJLIB!
 
386
 *
 
387
 * We hope that you find PJLIB usefull for your application. If you
 
388
 * have any questions, suggestions, critics, bug fixes, or anything
 
389
 * else, we would be happy to hear it.
 
390
 *
 
391
 * Enjoy using PJLIB!
 
392
 *
 
393
 * Benny Prijono < bennylp at pjsip dot org >
 
394
 */
 
395
 
 
396
 
 
397
 
 
398
/*////////////////////////////////////////////////////////////////////////// */
 
399
/*
 
400
         CODING CONVENTION
 
401
 */
 
402
 
 
403
/**
 
404
 * @page pjlib_coding_convention_page Coding Convention
 
405
 *
 
406
 * Before you submit your code/patches to be included with PJLIB, you must
 
407
 * make sure that your code is compliant with PJLIB coding convention.
 
408
 * <b>This is very important!</b> Otherwise we would not accept your code.
 
409
 *
 
410
 * @section coding_conv_editor_sec Editor Settings
 
411
 *
 
412
 * The single most important thing in the whole coding convention is editor 
 
413
 * settings. It's more important than the correctness of your code (bugs will
 
414
 * only crash the system, but incorrect tab size is mental!).
 
415
 *
 
416
 * Kindly set your editor as follows:
 
417
 *  - tab size to \b 8.
 
418
 *  - indentation to \b 4.
 
419
 *
 
420
 * With \c vi, you can do it with:
 
421
 * <pre>
 
422
 *  :se ts=8
 
423
 *  :se sts=4
 
424
 * </pre>
 
425
 *
 
426
 * You should replace tab with eight spaces.
 
427
 *
 
428
 * @section coding_conv_detail_sec Coding Style
 
429
 *
 
430
 * Coding style MUST strictly follow K&R style. The rest of coding style
 
431
 * must follow current style. You SHOULD be able to observe the style
 
432
 * currently used by PJLIB from PJLIB sources, and apply the style to your 
 
433
 * code. If you're not able to do simple thing like to observe PJLIB
 
434
 * coding style from the sources, then logic dictates that your ability to
 
435
 * observe more difficult area in PJLIB such as memory allocation strategy, 
 
436
 * concurrency, etc is questionable.
 
437
 *
 
438
 * @section coding_conv_comment_sec Commenting Your Code
 
439
 *
 
440
 * Public API (e.g. in header files) MUST have doxygen compliant comments.
 
441
 *
 
442
 */
 
443
 
 
444
 
 
445
/*////////////////////////////////////////////////////////////////////////// */
 
446
/*
 
447
        BUILDING AND INSTALLING PJLIB
 
448
 */
 
449
 
 
450
 
 
451
 
 
452
/**
 
453
 * @page pjlib_build_sys_pg Building, and Installing PJLIB
 
454
 *
 
455
 * @section build_sys_install_sec Build and Installation
 
456
 *
 
457
 * \note
 
458
 * <b>The most up-to-date information on building and installing PJLIB
 
459
 *  should be found in the website, under "Getting Started" document.
 
460
 *  More over, the new PJLIB build system is now based on autoconf,
 
461
 *  so some of the information here might not be relevant anymore 
 
462
 *  (although most still are, since the autoconf script still use
 
463
 *  the old Makefile system as the backend).</b>
 
464
 *
 
465
 * @subsection build_sys_install_win32_sec Visual Studio
 
466
 *
 
467
 * The PJLIB Visual Studio workspace supports the building of PJLIB
 
468
 * for Win32 target. Although currently only the Visual Studio 6 Workspace is
 
469
 * actively maintained, developers with later version of Visual Studio
 
470
 * can easily imports VS6 workspace into their IDE.
 
471
 *
 
472
 * To start building PJLIB projects with Visual Studio 6 or later, open
 
473
 * the \a workspace file in the corresponding \b \c build directory. You have
 
474
 * several choices on which \a dsw file to open:
 
475
 \verbatim
 
476
  $PJPROJECT/pjlib/build/pjlib.dsw
 
477
  $PJPROJECT/pjsip/build/pjsip.dsw
 
478
 ..etc
 
479
 \endverbatim
 
480
 *
 
481
 * The easiest way is to open <tt>pjsip_apps.dsw</tt> file in \b \c $PJPROJECT/pjsip-apps/build
 
482
 * directory, and build pjsua project or the samples project. 
 
483
 * However this will not build the complete projects. 
 
484
 * For example, the PJLIB test is not included in this workspace. 
 
485
 * To build the complete projects, you must
 
486
 * open and build each \a dsw file in \c build directory in each
 
487
 * subprojects. For example, to open the complete PJLIB workspace, open
 
488
 * <tt>pjlib.dsw</tt> in <tt>$PJPROJECT/pjlib/build</tt> directory.
 
489
 *
 
490
 *
 
491
 * @subsubsection config_site_create_vc_sec Create config_site.h
 
492
 *
 
493
 * The file <tt><b>$PJPROJECT/pjlib/include/pj/config_site.h</b></tt>
 
494
 * is supposed to contain configuration that is specific to your site/target.
 
495
 * This file is not part of PJLIB, so you must create it yourself. Normally
 
496
 * you just need to create a blank file.
 
497
 *
 
498
 * The reason why it's not included in PJLIB is so that you would not accidently
 
499
 * overwrite your site configuration.
 
500
 *
 
501
 * If you fail to do this, Visual C will complain with error like: 
 
502
 *
 
503
 * <b>"fatal error C1083: Cannot open include file: 'pj/config_site.h': No such file 
 
504
 * or directory"</b>.
 
505
 *
 
506
 * @subsubsection build_vc_subsubsec Build the Projects
 
507
 *
 
508
 * Just hit the build button!
 
509
 *
 
510
 *
 
511
 * @subsection build_sys_install_unix_sec Make System
 
512
 *
 
513
 * For other targets, PJLIB provides a rather comprehensive build system
 
514
 * that uses GNU \a make (and only GNU \a make will work). 
 
515
 * Currently, the build system supports building * PJLIB for these targets:
 
516
 *  - i386/Win32/mingw
 
517
 *  - i386/Linux
 
518
 *  - i386/Linux (kernel)
 
519
 *  - alpha/linux
 
520
 *  - sparc/SunOS
 
521
 *  - etc..
 
522
 *
 
523
 *
 
524
 * @subsubsection build_req_sec Requirements
 
525
 *
 
526
 * In order to use the \c make based build system, you MUST have:
 
527
 *
 
528
 *  - <b>GNU make</b>
 
529
 *\n
 
530
 *    The Makefiles heavily utilize GNU make commands which most likely
 
531
 *    are not available in other \c make system.
 
532
 *  - <b>bash</b> shell is recommended.
 
533
 *\n
 
534
 *    Specificly, there is a command <tt>"echo -n"</tt> which may not work
 
535
 *    in other shells. This command is used when generating dependencies
 
536
 *    (<tt>make dep</tt>) and it's located in 
 
537
 *    <tt>$PJPROJECT/build/rules.mak</tt>.
 
538
 *  - <b>ar</b>, <b>ranlib</b> from GNU binutils
 
539
 *\n
 
540
 *    In your system has different <tt>ar</tt> or <tt>ranlib</tt> (e.g. they
 
541
 *    may have been installed as <tt>gar</tt> and <tt>granlib</tt>), then
 
542
 *    either you create the relevant symbolic links, <b>or</b> modify
 
543
 *    <tt>$PJPROJECT/build/cc-gcc.mak</tt> and rename <tt>ar</tt> and
 
544
 *    <tt>ranlib</tt> to the appropriate names.
 
545
 *  - <b>gcc</b> to generate dependency.
 
546
 *\n
 
547
 *    Currently the build system uses <tt>"gcc -MM"</tt> to generate build
 
548
 *    dependencies. If <tt>gcc</tt> is not desired to generate dependency,
 
549
 *    then either you don't run <tt>make dep</tt>, <b>or</b> edit
 
550
 *    <tt>$PJPROJECT/build/rules.mak</tt> to calculate dependency using
 
551
 *    your prefered method. (And let me know when you do so so that I can
 
552
 *    update the file. :) )
 
553
 *
 
554
 * @subsubsection build_overview_sec Building the Project
 
555
 *
 
556
 * Generally, steps required to build the PJLIB are:
 
557
 *
 
558
 \verbatim
 
559
   $ cd /home/user/pjproject
 
560
   $ ./configure
 
561
   $ touch pjlib/include/pj/config_site.h
 
562
   $ make dep
 
563
   $ make
 
564
 \endverbatim
 
565
 *
 
566
 * The above process will build all static libraries and all applications.
 
567
 *
 
568
 * \note the <tt>configure</tt> script is not a proper autoconf script,
 
569
 * but rather a simple shell script to detect current host. This script
 
570
 * currently does not support cross-compilation.
 
571
 *
 
572
 * \note For Linux kernel target, there are additional steps required, which
 
573
 * will be explained in section \ref linux_kern_target_subsec.
 
574
 *
 
575
 * @subsubsection build_mak_sec Cross Compilation
 
576
 * 
 
577
 * For cross compilation, you will need to edit the \c build.mak file in 
 
578
 * \c $PJPROJECT root directory manually. Please see <b>README-configure</b> file
 
579
 * in the root directory for more information.
 
580
 *
 
581
 * For Linux kernel target, you are also required to declare the following
 
582
 * variables in this file:
 
583
 *      - \c KERNEL_DIR: full path of kernel source tree.
 
584
 *      - \c KERNEL_ARCH: kernel ARCH options (e.g. "ARCH=um"), or leave blank
 
585
 *           for default.
 
586
 *      - \c PJPROJECT_DIR: full path of PJPROJECT source tree.
 
587
 *
 
588
 * Apart from these, there are also additional steps required to build
 
589
 * Linux kernel target, which will be explained in \ref linux_kern_target_subsec.
 
590
 *
 
591
 * @subsubsection build_dir_sec Files in "build" Directory
 
592
 *
 
593
 * The <tt>*.mak</tt> files in \c $PJPROJECT/build directory are used to specify
 
594
 * the configuration for the specified compiler, target machine target 
 
595
 * operating system, and host options. These files will be executed
 
596
 * (included) by \a make during building process, depending on the values
 
597
 * specified in <b>$PJPROJECT/build.mak</b> file.
 
598
 *
 
599
 * Normally you don't need to edit these files, except when you're porting
 
600
 * PJLIB to new target.
 
601
 *
 
602
 * Below are the description of some files in this directory:
 
603
 *
 
604
 *  - <tt>rules.mak</tt>: contains generic rules always included during make.
 
605
 *  - <tt>cc-gcc.mak</tt>: rules when gcc is used for compiler.
 
606
 *  - <tt>cc-vc.mak</tt>: rules when MSVC compiler is used.
 
607
 *  - <tt>host-mingw.mak</tt>: rules for building in mingw host.
 
608
 *  - <tt>host-unix.mak</tt>: rules for building in Unix/Posix host.
 
609
 *  - <tt>host-win32.mak</tt>: rules for building in Win32 command console
 
610
 *    (only valid when VC is used).
 
611
 *  - <tt>m-i386.mak</tt>: rules when target machine is an i386 processor.
 
612
 *  - <tt>m-m68k.mak</tt>: rules when target machine is an m68k processor.
 
613
 *  - <tt>os-linux.mak</tt>: rules when target OS is Linux.
 
614
 *  - <tt>os-linux-kernel.mak</tt>: rules when PJLIB is to be build as
 
615
 *    part of Linux kernel.
 
616
 *  - <tt>os-win32.mak</tt>: rules when target OS is Win32.
 
617
 *
 
618
 *
 
619
 * @subsubsection config_site_create_sec Create config_site.h
 
620
 *
 
621
 * The file <tt><b>$PJPROJECT/pjlib/include/pj/config_site.h</b></tt>
 
622
 * is supposed to contain configuration that is specific to your site/target.
 
623
 * This file is not part of PJLIB, so you must create it yourself.
 
624
 *
 
625
 * The reason why it's not included in PJLIB is so that you would not accidently
 
626
 * overwrite your site configuration.
 
627
 *
 
628
 *
 
629
 * @subsubsection invoking_make_sec Invoking make
 
630
 *
 
631
 * Normally, \a make is invoked in \c build directory under each project.
 
632
 * For example, to build PJLIB, you would invoke \a make in
 
633
 * \c $PJPROJECT/pjlib/build directory like below:
 
634
 *
 
635
 \verbatim
 
636
   $ cd pjlib/build
 
637
   $ make
 
638
 \endverbatim
 
639
 *
 
640
 * Alternatively you may invoke <tt>make</tt> in <tt>$PJPROJECT</tt> 
 
641
 * directory, to build all projects under that directory (e.g. 
 
642
 * PJLIB, PJSIP, etc.).
 
643
 *
 
644
 *
 
645
 * @subsubsection linux_kern_target_subsec Linux Kernel Target
 
646
 *
 
647
 * \note
 
648
 * <b>BUILDING APPLICATIONS IN LINUX KERNEL MODE IS A VERY DANGEROUS BUSINESS.
 
649
 * YOU MAY CRASH THE WHOLE OF YOUR SYSTEM, CORRUPT YOUR HARDISK, ETC. PJLIB
 
650
 * KERNEL MODULES ARE STILL IN EXPERIMENTAL PHASE. DO NOT RUN IT IN PRODUCTION
 
651
 * SYSTEMS OR OTHER SYSTEMS WHERE RISK OF LOSS OF DATA IS NOT ACCEPTABLE.
 
652
 * YOU HAVE BEEN WARNED.</b>
 
653
 *
 
654
 * \note
 
655
 * <b>User Mode Linux (UML)</b> provides excellent way to experiment with Linux
 
656
 * kernel without risking the stability of the host system. See
 
657
 * http://user-mode-linux.sourceforge.net for details.
 
658
 *
 
659
 * \note
 
660
 * I only use <b>UML</b> to experiment with PJLIB kernel modules.
 
661
 * <b>I wouldn't be so foolish to use my host Linux machine to experiment
 
662
 * with this.</b> 
 
663
 *
 
664
 * \note
 
665
 * You have been warned.
 
666
 *
 
667
 * For building PJLIB for Linux kernel target, there are additional steps required.
 
668
 * In general, the additional tasks are:
 
669
 *      - Declare some more variables in <b><tt>build.mak</tt></b> file (this
 
670
 *        has been explained in \ref build_mak_sec above).
 
671
 *      - Perform these two small modifications in kernel source tree.
 
672
 *
 
673
 * There are two small modification need to be applied to the kernel tree.
 
674
 *
 
675
 * <b>1. Edit <tt>Makefile</tt> in kernel root source tree.</b>
 
676
 *
 
677
 * Add the following lines at the end of the <tt>Makefile</tt> in your 
 
678
 * <tt>$KERNEL_SRC</tt> dir:
 
679
 \verbatim
 
680
script:
 
681
       $(SCRIPT)
 
682
 \endverbatim
 
683
 *
 
684
 * \note Remember to replace spaces with <b>tab</b> in the Makefile.
 
685
 *
 
686
 * The modification above is needed to capture kernel's \c $CFLAGS and 
 
687
 * \c $CFLAGS_MODULE which will be used for PJLIB's compilation.
 
688
 *
 
689
 * <b>2. Add Additional Exports.</b>
 
690
 *
 
691
 * We need the kernel to export some more symbols for our use. So we declare
 
692
 * the additional symbols to be exported in <tt>extra-exports.c</tt> file, and add
 
693
 * a this file to be compiled into the kernel:
 
694
 *
 
695
 *      - Copy the file <tt>extra-exports.c</tt> from <tt>pjlib/src/pj</tt> 
 
696
 *        directory to <tt>$KERNEL_SRC/kernel/</tt> directory.
 
697
 *      - Edit <tt>Makefile</tt> in that directory, and add this line
 
698
 *        somewhere after the declaration of that variable:
 
699
 \verbatim
 
700
obj-y   += extra-exports.o
 
701
 \endverbatim
 
702
 *
 
703
 * To illustrate what have been done in your kernel source tree, below
 
704
 * is screenshot of my kernel source tree _after_ the modification.
 
705
 *
 
706
 \verbatim
 
707
[root@vpc-linux linux-2.6.7]# pwd
 
708
/usr/src/linux-2.6.7
 
709
[root@vpc-linux linux-2.6.7]# 
 
710
[root@vpc-linux linux-2.6.7]# 
 
711
[root@vpc-linux linux-2.6.7]# tail Makefile 
 
712
 
 
713
endif   # skip-makefile
 
714
 
 
715
FORCE:
 
716
 
 
717
.PHONY: script
 
718
 
 
719
script:
 
720
        $(SCRIPT)
 
721
 
 
722
[root@vpc-linux linux-2.6.7]# 
 
723
[root@vpc-linux linux-2.6.7]# 
 
724
[root@vpc-linux linux-2.6.7]# head kernel/extra-exports.c 
 
725
#include <linux/module.h>
 
726
#include <linux/syscalls.h>
 
727
 
 
728
EXPORT_SYMBOL(sys_select);
 
729
 
 
730
EXPORT_SYMBOL(sys_epoll_create);
 
731
EXPORT_SYMBOL(sys_epoll_ctl);
 
732
EXPORT_SYMBOL(sys_epoll_wait);
 
733
 
 
734
EXPORT_SYMBOL(sys_socket);
 
735
[root@vpc-linux linux-2.6.7]# 
 
736
[root@vpc-linux linux-2.6.7]# 
 
737
[root@vpc-linux linux-2.6.7]# head -15 kernel/Makefile 
 
738
#
 
739
# Makefile for the linux kernel.
 
740
#
 
741
 
 
742
obj-y     = sched.o fork.o exec_domain.o panic.o printk.o profile.o \
 
743
            exit.o itimer.o time.o softirq.o resource.o \
 
744
            sysctl.o capability.o ptrace.o timer.o user.o \
 
745
            signal.o sys.o kmod.o workqueue.o pid.o \
 
746
            rcupdate.o intermodule.o extable.o params.o posix-timers.o \
 
747
            kthread.o
 
748
 
 
749
obj-y   +=  extra-exports.o
 
750
 
 
751
obj-$(CONFIG_FUTEX) += futex.o
 
752
obj-$(CONFIG_GENERIC_ISA_DMA) += dma.o
 
753
[root@vpc-linux linux-2.6.7]# 
 
754
 
 
755
 \endverbatim
 
756
 *
 
757
 * Then you must rebuild the kernel.
 
758
 * If you fail to do this, you won't be able to <b>insmod</b> pjlib.
 
759
 *
 
760
 * \note You will see a lots of warning messages during pjlib-test compilation.
 
761
 * The warning messages complain about unresolved symbols which are defined
 
762
 * in pjlib module. You can safely ignore these warnings. However, you can not
 
763
 * ignore warnings about non-pjlib unresolved symbols.
 
764
 *
 
765
 * 
 
766
 * @subsection makefile_explained_sec Makefile Explained
 
767
 *
 
768
 * The \a Makefile for each project (e.g. PJLIB, PJSIP, etc) should be
 
769
 * very similar in the contents. The Makefile is located under \c build
 
770
 * directory in each project subdir.
 
771
 *
 
772
 * @subsubsection pjlib_makefile_subsec PJLIB Makefile.
 
773
 *
 
774
 * Below is PJLIB's Makefile:
 
775
 *
 
776
 * \include build/Makefile
 
777
 *
 
778
 * @subsubsection pjlib_os_makefile_subsec PJLIB os-linux.mak.
 
779
 *
 
780
 * Below is file <tt><b>os-linux.mak</b></tt> file in 
 
781
 * <tt>$PJPROJECT/pjlib/build</tt> directory,
 
782
 * which is OS specific configuration file for Linux target that is specific 
 
783
 * for PJLIB project. For \b global OS specific configuration, please see
 
784
 * <tt>$PJPROJECT/build/os-*.mak</tt>.
 
785
 *
 
786
 * \include build/os-linux.mak
 
787
 *
 
788
 */
 
789
 
 
790
 
 
791
/*////////////////////////////////////////////////////////////////////////// */
 
792
/*
 
793
         PORTING PJLIB
 
794
 */
 
795
 
 
796
 
 
797
 
 
798
/**
 
799
 * @page porting_pjlib_pg Porting PJLIB
 
800
 *
 
801
 * \note
 
802
 * <b>Since version 0.5.8, PJLIB build system is now based on autoconf, so
 
803
 * most of the time we shouldn't need to apply the tweakings below to get
 
804
 * PJLIB working on a new platform. However, since the autoconf build system
 
805
 * still uses the old Makefile build system, the information below may still
 
806
 * be useful for reference.
 
807
 * </b>
 
808
 *
 
809
 * @section new_arch_sec Porting to New CPU Architecture
 
810
 *
 
811
 * Below is step-by-step guide to add support for new CPU architecture.
 
812
 * This sample is based on porting to Alpha architecture; however steps for 
 
813
 * porting to other CPU architectures should be pretty similar. 
 
814
 *
 
815
 * Also note that in this example, the operating system used is <b>Linux</b>.
 
816
 * Should you wish to add support for new operating system, then follow
 
817
 * the next section \ref porting_os_sec.
 
818
 *
 
819
 * Step-by-step guide to port to new CPU architecture:
 
820
 *  - decide the name for the new architecture. In this case, we choose
 
821
 *    <tt><b>alpha</b></tt>.
 
822
 *  - edit file <tt>$PJPROJECT/build.mak</tt>, and add new section for
 
823
 *    the new target:
 
824
 *    <pre>
 
825
 *      #
 
826
 *      # Linux alpha, gcc
 
827
 *      #
 
828
 *      export MACHINE_NAME := <b>alpha</b>
 
829
 *      export OS_NAME := linux
 
830
 *      export CC_NAME := gcc
 
831
 *      export HOST_NAME := unix
 
832
 *    </pre>
 
833
 *
 
834
 *  - create a new file <tt>$PJPROJECT/build/<b>m-alpha</b>.mak</tt>.
 
835
 *    Alternatively create a copy from other file in this directory.
 
836
 *    The contents of this file will look something like:
 
837
 *    <pre>
 
838
 *      export M_CFLAGS := $(CC_DEF)<b>PJ_M_ALPHA=1</b>
 
839
 *      export M_CXXFLAGS :=
 
840
 *      export M_LDFLAGS :=
 
841
 *      export M_SOURCES :=
 
842
 *    </pre>
 
843
 *  - create a new file <tt>$PJPROJECT/pjlib/include/pj/compat/<b>m_alpha.h</b></tt>.
 
844
 *    Alternatively create a copy from other header file in this directory.
 
845
 *    The contents of this file will look something like:
 
846
 *    <pre>
 
847
 *      #define PJ_HAS_PENTIUM          0
 
848
 *      #define PJ_IS_LITTLE_ENDIAN     1
 
849
 *      #define PJ_IS_BIG_ENDIAN        0
 
850
 *    </pre>
 
851
 *  - edit <tt>pjlib/include/pj/<b>config.h</b></tt>. Add new processor
 
852
 *    configuration in this header file, like follows:
 
853
 *    <pre>
 
854
 *      ...
 
855
 *      #elif defined (PJ_M_ALPHA) && PJ_M_ALPHA != 0
 
856
 *      #   include <pj/compat/m_alpha.h>
 
857
 *      ...
 
858
 *    </pre>
 
859
 *  - done. Build PJLIB with:
 
860
 *    <pre>
 
861
 *      $ cd $PJPROJECT/pjlib/build
 
862
 *      $ make dep
 
863
 *      $ make clean
 
864
 *      $ make
 
865
 *    </pre>
 
866
 *
 
867
 * @section porting_os_sec Porting to New Operating System Target
 
868
 *
 
869
 * This section will try to give you rough guideline on how to
 
870
 * port PJLIB to a new target. As a sample, we give the target a name tag, 
 
871
 * for example <tt><b>xos</b></tt> (for X OS). 
 
872
 *
 
873
 * @subsection new_compat_os_h_file_sec Create New Compat Header File
 
874
 *
 
875
 * You'll need to create a new header file 
 
876
 * <b><tt>include/pj/compat/os_xos.h</tt></b>. You can copy as a 
 
877
 * template other header file and edit it accordingly.
 
878
 *
 
879
 * @subsection modify_config_h_file_sec Modify config.h
 
880
 *
 
881
 * Then modify file <b><tt>include/pj/config.h</tt></b> to include
 
882
 * this file accordingly (e.g. when macro <tt><b>PJ_XOS</b></tt> is
 
883
 * defined):
 
884
 *
 
885
 \verbatim
 
886
 ...
 
887
 #elif defined(PJ_XOS)
 
888
 #  include <pj/compat/os_xos.h>
 
889
 #else
 
890
 #...
 
891
 \endverbatim
 
892
 * 
 
893
 * @subsection new_target_mak_file_sec Create New Global Make Config File
 
894
 *
 
895
 * Then you'll need to create global configuration file that
 
896
 * is specific for this OS, i.e. <tt><b>os-xos.mak</b></tt> in 
 
897
 * <tt><b>$PJPROJECT/build</b></tt> directory.
 
898
 *
 
899
 * At very minimum, the file will normally need to define
 
900
 * <tt><b>PJ_XOS=1</b></tt> in the \c CFLAGS section:
 
901
 *
 
902
 \verbatim
 
903
#
 
904
# $PJPROJECT/build/os-xos.mak:
 
905
#
 
906
export OS_CFLAGS   := $(CC_DEF)PJ_XOS=1
 
907
export OS_CXXFLAGS := 
 
908
export OS_LDFLAGS  :=
 
909
export OS_SOURCES  := 
 
910
 \endverbatim
 
911
 *
 
912
 *
 
913
 * @subsection new_target_prj_mak_file_sec Create New Project's Make Config File
 
914
 *
 
915
 * Then you'll need to create xos-specific configuration file
 
916
 * for PJLIB. This file is also named <tt><b>os-xos.mak</b></tt>,
 
917
 * but its located in <tt><b>pjlib/build</b></tt> directory.
 
918
 * This file will specify source files that are specific to
 
919
 * this OS to be included in the build process.
 
920
 *
 
921
 * Below is a sample:
 
922
 \verbatim
 
923
#
 
924
# pjlib/build/os-xos.mak:
 
925
#  XOS specific configuration for PJLIB.
 
926
#
 
927
export PJLIB_OBJS +=    os_core_xos.o \
 
928
                        os_error_unix.o \
 
929
                        os_time_ansi.o
 
930
export TEST_OBJS +=     main.o
 
931
export TARGETS      =   pjlib pjlib-test
 
932
 \endverbatim
 
933
 *
 
934
 * @subsection new_target_src_sec Create and Edit Source Files
 
935
 *
 
936
 * You'll normally need to create at least these files:
 
937
 *  - <tt><b>os_core_xos.c</b></tt>: core OS specific
 
938
 *    functionality.
 
939
 *  - <tt><b>os_timestamp_xos.c</b></tt>: how to get timestamp
 
940
 *    in this OS.
 
941
 *
 
942
 * Depending on how things are done in your OS, you may need
 
943
 * to create these files:
 
944
 *  - <tt><b>os_error_*.c</b></tt>: how to manipulate
 
945
 *    OS error codes. Alternatively you may use existing
 
946
 *    <tt>os_error_unix.c</tt> if the OS has \c errno and
 
947
 *    \c strerror() function.
 
948
 *  - <tt><b>ioqueue_*.c</b></tt>: if the OS has specific method
 
949
 *    to perform asynchronous I/O. Alternatively you may
 
950
 *    use existing <tt>ioqueue_select.c</tt> if the OS supports
 
951
 *    \c select() function call.
 
952
 *  - <tt><b>sock_*.c</b></tt>: if the OS has specific method
 
953
 *    to perform socket communication. Alternatively you may
 
954
 *    use existing <tt>sock_bsd.c</tt> if the OS supports
 
955
 *    BSD socket API, and edit <tt>include/pj/compat/socket.h</tt>
 
956
 *    file accordingly.
 
957
 *
 
958
 * You will also need to check various files in 
 
959
 * <tt><b>include/pj/compat/*.h</b></tt>, to see if they're 
 
960
 * compatible with your OS.
 
961
 *
 
962
 * @subsection new_target_build_file_sec Build The Project
 
963
 *
 
964
 * After basic building blocks have been created for the OS, then
 
965
 * the easiest way to see which parts need to be fixed is by building
 
966
 * the project and see the error messages.
 
967
 *
 
968
 * @subsection new_target_edit_vs_new_file_sec Editing Existing Files vs Creating New File
 
969
 *
 
970
 * When you encounter compatibility errors in PJLIB during porting,
 
971
 * you have three options on how to fix the error:
 
972
 *  - edit the existing <tt>*.c</tt> file, and give it <tt>#ifdef</tt>
 
973
 *    switch for the new OS, or
 
974
 *  - edit <tt>include/pj/compat/*.h</tt> instead, or
 
975
 *  - create a totally new file.
 
976
 *
 
977
 * Basicly there is no strict rule on which approach is the best
 
978
 * to use, however the following guidelines may be used:
 
979
 *  - if the file is expected to be completely different than
 
980
 *    any existing file, then perhaps you should create a completely
 
981
 *    new file. For example, file <tt>os_core_xxx.c</tt> will 
 
982
 *    normally be different for each OS flavour.
 
983
 *  - if the difference can be localized in <tt>include/compat</tt>
 
984
 *    header file, and existing <tt>#ifdef</tt> switch is there,
 
985
 *    then preferably you should edit this <tt>include/compat</tt>
 
986
 *    header file.
 
987
 *  - if the existing <tt>*.c</tt> file has <tt>#ifdef</tt> switch,
 
988
 *    then you may add another <tt>#elif</tt> switch there. This
 
989
 *    normally is used for behaviors that are not totally
 
990
 *    different on each platform.
 
991
 *  - other than that above, use your own judgement on whether
 
992
 *    to edit the file or create new file etc.
 
993
 */
 
994
 
 
995
#endif  /* __PJ_DOXYGEN_H__ */
 
996