Build from Source Code
======================

This page describes how to build the application from source code.

Get the Source Code
-------------------

Download the source code from git repository

::

    git clone https://github.com/hluk/CopyQ.git

or download the latest source code archive from:

- `latest release <https://github.com/hluk/CopyQ/releases>`__
- `master branch in zip <https://github.com/hluk/CopyQ/archive/master.zip>`__
- `master branch in tar.gz <https://github.com/hluk/CopyQ/archive/master.tar.gz>`__

Install Dependencies
--------------------

The build requires:

- `CMake <https://cmake.org/download/>`__
- `Qt <https://download.qt.io/archive/qt/>`__

Optional (enabled by default, disable with the corresponding CMake option):

- `QCA <https://invent.kde.org/libraries/qca>`__ (Qt Cryptographic
  Architecture) -- for tab encryption (``-DWITH_QCA_ENCRYPTION=OFF`` to
  disable)
- `QtKeychain <https://github.com/frankosterfeld/qtkeychain>`__ -- for storing
  encryption passwords in the system keychain (``-DWITH_KEYCHAIN=OFF`` to
  disable)
- `KNotifications <https://invent.kde.org/frameworks/knotifications>`__ -- for
  native notifications (``-DWITH_NATIVE_NOTIFICATIONS=OFF`` to disable)
- `miniaudio <https://miniaud.io/>`__ -- for built-in audio playback
  (``playSound``) (``-DWITH_AUDIO=OFF`` to disable)

Conditional:

- `ECM <https://invent.kde.org/frameworks/extra-cmake-modules>`__ (Extra CMake
  Modules) -- for native notifications and Wayland clipboard support
- `KGuiAddons <https://invent.kde.org/frameworks/kguiaddons>`__ -- for Wayland
  clipboard support

Debian / Ubuntu
^^^^^^^^^^^^^^^
On **Debian** and derivatives you can install all build dependencies with:

::

    sudo apt install \
      build-essential \
      cmake \
      extra-cmake-modules \
      git \
      libminiaudio-dev \
      libqt6svg6-dev \
      libqt6waylandclient6 \
      libwayland-dev \
      libxfixes-dev \
      libxtst-dev \
      qt6-base-dev \
      qt6-base-dev-tools \
      qt6-base-private-dev \
      qt6-declarative-dev \
      qt6-l10n-tools \
      qt6-tools-dev \
      qt6-tools-dev-tools \
      qt6-wayland \
      qt6-wayland-dev \
      qt6-wayland-dev-tools \
      qtkeychain-qt6-dev


On Debian 13 or Ubuntu 24.04 and newer, you can also install `QCA` packages:

::

    sudo apt install \
      libqca-qt6-dev \
      libqca-qt6-plugins

On Debian 13 or Ubuntu 25.04 and newer, you can also install `KF6` packages:

::

    sudo apt install \
      libkf6guiaddons-dev

Fedora / RHEL / CentOS
^^^^^^^^^^^^^^^^^^^^^^
On **Fedora** and derivatives you can install all build dependencies with:

::

    sudo dnf install \
      cmake \
      extra-cmake-modules \
      gcc-c++ \
      git \
      kf6-kguiaddons-devel \
      kf6-knotifications-devel \
      kf6-kstatusnotifieritem-devel \
      libSM-devel \
      libXfixes-devel \
      libXtst-devel \
      miniaudio-devel \
      qca-qt6-devel \
      qca-qt6-ossl \
      qt6-qtbase-devel \
      qt6-qtbase-private-devel \
      qt6-qtdeclarative-devel \
      qt6-qtsvg-devel \
      qt6-qttools-devel \
      qt6-qtwayland-devel \
      qtkeychain-qt6-devel \
      wayland-devel

miniaudio (manual download)
^^^^^^^^^^^^^^^^^^^^^^^^^^

If your distribution does not package miniaudio, you can download the single
header file directly into the source tree:

::

    curl -sSLo src/miniaudio.h \
      https://raw.githubusercontent.com/mackron/miniaudio/0.11.25/miniaudio.h

CMake will find it automatically.  Alternatively, place ``miniaudio.h`` anywhere
and point CMake to it with ``-DMINIAUDIO_INCLUDE_DIR=/path/to/dir``.


Build and Install
-----------------

Build the source code with CMake and make or using an IDE of your choice (see next sections).

::

    cd CopyQ
    cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/usr/local .
    # Add -DWITH_QCA_ENCRYPTION=OFF for systems without `QCA` packages
    # Add -DWITH_NATIVE_NOTIFICATIONS=OFF for systems without `KF6` packages
    # Add -DWITH_AUDIO=OFF to disable audio support (or if miniaudio is unavailable)
    make
    make install

Qt Creator
----------

Qt Creator is IDE focused on developing C++ and Qt applications.

Install Qt Creator from your package manager or by selecting it from Qt installation utility.

Set up Qt library, C++ compiler and CMake.

.. seealso::

    `Adding Kits <https://doc.qt.io/qtcreator/creator-targets.html>`__

Open file ``CMakeLists.txt`` in repository clone to create new project.

Visual Studio
-------------

You need to install Qt for given version Visual Studio.

In Visual Studio 2017 open folder containing repository clone using "File - Open - Folder".

In older versions, create solution manually by running ``cmake -G "Visual Studio 14 2015 Win64" .``
(select appropriate generator name) in repository clone folder.

.. seealso::

    `CMake - Visual Studio Generators <https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html#visual-studio-generators>`__

Building and Packaging for OS X
-------------------------------

On OS X, required Qt 6 libraries and utilities can be easily installed with `Homebrew <https://brew.sh/>`__.

::

    cd CopyQ
    git -C "utils/github/homebrew" init .
    git -C "utils/github/homebrew" add .
    git -C "utils/github/homebrew" commit -m "Initial"

    brew tap copyq/kde utils/github/homebrew/
    # if the above "brew tap" command produces an error like
    #     "Error: Tap copyq/kde remote mismatch"
    # then run
    #     brew untap --force copyq/kde
    # and re-run the above "brew tap" command

    brew install qt6 copyq/kde/kf6-knotifications copyq/kde/kf6-kstatusnotifieritem

Build with the following commands:

::

    cmake -DCMAKE_PREFIX_PATH="$(brew --prefix qt6)" .
    cmake --build .
    cpack

This will produce a self-contained application bundle ``CopyQ.app``
which can then be copied or moved into ``/Applications``.

NOTE: If no Items are shown when you start CopyQ and open "File - Preferences - Items",
then your CopyQ plugins were not installed. If you saw warning messages like this::

     /<some_path>/install_name_tool: warning: changes being made to the file will invalidate the code signature in: /<some_path>/CopyQ/_CPack_Packages/Darwin/DragNDrop/copyq-6.2.0-Darwin/CopyQ.app/Contents/Plugins/<some_file>.dylib

when you ran the above "cpack" command, then you have likely encountered
`issue 1903 <https://github.com/hluk/CopyQ/issues/1903/>`__.

In that case you may codesign the CopyQ app again using the following command,
un-install the previous CopyQ app, and install the re-signed ``CopyQ.app``::

    codesign --force --deep --sign - $PWD/_CPack_Packages/Darwin/DragNDrop/copyq-*-Darwin/CopyQ.app
