Swiftdiff options
| author | Tobias Markmann <tm@ayena.de> | 2016-04-27 10:54:18 (GMT) |
|---|---|---|
| committer | Kevin Smith <kevin.smith@isode.com> | 2016-04-29 07:47:38 (GMT) |
| commit | 195300fc8b42f5c54eee2359f497b9dc28c6d27d (patch) | |
| tree | 9e0d47ba54cb59c89a4874385a926e2b1aca2894 | |
| parent | 0709bd664af7a052f2fb7dae2b04e37afed8fdde (diff) | |
| download | swift-195300fc8b42f5c54eee2359f497b9dc28c6d27d.zip swift-195300fc8b42f5c54eee2359f497b9dc28c6d27d.tar.bz2 | |
Restructure and reword project documentation
Restructured project documentation into two basically two
files at the top level.
README.md giving a rough project overview and information
and providing all information needed to build Swift, its
requirements and where to get them for all desktop platforms.
DEVELOPMENT.md is targeted at developers, describing the build
system, how to build only parts of the project. This document
also described how to build Swiften on Android and iOS, and
also covers testing and packaging guidelines.
Test-Information:
None.
Change-Id: Ic47bef6524888db972332b23e6510d10234f7808
| -rw-r--r-- | DEVELOPMENT.md | 203 | ||||
| -rw-r--r-- | Documentation/BuildingGenerics.txt | 6 | ||||
| -rw-r--r-- | Documentation/BuildingOnAndroid.txt | 97 | ||||
| -rw-r--r-- | Documentation/BuildingOnIOS.txt | 44 | ||||
| -rw-r--r-- | Documentation/BuildingOnUnix.txt | 35 | ||||
| -rw-r--r-- | Documentation/BuildingOnWindows.txt | 66 | ||||
| -rw-r--r-- | README.md | 76 | ||||
| -rw-r--r-- | README.txt | 1 |
8 files changed, 279 insertions, 249 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. diff --git a/Documentation/BuildingGenerics.txt b/Documentation/BuildingGenerics.txt deleted file mode 100644 index 284cf45..0000000 --- a/Documentation/BuildingGenerics.txt +++ /dev/null @@ -1,6 +0,0 @@ -To cause scons to search for dependencies instead of using cached results, add force-configure=1 to the commandline: -scons force-configure=1 - -Swift is usually built with Qt5. If you want to build it against Qt4, add the line -qt5 = 0 -to your config.py. However, Qt4 support is no longer actively maintained. diff --git a/Documentation/BuildingOnAndroid.txt b/Documentation/BuildingOnAndroid.txt deleted file mode 100644 index 8a29895..0000000 --- a/Documentation/BuildingOnAndroid.txt +++ /dev/null @@ -1,97 +0,0 @@ -Prerequisites -------------- -- Android SDK -- Android NDK -- Python -- Other requirements that are obtained during this guide - - LDNS - - Unbound - - OpenSSL - -Supported Components --------------------- -- Swiften - Note: 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.1 LDNS - cd 3rdParty/Ldns - bash prepare_ldns.sh - -1.2 Unbound - cd 3rdParty/Unbound - bash prepare_unbound.sh - -1.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 --------- -./scons test=none Swiften Swift/Controllers 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.1 Starting AVD (Android Device Manager) - android avd - -1.2 Create a test VM - Click "Create..." button - -1.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) - - Click "Ok" button - -1.4 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 - b) the test environment being emulated for an different CPU architecture. - -2.1 Start Android VM with resized /system partition - emulator -partition-size 2048 @swift_test - -2.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 diff --git a/Documentation/BuildingOnIOS.txt b/Documentation/BuildingOnIOS.txt deleted file mode 100644 index e310ca1..0000000 --- a/Documentation/BuildingOnIOS.txt +++ /dev/null @@ -1,44 +0,0 @@ -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.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. diff --git a/Documentation/BuildingOnUnix.txt b/Documentation/BuildingOnUnix.txt deleted file mode 100644 index b9f31ea..0000000 --- a/Documentation/BuildingOnUnix.txt +++ /dev/null @@ -1,35 +0,0 @@ -Prerequisites ------------- -- GCC -- Python -- OpenSSL (and development package) -- Qt Open Source Edition (and development package. Optional; not needed for Swiften) - -Building --------- -- Swift uses Qt5 for the UI and on Unix-like platforms it is automatically detected - using pkg-config. - - The dependencies can be installed by running ./BuildTools/InstallSwiftDependencies.sh -- Run - ./scons -- To build only a subdir, add the path as a target to scons. E.g., for Swift: - ./scons Swift - -Running tests -------------- -If you want to run the unit tests (only interesting if you're doing development work) -- Run - ./scons test=unit - for running the unit tests. - -Installing ----------- -- To install swift in /usr/local, run - ./scons SWIFT_INSTALLDIR=/usr/local /usr/local - -Swiften-only ------------- -- To compile just Swiften, add Swiften to the end of the scons command - ./scons Swiften -- To compile and install only Swiften, use SWIFTEN_INSTALLDIR - ./scons SWIFTEN_INSTALLDIR=/usr/local /usr/local diff --git a/Documentation/BuildingOnWindows.txt b/Documentation/BuildingOnWindows.txt deleted file mode 100644 index d296241..0000000 --- a/Documentation/BuildingOnWindows.txt +++ /dev/null @@ -1,66 +0,0 @@ -Prerequisites ------------- -- Microsoft Visual C++ Express Edition -- Windows SDK -- Python (2.5 <= version < 3) -- OpenSSL - * OpenSSL is optional - without it the Windows platform crypto will be used - * Download and extract the Windows binary version of OpenSSL from - http://www.slproweb.com/products/Win32OpenSSL.html -- Qt Open Source Edition (optional; not needed for Swiften) - -Building Qt for Microsoft Visual C++ ------------------------------------- -- These steps are optional - the pre-packaged Qt is fine -- From the 'Visual C++' 'Programs' group, launch the Visual C++ command prompt -- Go to the dir where you installed Qt -- Configure Qt: - configure -- Build Qt: - nmake - -Building Swift --------------- -- From the 'Visual C++' 'Programs' group, launch the Visual C++ command prompt -- Go to the Swift source dir -- Create a file 'config.py' with the following contents, reflecting your local - setup: - openssl = "path\to\openssl" #optional - qt = "path\to\qt" -- Run 'scons' -- To build only a subdir, add the path as a target to scons. E.g., for Swift: - scons Swift - -Running tests -------------- -- Run - scons test=unit - for running the unit tests, or - scons test=all - for running all tests. - -Packaging Swift ---------------- -For packaging use: -- Microsoft Visual C++ Express 2008 or Microsoft VS 2013 Express -- No OpenSSL -- 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 diff --git a/README.md b/README.md new file mode 100644 index 0000000..b48d5c4 --- /dev/null +++ b/README.md @@ -0,0 +1,76 @@ +# 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`. diff --git a/README.txt b/README.txt deleted file mode 100644 index 54e71f2..0000000 --- a/README.txt +++ /dev/null @@ -1 +0,0 @@ -See Documentation/* for build instructions. |