Updated README.txt from using.htm
git-svn-id: https://svn.pjsip.org/repos/pjproject/trunk@707 74dad513-b988-da41-8d7b-12977e46ad98
diff --git a/README.txt b/README.txt
index e4ee71d..ee4d83c 100644
--- a/README.txt
+++ b/README.txt
@@ -1,70 +1,677 @@
-See INSTALL.txt for compiling.
+
+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
-TOP LEVEL DIRECTORIES
-======================
-Below is the descriptions of the top-level directories:
+If you're so impatient..
--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.
+ 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.
-SUB-DIRECTORY LAYOUT
-======================
-Each subdirectories normally would have this layout:
+Table of Contents:
+ _________________________________________________________________
- -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.
+ 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
-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
+ 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>