# HOW TO COMPILE SIMPHONE 0.9.1 FROM ITS SOURCE CODE

## 1. General Notes

Simphone can easily be compiled from its source code on Windows, Mac OS, Linux or other unix-like operating systems. Only native builds are currently supported (no compiling for an operating system or an architecture different from the one you are using to compile the sources).

The procedures detailed below allow anyone with command-line skills to produce the same executable file as available on the internet from the source codes. Please refer to chapter 6 to see how to do that.

This table lists internet sites that you can use to download the source code and tools required to compile it:

what | where | OS | md5sum
--- | --- | --- | ---
simphone source | http://www.simphone.org/0.9.1/simphone-src-0.9.1.zip | ALL |
Qt Windows | https://download.qt.io/new_archive/qt/5.3/5.3.2/qt-opensource-windows-x86-mingw482_opengl-5.3.2.exe | Windows | 1ee1aa4eb5db4a18917eaed965a0bc67
Qt unix source | https://download.qt.io/new_archive/qt/5.6/5.6.3/single/qt-everywhere-opensource-src-5.6.3.tar.xz | Linux | 010342d515b62ee1c0e709254f4ef9ab
Qt Mac OS | https://download.qt.io/new_archive/qt/5.3/5.3.2/single/qt-everywhere-opensource-src-5.3.2.tar.gz | Mac OS | febb001129927a70174467ecb508a682
Xcode | https://developer.apple.com/download | Mac OS | 2a02f5c2b44d80ff3047cc4d7a281127
Debian DVD 1 | https://cdimage.debian.org/mirror/cdimage/archive/6.0.10/amd64/iso-dvd/debian-6.0.10-amd64-DVD-1.iso | Linux | 146eeebe6535fb2432ba65f1ad0c7989
Debian DVD 2 | https://cdimage.debian.org/mirror/cdimage/archive/6.0.10/amd64/iso-dvd/debian-6.0.10-amd64-DVD-2.iso | Linux | df7f7ae495d611c8706fdeffb5f2c762

Please follow the instructions for your operating system as specified in chapter 2, chapter 3 or chapter 4.

## 2. Microsoft Windows

You need Windows XP (Service Pack 3) or any later version such as Windows Seven, and a Pentium-2 (i686) or newer compatible processor.

Before you begin, make sure you have at least four gigabytes of free disk space, and that your system clock is not set to a past date.

### step one: fetch the simphone source code

Download the source archive simphone-src-0.9.1.zip and unpack it (you can click on the .zip file and then copy the files to a directory of your choice). A simphone directory will appear there.

To avoid unpleasant surprises, do not choose parent directories that have spaces or non-english letters in their names. The examples given here assume that you have unpacked the file to c:\ so that all source files are under c:\simphone.

### step two: install the qt toolkit

Download qt-opensource-windows-x86-mingw482_opengl-5.3.2.exe from the Qt archive on the internet. Click on the exe file to run it.

You must customize the installation as components selected to install by default are not enough. After picking a directory to install to, do the following when prompted to Select Components:

- optionally deselect MinGW from under Qt 5.3 (to avoid requiring two additional gigabytes of disk space)
- select to install Source Components from under Qt 5.3
- optionally deselect Add-Ons from under Source Components (leave only Essentials)
- select to install MinGW from under Tools.

Afterwards, accept the Qt Installer LGPL Agreement to proceed. If the Qt installer reports errors, click the Ignore button to continue.

After Qt has been installed, copy or move the Qt sources and tools to the simphone directory, while renaming mingw482_32 to mingw. You can use either drag-and-drop, or commands like:

`move c:\Qt\Qt5.3.2\5.3\Src\qtbase c:\simphone`
`xcopy /e /i c:\Qt\Qt5.3.2\Tools\mingw482_32 c:\simphone\mingw`

You can uninstall Qt now, unless you plan to use Qt Creator later.

### step three: compile qt

Open a "DOS" command prompt and execute:

`c:`
`cd \simphone\build`
`build_qt`

This will take a long time. When it's finished and you see a message that Qt has been compiled successfully, proceed to the next step.

### step four: compile simphone

While still in the same directory at the command prompt, execute:

`build_simphone`

The rlink script used under Windows takes a long time to complete. Please be patient.

