+# Swift Development Overview

+## Build System

+It is also possible to set frequently used configuration options in a `config.py`

+file in the project folder.

+Settings of particular interest are:

+- `qt` to set the path to a Qt installation

+- `cc`, `cxx`, `link` to set the C compiler, C++ compiler and linker to use

+- `cxxflags` to set additional flags to pass to the C++ compiler

+- `linkflags` to set additional flags to pass to the linker

+

+If you change anything in the configuration, or install previously missing dependencies, you might need to pass `force-configure=1` to SCons to force it to

+look for the dependencies again and not use cached information.

+

+It is also possible to only build Swiften or Sluift by passing explicit build targets to scons. For example `./scons Swiften` to only build Swiften.

+

+To install the build output on the system, simply run `./scons SWIFTEN_INSTALLDIR=/usr/local /usr/local

+

+Swift is written in cross-platform C++11. It is continuously tested with GCC, Clang and Visual Studio 2013.

+

+## Testing

+Swift has unit and integration tests. To run the unit tests, pass `test=unit`, and to run the integration tests, pass `test=system`, or pass `test=all` to run both.

+

+The integration tests require external setup and parameters to run.

+- `SWIFT_CLIENTTEST_JID=user@domain`

+- `SWIFT_CLIENTTEST_PASS=password`

+- `SWIFT_FILETRANSFERTEST_JID=user@domain`

+- `SWIFT_FILETRANSFERTEST_PASS=password`

+- `SWIFT_FILETRANSFERTEST2_JID=anotheruser@domain`

+- `SWIFT_FILETRANSFERTEST2_PASS=password`

+- `SWIFT_NETWORK_TEST_IPV4=0.0.0.0`

+

+Note: The unit and integration tests are build targets. When passing specific build targets to SCons the tests will not be build and run (even with `test=all`) unless the build targets for the tests are added as arguments to the `scons` call.

+

+## Packaging

+### Mac OS X

+The Mac OS X package consists of a disk image (.dmg) file containing an independently deployable **Swift.app** application bundle.

+

+### Windows

+The Windows package consist of a Widnows Installer (.msi) file. This is generated using the Windows Installer XML Toolset.

+

+For packaging use:

+- Microsoft VS 2013 Express

+- WiX

+- Download the C++ redistributable package from Microsoft and put it at `C:\Program Files (x86)\Common Files\Merge Modules\`

+- `config.py` should contain:

+ qt = "c:\\qt\\5.4.2"

+ vcredist = "C:\\Program Files (x86)\\Common Files\\Merge Modules\\vcredist_x86.exe"

+ debug = 1

+ optimize = 1

+ wix_bindir = "c:\\program files\\Windows Installer XML v3.5\\bin"

+- Run the following commands. Two scons runs are required as 'scons dist=1' requires the Swift.exe to be in place.

+```

+scons

+scons dist=1

+```

+

+Notes:

+- The settings `debug = 1` and `optimize = 1` are **strictly required** if you use a precompiled Qt release from the Qt Project; otherwise you will get linker errors

+- On 64-bit Windows it's "Program Files (x86)" instead of "Program Files" in the

+ paths

+- Currently only 32-bit builds of the Swift client are supported

+

+## Building Swiften for Android

+This section describes how to build Swiften for Android. It can then be used from any Android native code. This guide has been tested on OS X and Linux.

+

+### Prerequisites

+- Android SDK

+- Android NDK

+- Python

+- Other requirements that are obtained during this guide

+ - LDNS

+ - Unbound

+ - OpenSSL

+

+### Note on Supported Features

+File-transfer support has not been tested on Android. Link-local features are not supported under Android.

+

+### Supported Android NDK Level

+The minimal supported Android NDK API level is 14 (see --platform parameter of make-standalone-toolchain.sh).

+This is the NDK API level associated with Android 4.0. Higher Android NDK API levels however should work.

+

+### Preparation of Build Environment

+1. Fetch 3rd-party dependencies

+ 1. LDNS

+ ```

+ cd 3rdParty/Ldns

+ bash prepare_ldns.sh

+ ```

+ 2. Unbound

+ ```

+ cd 3rdParty/Unbound

+ bash prepare_unbound.sh

+ ```

+

+ 3. OpenSSL

+ ```

+ cd 3rdParty/OpenSSL

