summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--DEVELOPMENT.md203
-rw-r--r--Documentation/BuildingGenerics.txt6
-rw-r--r--Documentation/BuildingOnAndroid.txt97
-rw-r--r--Documentation/BuildingOnIOS.txt44
-rw-r--r--Documentation/BuildingOnUnix.txt35
-rw-r--r--Documentation/BuildingOnWindows.txt66
-rw-r--r--README.md76
-rw-r--r--README.txt1
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.