At the end, you should see a message that Simphone has been compiled successfully. You will find simphone.exe as c:\simphone\qsimphone\release\simphone.exe.

## 3. Mac OS

You need Mac OS version 10.6.7 (Snow Leopard) or later.

First of all, download and install Xcode from the Apple developer site. Make sure the Xcode version you downloaded is compatible with your version of Mac OS.

When installing Xcode and prompted for a Custom Install, you can skip the iOS SDK because it would occupy much disk space and is not needed.

Before you begin step one, make sure you still have at least two gigabytes of free disk space, and that your system clock is not set to a past date.

### step one: fetch the simphone source code

Download the source archive simphone-src-0.9.1.zip and unpack it with commands like:

`rm -rf simphone`
`unzip simphone-src-0.9.1.zip`

### step two: fetch the qt source code

Download qt-everywhere-opensource-src-5.3.2.tar.gz from the Qt archive on the internet. Unpack it with a command like:

`tar -xzf qt-everywhere-opensource-src-5.3.2.tar.gz`

Move the just unpacked qtbase directory to the simphone directory with a command like:

`mv qt-everywhere-opensource-src-5.3.2/qtbase simphone`

### step three: compile qt

At the shell (terminal) prompt, execute:

`cd simphone/build`
`sh ./build_qt`

This will take a long time. When it's finished and you see a message that Qt has been compiled successfully, proceed to the next step.

### step four: compile simphone

While still in the same directory at the shell prompt, execute:

`sh ./build_simphone`

At the end, you should see a message that Simphone has been compiled successfully. You will find the simphone binary as simphone/qsimphone/simphone.

## 4. GNU/Linux, FreeBSD or Other unix-like Systems

Any non-ancient version should work. If you encounter problems, please report them.

You need to have the following tools and libraries installed, as prerequisites:

name | description | needed to
--- | --- | ---
g++ | The GNU C++ compiler | compile anything
gmake | GNU make | compile anything
perl5 | Practical Extraction and Report Language | configure openssl
patch | Apply a diff file to an original | patch Qt source code
pkgconf | pkg-config | configure Qt
libc | The C development library | compile simcore
gtk2 | GIMP toolkit development library | compile the GUI

To enable the full functionality of Simphone, you also need to have the following development libraries installed:

name | description | needed by
--- | --- | ---
libexecinfo | Library for inspecting backtrace | compile Qt on BSD unix
libSM | X11 session management library | Qt session management
libasound | ALSA development library | Linux audio support
libudev | hotplug management library | Linux audio PNP function
libxss | X11 Screen Saver extension library | GUI auto-away function
libkeysyms | XCB utility library for keycodes | GUI global hotkeys

Non-bold names indicate that these components are usually already available with the "base" system and need not be installed separately. Note that it is possible to compile Qt without gtk2, if it is not available. But in that case some other development libraries (which are not listed here) are required.

Before you begin step one, make sure you have at least three gigabytes of free disk space, and that your system clock is not set to a past date.

### step one: fetch the simphone source code

Download the source archive simphone-src-0.9.1.zip and unpack it with commands like:

`rm -rf simphone`
`unzip simphone-src-0.9.1.zip`

### step two: fetch the qt source code

Download qt-everywhere-opensource-src-5.6.3.tar.xz from the Qt archive on the internet. Unpack it with a command like:

`xz -cd qt-everywhere-opensource-src-5.6.3.tar.xz | tar -xf -`

Move the just unpacked qtbase directory to the simphone directory with a command like:

`mv qt-everywhere-opensource-src-5.6.3/qtbase simphone`

### step three: compile qt

At the shell (terminal) prompt, execute:

`cd simphone/build`
`sh ./build_qt`

This will take a long time. When it's finished and you see a message that Qt has been compiled successfully, proceed to the next step.

### step four: compile simphone

While still in the same directory at the shell prompt, execute:

`sh ./build_simphone`

At the end, you should see a message that Simphone has been compiled successfully. You will find the simphone binary as simphone/qsimphone/simphone.

## 5. Development

For simple modifications to the source code, you can re-run build_simphone to recompile Simphone. This will still take a long time to complete. If you are not using Windows, sometimes it is enough to run make (or gmake under BSD) instead. But if you want to do any serious development, you should also read and understand this chapter.

