diff options
Diffstat (limited to 'DEVELOPMENT.md')
-rw-r--r-- | DEVELOPMENT.md | 203 |
1 files changed, 203 insertions, 0 deletions
diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md new file mode 100644 index 0000000..761fad3 --- /dev/null +++ b/DEVELOPMENT.md @@ -0,0 +1,203 @@ +# 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. |