diff --git a/admin_manual/desktop/index.rst b/admin_manual/desktop/index.rst index e6eb0463a..b9a4e213f 100644 --- a/admin_manual/desktop/index.rst +++ b/admin_manual/desktop/index.rst @@ -11,12 +11,6 @@ Desktop Sync client enables you to: Your files are always automatically synchronized between your Nextcloud server, computer and mobile device. -You can find the old documentation here: -* `Nextcloud Desktop Client`_ - -.. _`Nextcloud Desktop Client`: https://docs.nextcloud.com/desktop/latest/ - - .. toctree:: :maxdepth: 1 @@ -28,3 +22,10 @@ You can find the old documentation here: accountcommand troubleshooting +You can find additional information here: + +* `User manual`_ +* `Developer manual`_ + +.. _`User manual`: https://docs.nextcloud.com/server/latest/user_manual/en/desktop/index.html +.. _`Developer manual`: https://docs.nextcloud.com/server/latest/developer_manual/desktop/index.html diff --git a/developer_manual/desktop/building.rst b/developer_manual/desktop/building.rst new file mode 100644 index 000000000..842d79b45 --- /dev/null +++ b/developer_manual/desktop/building.rst @@ -0,0 +1,446 @@ +=================== +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 + +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//desktop.git + +4. SSH from a fork (see above): + + .. code-block:: bash + + % git clone git@github.com:/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 karchive + +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 QT_PATH=$(brew --prefix qt6)/bin' >> ~/.nextcloud_build_variables + % echo 'export CMAKE_PREFIX_PATH=$(brew --prefix qt6);$(brew --prefix karchive)' >> ~/.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 + + (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 +------------------------- + +System requirements +^^^^^^^^^^^^^^^^^^^ + + +- Windows 10 or Windows 11 +- `The desktop client code `_ +- Python 3 +- PowerShell +- Microsoft Visual Studio 2022 and tools to compile C++ +- `KDE Craft `_ + +Setting up Microsoft Visual Studio +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +1. Click on 'Modify' in the Visual Studio Installer: + + .. image:: images/visual-studio-installer.png + :alt: Visual Studio Installer + +2. Select 'Desktop development with C++' + + .. image:: images/desktop-development-with-cpp.png + :alt: Desktop development with C++ + +Handling the dependencies +^^^^^^^^^^^^^^^^^^^^^^^^^ + +We handle the dependencies using `KDE Craft `_ because it is easy to set it up and it makes the maintenance much more reliable in all platforms. + +1. Set up KDE Craft as instructed in `Get Involved/development/Windows - KDE Community Wiki `_ - it requires Python 3 and PowerShell. +2. After running: + +.. code-block:: winbatch + + C:\CraftRoot\craft\craftenv.ps1 + +3. Add the `desktop client blueprints `_ - the instructions to handle the client dependencies: + +.. code-block:: winbatch + + craft --add-blueprint-repository [git]https://github.com/nextcloud/desktop-client-blueprints.git + craft craft + +4. Install all client dependencies: + +.. code-block:: winbatch + + craft --install-deps nextcloud-client + +Compiling +^^^^^^^^^ + +1. Make sure your environment variable %PATH% has no conflicting information to the environment you will use to compile the client. For instance, if you have installed OpenSSL previously and have added it to %PATH%, the OpenSSL installed might be a different version than what was installed via KDE Craft. +2. Open the Command Prompt (cmd.exe) +3. Run: + +.. code-block:: winbatch + + "C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Auxiliary\Build\vcvarsall.bat" x64 + +4. To use the tools installed with Visual Studio, you need the following in your %PATH%: + + .. image:: images/path.png + :alt: Windows environment variables + +5. Alternatively you can use the tools installed with KDE Craft by adding them to %PATH%: + +.. code-block:: winbatch + + set "PATH=C:\CraftRoot\bin;C:\CraftRoot\dev-utils\bin;%PATH%" + +.. note:: + C:\CraftRoot is the path used by default by KDE Craft. When you are setting it up you may choose a different folder. + +6. Create build folder, run cmake, compile and install: + +.. code-block:: winbatch + + cd + mkdir build + cd build + cmake .. -G Ninja -DCMAKE_INSTALL_PREFIX=. -DCMAKE_PREFIX_PATH=C:\CraftRoot -DCMAKE_BUILD_TYPE=RelWithDebInfo + cmake --build . --target install + +7. Now you can use `Qt Creator `_ to import the build folder with its configurations to be able to work with the code. + +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: + + Replace ```` 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: \ + /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/qt6 -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/Qt6/6.7.0/yourarch/lib/cmake/``: Builds using Qt6. +* ``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 `_. + +.. 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 diff --git a/developer_manual/desktop/images/desktop-development-with-cpp.png b/developer_manual/desktop/images/desktop-development-with-cpp.png new file mode 100644 index 000000000..4d4f0d34f Binary files /dev/null and b/developer_manual/desktop/images/desktop-development-with-cpp.png differ diff --git a/developer_manual/desktop/images/path.png b/developer_manual/desktop/images/path.png new file mode 100644 index 000000000..88f028700 Binary files /dev/null and b/developer_manual/desktop/images/path.png differ diff --git a/developer_manual/desktop/images/visual-studio-installer.png b/developer_manual/desktop/images/visual-studio-installer.png new file mode 100644 index 000000000..23f4f7a4d Binary files /dev/null and b/developer_manual/desktop/images/visual-studio-installer.png differ diff --git a/developer_manual/desktop/index.rst b/developer_manual/desktop/index.rst new file mode 100644 index 000000000..38811125f --- /dev/null +++ b/developer_manual/desktop/index.rst @@ -0,0 +1,25 @@ +=============== +Desktop Clients +=============== + +Available for Windows, macOS, and various Linux distributions, the Nextcloud +Desktop Sync client enables you to: + +- Specify one or more directories on your computer that you want to synchronize + to the Nextcloud server. +- Always have the latest files synchronized, wherever they are located. + +This documentation is targeted for developers to build the client on their own. + +.. toctree:: + :maxdepth: 1 + + building + +You can find additional information here: + +* `User manual`_ +* `Admin manual`_ + +.. _`User manual`: https://docs.nextcloud.com/server/latest/user_manual/en/desktop/index.html +.. _`Admin manual`: https://docs.nextcloud.com/server/latest/admin_manual/desktop/index.html diff --git a/developer_manual/index.rst b/developer_manual/index.rst index 2617df81b..f2181312a 100644 --- a/developer_manual/index.rst +++ b/developer_manual/index.rst @@ -25,3 +25,4 @@ Table of contents design/index html_css_design/index client_apis/index + desktop/index diff --git a/index.html b/index.html index c6e7d6b94..5035328d4 100644 --- a/index.html +++ b/index.html @@ -277,6 +277,7 @@ diff --git a/user_manual/desktop/index.rst b/user_manual/desktop/index.rst index 4c53bcea9..3c34a02b3 100644 --- a/user_manual/desktop/index.rst +++ b/user_manual/desktop/index.rst @@ -20,3 +20,11 @@ Your files are always automatically synchronized between your Nextcloud server, autoupdate conflicts faq + +You can find additional information here: + +* `Admin manual`_ +* `Developer manual`_ + +.. _`Admin manual`: https://docs.nextcloud.com/server/latest/admin_manual/desktop/index.html +.. _`Developer manual`: https://docs.nextcloud.com/server/latest/developer_manual/desktop/index.html