Updated README.txt from using.htm

git-svn-id: http://svn.pjsip.org/repos/pjproject/trunk@707 74dad513-b988-da41-8d7b-12977e46ad98

1 files changed, 674 insertions, 67 deletions

diff --git a/README.txt b/README.txt
index e4ee71dc..ee4d83cf 100644
--- a/README.txt
+++ b/README.txt
@@ -1,70 +1,677 @@
 
-See INSTALL.txt for compiling.
-
-
-TOP LEVEL DIRECTORIES
-======================
-Below is the descriptions of the top-level directories:
-
--root
- -build..................... Makefiles includes, nothing interesting to see except
-                             when porting to new platforms.
- -pjlib..................... Base library used by all other libraries.  It contains 
-                             platform abstraction, data structures, etc. 
- -pjlib-util................ Utilities, such as text scanner, XML parser, etc.
- -pjmedia................... Media framework, contains:
-                              - pjmedia.......... the core media framework, which 
-                                                  contains codec framework, streams,
-                                                  stream ports, conference bridge,
-                                                  RTP/RTCP, SDP, SDP negotiator, etc.
-                              - pjmedia-codec.... the static library container for 
-                                                  all codecs. For the moment, it
-                                                  contains GSM and SPEEX codec.
- -pjsip..................... SIP stack, contains:
-                              - pjsip............ The core SIP stack, which contains
-                                                  endpoint, transport layer, message and
-                                                  URI structures, transaction layer, 
-                                                  UA layer and dialog, utilities, etc.
-                              - pjsip-simple..... SIMPLE (+presence, IM), contains
-                                                  basic event framework, presence, and
-                                                  instant messaging.
-                              - pjsip-ua......... SIP "call" abstraction, which blends
-                                                  INVITE session and SDP negotiation.
-                                                  Also contains call features such as
-                                                  call transfer, and client side SIP
-                                                  registration.
-                              - pjsua-lib........ Very high level UA app. library,
-                                                  which blends all functionalities
-                                                  together in very easy to use API.
-                                                  Good to build a powerfull softphone
-                                                  very quickly.
- -pjsip-apps................ Contains some sample applications:
-                              - pjsua............ A powerful, console based SIP
-                                                  UA, based on pjsua-lib.
-                              - pjsip-perf....... SIP performance tester or call 
-                                                  generator.
-
-
-SUB-DIRECTORY LAYOUT
-======================
-Each subdirectories normally would have this layout:
-
- -bin...................... The binaries resulted from the build process will
-                            go here.
- -build.................... Makefile and project files.
- -docs..................... Documentation specific to the project and doxygen config file
-                            to generate documentation from the source code.
- -include.................. Header files.
- -lib...................... The static libraries resulted from the build process
-                            will go here.
- -src...................... Source files.
-
-
-YOUR EDITOR SETTINGS ARE IMPORTANT!
-====================================
-You need to set your editor settings to tab=8 and indent=4. For example,
-with vim, you can do this with:
- :se ts=8
- :se sts=4
 
