nextcloud-desktop/doc/building.rst
Dimitri Papadopoulos 9d830e94f9 Fix typos found by codespell
Signed-off-by: Dimitri Papadopoulos <3234522+DimitriPapadopoulos@users.noreply.github.com>
2023-06-21 08:47:13 +02:00

417 lines
16 KiB
ReStructuredText
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

.. _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