mirror of
https://github.com/nextcloud/desktop.git
synced 2025-10-26 11:17:43 +00:00
5f85c76703
While these are definitely required and useful in some circumstances, artificially breaking paragraphs onto separate lines, to me, reduces rather than increases readability.
424 lines
17 KiB
Plaintext
424 lines
17 KiB
Plaintext
= Appendix A: Building the Client
|
||
:kde-craft-url: https://community.kde.org/Craft
|
||
:kde-craft-build-from-source-url: https://community.kde.org/Guidelines_and_HOWTOs/Build_from_source/Windows
|
||
:install-powershell-url: https://docs.microsoft.com/en-us/powershell/scripting/install/installing-windows-powershell?view=powershell-6
|
||
:python-2_7-url: https://www.python.org/download/releases/2.7/
|
||
:python-3_6-url: https://www.python.org/downloads/release/python-360/
|
||
:ms-visual-studio-2017-url: https://visualstudio.microsoft.com/vs/whatsnew/
|
||
:mingw-w64-url: https://mingw-w64.org/doku.php
|
||
:cmake-url: http://www.cmake.org/download
|
||
:git-url: http://git-scm.com
|
||
:qt-download-url: http://www.qt.io/download
|
||
:openssl-windows-build-url: http://slproweb.com/products/Win32OpenSSL.html
|
||
:qtkeychain-url: https://github.com/frankosterfeld/qtkeychain
|
||
|
||
This section explains how to build link:https://owncloud.org/download/#owncloud-desktop-client[the ownCloud Client] from source for all major platforms.
|
||
You should read this section if you want to develop for the desktop client.
|
||
Build instructions are subject to change as development proceeds.
|
||
|
||
NOTE: Please check the version for which you want to build.
|
||
|
||
These instructions are updated to work with version of the ownCloud Client.
|
||
|
||
[[compiling-via-ownbrander]]
|
||
== Compiling via ownBrander
|
||
|
||
If you don’t want to go through the trouble of doing all the compile work manually, you can use
|
||
https://doc.owncloud.org/branded_clients/[ownBrander] to create installer images for all platforms.
|
||
|
||
[[getting-source-code]]
|
||
== Getting the Source Code
|
||
|
||
The xref:generic-build-instructions[generic build instructions] pull the latest code directly from GitHub, and work on xref:linux[Linux], xref:macos[Mac OS X], and xref:windows-development-build-mingw[Windows].
|
||
|
||
[[linux]]
|
||
== Linux
|
||
|
||
For the published desktop clients we link against QT5 dependencies from our own repositories so that we can have the same versions on all distributions.
|
||
This chapter shows you how to build the client yourself with this setup.
|
||
If you want to use the QT5 dependencies from your system, see the next chapter.
|
||
|
||
You may wish to use source packages for your Linux distribution, as these give you the exact sources from which the binary packages are built.
|
||
These are hosted on the http://software.opensuse.org/download/package?project=isv:ownCloud:desktop&package=owncloud-client[ownCloud repository from OBS].
|
||
Go to the http://download.opensuse.org/repositories/isv:/ownCloud:/desktop/[Index of repositories] to see all the Linux client repositories.
|
||
|
||
[NOTE]
|
||
====
|
||
To get the `.deb` source packages, add the source repository for your Debian or Ubuntu version, as in the following example for Debian 9:
|
||
|
||
[source,console]
|
||
....
|
||
# Run as root
|
||
echo 'deb http://download.opensuse.org/repositories/isv:/ownCloud:/desktop/Debian_9.0/ /' >> /etc/apt/sources.list.d/owncloud-client.list
|
||
echo 'deb-src http://download.opensuse.org/repositories/isv:/ownCloud:/desktop/Debian_9.0/ /' >> /etc/apt/sources.list.d/owncloud-client.list
|
||
....
|
||
====
|
||
|
||
Install the dependencies using the following commands for your specific Linux distribution.
|
||
Make sure the repositories for source packages are enabled.
|
||
These are:
|
||
|
||
[cols="30%,70%",options="header"]
|
||
|===
|
||
| Distribution | Installation Instructions
|
||
| Debian/Ubuntu | `apt update; apt build-dep owncloud-client`
|
||
| openSUSE/SLES | `zypper ref; zypper si -d owncloud-client`
|
||
| Fedora/CentOS/RHEL | `yum install yum-utils; yum-builddep owncloud-client`
|
||
|===
|
||
|
||
Follow the xref:generic-build-instructions[generic build instructions], starting with step 2.
|
||
|
||
[[linux-with-system-dependencies]]
|
||
== Linux with System Dependencies
|
||
|
||
Build sources from a GitHub checkout with dependencies provided by your Linux distribution.
|
||
While this allows more freedom for development, it does not exactly represent what we ship as packages.
|
||
See above for how to recreate packages from source.
|
||
|
||
[NOTE]
|
||
====
|
||
To get the source dependencies on Debian and Ubuntu, run the following command:
|
||
|
||
[source,console]
|
||
....
|
||
sudo apt install qtdeclarative5-dev libinotifytools-dev \
|
||
qt5keychain-dev python-sphinx \
|
||
libsqlite3-dev
|
||
....
|
||
====
|
||
|
||
Follow the xref:generic-build-instructions[generic build instructions], starting with step 1.
|
||
|
||
[[macos]]
|
||
== macOS
|
||
|
||
In addition to needing Xcode (along with the command line tools), developing in the macOS environment requires extra dependencies.
|
||
You can install these dependencies through http://www.macports.org[MacPorts] or http://mxcl.github.com/homebrew/[Homebrew].
|
||
These dependencies are required only on the build machine, because non-standard libs are deployed in the app bundle.
|
||
|
||
The tested and preferred way to develop in this environment is through the use of http://mxcl.github.com/homebrew/[HomeBrew].
|
||
The ownCloud team has its own repository containing non-standard recipes.
|
||
To set up your build environment for development using http://mxcl.github.com/homebrew/[HomeBrew]:
|
||
|
||
. Install https://developer.apple.com/xcode[Xcode].
|
||
. Install Xcode command line tools using `xcode-select –install`.
|
||
. Install Homebrew using `/usr/bin/ruby -e $(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)`.
|
||
. Add the ownCloud repository using the command `brew tap owncloud/owncloud`
|
||
. Install a Qt5 version, ideally from from 5.10.1, using the command `brew install qt5`.
|
||
. Install any missing dependencies, using the command: `brew install $(brew deps owncloud-client)`.
|
||
. Install qtkeychain by running `git clone https://github.com/frankosterfeld/qtkeychain.git`.
|
||
Make sure you make the same install prefix as later while building the client
|
||
e.g., `-DCMAKE_INSTALL_PREFIX=/Path/to/client/../install`.
|
||
. For compilation of the client, follow the xref:generic-build-instructions[generic build instructions].
|
||
. Install the http://s.sudre.free.fr/Software/Packages/about.html[Packages] package creation tool.
|
||
. In the build directory, run `admin/osx/create_mac.sh <CMAKE_INSTALL_DIR> <build dir> <installer sign identity>`. If you have a developer signing certificate, you can specify its Common Name as a third parameter (use quotes) to have the package signed automatically.
|
||
+
|
||
[NOTE]
|
||
====
|
||
Contrary to earlier versions, version 1.7 and later are packaged as a `pkg` installer.
|
||
Do not call `make package` at any time when compiling for OS X, as this will build a disk image, which will not work correctly.
|
||
====
|
||
|
||
== Windows Development Build with KDE Craft
|
||
|
||
If you want to test some changes, you can build the ownCloud Client natively on Windows using {kde-craft-url}[KDE Craft].
|
||
You can also use it to build unsupported and unoptimized installers.
|
||
|
||
=== Install KDE Craft
|
||
|
||
To install KDE Craft, {python-2_7-url}[Python 2.7] or {python-3_6-url}[Python 3.6+], and {install-powershell-url}[PowerShell 5.0+] must be installed.
|
||
You can find the full installation guide in the {kde-craft-build-from-source-url}[KDE Community Wiki].
|
||
|
||
TIP: If you want to use Microsoft Visual Studio, naturally, that must be installed as well.
|
||
|
||
When the dependencies are installed, install KDE Craft using the following lines in PowerShell:
|
||
|
||
[source,powershell]
|
||
....
|
||
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
|
||
iex ((new-object net.webclient).DownloadString('https://raw.githubusercontent.com/KDE/craft/master/setup/install_craft.ps1'))
|
||
....
|
||
|
||
The first command allows running scripts from remote sources.
|
||
The second command starts installing KDE Craft.
|
||
You are asked where you want to put the main folder, called `CraftRoot`, which will contain all source, build, and install folders.
|
||
Please chose a disk with sufficient free space.
|
||
|
||
Last but not least, you need to chose the compiler you want to use.
|
||
The official builds only supports {ms-visual-studio-2017-url}[Microsoft Visual Studio 2017].
|
||
However, if you're feeling adventurous, you can also try to use {mingw-w64-url}[Mingw-w64].
|
||
In contrast to Visual Studio, which you need to install in advance, KDE Craft can install `Mingw-w64` for you.
|
||
|
||
TIP: Unless you need 32bit builds, you should stick to the default of x64 builds.
|
||
|
||
=== Setup KDE Craft
|
||
|
||
After you install KDE Craft, there are two steps left before the ownCloud Client can be compiled.
|
||
These are:
|
||
|
||
. xref:launch-the-kde-craft-environment[Launch the KDE Craft Environment]
|
||
. xref:build-the-client[Build the Client]
|
||
|
||
==== Launch the KDE Craft Environment
|
||
|
||
To launch the KDE Craft environment, you need to run the following command in PowerShell.
|
||
This provides you with a shell with all the environment variables set that you need to work with KDE Craft.
|
||
|
||
[source,powershell]
|
||
....
|
||
C:\CraftRoot\craft\craftenv.ps1
|
||
....
|
||
|
||
TIP: This needs to be done every time you want to work with Craft.
|
||
|
||
NOTE: We're assuming that you installed KDE Craft in the default path of `C:\CraftRoot`.
|
||
If you have installed it somewhere else, please adjust the path as necessary.
|
||
|
||
==== Setup the ownCloud repository
|
||
|
||
The last step before we can begin, is adding the ownCloud repository.
|
||
It provides you with additional dependencies and tools, which are not available from the standard KDE repository.
|
||
|
||
[source,powershell]
|
||
....
|
||
craft --add-blueprint-repository https://github.com/owncloud/craft-blueprints-owncloud.git
|
||
....
|
||
|
||
TIP: You only need to do this once.
|
||
|
||
==== Build The Client
|
||
|
||
Finally we can build the client with the following command:
|
||
|
||
[source,powershell]
|
||
....
|
||
craft owncloud-client
|
||
....
|
||
|
||
This installs all required dependencies and builds the ownCloud Client from the `master` git branch.
|
||
If you want to build a different branch, first install all dependencies and then clone the source code from git, like this:
|
||
|
||
[source,powershell]
|
||
....
|
||
craft --install-deps owncloud-client
|
||
craft --fetch owncloud-client
|
||
....
|
||
|
||
You can find the git checkout in `C:\CraftRoot\downloads\git\owncloud\owncloud-client`.
|
||
There you can use the usual git commands to switch branches and remotes, e.g., to build the `2.5` stable branch:
|
||
|
||
[source,powershell]
|
||
....
|
||
git checkout 2.5
|
||
....
|
||
|
||
Afterwards you can build the client like this:
|
||
|
||
[source,powershell]
|
||
....
|
||
craft --configure --make --install
|
||
....
|
||
|
||
==== Run the Client
|
||
|
||
Neither `craft owncloud-client` nor `craft --configure --make --install` make the ownCloud Client available in your PATH, they only install to the so-called image directory.
|
||
This is so KDE Craft knows which files belong to which package.
|
||
In order to run the client, you first need to merge the image directory to the regular KDE Craft root (`C:\CraftRoot`).
|
||
Afterwards, you can run `owncloud.exe` from your shell.
|
||
|
||
```
|
||
craft --qmerge owncloud-client
|
||
owncloud.exe
|
||
```
|
||
|
||
==== Package the Client (Unsupported)
|
||
|
||
Although this is not officially supported, it is, generally, possible to build an installer with:
|
||
|
||
[source,powershell]
|
||
....
|
||
craft nsis
|
||
craft --package owncloud-client
|
||
....
|
||
|
||
Now you should have a file called: `owncloud-client-master-${COMMIT_HASH}-windows-${COMPILER}.exe` in `C:\CraftRoot\tmp`.
|
||
|
||
[NOTE]
|
||
====
|
||
This is not supported, optimised, nor regularly tested!
|
||
Fully supported Windows installers are currently only provided by xref:compiling-via-ownbrander[ownBrander].
|
||
====
|
||
|
||
[[windows-development-build-mingw]]
|
||
== Windows Development Build MinGW without KDE Craft
|
||
|
||
If you don't want to use KDE Craft, these are the manual steps you need to follow to compile the ownCloud Client natively on Windows.
|
||
|
||
. Install the required dependencies
|
||
|
||
* Make sure that you have {cmake-url}[CMake] and {git-url}[Git].
|
||
* Download the {qt-download-url}[Qt] MinGW package. You will use the MinGW version bundled with it.
|
||
* Download an {openssl-windows-build-url}[OpenSSL Windows Build] (the non-'Light' version)
|
||
. Get the {qtkeychain-url}[QtKeychain] sources as well as the latest versions of the ownCloud client from Git as follows:
|
||
+
|
||
....
|
||
git clone https://github.com/frankosterfeld/qtkeychain.git
|
||
git clone git://github.com/owncloud/client.git
|
||
....
|
||
|
||
[start=3]
|
||
. Open the Qt MinGW shortcut console from the Start Menu
|
||
. Make sure that OpenSSL’s `bin` directory as well as your QtKeychain source directories are in your PATH.
|
||
This will allow CMake to find the library and headers, as well as allow the ownCloud client to find the DLLs at runtime:
|
||
+
|
||
[source,console]
|
||
....
|
||
set PATH=C:\<OpenSSL Install Dir>\bin;%PATH%
|
||
set PATH=C:\<qtkeychain Clone Dir>;%PATH%
|
||
....
|
||
|
||
[start=5]
|
||
. Build QtKeychain *directly in the source directory* so that the DLL is built in the same directory as the headers to let CMake find them together through PATH:
|
||
+
|
||
[source,console]
|
||
....
|
||
cd <qtkeychain Clone Dir>
|
||
cmake -G "MinGW Makefiles" .
|
||
mingw32-make
|
||
cd ..
|
||
....
|
||
|
||
[start=6]
|
||
. Create the build directory:
|
||
+
|
||
[source,console]
|
||
....
|
||
mkdir client-build
|
||
cd client-build
|
||
....
|
||
|
||
[start=7]
|
||
. Build the client:
|
||
+
|
||
[source,console]
|
||
....
|
||
cmake -G "MinGW Makefiles" ../client
|
||
mingw32-make
|
||
....
|
||
+
|
||
You can try using ninja to build in parallel using `cmake -G Ninja ../client` and `ninja` instead.
|
||
Refer to the xref:generic-build-instructions[generic build instructions] section for additional options.
|
||
The ownCloud binary will appear in the `bin` directory.
|
||
|
||
[[windows-installer-build-cross-compile]]
|
||
== Windows Installer Build (Cross-Compile, deprecated)
|
||
|
||
You can set up any currently supported version of openSUSE in a virtual machine if you do not have it installed already.
|
||
In order to make setup simple, you can use the provided Dockerfile to build your own image.
|
||
|
||
. Assuming you are in the root of the ownCloud Client’s source tree, you can build an image from this Dockerfile like this:
|
||
+
|
||
[source,console]
|
||
....
|
||
cd admin/win/docker
|
||
docker build . -t owncloud-client-win32:<version>
|
||
....
|
||
+
|
||
Replace `<version>` by the version of the client you are building, e.g., for the release of the client that this document describes.
|
||
If you do not wish to use docker, you can run the commands in `RUN` manually in a shell, e.g., to create your own build environment in a virtual machine.
|
||
+
|
||
Docker images are specific to releases.
|
||
Newer releases may have different dependencies, and thus require a later version of the docker image!
|
||
Always pick the docker image fitting your release of ownCloud client!
|
||
|
||
|
||
[start=2]
|
||
. From within the source tree Run the docker instance:
|
||
+
|
||
[source,console]
|
||
....
|
||
docker run -v "$PWD:/home/user/client" owncloud-client-win32:<version> \
|
||
/home/user/client/admin/win/docker/build.sh client/ $(id -u)
|
||
....
|
||
+
|
||
It will run the build, create an NSIS based installer, as well as run tests.
|
||
You will find the resulting binary in an newly created `build-win32` subfolder.
|
||
+
|
||
If you do not wish to use docker, and ran the `RUN` commands above in a virtual machine, you can run the indented commands in the lower section of `build.sh` manually in your source tree.
|
||
|
||
[start=3]
|
||
. Finally, you should sign the installer to avoid warnings upon installation. This requires a https://msdn.microsoft.com/en-us/library/ie/ms537361%28v=vs.85%29.aspx[Microsoft Authenticode] Certificate `osslsigncode` to sign the installer:
|
||
+
|
||
[source,console]
|
||
....
|
||
osslsigncode -pkcs12 $HOME/.codesign/packages.pfx -h sha256 \
|
||
-pass yourpass \
|
||
-n "ACME Client" \
|
||
-i "http://acme.com" \
|
||
-ts "http://timestamp.server/" \
|
||
-in ${unsigned_file} \
|
||
-out ${installer_file}
|
||
....
|
||
+
|
||
For `-in`, use the URL to the time stamping server provided by your CA along with the Authenticode certificate. Alternatively, you may use the official Microsoft `signtool` utility on Microsoft Windows.
|
||
|
||
TIP: If you’re familiar with Docker, you can use the version of `osslsigncode` that is part of the docker image.
|
||
|
||
[[generic-build-instructions]]
|
||
== Generic Build Instructions
|
||
|
||
To build the most up-to-date version of the client:
|
||
|
||
. Clone the latest versions of the client from http://git-scm.com[Git] as follows:
|
||
+
|
||
[source,console]
|
||
....
|
||
git clone git://github.com/owncloud/client.git
|
||
cd client
|
||
# master this default, but you can also check out a tag like v2.4.1
|
||
git checkout master
|
||
git submodule init
|
||
git submodule update
|
||
....
|
||
|
||
[start=2]
|
||
. Create the build directory:
|
||
+
|
||
[source,console]
|
||
....
|
||
mkdir client-build
|
||
cd client-build
|
||
....
|
||
|
||
[start=3]
|
||
. Configure the client build:
|
||
+
|
||
[source,console]
|
||
....
|
||
cmake -DCMAKE_PREFIX_PATH=/opt/ownCloud/qt-5.10.1 -DCMAKE_INSTALL_PREFIX=/Users/path/to/client/../install/ ..
|
||
....
|
||
+
|
||
For Linux builds (using QT5 libraries via build-dep) a typical setting is `-DCMAKE_PREFIX_PATH=/opt/ownCloud/qt-5.10.1/`. However, the version number may vary.
|
||
For Linux builds using system dependencies `-DCMAKE_PREFIX_PATH` is not needed.
|
||
You must use absolute paths for the `include` and `library` directories.
|
||
+
|
||
On Mac OS X, you need to specify `-DCMAKE_INSTALL_PREFIX=target`, where `target` is a private location, i.e. in parallel to your build dir by specifying `../install`.
|
||
+
|
||
qtkeychain must be compiled with the same prefix e.g., `-DCMAKE_INSTALL_PREFIX=/Users/path/to/client/../install/`.
|
||
|
||
[start=4]
|
||
. Call `make`. The ownCloud binary will appear in the `bin` directory.
|
||
|
||
[start=5]
|
||
. (Optional) Call `make install` to install the client to the `/usr/local/bin` directory. +
|
||
The following are known CMake parameters:
|
||
|
||
* `QTKEYCHAIN_LIBRARY=/path/to/qtkeychain.dylib -DQTKEYCHAIN_INCLUDE_DIR=/path/to/qtkeychain/`
|
||
Used for stored credentials. When compiling with Qt5, the library is
|
||
called `qt5keychain.dylib.` You need to compile QtKeychain with the
|
||
same Qt version. If you install QtKeychain into the CMAKE_PREFIX_PATH
|
||
then you don’t need to specify the path manually.
|
||
* `WITH_DOC=TRUE`: Creates doc and man pages through running `make`; also adds install statements, providing the ability to install using `make install`.
|
||
* `CMAKE_PREFIX_PATH=/path/to/Qt5.10.1/5.10.1/yourarch/lib/cmake/`: Builds using that Qt version.
|
||
* `CMAKE_INSTALL_PREFIX=path`: Set an install prefix. This is mandatory on Mac OS.
|