The recommended way to develop is by using the autoconf (configure) script from the top-level simphone directory. The script has a few options:

- ./configure --config-cache to speed up the run of the configure script
- ./configure --with-debug to facilitate debugging
- ./configure --without-qt to compile only simcore (not the GUI)
- ./configure --with-qt if you did not compile Qt (under simphone)
- ./configure --help to see more options that are available to you.

In order to use --with-qt, you need to first have installed Qt to your system, and made sure that qmake is available at the current PATH. Note that this option will probably produce an executable file that is dynamically-linked to Qt libraries, so the compiled program will occupy much memory. In addition to that, the GUI may exhibit buggy behavior; long chat messages may be invisible. Under Linux, the system tray icon might not work; on Windows, blinking the task bar will be broken.

Qt versions earlier than the ones listed here do not work, and versions earlier than Qt 5.2 do not allow to compile. On Linux, Qt 5.7 and later do not include a Gtk style, which changes the appearance of the simphone GUI to something that's not Linux style.

The top-level configure script and Makefile neither configure nor compile Qt; you need to either have compiled Qt before running configure, as explained in the previous chapters, or use the --with-qt or --without-qt option.

From then on, you can run just make (or gmake under BSD) whenever necessary. Note that simcore doesn't have any dependencies in its Makefile, so changes to simcore usually require that you do a make clean (or gmake clean under BSD) in the simcore directory.

Upgrading any of the libraries used by simcore usually requires a make distclean (or gmake distclean under BSD) followed by a re-run of the configure script.

### Microsoft Windows

In order to be able to run the configure script under Windows, you need to have msys installed.

The first time you start the msys shell, you have to let msys know where mingw is. This can be done with a command like:

`mount c:/simphone/MinGW /mingw`

If you got errors during Qt installation, Qt Creator may refuse to start. You might be missing "Windows Installer 3.1" (KB893803) or later, which is required by vcredist (the VC redistributable installer), which in turn is required by and included with Qt Creator. Administrative privileges are probably required to install all of that.

If you want to avoid compiling Qt from its source code and work with its precompiled version instead, DO NOT deselect mingw from under Qt 5.3, when installing Qt components (as explained in chapter 2).

Alternatively, you can use the Microsoft C++ compiler to compile the GUI. Before you do that, you'll need to first compile simcore as a DLL with gcc (mingw). Use the following commands:

`./configure --without-qt --with-debug`
`make`
`make dll`

This will produce simcore.dll and simcore.def. The Microsoft compiler also requires simcore.exp and simcore.lib. These can be produced by LIB.EXE from Microsoft, and make dll will do that too, if LIB.EXE is found at the current PATH (make sure you have ran the Visual Studio .bat file that sets the path).

simcore can also be compiled directly with the Microsoft compiler after copying config-msvc.h to config.h; the configure step can be skipped in this case. A project file to compile libraries used by simcore with Visual Studio is not currently available.

For security reasons, using an executable file compiled with the Microsoft compiler for anything other than testing is not recommended.

### embedded platforms

The sources can be easily compiled on the Raspberry Pi and on Ubuntu Touch, but the current GUI is useless with a small display.

Cross-compilation is currently not supported; the main difficulty is cross-compiling the Qt toolkit.

For Android and iOS, programming is required, mostly for the GUI. If you want to work on that, please let us know.

## 6. Binary Reproduction

Following all instructions in chapter 2 or chapter 3 should produce the same executable that you have downloaded from the internet, provided that you used the same versions of all tools and libraries, and the same version of Simphone (source and binary).

On Windows and Mac OS, you MUST compile Qt version 5.3.2 from its source code (do not use the --with-qt option).

For Mac OS, use Xcode 3.2.6 and execute:

`sh ./build_simphone --with-install-exec`

To avoid differing pathnames in the executable file, you should have put the sources to c:\ on Windows, and /Users/mac on Mac OS.

After you've compiled successfully, compare simphone (or simphone.exe on Windows) byte by byte to the one that's on the internet. You can do that with the following command:

`cmp -l` `compiled-simphone-exe``` `other-simphone-exe`

