README.md 8.89 KB
Newer Older
1
[![Build Status](https://travis-ci.org/BelledonneCommunications/linphone-iphone.svg?branch=master)](https://travis-ci.org/BelledonneCommunications/linphone-iphone)
Gui13's avatar
Gui13 committed
2

3 4 5 6
Linphone is a free VoIP and video softphone based on the SIP protocol.

![Dialer screenshot](http://www.linphone.org/img/slideshow-phone.png)

7 8 9 10 11 12 13
# How can I contribute?

Thanks for asking! We love pull requests from everyone. Depending on what you want to do, you can help us improve Linphone in
various ways:

## Help on translations

14
<a target="_blank" style="text-decoration:none; color:black; font-size:66%" href="https://www.transifex.com/belledonne-communications/linphone-ios/"
15
title="See more information on Transifex.com">Top translations: linphone-ios</a><br/>
16
<img border="0" src="https://transifex.com/projects/p/linphone-ios/resource/localizablestrings/chart/image_png"/><br/><a target="_blank" href="/"><img border="0" src="https://ds0k0en9abmn1.cloudfront.net/static/charts/images/tx-logo-micro.646b0065fce6.png"/></a>
17 18 19 20 21

Interested in helping translate Linphone? Contribute [on Transifex](https://www.transifex.com/belledonne-communications/linphone-ios).

## Report bugs and submit patchs

22
If you want to dig through Linphone code or report a bug, please read `CONTRIBUTING.md` first. You should also read this `README` entirely ;-).
Benjamin REIS's avatar
Benjamin REIS committed
23

24
## How to be a beta tester ?
Benjamin REIS's avatar
Benjamin REIS committed
25

26
Enter the Beta :
Benjamin REIS's avatar
Benjamin REIS committed
27
 - Download TestFlight from the App Store and log in it with your apple-id
Benjamin REIS's avatar
Benjamin REIS committed
28
 - Send an email to linphone-iphone@belledonne-communications.com, with object : [Beta test - Request], where you precise your apple-id you logged in TestFlight with
Benjamin REIS's avatar
Benjamin REIS committed
29 30 31
 - You will receive an invitation code to the beta in the following days via your email associated to your apple-id
 - Enter the invitation code received into TestFlight
 - Download Linphone from TestFlight
Benjamin REIS's avatar
Benjamin REIS committed
32
 - And voilà ! TestFlight will send you a notification every time a new beta test is available.
Benjamin REIS's avatar
Benjamin REIS committed
33

34
Send a crash report :
Benjamin REIS's avatar
Benjamin REIS committed
35
 - It is done automatically by TestFlight
Benjamin REIS's avatar
Benjamin REIS committed
36

37
Report a bug :
Benjamin REIS's avatar
Benjamin REIS committed
38 39 40 41 42 43 44 45 46 47
 - Open Linphone
 - Go to Settings —> Advanced —> Send logs
 - An email to linphone-iphone@belledonne-communications.com is created with your logs attached
 - Fill in the bug description with :
	* What you were doing
	* What happened
	* What you were expecting
	* Approximately when the bug happened
 - Change the object to [Beta test - Bug report]
 - Send the mail
48

49
# Building and customizing the SDK
50

51
Linphone for iPhone depends on liblinphone SDK. This SDK is generated from makefiles and shell scripts.
52

53 54 55 56 57 58 59 60 61 62 63
 Steps to customize the liblinphone SDK options are:

 1. Install [HomeBrew, a package manager for OS X](http://brew.sh) (MacPorts is supported but deprecated).
 2. Install Linphone dependencies: open iTerm.app in the current directory and list dependencies to install using:
 `./prepare.py`
 3. Reorder your path so that brew tools are used instead of Apple's ones which are obsolete:
 `export PATH=/usr/local/bin:$PATH`
 4. Build SDK (see below for options and explanations):
 `./prepare.py -c && ./prepare.py && make`

 For instance to generate the liblinphone multi-arch SDK in GPL mode, simply invoke:
64

65
        ./prepare.py [options] && make
jehan's avatar
jehan committed
66

67
**The resulting SDK is located in `liblinphone-sdk/` root directory.**
68

69 70
## Incorporating our SDK in your project

Benjamin REIS's avatar
Benjamin REIS committed
71 72 73 74
After the SDK has been built, add all the `.framework` files located in `liblinphone-sdk/apple-darwin/Frameworks` to your XCode project Embedded Frameworks and linked binaries.
Make sure that your project FRAMEWORK_SEARCH_PATHS contains "$(PROJECT_DIR)/liblinphone-sdk/apple-darwin/Frameworks"
Make sure that your project HEADER_SEARCH_PATHS contains "$(SRCROOT)/liblinphone-sdk/apple-darwin/include"
Make sure that your project LD_RUNPATH_SEARCH_PATHS contains "$(inherited) @executable_path/Frameworks";
Benjamin REIS's avatar
Benjamin REIS committed
75
Add a Run Script step to your build steps, put it after your step to embed frameworks, set it to use our `deploy.sh` script located in the `Tools` folder of linphone-iphone root directory.
76

77
## Licensing: GPL third parties versus non GPL third parties
78

79
This SDK can be generated in 2 flavors:
80

81
* GPL third parties enabled means that liblinphone includes GPL third parties like FFmpeg. If you choose this flavor, your final application **must comply with GPL in any case**. This is the default mode.
82

83 84
* NO GPL third parties means that Linphone will only use non GPL code except for `liblinphone`, `mediastreamer2`, `oRTP` and `belle-sip`. If you choose this flavor, your final application is **still subject to GPL except if you have a [commercial license for the mentioned libraries](http://www.belledonne-communications.com/products.html)**.
 To generate the liblinphone multi arch SDK without GPL third parties, invoke:
85

86
        ./prepare.py -DENABLE_GPL_THIRD_PARTIES=NO -DENABLE_FFMPEG=NO [other options] && make
87 88 89

## Customizing features

90
You can enable non-free codecs by using `-DENABLE_NON_FREE_CODECS=ON` and `-DENABLE_<codec>=ON`. To get a list of all features, the simplest way is to invoke `prepare.py` with `--list-features`:
91 92 93

        ./prepare.py --list-features

94
You can for instance enable X264 using:
95

96
        ./prepare.py -DENABLE_NON_FREE_CODECS=ON -DENABLE_X264=ON [other options]
97 98 99 100 101 102 103 104 105 106

## Built architectures

4 architectures currently exists on iOS:

- 64 bits ARM64 for iPhone 5s, iPad Air, iPad mini 2, iPhone 6, iPhone 6 Plus, iPad Air 2, iPad mini 3.
- 32 bits ARMv7 for older devices.
- 64 bits x86_64 for simulator for all ARM64 devices.
- 32 bits i386 for simulator for all ARMv7 older devices.

107
 Note: We are not compiling for the 32 bits i386 simulator by default because Xcode default device (iPhone 6) runs in 64 bits. If you want to enable it, you should invoke `prepare.py` with `i386` argument: `./prepare.py i386 [other options]`.
jehan's avatar
jehan committed
108

109
## Upgrading your iOS SDK
jehan's avatar
jehan committed
110

111
Simply re-invoking `make` should update your SDK. If compilation fails, you may need to rebuilding everything by invoking:
112

113
        ./prepare.py -c && ./prepare.py [options] && make
114

115
# Building the application
116

117
After the SDK is built, just open the Linphone Xcode project with Xcode, and press `Run`.
118

119
## Note regarding third party components subject to license
jehan's avatar
jehan committed
120

121
 The liblinphone SDK is compiled with third parties code that are subject to patent license, specially: AMR, SILK G729 and H264 codecs.
122
 Linphone controls the embedding of these codecs by generating dummy libraries when there are not available. You can enable them using `prepare.py`
123
 script (see `-DENABLE_NON_FREE_CODECS=OFF` option). Before embedding these 4 codecs in the final application, **make sure to have the right to do so**.
124

125
# Testing the application
126

127
We are using the KIF framework to test the UI of Linphone. It is used as a submodule (instead of CocoaPods) for ease.
128

129
Simply press `⌘U` and the default simulator / device will launch and try to pass all the tests.
130 131


132
# Limitations and known bugs
jehan's avatar
jehan committed
133

134
* Video capture will not work in simulator (not implemented in it).
jehan's avatar
jehan committed
135

136
# Debugging the SDK
137

138
Sometime it can be useful to step into liblinphone SDK functions. To allow Xcode to enable breakpoint within liblinphone, SDK must be built with debug symbols by using option `--debug`:
139

140
        ./prepare.py --debug [other options] && make
jehan's avatar
jehan committed
141

142
## Debugging mediastreamer2
143

144
For iOS specific media development like audio video capture/playback it may be interesting to use `mediastream` test tool.
145 146 147 148 149 150 151
You can build it using the following:

        ./prepare.py -G Xcode -g && make
        # then open the project for a given architecture (here x86_64, to run on simulator):
        open WORK/ios-x86_64/Build/linphone_builder/EP_linphone_builder.xcodeproj

Then you can select mediastream target and launch it on device. You can configure scheme to pass custom parameters.
152

153
# Quick UI reference
154 155 156 157 158

- The app is contained in a window, which resides in the MainStoryboard file.
- The delegate is set to LinphoneAppDelegate in main.m, in the UIApplicationMain() by passing its class
- Basic layout:

159 160 161 162 163 164 165 166 167
        MainStoryboard
                |
                | (rootViewController)
                |
            PhoneMainView ---> view |--> app background
                |                   |
                |                   |--> statusbar background
                |
                | (mainViewController)
168
                |
169 170 171 172 173 174 175
            UICompositeView : TPMultilayout
                        |
                        |---> view  |--> statusBar
                                    |
                                    |--> contentView
                                    |
                                    |--> tabBar
176 177


178
When the application is started, the phoneMainView gets asked to transition to the Dialer view or the Assistant view.
179
PhoneMainView exposes the -changeCurrentView: method, which will setup its
Gautier Pelloux-Prayer's avatar
Gautier Pelloux-Prayer committed
180
Any Linphone view is actually presented in the UICompositeView, with or without a statusBar and tabBar.
181

Gautier Pelloux-Prayer's avatar
Gautier Pelloux-Prayer committed
182
The UICompositeView consists of 3 areas laid out vertically. From top to bottom: StatusBar, Content and TabBar.
183 184
The TabBar is usually the UIMainBar, which is used as a navigation controller: clicking on each of the buttons will trigger
a transition to another "view".