mirror of https://github.com/nextcloud/desktop
418 lines
16 KiB
ReStructuredText
418 lines
16 KiB
ReStructuredText
.. _building-label:
|
||
|
||
===============================
|
||
Appendix A: Building the Client
|
||
===============================
|
||
|
||
The goal of this section is to set up a build environment for developing
|
||
and testing the Nextcloud Desktop client. If you just want to use the
|
||
Nextcloud Desktop client without developing and testing it, you should
|
||
download the latest stable build instead.
|
||
|
||
.. note:: These instructions represent a particular streamlined and easy-to-understand
|
||
methodology, but they are by no means the only way of setting up a build
|
||
environment.
|
||
|
||
The steps listed here have been tested multiple times and should allow you
|
||
to build the client and/or the documentation with not warnings or errors.
|
||
These instructions should be current with the version, |version|, of the
|
||
Nextcloud Client with which it ships. If you are using the most recent version
|
||
of these instructions, and you run into errors or warnings with the latest
|
||
code from the repository, please open a GitHub Issue to let us know so we can
|
||
document a workaround or fix any underlying problems.
|
||
|
||
|
||
Using GitHub
|
||
------------
|
||
|
||
By default, cloning the GitHub repository will give you the "master" branch,
|
||
which is the most recent. If for some reason you want to build an older
|
||
version of the Nextcloud Desktop client, you can choose a branch corresponding
|
||
with that version. However, for older versions of the client, please be mindful
|
||
that any issues present may have been fixed in more recent versions.
|
||
|
||
.. note:: Doing anything other than just downloading the existing code will
|
||
require you to have a GitHub account.
|
||
|
||
If your goal in cloning and building the Nextcloud Desktop client is to
|
||
contribute to its development, and you are not already a "collaborator"
|
||
on the Nextcloud Desktop GitHub repository, you will need to create a "fork"
|
||
by clicking the "fork" button in the upper right on any GitHub page in the
|
||
repository. It is important to do this in advance because the URL for cloning
|
||
the repository is different for a fork than for the main official version.
|
||
|
||
When cloning a GitHub repository, you have two options for authenticating your
|
||
GitHub account, SSH or HTTPS. SSH requires additional setup but is more secure
|
||
and simplifies things later on. For an explanation of the differences between
|
||
HTTPS and SSH, as well as instructions to set up SSH, see this `GitHub
|
||
help article`_ on the subject.
|
||
|
||
.. _`GitHub help article`: https://help.github.com/en/articles/which-remote-url-should-i-use
|
||
|
||
The most basic version of the Git command for cloning a repository is as follows:
|
||
|
||
.. code-block:: bash
|
||
|
||
$ git clone <repository_url>
|
||
|
||
Which will clone the repository into the directory where you run the command.
|
||
|
||
The four versions of the ``git clone`` command are as follows:
|
||
|
||
1. HTTPS from the official repository:
|
||
|
||
.. code-block:: bash
|
||
|
||
$ git clone https://github.com/nextcloud/desktop.git
|
||
|
||
2. SSH from the official repository:
|
||
|
||
.. code-block:: bash
|
||
|
||
$ git clone git@github.com:nextcloud/desktop.git
|
||
|
||
3. HTTPS from a fork (see above):
|
||
|
||
.. code-block:: bash
|
||
|
||
% git clone https://github.com/<github_username>/desktop.git
|
||
|
||
4. SSH from a fork (see above):
|
||
|
||
.. code-block:: bash
|
||
|
||
% git clone git@github.com:<github_username>/desktop.git
|
||
|
||
macOS Development Build
|
||
-----------------------
|
||
|
||
.. note:: While it is possible to do many of the following steps using GUI
|
||
frontends, wherever possible the Terminal commands are listed instead, in order
|
||
to streamline the process.
|
||
|
||
1. Install Xcode from the Mac App Store:
|
||
|
||
https://apps.apple.com/app/xcode/id497799835
|
||
|
||
Then, in Terminal:
|
||
|
||
2. Install Xcode command line tools:
|
||
|
||
.. code-block:: bash
|
||
|
||
% xcode-select –install
|
||
|
||
3. Install Homebrew from `brew.sh`_ (which will just give you the following):
|
||
|
||
.. _`brew.sh`: https://brew.sh
|
||
|
||
.. code-block:: bash
|
||
|
||
% /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
|
||
|
||
.. note:: Under certain circumstances, you may get on error along the
|
||
lines of ``Permission denied @ apply2files`` when installing certain
|
||
Homebrew packages. This is `a known issue`_ and can be fixed by changing
|
||
the permissions on the affected files with the following command:
|
||
|
||
.. code-block:: bash
|
||
|
||
% sudo chown -R $(whoami):admin /usr/local/* \
|
||
&& sudo chmod -R g+rwx /usr/local/*
|
||
|
||
This workaround may lead to other shell warnings.
|
||
|
||
.. _`a known issue`: https://stackoverflow.com/a/63241724
|
||
|
||
4. Install Homebrew packages:
|
||
|
||
.. code-block:: bash
|
||
|
||
% brew install git qt qtkeychain cmake openssl glib cmocka
|
||
|
||
5. Certain Homebrew packages are not automatically linked in places where
|
||
the build scripts can find them, so you can create a shell-profile script
|
||
that will find and load them dynamically when you run a build:
|
||
|
||
.. code-block:: bash
|
||
|
||
% echo 'export OPENSSL_ROOT_DIR=$(brew --prefix openssl)' >> ~/.nextcloud_build_variables
|
||
% echo 'export QT_PATH=$(brew --prefix qt5)/bin' >> ~/.nextcloud_build_variables
|
||
% echo 'export Qt5LinguistTools_DIR=$(brew --prefix qt5)/lib/cmake/Qt5LinguistTools/' >> ~/.nextcloud_build_variables
|
||
|
||
.. note:: The name ``~/.nextcloud_build_variables`` is just a suggestion for
|
||
convenience. You can use a different file or create an entire shell
|
||
script, but this way of doing things is the simplest to explain.
|
||
|
||
6. Clone the Nextcloud repository to a convenient location, such as ``~/Repositories``:
|
||
|
||
.. code-block:: bash
|
||
|
||
% mkdir ~/Repositories
|
||
|
||
(if it doesn't already exist), then:
|
||
|
||
.. code-block:: bash
|
||
|
||
% cd ~/Repositories
|
||
|
||
.. note:: The cloned repository can go basically anywhere your user account
|
||
has write access, though it should not go in a directory synced with another
|
||
cloud service (especially not iCloud Drive). ``~/Repositories`` is recommended
|
||
for tidiness and consistency.
|
||
|
||
.. code-block:: bash
|
||
|
||
% git clone <repository_url>
|
||
|
||
(See the above section on using GitHub for an explanation of what URL to use.)
|
||
|
||
7. Create build directory:
|
||
|
||
.. code-block:: bash
|
||
|
||
% cd ~/Repositories/desktop
|
||
% mkdir build
|
||
|
||
8. Generate the build files:
|
||
|
||
.. note::
|
||
|
||
By default Nextcloud Desktop will build in a protected directory on macOS,
|
||
so you need to specify a build location. You can do this every time you build,
|
||
or you can add it to your save build variables, like so:
|
||
|
||
.. code-block:: bash
|
||
|
||
% echo 'export CMAKE_INSTALL_PREFIX=~/Builds' >> ~/.nextcloud_build_variables
|
||
# If you want to build a macOS app bundle for distribution
|
||
% echo 'export BUILD_OWNCLOUD_OSX_BUNDLE=ON' >> ~/.nextcloud_build_variables
|
||
|
||
Replace ``~/Builds`` with a different directory if you'd like the build to end up elsewhere.
|
||
|
||
..
|
||
|
||
.. code-block:: bash
|
||
|
||
% source ~/.nextcloud_build_variables
|
||
% cd ~/Repositories/desktop/build
|
||
% cmake ..
|
||
|
||
9. Compile and install:
|
||
|
||
.. code-block:: bash
|
||
|
||
% make install
|
||
|
||
Windows Development Build
|
||
-------------------------
|
||
|
||
If you want to test some changes and deploy them locally, you can build natively
|
||
on Windows using MinGW. If you want to generate an installer for deployment, please
|
||
follow `Windows Installer Build (Cross-Compile)`_ instead.
|
||
|
||
1. Get the required dependencies:
|
||
|
||
* Make sure that you have CMake_ and Git_.
|
||
* Download the Qt_ MinGW package. You will use the MinGW version bundled with it.
|
||
* Download an `OpenSSL Windows Build`_ (the non-"Light" version)
|
||
|
||
2. Get the QtKeychain_ sources as well as the latest versions of the Nextcloud client
|
||
from Git as follows
|
||
|
||
.. code-block:: bash
|
||
|
||
git clone https://github.com/frankosterfeld/qtkeychain.git
|
||
git clone git://github.com/nextcloud/client.git
|
||
|
||
3. Open the Qt MinGW shortcut console from the Start Menu
|
||
|
||
4. 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 Nextcloud client to find the DLLs at runtime::
|
||
|
||
set PATH=C:\<OpenSSL Install Dir>\bin;%PATH%
|
||
set PATH=C:\<qtkeychain Clone Dir>;%PATH%
|
||
|
||
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::
|
||
|
||
cd <qtkeychain Clone Dir>
|
||
cmake -G "MinGW Makefiles" .
|
||
mingw32-make
|
||
cd ..
|
||
|
||
6. Create the build directory::
|
||
|
||
mkdir client-build
|
||
cd client-build
|
||
|
||
7. Build the client::
|
||
|
||
cmake -G "MinGW Makefiles" ../client
|
||
mingw32-make
|
||
|
||
.. note:: You can try using ninja to build in parallel using
|
||
``cmake -G Ninja ../client`` and ``ninja`` instead.
|
||
.. note:: Refer to the :ref:`generic-build-instructions` section for additional options.
|
||
|
||
The Nextcloud binary will appear in the ``bin`` directory.
|
||
|
||
.. _`Windows Installer Build (Cross-Compile)`:
|
||
|
||
Windows Installer (i.e. Deployment) Build (Cross-Compile)
|
||
---------------------------------------------------------
|
||
|
||
Due to the large number of dependencies, building the client installer for Windows
|
||
is **currently only officially supported on openSUSE**, by using the MinGW cross compiler.
|
||
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.
|
||
|
||
1. Assuming you are in the root of the Nextcloud Client's source tree, you can
|
||
build an image from this Dockerfile like this::
|
||
|
||
cd admin/win/docker
|
||
docker build . -t nextcloud-client-win32:<version>
|
||
|
||
Replace ``<version>`` by the version of the client you are building, e.g.
|
||
|version| 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.
|
||
|
||
.. note:: Docker images are specific to releases. This one refers to |version|.
|
||
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 Nextcloud client!
|
||
|
||
2. From within the source tree Run the docker instance::
|
||
|
||
docker run -v "$PWD:/home/user/client" nextcloud-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.
|
||
|
||
4. Finally, you should sign the installer to avoid warnings upon installation.
|
||
This requires a `Microsoft Authenticode`_ Certificate ``osslsigncode`` to sign the installer::
|
||
|
||
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.
|
||
|
||
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
|
||
--------------------------
|
||
|
||
Compared to previous versions, building the desktop sync client has become easier. Unlike
|
||
earlier versions, CSync, which is the sync engine library of the client, is now
|
||
part of the client source repository and not a separate module.
|
||
|
||
To build the most up-to-date version of the client:
|
||
|
||
1. Clone the latest versions of the client from Git_ as follows:
|
||
|
||
.. code-block:: bash
|
||
|
||
$ git clone git://github.com/nextcloud/client.git
|
||
$ cd client
|
||
$ git submodule update --init
|
||
|
||
2. Create the build directory
|
||
|
||
.. code-block:: bash
|
||
|
||
$ mkdir client-build
|
||
$ cd client-build
|
||
|
||
3. Configure the client build
|
||
|
||
.. code-block:: bash
|
||
|
||
$ cmake -DCMAKE_BUILD_TYPE="Debug" ..
|
||
|
||
.. note:: You must use absolute paths for the ``include`` and ``library``
|
||
directories.
|
||
|
||
.. note:: On macOS, 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``.
|
||
|
||
.. note:: qtkeychain must be compiled with the same prefix e.g ``CMAKE_INSTALL_PREFIX=/Users/path/to/client/install/ .``
|
||
|
||
.. note:: Example:: ``cmake -DCMAKE_PREFIX_PATH=/usr/local/opt/qt5 -DCMAKE_INSTALL_PREFIX=/Users/path/to/client/install/``
|
||
|
||
4. Call ``make``.
|
||
|
||
The Nextcloud binary will appear in the ``bin`` directory.
|
||
|
||
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.
|
||
* ``WITH_DOC=TRUE``: Creates doc and manpages through running ``make``; also adds install statements,
|
||
providing the ability to install using ``make install``.
|
||
* ``CMAKE_PREFIX_PATH=/path/to/Qt5.2.0/5.2.0/yourarch/lib/cmake/``: Builds using Qt5.
|
||
* ``BUILD_WITH_QT4=ON``: Builds using Qt4 (even if Qt5 is found).
|
||
* ``CMAKE_INSTALL_PREFIX=path``: Set an install prefix. This is mandatory on Mac OS
|
||
|
||
Address Sanitizer
|
||
=================
|
||
|
||
You can enable the address sanitizer to detect memory corruptions and other mistakes.
|
||
The are the following sanitizers are available:
|
||
|
||
|
||
* Address Sanitizer
|
||
* Leak anitizer
|
||
* Memory sanitizer
|
||
* Undefined sanitizer
|
||
* Threads sanitizer
|
||
|
||
You can enable one or more sanitizers through CMake. For example, to
|
||
enable the address and the undefined sanitizer, execute CMake like
|
||
``cmake .. -D ECM_ENABLE_SANITIZERS="address;undefined"``.
|
||
Keep in mind that not all combinations of sanitizers work together, and on some
|
||
platforms, not all types of sanitizers are available. For example, on Windows there is
|
||
currently only the address sanitizer available. If you are on Windows, you need to
|
||
make sure that the linker can find the sanitizer dlls at runtime. If you installed
|
||
Visual Studio in the standard location, you could find them in
|
||
**C:/ProgramFiles (x86)/Microsoft Visual Studio/2019/Community/VC/Tools/Llvm/x64/lib/clang/10.0.0/lib/windows**.
|
||
Make sure you add this location to your path. You may also need to
|
||
`upgrade your Visual Studio version <https://docs.microsoft.com/en-us/cpp/sanitizers/asan?view=msvc-160#install-the-addresssanitizer>`_.
|
||
|
||
.. note:: If you use Visual Studio on Windows, you can enable the
|
||
sanitizer if you click on **Manage Configurations**, scroll
|
||
down to the section **CMake Command Arguments** and enter then
|
||
``-D ECM_ENABLE_SANITIZERS="address"`` in the text input field below.
|
||
After that, click on **Save and generate CMake cache to load variables**
|
||
right above the table.
|
||
|
||
.. _CMake: http://www.cmake.org/download
|
||
.. _CSync: http://www.csync.org
|
||
.. _Client Download Page: https://nextcloud.com/install/#install-clients
|
||
.. _Git: http://git-scm.com
|
||
.. _OpenSSL Windows Build: http://slproweb.com/products/Win32OpenSSL.html
|
||
.. _Qt: http://www.qt.io/download
|
||
.. _Microsoft Authenticode: https://msdn.microsoft.com/en-us/library/ie/ms537361%28v=vs.85%29.aspx
|
||
.. _QtKeychain: https://github.com/frankosterfeld/qtkeychain
|