Changes between Version 9 and Version 10 of Getting-Started/BB10


Ignore:
Timestamp:
Apr 16, 2013 3:04:41 AM (6 years ago)
Author:
bennylp
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • Getting-Started/BB10

    v9 v10  
    33[[PageOutline(2-3,,inline)]] 
    44 
    5 For the latest guide see this [http://blog.pjsip.org/2013/01/15/port-your-pjsip-engine-to-blackberry-10-in-less-than-10-minutes/ blog post]. 
     5 
     6[[BR]] 
    67 
    78== Requirements == 
    89 
    9 * You'll need !BlackBerry 10 Native SDK. After you download and install the SDK, set the environment variables by running {{{bbndk-env}}} script provided in the SDK: 
    10  {{{ 
    11 $ source bbndk_dir/bbndk-env.sh 
    12  }}} 
    13  
    14 * [https://github.com/blackberry/Cascades-Community-Samples/tree/master/bb10-pjsipdemo BB10 PJSIP Demo] 
    15  * In particular read through [https://github.com/blackberry/Cascades-Community-Samples/blob/master/bb10-pjsipdemo/README.txt README] 
    16  
    17 == Building PJSIP == 
    18  
    19 [wiki:Getting-Started/Download-Source Get the source code], if you haven't already. 
    20  
    21 Just run: 
    22  {{{ 
    23 $ cd /path/to/your/pjsip/dir 
    24 $ ./configure-bb10 
    25 $ make dep && make clean && make 
    26  }}} 
    27  
    28 Notes: 
    29  * the {{{./configure-bb10}}} is a wrapper that calls the standard {{{./configure}}} script with settings suitable for BB10 target. 
    30  * you may pass standard {{{./configure}}} options to this script too. 
    31  * for more info, run {{{./configure-bb10 --help}}} 
    32  * other customizations are similar to what is explained in [wiki:Getting-Started/Autoconf Building with GNU] page. 
     10=== !BlackBerry 10 Native SDK === #ndk 
     11 
     12You'll need [https://developer.blackberry.com/native/ BlackBerry 10 Native SDK] for native development. We tested with SDK version 10.1.0.1020, but this should work with later versions too.  
     13 
     14After you download and install the SDK, set the environment variables by running {{{bbndk-env}}} script provided in the SDK: 
     15 {{{ 
     16$ source $BBNDK_DIR/bbndk-env.sh 
     17 }}} 
     18 
     19 
     20Note that it is '''no longer necessary''' to have the [https://github.com/blackberry/Cascades-Community-Samples/tree/master/bb10-pjsipdemo BB10 PJSIP Demo] as PJSIP now contains a PJSUA demo for !BlackBerry. 
     21 
     22 
     23[[BR]] 
     24 
     25== Configure and Build PJSIP == 
     26 
     27=== Get PJSIP Source Code === 
     28 
     29[wiki:Getting-Started/Download-Source Get the source code], if you haven't already. This tutorial applies to PJSIP version 2.2 and above (or the 2.1 from SVN trunk dated 2013/04/16 or later). 
     30 
     31[[BR]] 
     32=== Configure PJSIP === 
     33 
     34 1. Run this in your BB10 NDK directory, otherwise the {{{configure}}} command will fail: 
     35 {{{ 
     36$ source $BBNDK_DIR/bbndk-env.sh 
     37 }}} 
     38 1. {{{cd}}} to PJSIP source directory. 
     39 1. Run '''{{{configure-bb10}}}''' script with suggested parameters as follows. This will setup PJSIP with debugging info and '''without optimization'''.  
     40 {{{ 
     41$ CFLAGS="-O -g" ./configure-bb10 --disable-speex-aec 
     42 }}} 
     43 You can pass additional parameters as both environment variables or command line options to the '''{{{configure-bb10}}}''' script. See further customization options in [wiki:Getting-Started/Autoconf Building with GNU] page or run '''{{{./configure --help}}}''' for more info. 
     44 1. We suggest to fill in your '''{{{config_site.h}}}''' ({{{pjlib/include/pj/config-site.h}}} file) with the following: 
     45 {{{ 
     46#include <pj/config_site_sample.h> 
     47 }}} 
     48 1. Run {{{make dep}}} to build the dependencies: 
     49 {{{ 
     50$ make dep 
     51 }}} 
     52 
     53 
     54At this point, you may build PJSIP simply by executing '''{{{make}}}''', but we'll show you how to import PJSIP into Momentics IDE and build it from there. 
     55 
     56 
     57[[BR]] 
     58=== The pjsip.pri QMake Project File === #pjsippri 
     59 
     60The {{{configure-bb10}}} script above also creates '''pjsip.pri''' at the root of PJSIP directory. This file contains PJSIP build settings in QMake project (.pro) file format, which can be included in application's '''.pro''' file to build with PJSIP. 
     61 
     62See [#newappintegrate creating new app] section for more info. 
     63 
     64 
     65[[BR]] 
     66=== Import and Build PJSIP to/in Momentics IDE === 
     67 
     68This is optional, as you can just run '''{{{make}}}''' in PJSIP directory to build PJSIP. But nevertheless this is a lot more convenient especially if you are developing PJSIP. 
     69 
     70==== Import PJSIP as New Project ==== 
     71 
     72In Momentics IDE: 
     73 1. Select '''File''' --> '''Import..''' 
     74 1. From the list, open '''!BlackBerry''', select '''Existing Code as !BlackBerry C/C++ Makefile Project''', and click '''Next >''' 
     75 1. In the "Import.." wizard, set 
     76    - Project name: '''pjproject''' (or other name. But in this tutorial we will refer the PJSIP project as ''pjproject'') 
     77    - Code location: the directory where you extract PJSIP to 
     78    - Language: C 
     79    and click '''Next >''' 
     80 1. Accept the default "Use workspace SDK selection", and click '''Finish'''. 
     81 
     82==== Create Build Configuration ==== 
     83 
     84 1. Right click ''pjproject'' from the '''Project Explorer''' view (tab), then select '''Build Configurations''' --> '''Manage''' from the pop-up menu. 
     85 1. In the dialog, click '''New..''' to create new build configuration 
     86    - In "Create New Configuration Dialog": 
     87        - set Name: ''PJSIP-Default'' 
     88        - press '''OK''' to close the dialog 
     89 1. Set ''PJSIP-Default'' as the active build configuration by selecting it from the list and pressing the '''Set Active''' button 
     90 1. Press '''OK''' to close the "Manage Configurations" dialog 
     91 
     92==== Configure Build Configuration ==== 
     93 
     94 1. Right click ''pjproject'' from the '''Project Explorer''' view (tab) and select '''Properties''' from the pop-up menu. 
     95 1. In the ''Properties for pjproject'' dialog: 
     96     - Select '''C/C++ Build''' from the left tree pane 
     97     - Make sure ''"PJSIP-Default [Active]"'' Configuration is selected from the combo box in the top center of the dialog. 
     98         - if it's not marked as active, make it active 
     99     - Go to '''Behaviour''' tab 
     100     - Set '''Make build target''' in the textbox right to '''Build on resource save (Auto build)''' to: '''all''' 
     101     - I personally uncheck the '''Build on resource save (Auto build)''' (I'd rather build manually) 
     102     - Also set the build target  in the textbox right to '''Build (Incremental build)''' to: "all" 
     103     - Click '''Apply''' 
     104     - Click '''OK''' to close the dialog 
     105 
     106==== Build PJSIP ==== 
     107 
     108Now you can build the ''pjproject'' PJSIP project. 
     109 
     110 
     111[[BR]] 
     112 
     113== Configuring the Device and Momentics IDE == 
     114 
     115For the rest of this tutorial, we will assume that you already have the IDE and target device (or simulator) configured for debugging BB10 application. If not, follow [https://developer.blackberry.com/native/documentation/bb10/com.qnx.doc.native_sdk.quickstart/topic/set_up_your_environment.html these instructions].  
     116 
     117Assorted things to check before debugging an application to the device: 
     118 1. Development mode is turned ON (''Settings'' --> ''Security and Privacy'' --> ''Development Mode'') 
     119    - Otherwise when you connect the USB you'll have a random IP address and you are not able to connect to target device in Momentics 
     120 1. You can connect to !BlackBerry target device in Momentics IDE. A !BlackBerry target device will be named something like ''usb'' or ''usb1'' if you're connecting via USB 
     121    - right click the target device in '''Project Explorer''', select '''!BlackBerry Tools''' --> '''Connect''' 
     122    [[BR]] 
     123    If you can't connect, make sure that: 
     124     - the device is really connected 
     125     - it has the right IP address 
     126     - you can ping it (make sure Development Mode is ON) 
     127     - the IP address is correct in Momentics target properties 
     128 
     129 
     130[[BR]] 
     131 
     132== Building and Running the pjsua Demo Application == 
     133 
     134PJSIP comes with a fully featured pjsua application which runs on all platforms that PJSIP supports including BB10.  
     135 
     136=== Import the PjsuaBB Project === 
     137 
     138In Momentics IDE: 
     139 1. Select '''File''' --> '''Import..''' 
     140 1. Select '''General''' and '''Existing Projects into Workspace''', and press '''Next >''' 
     141 1. In ''Import..'' dialog: 
     142    - Select root directory: '''{{{$PJ_DIR/pjsip-apps/src/pjsua/bb10}}}''' 
     143 Once you select the directory, '''PjsuaBB''' will appear under ''Projects'' list in the dialog. Make sure it is selected (by default it is). Click '''Finish''' 
     144 
     145=== Build PjsuaBB === 
     146 
     147Just build it. 
     148 
     149=== Create Debug Configuration === 
     150 
     151 1. Highlight "PjsuaBB" from the Project Navigator, select '''Run''' --> '''Debug Configurations..''' from the main menu 
     152 1. From the left list, right click '''!BlackBerry C/C++ Application''', and select '''New..''' 
     153 1. New debug settings will appear with default values 
     154 1. Go to '''Debugger''' tab and uncheck '''Stop on startup''' 
     155 1. Press '''Apply''' 
     156 
     157 
     158[[BR]] 
     159 
     160== Creating a New PJSIP Based Application == #newapp 
     161 
     162=== Creating a !BlackBerry Native Application === #appconfig 
     163 
     164Use Momentics new project wizard to create a new !BlackBerry native application. This should be easy, and we will not explain it here. 
     165 
     166Configure the permissions by double-clicking ''bar-descriptor.xml'' file and select ''Application'' tab from the bottom of the page, and check these permissions: 
     167  - Internet 
     168  - Microphone 
     169  - Run When Backgrounded 
     170 
     171 
     172=== Integrating PJSIP into the App ===  #newappintegrate 
     173 
     174Integrating PJSIP settings into the app is very easy: 
     175 1. Open the app's '''.pro''' file (e.g. {{{PjsipBB.pro}}} for PjsipBB app) 
     176 1. Include '''pjsip.pri''' file in the relevant target section, e.g.: 
     177 {{{ 
     178.. 
     179device { 
     180    CONFIG(debug, debug|release) { 
     181        .. 
     182        include(../../../../pjsip.pri) 
     183        LIBS += -lbb 
     184        .. 
     185    } 
     186} 
     187.. 
     188 }}} 
     189 
     190The '''pjsip.pri''' file is generated by {{{configure-bb10}}} script (as explained [#pjsippri above]) and contains compilation and link flags to integrate PJSIP with your app.  
     191 
     192 
     193[[BR]] 
    33194 
    34195== Simulator == 
    35196 
    36 Install and configure the BB10 simulator, you will need to install a virtual machine player in order to use the simulator. To build for BB10 simulator, just run: 
     197Install and configure the BB10 simulator, you will need to install a virtual machine player in order to use the simulator. To build for BB10 simulator, just run {{{configure-bb10}}} script with {{{--simulator}}} option: 
    37198 {{{ 
    38199$ ./configure-bb10 --simulator 
    39 $ make dep && make clean && make 
    40  }}} 
     200 }}} 
     201 
     202 
     203[[BR]] 
     204 
     205== Multiple PJSIP Build Configurations == 
     206 
     207If you want to have multiple PJSIP build configurations for your app (for example, Device-Debug, Device-Release, and/or Simulator), you can use the following approach when building PJSIP. 
     208 
     209 
     210=== Option 1: Build PJSIP in Multiple Directories === 
     211 
     212This is of course the easiest, just extract or checkout PJSIP in multiple locations, configure it differently, build, and include the right '''pjsip.pri''' file in the relevant section of you application's QMake '''.pro''' file. 
     213 
     214=== Option 2: Checkout Once, Configure Build and Install Several Times === 
     215 
     216The second option is to checkout PJSIP in one directory, but configure, build, and install it several times, each with separate build settings and to different install '''{{{--prefix}}}'''. Once the build completes, run {{{make install}}} to install PJSIP development headers and libraries to the installation prefix. You also need to edit the contents of {{{pjsip.pri}}} file, point the path to the right prefix, and rename the {{{pjsip.pri}}} to something more appropriate (e.g. {{{pjsip-device-debug.pri}}}). You then include this .pri file in the relevant section of your application's QMake {{{.pro}}} file. 
     217 
     218 
     219 
     220[[BR]] 
    41221 
    42222== Notes == 
    43223 
     224=== Missing Separator === 
     225 
     226If you forgot to run '''{{{source bbndk-env.sh}}}''' (as explained [#ndk above]) before running {{{make dep}}}, the dependency files will get corrupted with the ''' "!** missing separator" ''' error and you'll have to delete each of those dependency files manually. 
     227 
    44228=== GSM Call Interruption Problem === #gsm 
    45229 
     
    49233 
    50234Thank you Bob Cripps of Truphone for the note. 
     235 
     236=== Unable to Get Sound Device Parameters === #snd0 
     237 
     238This error happens because PJSIP is unable to open the audio capture device. Make sure you set the [#appconfig application permissions] correctly. 
     239