There should be no output, as no bytes would differ. If they do, you can proceed to verify whether the text (assembly code) of the program differs with a command sequence like:

`objdump -d` `compiled-simphone-exe``> mytext`
`objdump -d` `other-simphone-exe``> othertext`
`diff -u mytext othertext`

### x64 Linux

Download Debian version 6.0.10 (squeeze) installation DVDs (you only need the first two of them). Note that the files are very old, so they may be available only via BitTorrent or/and Jigdo. Please check that the md5sums of both DVDs match the ones listed in chapter 1.

Before you proceed, make sure your computer is NOT connected to the internet. Boot from the first DVD to install Debian GNU/Linux on your computer. The installer will ask you questions; provide all of them with default answers (by hitting the Enter key at each question), except as noted below:

- choose Do not configure the network at this time (so that no system updates may creep in)
- set a non-empty Root password
- select a Username for your account (what ever you like) and choose a password for that user
- when asked to Write the changes to disks, answer Yes (to format your hard disk)
- when asked If you wish to scan another CD or DVD for the first time, insert the second DVD and answer Yes (only once)
- after the second DVD has been scanned, you may be prompted to switch between the two DVDs several times. Do exactly as asked
- when finally prompted to Choose software to install, deselect Graphical desktop environment (this saves a lot of time and space)

Remove any DVD to boot into your new system when prompted and log in as root with the password you have previously chosen. Insert the first DVD and then type the following at the root shell prompt:

`apt-get install g++ make patch libfontconfig1-dev libsm-dev libasound2-dev libxss-dev`

At this point, you may connect to the internet if you like. Unpack the simphone and Qt version 5.6.3 source code under the /root directory (as described by step one and step two of chapter 4) and execute:

`cd /root/simphone/build`
`sh ./build_qt -no-gtk -install-exec`
`sh ./build_simphone --without-udev --without-xcb --with-xss --with-alsa --with-oss --with-crash-handler --with-install-exec`

Finally, do the binary comparison as already described above.

### unix installer: simple verification

The unix installer compiles a simphone binary from the included source code, which is a subset of the simphone source code (unnecessary source files are not included with the installer, in order to save space).

You can verify that this is so (at any unix system) by running:

`sh ./simphone_installer.shar --unpack`

which will create a subdirectory called installer_simphone but not proceed to compile the source code. You can then compare by executing:

`mv qt-everywhere-opensource-src-5.6.3/qtbase simphone`
`cd simphone`
`autoconf`
`cd build`
`autoconf`
`cd ../..`
`diff -qrb installer_simphone simphone | grep -v '^Only in simphone'`

Empty output indicates that the simphone installer contains nothing more than the simphone directory (which should contain the full simphone source code).

Note that the "autoconf" commands are needed only to reproduce the two configure scripts. They require autoconf version 2.67.

### unix installer: complete reproduction

You need autoconf version 2.67 and GNU sharutils 4.9, as well as tools and libraries listed here, including gtk2. Then execute:

`mv qt-everywhere-opensource-src-5.6.3/qtbase simphone`
`cd simphone/build`
`sh ./make_installer.sh`

On success, compare the just created installer to the one that's on the internet:

`cd ../..`
`diff -u simphone_installer.shar` `other_simphone_installer.shar`

Empty output indicates no differences. If this didn't work for whatever reason, please first install Debian version 6.0.10 as described above.

After you have logged in as root to the newly installed system, type the following at the root shell prompt:

`apt-get install g++ make patch libasound2-dev libxss-dev`
`apt-get install autoconf sharutils libgtk2.0-dev libsm-dev`

to fetch all the needed tools and libraries, and then unpack simphone and Qt version 5.6.3 source code under /root. Then do:

`cd /root/simphone/build`
`sh ./make_installer.sh`
`diff -u /root/simphone_installer.shar` `other_simphone_installer.shar`

The only difference should be the lock_dir shar pid, which is a somewhat random number and therefore different for each run.

### translated messages

To verify that strings included with the GUI match the ones from the translations subdirectory of the source code, execute:

`cd translations`
`lrelease -removeidentical *.ts`
`diff -qrb . ../resources | grep -v 'Only in .:'`

You need to install Qt Linguist so that the lrelease command is available. Version 5.6.3 is recommended.