+ curl -O http://www.openssl.org/source/openssl-1.0.1j.tar.gz

+ tar -xf openssl-1.0.1j.tar.gz

+ mv openssl-1.0.1j openssl

+ ```

+

+2. Patch 3rd-party dependencies

+ ```

+ patch -p0 < 3rdParty/Ldns/01_andoird_compilation_fixes.diff

+ patch -p1 < 3rdParty/LibMiniUPnPc/01_android_compilation_fixes.diff

+ patch -p1 < 3rdParty/Unbound/01_android_fixes.diff

+ ```

+

+3. Create Android NDK Toolchain

+ ```

+ cd $ANDROID_NDK_ROOT (this is the folder where you extracted Android NDK)

+ bash ./build/tools/make-standalone-toolchain.sh --platform=android-14 --install-dir=$HOME/android-14-tc

+ ```

+

+### Configuring Swift Build

+1. Set config.py to (probably other paths, replace $NDK_TOOLCHAIN_INSTALL_DIR with the expanded path of the install dir used in the previous step):

+```

+android_toolchain=$NDK_TOOLCHAIN_INSTALL_DIR

+android_sdk_bin="/usr/local/bin"

+target = "android"

+unbound = 1

+```

+

+### Building

+Simply run `./scons test=none Swiften QA max_jobs=1`.

+

+### Testing

+Running Swift's test suite on Android requires a one time preparation of a testing environment.

+This creates an Android VM where the test will be deployed to and run on.

+

+1. Preparation of test environment (one time)

+ 1. Starting AVD (Android Device Manager) by running `android avd`

+ 2. Create a test VM by clicking the "Create..." button

+ 3. Fill out dialog

+ - AVD Name: swift_test

+ - Device: Nexus 4

+ - Target: Anything with API level equal or greater than your toolchain you build

+ - CPU/ABI: ARM (unless you build a different toolchain)

+ 4. Click "Ok" button

+ 5. Close AVD

+

+2. Running integration and unit tests

+ To run the unit tests you need to have an Android VM running while the test suite is running.

+ This requires to leave the command under step 2.1 running while you execute step 2.2.

+

+ Running the test suite on Android can take quite some time ( >30 minutes ) compared to a native run.

+ This is due to a) the slow transfer speed from host machine to VM (~ 2 MB/s) and and b) the test environment being emulated for an different CPU architecture.

+

+ 1. Start Android VM with resized /system partition:

+ `emulator -partition-size 2048 @swift_test`

+

+ 2. Run integration and unit tests (wait until the android boot screen is gone)

+ `env SWIFT_CLIENTTEST_JID="some jabber id" SWIFT_CLIENTTEST_PASS="password for the jabber id" ./scons test=all Swiften Swift/Controllers QA`

+

+## Building Swiften for iOS

+### Prerequisites

+- XCode

+- Python

+- Other requirements that are obtained during this guide

+ - OpenSSL

+

+### Supported Components

+- Swiften

+

+ Note: File-transfer support has not been tested on iOS. Link-local features are not supported under iOS.

+- Swift/Controllers

+

+### Preparation of Build Environment

+1. Fetch 3rd-party dependencies

+ 1. OpenSSL

+ ```

+ cd 3rdParty/OpenSSL

+ curl -O http://www.openssl.org/source/openssl-1.0.1j.tar.gz

+ tar -xf openssl-1.0.1j.tar.gz

+ mv openssl-1.0.1j openssl

+ ```

+

+### Building

+1. Switch to iOS directory

+ ```

+ cd BuildTools/iOS

+ ```

+

+2. Look up installed SDKs

+ ```

+ xcodebuild -showsdks

+ ```

+ Note: Here the iOS SDKs and iOS Simulator SDKs are of interest.

+

+3. Build Swiften (adjust the sdk parameter to one of the installed SDKs)

+ ```

+ xcodebuild build -arch i386 -sdk iphonesimulator8.1

+ ```

+

+ Note: When not specifying the architecture (-arch flag) XCode will try an universal build which is not supported.

+

+ Only specify one architecture at a time and if you require a universal lib you can create one using the `lipo` tool.

+

+4. The final libSwiften.a is located at `$SWIFT/build/current/Swiften/libSwiften.a`.

+

+### Testing

+Integration and unit tests are not supported on iOS.