+Getting Started: Building and Using PJSIP and PJMEDIA
+[Last Update: 12/Sept/2006]
+
+   This article describes how to get, build, and use the open source PJSIP and
+   PJMEDIA SIP and media stack. You can get the online (and HTML) version of
+   this file in http://www.pjsip.org/using.htm
+
+
+If you're so impatient..
+
+   If you just want to get going quickly (and maybe read this document later),
+   this is what you can do to build the libraries:
+
+   Building with GNU tools
+          Just do:
+
+   $ ./configure
+   $ make dep && make clean && make
+
+   Building with Microsoft Visual Studio
+          Just follow the following steps:
+
+         1. Open pjsip-apps/build/pjsip_apps.dsw workspace,
+         2. Create an empty pjlib/include/pj/config_site.h, and
+         3. build the pjsua application.
+
+   Building for Windows Mobile
+          Just follow the following steps:
+
+         1. Open pjsip-apps/build/wince-evc4/wince_demos.vcw EVC4 workspace,
+         2. Create an empty pjlib/include/pj/config_site.h, and
+         3. build the pjsua_wince application.
+
+   With  all  the  build systems, the output libraries will be put in lib
+   directory under each projects, and the output binaries will be put in bin
+   directory under each projects.
+
+
+Table of Contents:
+     _________________________________________________________________
+
+   1. Getting the Source Distribution
+
+     1.1 Getting the Release tarball
+
+     1.2 Getting from Subversion trunk
+
+     1.3 Source Directories Layout
+
+   2. Build Preparation
+
+     2.1 config_site.h file
+
+     2.2 Disk Space Requirements
+
+   3. Building Linux, *nix, *BSD, and MacOS X Targets with GNU Build Systems
+
+     3.1 Supported Targets
+
+     3.2 Requirements
+
+     3.3 Running configure
+
+     3.4 Running make
+
+     3.5 Cross Compilation
+
+   4. Building for Windows Targets with Microsoft Visual Studio
+
+     4.1 Requirements
+
+     4.2 Building the Projects
+
+     4.3 Debugging the Sample Application
+
+   5. Building for Windows Mobile Targets (Windows CE/WinCE/PDA/SmartPhone)
+
+     5.1 Requirements
+
+     5.2 Building the Projects
+
+   6. Using PJPROJECT with Your Applications
+
+
+   Appendix I: Common Problems/Frequently Asked Question (FAQ)
+
+     I.1 fatal error C1083: Cannot open include file: 'pj/config_site.h':
+   No such file or directory
+
+
+1. Getting the Source Code Distribution
+     _________________________________________________________________
+
+   Since all libraries are released under Open Source license, all source code
+   are available for your scrutinizing pleasure.
+
+   All libraries (PJLIB, PJLIB-UTIL, PJSIP, PJMEDIA, and PJMEDIA-CODEC) are
+   currently distributed under a single source tree, collectively named as
+   PJPROJECT or just PJ libraries. These libraries can be obtained by either
+   downloading the release tarball or getting them from the Subversion trunk.
+
+
+1.1 Getting the Release tarball
+     _________________________________________________________________
+
+   Getting the released tarball is a convenient way to obtain stable version of
+   PJPROJECT. The tarball may not contain the latest features or bug-fixes, but
+   normally it is considered more stable as it will be tested more rigorously
+   before it is released.
+
+   You    can    get    the    latest    released    tarball   from   the
+   http://www.pjsip.org/download.htm.
+
+
+1.2 Getting from Subversion trunk
+     _________________________________________________________________
+
+   You can always get the most up-to-date version of the sources from the
+   Subversion trunk. However, please bear in mind that the sources in the
+   Subversion trunk may not be the most stable one. In fact, it may not even
+   compile for some particular targets, because of the time lag in the updating
+   process for all targets. Please consult the mailing list if you encounter
+   such problems.
+
+   Using Subversion also has benefits of keeping your source up to date with
+   the main PJ source tree and to track your changes made to your local copy,
+   if any.
+
+
+What is Subversion
+
+   Subversion is Open Source version control system similar to CVS. Subversion
+   homepage is in http://subversion.tigris.org/
+
+
+Getting Subversion Client
+
+   Before you can download the PJ source files from pjsip.org SVN tree, you
+   need  to  install  a Subversion client. You can download binaries from
+   http://subversion.tigris.org/  and  follow the instructions there.
+   Subversion clients are available for Windows, Linux, MacOS X, and many more
+   platforms.
+
+
+Getting the Source for The First Time
+
+   Once Subversion client is installed, you can use these commands to initially
+   retrieve the latest sources from the Subversion trunk:
+
+   $ svn co http://svn.pjproject.net/repos/pjproject/trunk pjproject
+   $ cd pjproject
+
+
+Keeping Your Local Copy Up-to-Date
+
+   Once you have your local copy of the sources, you will want to keep your
+   local copy up to date by periodically synchronizing your source with the
+   latest revision from the Subversion trunk. The mailing list provides best
+   source of information about the availability of new updates in the trunk.
+
+   You can use these commands to synchronize your copy with the main trunk:
+
+   $ cd pjproject
+   $ svn update
+
+
+Tracking Local and Remote Changes
+
+   In general, it is not recommended to keep your local changes (to the library
+   source codes) for a long time, because the longer you keep your changes, the
+   more chances that your source will be out-of-sync with the main PJ source
+   tree (the trunk), because the trunk may be updated to support new features
+   or to fix some bugs.
+
+   The  best way to resolve this is to send your modification back to the
+   author, so that he can change the copy in the SVN trunk.
+
+   To see what files have been changed locally:
+
+   $ cd pjproject
+   $ svn status
+
+   The above command only compares local file against the original local copy,
+   so it doesn't require Internet connection to perform the check.
+
+   To see what files have been changed both locally and remotely:
+
+   $ cd pjproject
+   $ svn status -u
+
+   Note that svn status -u requires Internet connection to the SVN tree.
+
+
+1.3 Source Directories Layout
+     _________________________________________________________________
+
+Top-Level Directory Layout
+
+   The top-level directories (denoted as $PJ here) in the source distribution
+   contains the sources of individual libraries:
+
+   $PJ/build
+          Contains makefiles that are common for all projects.
+
+   $PJ/pjlib
+          Contains PJLIB header and source files.
+
+   $PJ/pjlib-util
+          Contains PJLIB-UTIL header and source files.
+
+   $PJ/pjmedia
+          Contains PJMEDIA and PJMEDIA-CODEC header and source files.
+
+   $PJ/pjsip
+          Contains PJSIP header and source files.
+
+   $PJ/pjsip-apps
+          Contains source code for PJSUA and samples applications.
+
+
+Individual Directory Inside Each Project
+
+   The directories inside each project (for example, inside pjlib, pjmedia, or
+   pjsip) further contains some sub-directories below:
+
+   bin
+          Contains binaries produced by the build process. The contents of this
+          directory will not get synchronized with the SVN trunk.
+
+   build
+          Contains build scripts/makefiles, project files, project workspace,
+          etc. to build the project. In particular, it contains one Makefile
+          file  to  build the project with GNU build systems, and a *.dsw
+          workspace file to build the library with Microsoft Visual Studio 6 or
+          later.
+
+   build/output
+          The build/output directory contains the object files and other files
+          generated by the build process.
+
+   build/wince-evc4
+          This directory contains the project/workspace files to build Windows
+          CE/WinCE version of the project using Microsoft Embedded Visual C++
+          4.
+
+   docs
+          Contains Doxygen configuration file (doxygen.cfg) to generate online
+          documentation from the source files. The output documentation will be
+          put in this directory as well (for example, docs/html directory for
+          the HTML files).
+
+   include
+          Contains the header files for the project.
+
+   lib
+          Contains libraries produced by the build process.
+
+   src
+          Contains the source files of the project.
+
+
+2. Build Preparation
+     _________________________________________________________________
+
+2.1 config_site.h file
+     _________________________________________________________________
+
+   Before you can compile and use the libraries, you need to create your
+   config_site.h MANUALLY.
+
+   (Sorry to write in red background, but this question comes out quite often
+   so I thought it's worth to put some punctuation)
+
+Q: What is config_site.h File
+
+   The pjlib/include/pj/config_site.h contains your local customizations to the
+   libraries.
+
+Q: Why do we need config_site.h file
+
+   You should put your customization in this file instead of modifying PJ's
+   files,  because  if you modify PJ's files, then you will prevent those
+   modified files from being updated next time you synchronize your local copy
+   to the SVN trunk. Or even worse, you may accidently overwrite your local
+   modification with the fresh copy from the SVN.
+
+   Putting your local customization to the config_site.h solves this problem,
+   because this file is not included in the version control.
+
+Q: What customizations can be put in config_site.h file
+
+   You  can  put  your  #define macros in this file. You can find list of
+   configuration macros that you can override by scanning:
+     * pjlib/config.h file
+     * pjmedia/config.h file
+     * pjsip/sip_config.h file
+
+   You    can    also    see    a    sample    config_site.h    file   in
+   pjlib/include/config_site_sample.h.
+
+Q: How to create config_site.h file
+
+   The simplest way is just to create an empty file.
+
+   Another way to create your config_site.h is to write something like this:
+
+   // Uncomment to get minimum footprint (suitable for 1-2 concurrent calls
+   only)
+   //#define PJ_CONFIG_MINIMAL_SIZE
+   // Uncomment to get maximum performance
+   //#define PJ_CONFIG_MAXIMUM_SPEED
+   #include <pj/config_site_sample.h>
+
+
+2.2 Disk Space Requirements
+     _________________________________________________________________
+
+   PJ will need
+   currently about 50-60 MB of disk space to store the source files, and
+     * approximately 30-50 MB of additional space for building each target
+
+   (For example, Visual Studio Debug and Release are considered to be separate
+   targets, so you'll need twice the capacity to build both of them)
+
+
+3. Building Linux, *nix, *BSD, and MacOS X Targets with GNU Build Systems
+     _________________________________________________________________
+
+3.1 Supported Targets
+     _________________________________________________________________
+
+   The  new,  autoconf  based  GNU  build system can be used to build the
+   libraries/applications for the following targets:
+     * Linux/uC-Linux (i386, Opteron, Itanium, MIPS, PowerPC, etc.),
+     * MacOS X (PowerPC),
+     * mingw (i386),
+     * *BSD (i386, Opteron, etc.),
+     * RTEMS (ARM, powerpc),
+     * etc.
+
+
+3.2 Requirements
+     _________________________________________________________________
+
+   To use PJ's GNU build system, you would need the typical GNU tools such as:
+     * GNU Make (other make will not work),
+     * binutils,
+     * gcc, and
+     * sh compatible shell (for autoconf to work)
+
+   On Windows, mingw will work, but cygwin currently doesn't. As usual, your
+   mileage may vary.
+
+
+3.3 Running configure
+     _________________________________________________________________
+
+Using Default Settings
+
+   Just  run  configure  without any options to let the script detect the
+   appropriate settings for the host:
+
+   $ cd pjproject
+   $ ./configure
+   ...
+
+   Notes:
+          The  default settings build the library in "release" mode, with
+          default CFLAGS set to "-O2 -DNDEBUG".
+
+    Features Customization
+
+   With the new autoconf based build system, most configuration/customization
+   can  be  specified  as  configure  arguments.  You can get the list of
+   customizable features by running ./configure --help:
+
+   $ cd pjproject
+   $ ./configure --help
+   ...
+   Optional Features:
+   --disable-floating-point   Disable floating point where possible
+   --disable-sound            Exclude sound (i.e. use null sound)
+   --disable-small-filter     Exclude small filter in resampling
+   --disable-large-filter     Exclude large filter in resampling
+   --disable-g711-plc         Exclude G.711 Annex A PLC
+   --disable-speex-aec        Exclude Speex Acoustic Echo Canceller/AEC
+   --disable-g711-codec       Exclude G.711 codecs from the build
+   --disable-l16-codec        Exclude Linear/L16 codec family from the build
+   --disable-gsm-codec        Exclude GSM codec in the build
+   --disable-speex-codec      Exclude Speex codecs in the build
+   --disable-ilbc-codec       Exclude iLBC codec in the build
+   ...                       
+
+    Debug Version and Other Customizations
+
+   The configure script accepts standard customization such as the CFLAGS,
+   LDFLAGS, etc.
+
+   For example, to build the libraries/application in debug mode:
+
+   $ ./configure CFLAGS="-g"
+   ...
+
+
+  3.4 Cross Compilation
+     _________________________________________________________________
+
+   (.. to be completed)
+
+   $ ./configure --target=powerpc-linux-unknown
+   ...
+
+
+  3.5 Running make
+     _________________________________________________________________
+
+   Once the configure script completes successfully, start the build process by
+   invoking these commands:
+
+   $ cd pjproject
+   $ make dep
+   $ make
+
+   Note:
+          You may need to call gmake instead of make for your host to invoke
+          GNU make instead of the native make.
+
+   Description of all make targets supported by the Makefile's:
+
+   all
+          The default (or first) make target to build the libraries/binaries.
+
+   dep, depend
+          Build dependencies rule from the source files.
+
+   clean
+          Clean the object files, but keep the output library/binary files
+          intact.
+
+   distclean, realclean
+          Clean  all  generated  files  (object, libraries, binaries, and
+          dependency files).
+
+
+   Note:
+          You can run make in the top-level PJ directory or in build directory
+          under each project to build only the particular project.
+
+
+4. Building for Windows Targets with Microsoft Visual Studio
+     _________________________________________________________________
+
+  4.1 Requirements
+     _________________________________________________________________
+
+   In order to build the projects using Microsoft Visual Studio, you need to
+   have one of the following:
+
+     * Microsoft Visual Studio 6,
+     * Microsoft Visual Studio .NET 2002,
+     * Microsoft Visual Studio .NET 2003,
+     * Microsoft Visual Studio Express 2005 with Platform SDK and DirectX SDK,
+
+   For the host, you need:
+     * Windows NT, 2000, XP, 2003, or later (it may work on Windows 95 or 98,
+       but this has not been tested),
+     * Sufficient amount of RAM for the build process,
+
+
+  4.2 Building the Projects
+     _________________________________________________________________
+
+   Follow the steps below to build the libraries/application using Visual
+   Studio:
+    1. Open Visual Studio 6 workspace file pjsip-apps/build/pjsip_apps.dsw. If
+       you're using later version of Visual Studio, it should convert the
+       workspace file and project files into the new formats.
+    2. Set pjsua as Active Project.
+    3. Select Debug or Release build as appropriate.
+    4. Build the project. This will build pjsua application and all libraries
+       needed by pjsua.
+    5. After  successful  build,  the pjsua application will be placed in
+       pjsip-apps/bin directory, and the libraries in lib directory under each
+       projects.
+
+   To build the samples:
+    1. (Still using the same workspace)
+    2. Set samples project as Active Project
+    3. Select Debug or Release build as appropriate.
+    4. Build the project. This will build all sample applications and all
+       libraries needed.
+    5. After  successful build, the sample applications will be placed in
+       pjsip-apps/bin/samples directory, and the libraries in lib directory
+       under each projects.
+
+  4.3 Debugging the Sample Application
+     _________________________________________________________________
+
+   The sample applications are build using Samples.mak makefile, therefore it
+   is  difficult  to  setup  debugging session in Visual Studio for these
+   applications. To solve this issue, the pjsip_apps workspace contain one
+   project  called  sample_debug  which  can  be used to debug the sample
+   application.
+
+   To setup debugging using sample_debug project:
+    1. (Still using pjsip_apps workspace)
+    2. Set sample_debug project as Active Project
+    3. Edit debug.c file inside this project.
+    4. Modify the #include line to include the particular sample application
+       you want to debug
+    5. Select Debug build.
+    6. Build and debug the project.
+
+
+5. Building for Windows Mobile Targets (Windows CE/WinCE/PDA/SmartPhone)
+     _________________________________________________________________
+
+   PJ supports building SIP and media stacks and applications for Windows
+   Mobile targets. A very simple WinCE SIP user agent (with media) application
+   is provided just as proof of concept that the port works.
+
+  5.1 Requirements
+     _________________________________________________________________
+
+   You will need the following to build SIP and media components for Windows
+   Mobile:
+     * Microsoft Embedded Visual C++ 4 with appropriate SDKs, or
+     * Microsoft Visual Studio 2005 for Windows Mobile with appropriate SDKs.
+
+   Note that VS2005 is not directly supported (as I don't have the tools), but
+   it is reported to work (and I assumed that VS2005 for Windows Mobile can
+   import EVC4 workspace file).
+
+  5.2 Building the Projects
+     _________________________________________________________________
+
+   The Windows Mobile port is included in the main source distribution. Please
+   follow  the  following  steps  to build the WinCE libraries and sample
+   application:
+    1. Open pjsip-apps/build/wince-evc4/wince_demos.vcw workspace file. If
+       you're using later version of EVC4 this may cause the workspace file to
+       be converted to the current version of your Visual Studio.
+    2. Select pjsua_wince project as the Active Project.
+    3. Select the appropriate SDK (for example Pocket PC 2003 SDK or SmartPhone
+       2003 SDK)
+    4. Select the appropriate configuration (for example, Win32 (WCE Emulator
+       Debug) if you plan to debug the program in emulator)
+    5. Select the appropriate device (Emulator or the actual Device).
+    6. Build the project. This will build the sample WinCE application and all
+       libraries (SIP, Media, etc.) needed by this application.
+
+   Notes
+          If your config_site.h includes config_site_sample.h file, then
+          there are certain configuration in config_site_sample.h that get
+          activated for Windows CE targets.
+
+
+6. Using PJPROJECT with Your Applications
+     _________________________________________________________________
+
+   Regardless if you use Visual Studio or GNU build systems or other tools, in
+   order to build your application to use PJSIP and PJMEDIA SIP and media
+   stack, you need to configure your build tools as follows:
+    1. Put these include directories in your include search path:
+          + pjlib/include
+          + pjlib-util/include
+          + pjmedia/include
+          + pjsip/include
+    2. Put these library directories in your library search path:
+          + pjlib/lib
+          + pjlib-util/lib
+          + pjmedia/lib
+          + pjsip/lib
+    3. Include the relevant PJ header files in your application source file.
+       For example, using these would include ALL APIs exported by PJ:
+
+      #include <pjlib.h>
+      #include <pjlib-util.h>
+      #include <pjsip.h>
+      #include <pjsip_ua.h>
+      #include <pjsip_simple.h>
+      #include <pjsua.h>
+      #include <pjmedia.h>
+      #include <pjmedia-codec.h>
+       (Note: the documentation of the relevant libraries should say which
+       header files should be included to get the declaration of the APIs).
+    4. Declare the OS macros.
+          + For Windows applications built with Visual Studio, you need to
+            declare PJ_WIN32=1 macro in your project settings (declaring the
+            macro in your source file may not be sufficient).
+          + For Windows Mobile applications build with Visual C++, you need to
+            declare PJ_WIN32_WINCE=1 macro in your project settings.
+          + For GNU build system/autoconf based build system, you need to
+            declare PJ_AUTOCONF=1 macro when compiling your applications.
+       (Note: the old PJ build system requires declaring the target processor
+       with PJ_M_XXX=1 macro, but this has been made obsolete. The target
+       processor  will  be  detected  from compiler's predefined macro by
+       pjlib/config.h file).
+    5. Link with the appropriate PJ libraries. The following libraries will
+       need to be included in your library link specifications:
+
+        pjlib
+                Base library used by all libraries.
+
+        pjlib-util
+                Auxiliary library containing scanner, XML, STUN, MD5, getopt,
+                etc, used by the SIP and media stack.
+
+        pjsip
+                SIP core stack library.
+
+        pjsip-ua
+                SIP user agent library containing INVITE session, call
+                transfer, client registration, etc.
+
+        pjsip-simple
+                SIP SIMPLE library for base event framework, presence, instant
+                messaging, etc.
+
+        pjsua
+                High level SIP UA library, combining SIP and media stack into
+                high-level easy to use API.
+
+        pjmedia
+                The media framework.
+
+        pjmedia-codec
+                Container library for various codecs such as GSM, Speex, and
+                iLBC.
+
+
+   Note: the actual library names will be appended with the target name and the
+   build configuration. For example:
+
+        For Visual Studio builds
+                The actual library names will look like
+                pjlib-i386-win32-vc6-debug.lib,
+                pjlib-i386-win32-vc6-release.lib, etc., depending on whether
+                you build the Debug or Release version of the library.
+
+        For GNU builds
+                You can get the library suffix by including PJ's build.mak file
+                from the root PJ directory (the suffix is contained in
+                TARGET_NAME variable). For example, to link with PJLIB and
+                PJMEDIA, you can use this in syntax your LDFLAGS:
+                "-lpj-$(TARGET_NAME) -lpjmedia-$(TARGET_NAME)"
+
+   Should you encounter any difficulties with using PJ libraries, you can
+   consult the mailing list for some help.
+
+
+Appendix I: Common Problems/Frequently Asked Question (FAQ)
+     _________________________________________________________________
+
+  I.1 fatal error C1083: Cannot open include file: 'pj/config_site.h': No such
+  file or directory
+
+   If  you  encounter  this  error, then probably you haven't created the
+   config_site.h file. Please follow the Build Preparation instructions
+   above to create this file.
+
+
+
+
+
+
+
+
+     _________________________________________________________________
+
+   Feedback:
+          Thanks for downloading PJ libraries and for reading this document. If
+          you'd like to comment on anything, send your email to me and I would
+          be delighted to hear them. -benny <bennylp at pjsip dot org>