+# 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.

+# Swift - An elegant, secure, adaptable and intuitive XMPP Client

+## Quick Start

+Simply run `./scons Swift` on Linux/Mac or `scons.bat Swift` on Windows to build Swift.

+

+This document only covers the general structure, project dependencies and building the Swift GUI application.

+More detailed information on building components, development, testing and packaging can be found in DEVELOPMENT.md.

+

+## Components

+* Swiften: A cross-platform C++ XMPP library.

+* Swift: A Qt-based cross-platform desktop GUI client based on Swiften.

+* Sluift: A XMPP scripting environment based on Lua and Swiften.

+* Limber: A XMPP proxy server proxying zero-configuration (XEP-0174) to a

+connected XMPP client.

+* Slimber: Qt and Cocoa frontends for Limber.

+* SwiftTools: A collection of utilities for Swift.

+

+## Supported Platforms

+* Swift

+ * Windows 7 and later

+ * Mac OS X 10.10 and later

+ * Linux distributions. We usually test on default Ubuntu and Debian installations.

+* Swiften (same as above)

+ * Android

+ * iOS

+

+## External Dependencies

+The Swift repository includes some third party dependencies in the 3rdParty directory

+to easy development. Third party dependencies not included are listed below:

+

+* OpenSSL is required when building Swiften on Linux or Android

+* Qt 5 is required by Swift; **Qt up to version Qt 5.5 is supported**

+

+## General Build Instructions

+The Swift projects use the SCons build system for build configuration and Build

+execution. SCons is one of the included third party dependencies.

+

+To build all Swift components simply run SCons. On Mac OS X and Linux you run the `./scons` command. On Windows you run the `scons.bat` command in a Visual Studio developer shell.

+

+On multi-processor systems, i.e. most desktop and server machines, you can use the `-j NUMBER_OF_PARALLEL_TASKS` flag to speed up build time.

+

+## Platform Specific Instructions

+### Mac OS X

+#### Prerequisites

+- XCode (C++ 11 compiler) or Clang

+- Qt 5: The binary release of Qt provided on https://www.qt.io/download-open-source/ works just fine.

+

+#### Building Swift

+

+After installing Qt, simply run `./scons qt=/Users/username/Qt_installation_path/Qt/5.4.2/5.4/clang_64 Swift` to build Swift. Afterwards you can find a runnable app bundle at `Swift/QtUI/Swift.app`.

+

+### Windows

+#### Prerequisites

+- Microsoft Visual Studio 2013 Express or later (C++11)

+- Windows SDK

+- Python (2.5 <= version < 3)

+- Qt Open Source Edition

+

+A binary release of Qt can be obtained from https://www.qt.io/download-open-source/. Make sure it matches the Visual Studio version you have installed.

+

+#### Building Swift

+

+From the 'Visual C++' 'Programs' group, launch the Visual C++ command prompt, go to your checked out Swift directory and run `scons.bat qt=C:\path\to\qt Swift` to build Swift.

+

+To start Swift, simply change to `Swift/QtUI` and run `Swift.exe`.

+

+### Unix / Linux

+#### Prerequisites

+On Linux Swift mainly depends on Qt and OpenSSL.

+To install all required dependencies take a look at `./BuildTools/InstallSwiftDependencies.sh`. It is a script that supports various Linux distributions and will install the required system packages for building and running Swift.

+

+On Unix/Linux SCons will use `pkg-config` to determine the compiler and linker flags for Qt 5.

+

+Note: The Qt that comes with your Linux distribution might not be up to date and may have issues with some desktop environments.

+

+### Building Swift

+To build Swift, simply open a terminal, go to the project root and run `./scons Swift`. Afterwards you can start Swift by running `./Swift/QtUI/swift-im`.