Add support for ICE/STUN/TURN in res_rtp_asterisk and chan_sip.
[asterisk/asterisk.git] / res / pjproject / README.txt
1  Copyright (C) 2003-2008 Benny Prijono <benny@prijono.org>
2  Copyright (C) 2008-2011 Teluu Inc. (http://www.teluu.com)
3
4  This program is free software: you can redistribute it and/or modify it
5  under the terms of the GNU General Public License as published by the Free
6  Software Foundation, either version 2 of the License, or (at your option)
7  any later version.
8
9  This program is distributed in the hope that it will be useful, but
10  WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
11  or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
12  for more details.
13
14  You should have received a copy of the GNU General Public License along
15  with this program. If not, see http://www.gnu.org/licenses/.
16
17
18 Getting Started: Building and Using PJSIP and PJMEDIA
19
20    [Last Update: $Date$]
21
22                                                    Print Friendly Page
23      _________________________________________________________________
24
25    This article describes how to download, customize, build, and use the open
26    source PJSIP and PJMEDIA SIP and media stack. The online (and HTML) version
27    of this file can be downloaded from http://www.pjsip.org/using.htm
28
29
30 Quick Info
31      _________________________________________________________________
32
33    Building with GNU tools (Linux, *BSD, MacOS X, mingw, etc.)
34           Generally these should be all that are needed to build the libraries,
35           applications, and samples:
36
37    $ ./configure
38    $ make dep && make clean && make
39
40    Building Win32 Target with Microsoft Visual Studio
41           Generally we can just do these steps:
42
43          1. Visual Studio 6: open pjproject.dsw workspace,
44          2. Visual Studio 2005: open pjproject-vs8.sln solution,
45          3. Create an empty pjlib/include/pj/config_site.h, and
46          4. build the pjsua application.
47
48    Building for Windows Mobile
49           Generally these are all that are needed:
50
51          1. Open pjsip-apps/build/wince-evc4/wince_demos.vcw EVC4 workspace,
52          2. Create an empty pjlib/include/pj/config_site.h, and
53          3. build the pjsua_wince application.
54
55    Invoking Older Build System (e.g. for RTEMS)
56           Generally these should be all that are needed to build the libraries,
57           applications, and samples:
58
59    $ ./configure-legacy
60    $ make dep && make clean && make
61
62    Locating Output Binaries/Libraries
63           Libraries will be put in lib directory, and binaries will be put in
64           bin directory, under each projects.
65
66    Running the Applications
67           After successful build, you can try running pjsua application on
68           pjsip-apps/bin   directory.   PJSUA  manual  can  be  found  in
69           http://www.pjsip.org/pjsua.htm page.
70
71
72 Table of Contents:
73      _________________________________________________________________
74
75    1. Getting the Source Distribution
76
77      1.1 Getting the Release tarball
78
79      1.2 Getting from Subversion trunk
80
81      1.3 Source Directories Layout
82
83    2. Build Preparation
84
85      2.1 config_site.h file
86
87      2.2 Disk Space Requirements
88
89    3.  Building Linux, *nix, *BSD, and MacOS X Targets with GNU Build
90    Systems
91
92      3.1 Supported Targets
93
94      3.2 Requirements
95
96      3.3 Running configure
97
98      3.4 Running make
99
100      3.5 Cross Compilation
101
102      3.6 Build Customizations
103
104    4. Building for Windows Targets with Microsoft Visual Studio
105
106      4.1 Requirements
107
108      4.2 Building the Projects
109
110      4.3 Debugging the Sample Application
111
112    5. Building for Windows Mobile Targets (Windows CE/WinCE/PDA/SmartPhone)
113
114      5.1 Requirements
115
116      5.2 Building the Projects
117
118    6. Older PJLIB Build System for Non-Autoconf Targets (e.g. RTEMS)
119
120      6.1 Supported Targets
121
122      6.2 Invoking the Build System
123
124    7. Running the Applications
125
126      7.1 pjsua
127
128      7.2 Sample Applications
129
130      7.3 pjlib-test
131
132      7.4 pjsip-test
133
134    8. Using PJPROJECT with Applications
135
136
137    Appendix I: Common Problems/Frequently Asked Question (FAQ)
138
139      I.1 fatal error C1083: Cannot open include file: 'pj/config_site.h':
140    No such file or directory
141
142
143 1. Getting the Source Code Distribution
144      _________________________________________________________________
145
146    All libraries (PJLIB, PJLIB-UTIL, PJSIP, PJMEDIA, and PJMEDIA-CODEC) are
147    currently distributed under a single source tree, collectively named as
148    PJPROJECT or just PJ libraries. These libraries can be obtained by either
149    downloading the release tarball or getting them from the Subversion trunk.
150
151
152 1.1 Getting the Release tarball
153      _________________________________________________________________
154
155    Getting the released tarball is a convenient way to obtain stable version of
156    PJPROJECT. The tarball may not contain the latest features or bug-fixes, but
157    normally it is considered more stable as each will be tested more rigorously
158    before released.
159
160    The   latest   released   tarball   can   be   downloaded   from   the
161    http://www.pjsip.org/download.htm.
162
163
164 1.2 Getting from Subversion trunk
165      _________________________________________________________________
166
167    PJPROJECT  Subversion  repository  will always contain the latest/most
168    up-to-date version of the sources. Normally the Subversion repository is
169    always kept in a "good" state. However, there's always a chance that things
170    break  and  the  tree  doesn't  build  correctly (particularly for the
171    "not-so-popular" targets), so please consult the mailing list should there
172    be any problems.
173
174    Using Subversion also has benefits of keeping the local copy of the source
175    up to date with the main PJ source tree and to easily track the changes made
176    to the local copy, if any.
177
178
179 What is Subversion
180
181    Subversion (SVN) is Open Source version control system similar to CVS.
182    Subversion homepage is in http://subversion.tigris.org/
183
184
185 Getting Subversion Client
186
187    A Subversion (SVN) client is needed to download the PJ source files from
188    pjsip.org  SVN  tree.  SVN  client  binaries  can  be  downloaded from
189    http://subversion.tigris.org/, and the program should be available for
190    Windows, Linux, MacOS X, and many more platforms.
191
192
193 Getting the Source for The First Time
194
195    Once Subversion client is installed, we can use these commands to initially
196    retrieve the latest sources from the Subversion trunk:
197
198
199
200    $ svn co http://svn.pjproject.net/repos/pjproject/trunk pjproject
201    $ cd pjproject
202
203
204 Keeping The Local Copy Up-to-Date
205
206    Once sources have been downloaded, we can keep the local copy up to date by
207    periodically synchronizing the local source with the latest revision from
208    the  PJ's  Subversion  trunk. The mailing list provides best source of
209    information about the availability of new updates in the trunk.
210
211    To  update  the  local  copy  with the latest changes in the main PJ's
212    repository:
213
214
215
216    $ cd pjproject
217    $ svn update
218
219
220 Tracking Local and Remote Changes
221
222    To see what files have been changed locally:
223
224
225
226    $ cd pjproject
227    $ svn status
228
229    The above command only compares local file against the original local copy,
230    so it doesn't require Internet connection while performing the check.
231
232    To see both what files have been changed locally and what files have been
233    updated in the PJ's Subversion repository:
234
235
236
237    $ cd pjproject
238    $ svn status -u
239
240    Note that this command requires active Internet connection to query the
241    status of PJPROJECT's source repository.
242
243
244 1.3 Source Directories Layout
245      _________________________________________________________________
246
247 Top-Level Directory Layout
248
249    The top-level directories (denoted as $TOP here) in the source distribution
250    contains the following sub-directories:
251
252    $TOP/build
253           Contains makefiles that are common for all projects.
254
255    $TOP/pjlib
256           Contains  header  and  source files of PJLIB. PJLIB is the base
257           portability  and  framework  library which is used by all other
258           libraries
259
260    $TOP/pjlib-util
261           Contains  PJLIB-UTIL  header and source files. PJLIB-UTIL is an
262           auxiliary library that contains utility functions such as scanner,
263           XML, STUN, MD5 algorithm, getopt() implementation, etc.
264
265    $TOP/pjmedia
266           Contains PJMEDIA and PJMEDIA-CODEC header and source files. The
267           sources of various codecs (such as GSM, Speex, and iLBC) can be found
268           under this directory.
269
270    $TOP/pjsip
271           Contains PJSIP header and source files.
272
273    $TOP/pjsip-apps
274           Contains source code for PJSUA and various sample applications.
275
276
277 Individual Directory Inside Each Project
278
279    Each library directory further contains these sub-directories:
280
281    bin
282           Contains binaries produced by the build process.
283
284    build
285           Contains build scripts/makefiles, project files, project workspace,
286           etc. to build the project. In particular, it contains one Makefile
287           file  to  build the project with GNU build systems, and a *.dsw
288           workspace file to build the library with Microsoft Visual Studio 6 or
289           later.
290
291    build/output
292           The build/output directory contains the object files and other files
293           generated by the build process. To support building multiple targets
294           with a single source tree, each build target will occupy a different
295           subdirectory under this directory.
296
297    build/wince-evc4
298           This directory contains the project/workspace files to build Windows
299           CE/WinCE version of the project using Microsoft Embedded Visual C++
300           4.
301
302    build/wince-evc4/output
303           This directory contains the library, executable, and object files
304           generated by Windows Mobile build process.
305
306    docs
307           Contains Doxygen configuration file (doxygen.cfg) to generate online
308           documentation from the source files. The output documentation will be
309           put in this directory as well (for example, docs/html directory for
310           the HTML files).
311
312           (to generate Doxygen documentation from the source tree, just run
313           "doxygen docs/doxygen.cfg" in the individual project directory. The
314           generated files will reside in docs directory).
315
316    include
317           Contains the header files for the project.
318
319    lib
320           Contains libraries produced by the build process.
321
322    src
323           Contains the source files of the project.
324
325
326 2. Build Preparation
327      _________________________________________________________________
328
329 2.1 Create config_site.h file
330      _________________________________________________________________
331
332    Before source files can be built, the pjlib/include/pj/config_site.h file
333    must be created (it can just be an empty file).
334
335    Note:
336           When the Makefile based build system is used, this process is taken
337           care by the Makefiles. But when non-Makefile based build system (such
338           as Visual Studio) is used, the config_site.h file must be created
339           manually.
340
341
342 What is config_site.h File
343
344    The pjlib/include/pj/config_site.h contains local customizations to the
345    libraries.
346
347    All customizations should be put in this file instead of modifying PJ's
348    files, because if PJ's files get modified, then those modified files will
349    not be updated the next time the source is synchronized. Or in other case,
350    the local modification may be overwritten with the fresh copy from the SVN.
351
352    Putting the local customization to the config_site.h solves this problem,
353    because this file is not included in the version control, so it will never
354    be overwritten by "svn update" command.
355
356    Please find list of configuration macros that can be overriden from these
357    files:
358      * PJLIB Configuration (the pjlib/config.h file)
359      * PJLIB-UTIL Configuration (the pjlib-util/config.h file)
360      * PJMEDIA Configuration (the pjmedia/config.h file)
361      * PJSIP Configuration (the pjsip/sip_config.h file)
362
363    A     sample    config_site.h    file    is    also    available    in
364    pjlib/include/config_site_sample.h.
365
366
367 Creating config_site.h file
368
369    The simplest way is just to create an empty file, to use whetever default
370    values set by the libraries.
371
372    Another way to create the config_site.h file is to write something like the
373    following:
374
375
376    // Uncomment to get minimum footprint (suitable for 1-2 concurrent calls
377    only)
378    //#define PJ_CONFIG_MINIMAL_SIZE
379    // Uncomment to get maximum performance
380    //#define PJ_CONFIG_MAXIMUM_SPEED
381    #include <pj/config_site_sample.h>
382
383
384 2.2 Disk Space Requirements
385      _________________________________________________________________
386
387    The building process needs:
388    about 50-60 MB of disk space to store the uncompressed source files, and
389      * about 30-50 MB of additional space for building each target
390
391    (Visual Studio Debug and Release are considered as separate targets)
392
393
394 3. Building Linux, *nix, *BSD, and MacOS X Targets with GNU Build Systems
395      _________________________________________________________________
396
397 3.1 Supported Targets
398      _________________________________________________________________
399
400    The  new,  autoconf  based  GNU  build system can be used to build the
401    libraries/applications for the following targets:
402      * Linux/uC-Linux (i386, Opteron, Itanium, MIPS, PowerPC, etc.),
403      * MacOS X (PowerPC),
404      * mingw (i386),
405      * FreeBSD and maybe other BSD's (i386, Opteron, etc.),
406      * RTEMS with cross compilation (ARM, powerpc),
407      * etc.
408
409
410 3.2 Requirements
411      _________________________________________________________________
412
413    In order to use PJ's GNU build system, these typical GNU tools are needed:
414      * GNU make (other make will not work),
415      * GNU binutils for the target, and
416      * GNU gcc for the target.
417      * OpenSSL header files/libraries (optional) if TLS support is wanted.
418
419    In addition, the appropriate "SDK" must be installed for the particular
420    target (this could just be a libc and the appropriate system abstraction
421    library such as Posix).
422
423    The build system is known to work on the following hosts:
424      * Linux, many types of distributions.
425      * MacOS X 10.2
426      * mingw (Win2K, XP)
427      * FreeBSD (must use gmake instead of make)
428
429    Building Win32 applications with Cygwin is currently not supported by the
430    autoconf script (there is some Windows header conflicts), but one can still
431    use the old configure script by calling ./configure-legacy. More over,
432    cross-compilations might also work with Cygwin.
433
434
435 3.3 Running configure
436      _________________________________________________________________
437
438 Using Default Settings
439
440    Run  "./configure"  without  any  options to let the script detect the
441    appropriate settings for the host:
442
443
444
445    $ cd pjproject
446    $ ./configure
447    ...
448
449    Notes:
450           The default settings build the libraries in "release" mode, with
451           default CFLAGS set to "-O2 -DNDEBUG". To change the default CFLAGS,
452           we can use the usual "./configure CFLAGS='-g'" construct.
453
454     Features Customization
455
456    With the new autoconf based build system, most configuration/customization
457    can be specified as configure arguments. The list of customizable features
458    can be viewed by running "./configure --help" command:
459
460
461
462    $ cd pjproject
463    $ ./configure --help
464    ...
465    Optional Features:
466    --disable-floating-point     Disable floating point where possible
467    --disable-sound              Exclude sound (i.e. use null sound)
468    --disable-small-filter       Exclude small filter in resampling
469    --disable-large-filter       Exclude large filter in resampling
470    --disable-g711-plc           Exclude G.711 Annex A PLC
471    --disable-speex-aec          Exclude Speex Acoustic Echo Canceller/AEC
472    --disable-g711-codec         Exclude G.711 codecs from the build
473    --disable-l16-codec          Exclude Linear/L16 codec family from the build
474    --disable-gsm-codec          Exclude GSM codec in the build
475    --disable-speex-codec        Exclude Speex codecs in the build
476    --disable-ilbc-codec         Exclude iLBC codec in the build
477    --disable-tls Force excluding TLS support (default is autodetected based on
478    OpenSSL availability)
479    ...
480
481     Configuring Debug Version and Other Customizations
482
483    The configure script accepts standard customization, which details can be
484    obtained by executing ./configure --help.
485
486    Below is an example of specifying CFLAGS in configure:
487
488
489
490    $ ./configure CFLAGS="-O3 -DNDEBUG -msoft-float -fno-builtin"
491    ...
492
493     Configuring TLS Support
494
495    By default, TLS support is configured based on the availability of OpenSSL
496    header files and libraries. If OpenSSL is available at the default include
497    and library path locations, TLS will be enabled by the configure script.
498
499    You  can explicitly disable TLS support by giving the configure script
500    --disable-tls option.
501
502
503   3.4 Cross Compilation
504      _________________________________________________________________
505
506    Cross compilation should be supported, using the usual autoconf syntax:
507
508
509
510    $ ./configure --host=arm-elf-linux
511    ...
512
513    Since cross-compilation is not tested as often as the "normal" build, please
514    watch for the ./configure output for incorrect settings (well ideally this
515    should be done for normal build too).
516
517    Please refer to Porting Guide for further information about porting PJ
518    software.
519
520
521   3.5 Running make
522      _________________________________________________________________
523
524    Once the configure script completes successfully, start the build process by
525    invoking these commands:
526
527
528
529    $ cd pjproject
530    $ make dep
531    $ make
532
533    Note:
534           gmake may need to be specified instead of make for some hosts, to
535           invoke GNU make instead of the native make.
536
537
538    Description of all make targets supported by the Makefile's:
539
540    all
541           The default (or first) target to build the libraries/binaries.
542
543    dep, depend
544           Build dependencies rule from the source files.
545
546    clean
547           Clean  the object files for current target, but keep the output
548           library/binary files intact.
549
550    distclean, realclean
551           Remove  all  generated  files (object, libraries, binaries, and
552           dependency files) for current target.
553
554
555    Note:
556           make can be invoked either in the top-level PJ directory or in build
557           directory under each project to build only the particular project.
558
559
560   3.6 Build Customizations
561      _________________________________________________________________
562
563    Build features can be customized by specifying the options when running
564    ./configure as described in Running Configure above.
565
566    In addition, additional CFLAGS and LDFLAGS options can be put in user.mak
567    file in PJ root directory (this file may need to be created if it doesn't
568    exist). Below is a sample of user.mak file contents:
569
570
571
572    export CFLAGS += -msoft-float -fno-builtin
573    export LDFLAGS +=
574
575
576 4. Building for Windows Targets with Microsoft Visual Studio
577      _________________________________________________________________
578
579   4.1 Requirements
580      _________________________________________________________________
581
582    The Microsoft Visual Studio based project files can be used with one of the
583    following:
584
585      * Microsoft Visual Studio 6,
586      * Microsoft Visual Studio .NET 2002,
587      * Microsoft Visual Studio .NET 2003,
588      * Microsoft Visual C++ 2005 (including Express edition),
589
590    In addition, the following SDK's are needed:
591      * Platform SDK, if you're using Visual Studio 2005 Express (tested with
592        Platform SDK for Windows Server 2003 SP1),
593      * DirectX SDK (tested with DirectX version 8 and 9),
594      * OpenSSL development kit would be needed if TLS support is wanted, or
595        otherwise this is optional.
596
597    For the host, the following are required:
598      * Windows NT, 2000, XP, 2003, or later ,
599      * Windows 95/98 should work too, but this has not been tested,
600      * Sufficient amount of RAM for the build process (at least 256MB).
601
602
603     Enabling TLS Support with OpenSSL
604
605    If  TLS  support  is wanted, then OpenSSL SDK must be installed in the
606    development host.
607
608    To install OpenSSL SDK from the Win32 binary distribution:
609     1. Install OpenSSL SDK to any folder (e.g. C:\OpenSSL)
610     2. Add OpenSSL DLL location to the system PATH.
611     3. Add OpenSSL include path to Visual Studio includes search directory.
612        Make sure that OpenSSL header files can be accessed from the program
613        with #include <openssl/ssl.h> construct.
614     4. Add OpenSSL library path to Visual Studio library search directory. Make
615        sure the following libraries are accessible:
616           + For Debug build: libeay32MTd and ssleay32MTd.
617           + For Release build: libeay32MT and ssleay32MT.
618
619    Then to enable TLS transport support in PJSIP, just add
620
621      #define PJSIP_HAS_TLS_TRANSPORT 1
622
623    in your pj/config_site.h. When this macro is defined, OpenSSL libraries will
624    be automatically linked to the application via the #pragma construct in
625    sip_transport_tls_ossl.c file.
626
627
628   4.2 Building the Projects
629      _________________________________________________________________
630
631    Follow the steps below to build the libraries/application using Visual
632    Studio:
633     1. For Visual Studio 6: open pjproject.dsw workspace file.
634     2. For Visual Studio 8 (VS 2005): open pjproject-vs8.sln solution file.
635     3. Set pjsua as Active Project.
636     4. Select Debug or Release build as appropriate.
637     5. Build the project. This will build pjsua application and all libraries
638        needed by pjsua.
639     6. After  successful  build,  the pjsua application will be placed in
640        pjsip-apps/bin directory, and the libraries in lib directory under each
641        projects.
642
643    To build the samples:
644     1. (Still using the same workspace)
645     2. Set samples project as Active Project
646     3. Select Debug or Release build as appropriate.
647     4. Build the project. This will build all sample applications and all
648        libraries needed.
649     5. After  successful build, the sample applications will be placed in
650        pjsip-apps/bin/samples directory, and the libraries in lib directory
651        under each projects.
652
653   4.3 Debugging the Sample Application
654      _________________________________________________________________
655
656    The sample applications are build using Samples.mak makefile, therefore it
657    is  difficult  to  setup  debugging session in Visual Studio for these
658    applications. To solve this issue, the pjsip_apps workspace contain one
659    project  called  sample_debug  which  can  be used to debug the sample
660    application.
661
662    To setup debugging using sample_debug project:
663     1. (Still using pjsip_apps workspace)
664     2. Set sample_debug project as Active Project
665     3. Edit debug.c file inside this project.
666     4. Modify the #include line to include the particular sample application to
667        debug
668     5. Select Debug build.
669     6. Build and debug the project.
670
671
672 5. Building for Windows Mobile Targets (Windows CE/WinCE/PDA/SmartPhone)
673      _________________________________________________________________
674
675    PJ supports building SIP and media stacks and applications for Windows
676    Mobile targets. A very simple WinCE SIP user agent (with media) application
677    is provided just as proof of concept that the port works.
678
679   5.1 Requirements
680      _________________________________________________________________
681
682    One of the following development tools is needed to build SIP and media
683    components for Windows Mobile:
684      * Microsoft Embedded Visual C++ 4 with appropriate SDKs, or
685      * Microsoft Visual Studio 2005 for Windows Mobile with appropriate SDKs.
686
687    Note that VS2005 is not directly supported (as I don't have the tools), but
688    it is reported to work (I assumed that VS2005 for Windows Mobile can import
689    EVC4 workspace file).
690
691   5.2 Building the Projects
692      _________________________________________________________________
693
694    The Windows Mobile port is included in the main source distribution. Please
695    follow  the  following  steps  to build the WinCE libraries and sample
696    application:
697     1. Open pjsip-apps/build/wince-evc4/wince_demos.vcw workspace file. If
698        later version of EVC4 is being used, this may cause the workspace file
699        to be converted to the appropriate format.
700     2. Select pjsua_wince project as the Active Project.
701     3. Select the appropriate SDK (for example Pocket PC 2003 SDK or SmartPhone
702        2003 SDK)
703     4. Select the appropriate configuration (for example, Win32 (WCE Emulator
704        Debug) to debug the program in emulator, or other configurations such as
705        ARMV4, MIPS, SH3, SH4, or whatever suitable for the device)
706     5. Select the appropriate device (Emulator or the actual Device).
707     6. Build the project. This will build the sample WinCE application and all
708        libraries (SIP, Media, etc.) needed by this application.
709
710    Notes
711
712           + If the config_site.h includes config_site_sample.h file, then
713             there are certain configuration in config_site_sample.h that get
714             activated for Windows CE targets. Please make sure that these
715             configurations are suitable for the application.
716           + The libraries, binaries and object files produced by the build
717             process are located under build/wince-evc4/output directory of each
718             projects.
719
720
721 6. Older PJLIB Build System for Non-Autoconf Targets (e.g. RTEMS)
722      _________________________________________________________________
723
724    The old PJLIB build system can still be used for building PJ libraries, for
725    example for RTEMS target. Please see the Porting PJLIB page in PJLIB
726    Reference documentation for information on how to support new target using
727    this build system.
728
729   6.1 Supported Targets
730      _________________________________________________________________
731
732    The older build system supports building PJ libraries for the following
733    operating systems:
734      * RTEMS
735      * Linux
736      * MacOS X
737      * Cygwin and Mingw
738
739    And it supports the following target architectures:
740      * i386, x86_64, itanium
741      * ARM
742      * mips
743      * powerpc
744      * mpc860
745      * etc.
746
747    For other targets, specific files need to be added to the build system,
748    please see the Porting PJLIB page in PJLIB Reference documentation for
749    details.
750
751   6.2 Invoking the Build System
752      _________________________________________________________________
753
754    To invoke the older build system, run the following:
755
756
757
758    $ cd pjproject
759    $ ./configure-legacy
760    $ make dep && make clean && make
761
762
763
764 7. Running the Applications
765      _________________________________________________________________
766
767    Upon successful build, the output libraries (PJLIB, PJLIB-UTIL, PJMEDIA,
768    PJSIP, etc.) are put under ./lib sub-directory under each project directory.
769    In addition, some applications may also be built, and such applications will
770    be put in ./bin sub-directory under each project directory.
771
772
773   7.1 pjsua
774      _________________________________________________________________
775
776    pjsua is the reference implementation for both PJSIP and PJMEDIA stack, and
777    is  the  main target of the build system. Upon successful build, pjsua
778    application will be put in pjsip-apps/bin directory.
779
780    pjsua manual can be found in pjsua Manual Page.
781
782
783   7.2 Sample Applications
784      _________________________________________________________________
785
786    Sample applications will be built with the Makefile build system. For Visual
787    Studio, you have to build the samples manually by selecting and building the
788    Samples project inside pjsip-apps/build/pjsip_apps.dsw project workspace.
789
790    Upon   successful   build,   the   sample   applications  are  put  in
791    pjsip-apps/bin/samples directory.
792
793    The  sample applications are described in PJMEDIA Samples Page and
794    PJSIP Samples Page in the website.
795
796
797   7.3 pjlib-test
798      _________________________________________________________________
799
800    pjlib-test contains comprehensive tests for testing PJLIB functionality.
801    This application will only be built when the Makefile build system is used;
802    with  Visual  Studio, one has to open pjlib.dsw project in pjlib/build
803    directory to build this application.
804
805    If  you're  porting PJLIB to new target, it is recommended to run this
806    application to make sure that all functionalities works as expected.
807
808
809   7.4 pjsip-test
810      _________________________________________________________________
811
812    pjsip-test contains codes for testing various SIP functionalities in PJSIP
813    and also to benchmark static performance metrics such as message parsing per
814    second.
815
816
817
818 8. Using PJPROJECT with Applications
819      _________________________________________________________________
820
821    Regardless of the build system being used, the following tasks are normally
822    needed to be done in order to build application to use PJSIP and PJMEDIA:
823     1. Put these include directories in the include search path:
824           + pjlib/include
825           + pjlib-util/include
826           + pjmedia/include
827           + pjsip/include
828     2. Put these library directories in the library search path:
829           + pjlib/lib
830           + pjlib-util/lib
831           + pjmedia/lib
832           + pjsip/lib
833     3. Include the relevant PJ header files in the application source file. For
834        example, using these would include ALL APIs exported by PJ:
835
836       #include <pjlib.h>
837       #include <pjlib-util.h>
838       #include <pjsip.h>
839       #include <pjsip_ua.h>
840       #include <pjsip_simple.h>
841       #include <pjsua.h>
842       #include <pjmedia.h>
843       #include <pjmedia-codec.h>
844        (Note: the documentation of the relevant libraries should say which
845        header files should be included to get the declaration of the APIs).
846     4. Declare the OS macros.
847           + For Windows applications built with Visual Studio, we need to
848             declare PJ_WIN32=1 macro in the project settings (declaring the
849             macro in the source file may not be sufficient).
850           + For Windows Mobile applications build with Visual C++, we need to
851             declare PJ_WIN32_WINCE=1 macro in the project settings.
852           + For  GNU build system/autoconf based build system, we need to
853             declare PJ_AUTOCONF=1 macro when compiling the applications.
854        (Note: the old PJ build system requires declaring the target processor
855        with PJ_M_XXX=1 macro, but this has been made obsolete. The target
856        processor  will  be  detected  from compiler's predefined macro by
857        pjlib/config.h file).
858     5. Link with the appropriate PJ libraries. The following libraries will
859        need to be included in the library link specifications:
860
861         pjlib
862                 Base library used by all libraries.
863
864         pjlib-util
865                 Auxiliary library containing scanner, XML, STUN, MD5, getopt,
866                 etc, used by the SIP and media stack.
867
868         pjsip
869                 SIP core stack library.
870
871         pjsip-ua
872                 SIP user agent library containing INVITE session, call
873                 transfer, client registration, etc.
874
875         pjsip-simple
876                 SIP SIMPLE library for base event framework, presence, instant
877                 messaging, etc.
878
879         pjsua
880                 High level SIP UA library, combining SIP and media stack into
881                 high-level easy to use API.
882
883         pjmedia
884                 The media framework.
885
886         pjmedia-codec
887                 Container library for various codecs such as GSM, Speex, and
888                 iLBC.
889
890
891    Note: the actual library names will be appended with the target name and the
892    build configuration. For example:
893
894         For Visual Studio builds
895                 The actual library names will look like
896                 pjlib-i386-win32-vc6-debug.lib,
897                 pjlib-i386-win32-vc6-release.lib, etc., depending on whether we
898                 are building the Debug or Release version of the library.
899
900                 An easier way to link with the libraries is to include PJ
901                 project files in the workspace, and to configure project
902                 dependencies so that the application depends on the PJ
903                 libraries. This way, we don't need to manually add each PJ
904                 libraries to the input library file specification, since VS
905                 will automatically link the dependency libraries with the
906                 application.
907
908         For Windows Mobile builds
909                 Unfortunately the PJ libraries built for Windows Mobile will
910                 not be placed in the usual lib directory, but rather under the
911                 output directory under build/wince-evc4 project directory.
912
913                 An easier way to link with the libraries is to include PJ
914                 project files in the workspace, and to configure project
915                 dependencies so that the application depends on the PJ
916                 libraries. This way, we don't need to manually add each PJ
917                 libraries to the input library file specification, since VS
918                 will automatically link the dependency libraries with the
919                 application.
920
921         For GNU builds
922                 Application's Makefile can get the PJ library suffix by
923                 including PJ's build.mak file from the root PJ directory (the
924                 suffix is contained in TARGET_NAME variable). For example, to
925                 link with PJLIB and PJMEDIA, we can use this syntax in the
926                 LDFLAGS: "-lpj-$(TARGET_NAME) -lpjmedia-$(TARGET_NAME)"
927
928
929     6. Link with system spesific libraries:
930
931         Windows
932                 Add (among other things): wsock32.lib, ws2_32.lib, ole32.lib,
933                 dsound.lib
934
935         Linux, *nix, *BSD
936                 Add (among other things): '-lpthread -lm' (at least).
937
938         MacOS X
939                 Add (among other things): '-framework CoreAudio -lpthread -lm'.
940
941
942 Appendix I: Common Problems/Frequently Asked Question (FAQ)
943      _________________________________________________________________
944
945   I.1 fatal error C1083: Cannot open include file: 'pj/config_site.h': No such
946   file or directory
947
948    This error normally occurs when the config_site.h file has not been created.
949    This file needs to be created manually (an empty file is sufficient). Please
950    follow the Build Preparation instructions above to create this file.
951
952
953
954
955
956
957
958
959      _________________________________________________________________
960
961    Feedback:
962           Thanks for using PJ libraries and for reading this document. Please
963           send feedbacks or general comments to <bennylp at pjsip dot org>.
964