← Back to branch summary

~ubuntu-branches/ubuntu/trusty/sflphone/trusty

« back to all changes in this revision

Viewing changes to daemon/libs/pjproject-2.0.1/README.txt

  • Committer: Package Import Robot
  • Author(s): Mark Purcell
  • Date: 2014-01-28 18:23:36 UTC
  • mfrom: (4.3.4 sid)
  • Revision ID: package-import@ubuntu.com-20140128182336-jrsv0k9u6cawc068
Tags: 1.3.0-1
http://bugs.debian.org/735846
http://bugs.debian.org/727164
http://bugs.debian.org/718178
http://bugs.debian.org/736583
http://bugs.debian.org/722040
http://bugs.debian.org/736746
* New upstream release 
  - Fixes "New Upstream Release" (Closes: #735846)
  - Fixes "Ringtone does not stop" (Closes: #727164)
  - Fixes "[sflphone-kde] crash on startup" (Closes: #718178)
  - Fixes "sflphone GUI crashes when call is hung up" (Closes: #736583)
* Build-Depends: ensure GnuTLS 2.6
  - libucommon-dev (>= 6.0.7-1.1), libccrtp-dev (>= 2.0.6-3)
  - Fixes "FTBFS Build-Depends libgnutls{26,28}-dev" (Closes: #722040)
* Fix "boost 1.49 is going away" unversioned Build-Depends: (Closes: #736746)
* Add Build-Depends: libsndfile-dev, nepomuk-core-dev

Show diffs side-by-side

added added

removed removed

Lines of Context:
daemon/libs/pjproject-2.0.1/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: 2007-02-02 20:42:44 +0000 (Fri, 02 Feb 2007) $]
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>.