khanh.pndc/nextcloud-docs
1
0
Fork 0
mirror of https://github.com/nextcloud/documentation.git synced 2025-12-12 07:29:47 +07:00
Code Issues Packages Projects Releases Wiki Activity

Desktop developer docu (#12551)

Browse Source 
Signed-off-by: Rello <Rello@users.noreply.github.com>
This commit is contained in:
Rello
2025-01-30 13:41:48 +01:00
committed by GitHub
parent 582f2a94bb
commit e3250cebcb
9 changed files with 488 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files

13
admin_manual/desktop/index.rst
View File

@@ -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

446
developer_manual/desktop/building.rst Normal file
View File

@@ -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 <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 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 <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
-------------------------
System requirements
^^^^^^^^^^^^^^^^^^^
- Windows 10 or Windows 11
- `The desktop client code <https://github.com/nextcloud/desktop>`_
- Python 3
- PowerShell
- Microsoft Visual Studio 2022 and tools to compile C++
- `KDE Craft <https://community.kde.org/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 <https://community.kde.org/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 <https://community.kde.org/Get_Involved/development/Windows>`_ - it requires Python 3 and PowerShell.
2. After running:
.. code-block:: winbatch
C:\CraftRoot\craft\craftenv.ps1
3. Add the `desktop client blueprints <https://github.com/nextcloud/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 <desktop-repo-path>
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 <https://doc.qt.io/qtcreator>`_ 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:<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/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 <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

BIN
developer_manual/desktop/images/desktop-development-with-cpp.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 10 KiB

BIN
developer_manual/desktop/images/path.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 15 KiB

BIN
developer_manual/desktop/images/visual-studio-installer.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 16 KiB

25
developer_manual/desktop/index.rst Normal file
View File

@@ -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

1
developer_manual/index.rst
View File

@@ -25,3 +25,4 @@ Table of contents
design/index
html_css_design/index
client_apis/index
desktop/index

1
index.html
View File

@@ -277,6 +277,7 @@
<ul class="simple">
<li><a class="reference external" href="https://docs.nextcloud.com/server/latest/user_manual/en/desktop/index.html">User Manual</a>
<li><a class="reference external" href="https://docs.nextcloud.com/server/latest/admin_manual/desktop/index.html">Administration Manual</a>
<li><a class="reference external" href="https://docs.nextcloud.com/server/latest/developer_manual/desktop/index.html">Developer Manual</a>
</ul>
</div> <!-- desktop -->

8
user_manual/desktop/index.rst
View File

@@ -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