KDE Utils/Ark: Difference between revisions

From KDE Community Wiki
(Add a list of the most critical Ark bugs)
(→‎How to contribute to Ark: Documentation moved, see https://invent.kde.org/utilities/ark/-/merge_requests/208)
 
(14 intermediate revisions by 3 users not shown)
Line 1: Line 1:
== Current most critical bugs ==
= How to build Ark on Linux=
* [https://bugs.kde.org/193908 Bug 193908]: There must be a way to tell the worker thread to stop when the GUI is being closed.
* [https://bugs.kde.org/203126 Bug 203126]: Most of the code before app.exec() in main.cpp must be moved elsewhere to be run after the main loop starts. This should fix most event loop bugs related to batchextract.
* [https://bugs.kde.org/204323 Bug 204323]: Support for remote locations must be implemented (shouldn't be too hard).


== Ark Plans ==
== Step 0 - Install build dependencies ==  
=== KDE 4.4 ===
See the [[Schedules/KDE4/4.4_Feature_Plan#kdeutils|feature plan]] for KDE 4.4.


* Add visual feedback for the operations in the status bar
Some distributions allow to install the build-time dependencies of any package with a single command. For example, on Debian or Ubuntu you can just run the following command:
* Add a proper way to display a notice to the user when autosubfolder is enabled in the extraction dialog
* Make single/double-clicking an entry open the file in the default launcher instead of using the internal previewer (which shall become a context menu option)
* proper cancel support and no crash if closed during exctraction
* letting a plugin try to open something and possible fail, basically rework the plugin management
* more GUI means a settings dialog for example. I also would like to share more functionality with dolphin as we discussed once (other view modes etc)
* finish AddDialog
* general code cleanup and api doxyfication


== Personal TODOs ==
<syntaxhighlight lang="bash">
=== Harald ===
sudo apt-get build-dep ark
* Formalize the dbus communication protocol and implement it in dolphin
</syntaxhighlight>
* BUG: After opening file from web, automatic subfolder detection name is confused
 
* BUG: extractiondialog is confused by "/" in subfolder name
If you are running the Plasma desktop, you should have most of these dependencies already installed. Usually one needs to manually install only the <code>extra-cmake-modules</code>.
* Check if we want the two last patches in bug #155220
 
* Revert the single folder label
== Step 1 - Build ark ==
Like most KDE projects, Ark relies on the CMake build-system. This means that compiling Ark is as simple as running the following commands:
 
<syntaxhighlight lang="bash">
mkdir build && cd build
cmake ..
make
</syntaxhighlight>
 
Everything should work fine, provided that you installed all the required build dependencies.
 
{{Note|You can speed-up the compilation by using <code>make -jN</code>, where N is the number of parallel jobs you will run. This number is usually set to the number of CPU cores of your machines. }}
 
== Step 2 - Install ark ==
Once you built Ark, it's time to install it with the <code>make install</code> command. However, by default CMake will use <tt>/usr/local</tt> as install prefix, so you will have to run <code>sudo make install</code>.
 
At this point your should be able to run <tt>/usr/local/bin/ark</tt>. If Ark fails to start with the '''Unable to find Ark's KPart component, please check your installation.''' error, you need to run cmake with the additional <tt>-DKDE_INSTALL_USE_QT_SYS_PATHS=ON</tt> argument:
 
<syntaxhighlight lang="bash">
cmake -DKDE_INSTALL_USE_QT_SYS_PATHS=ON ..
</syntaxhighlight>
 
=== Install to custom location ===
When running cmake, you can set the install prefix to whatever directory you want to install Ark in. For example
<syntaxhighlight lang="bash">
cmake -DCMAKE_INSTALL_PREFIX=/home/foo/whatever -DKDE_INSTALL_LIBDIR=lib ..
</syntaxhighlight>
 
This way you can run <code>make install</code> without having to type the sudo password. However, you will need to set a bunch of environment variables, in order to have everything working:
 
<syntaxhighlight lang="bash">
# Install prefix, replace with any folder you want
export KF5=~/foo/whatever
 
export XDG_DATA_DIRS=$KF5/share:$XDG_DATA_DIRS
export XDG_CONFIG_DIRS=$KF5/etc/xdg:/etc/xdg
export PATH=$KF5/bin:$PATH
export QT_PLUGIN_PATH=$KF5/lib/plugins:$QT_PLUGIN_PATH
</syntaxhighlight>
 
You can wrap the above exports in a bash script, for convenience. Then you just need to source this script before running the usual cmake/make commands.
 
{{Note|The <tt>KDE_INSTALL_LIBDIR</tt> cmake argument is not really necessary. If you don't use it, cmake will install the plugins in a <tt>lib64</tt> folder and you will just need a different <tt>QT_PLUGIN_PATH</tt> variable:
<syntaxhighlight lang="bash">
export QT_PLUGIN_PATH=$KF5/lib64/plugins:$QT_PLUGIN_PATH
</syntaxhighlight> }}
{{Warning | If you want to install Ark in a custom location, do not pass the <tt>KDE_INSTALL_USE_QT_SYS_PATHS</tt> option to cmake. It's not necessary and it conflicts with <tt>CMAKE_INSTALL_PREFIX</tt>.}}
 
== Step 3 - Run the Ark tests ==
Ark's unit tests are built by default (unless you pass <code>-DBUILD_TESTING=OFF</code> to cmake).
Once Ark is built and installed, you should run the tests to check that all of them are passing. You can do so by running the <code>ctest</code> command from the build directory:
 
<syntaxhighlight lang="bash">
ctest --output-on-failure
</syntaxhighlight>
 
 
<!--
TODO
Write a tutorial for an ark-friendly kdesrc-build configuration. Reference: https://community.kde.org/Guidelines_and_HOWTOs/Build_from_source
-->
 
== Build with Clazy ==
Clazy is a useful tool for static-analysis of Qt projects. It is recommended to use it if you use a recent-enough <code>clang</code> compiler. To install clazy, please referer to its README: https://phabricator.kde.org/diffusion/CLAZY/
 
Once you have installed clazy, it is very simple to use it. Just set clang as your C++ compiler and tell cmake to enable clazy:
 
<syntaxhighlight lang="bash">
export CXX=$(which clang++)
cmake -DENABLE_CLAZY=ON ..
</syntaxhighlight>
 
You will see the clazy warnings as soon as you start compiling Ark.
 
== Build with debug symbols ==
 
Debug symbols are useful to debug Ark with GDB. To build Ark with debug symbols enabled, just pass the <code>-DCMAKE_BUILD_TYPE=Debug</code> option to cmake.
This will also make Ark crash if a <code>Q_ASSERT</code> fails to validate at runtime. So it is highly recommended to enable this option while hacking on Ark.
 
== Enable debug output ==
The Ark debug output is useful to understand what's going on while Ark is running. If you are going to work with Ark, is a good idea to enable it, by setting the following environment variable:
 
<syntaxhighlight lang="bash">
export QT_LOGGING_RULES=ark.*.debug=true
</syntaxhighlight>
 
= How to contribute to Ark =
 
See [https://invent.kde.org/utilities/ark/-/blob/master/CONTRIBUTING.md CONTRIBUTING.md] in the project repository.

Latest revision as of 10:56, 24 October 2023

How to build Ark on Linux

Step 0 - Install build dependencies

Some distributions allow to install the build-time dependencies of any package with a single command. For example, on Debian or Ubuntu you can just run the following command:

sudo apt-get build-dep ark

If you are running the Plasma desktop, you should have most of these dependencies already installed. Usually one needs to manually install only the extra-cmake-modules.

Step 1 - Build ark

Like most KDE projects, Ark relies on the CMake build-system. This means that compiling Ark is as simple as running the following commands:

mkdir build && cd build
cmake ..
make

Everything should work fine, provided that you installed all the required build dependencies.

Note

You can speed-up the compilation by using make -jN, where N is the number of parallel jobs you will run. This number is usually set to the number of CPU cores of your machines.


Step 2 - Install ark

Once you built Ark, it's time to install it with the make install command. However, by default CMake will use /usr/local as install prefix, so you will have to run sudo make install.

At this point your should be able to run /usr/local/bin/ark. If Ark fails to start with the Unable to find Ark's KPart component, please check your installation. error, you need to run cmake with the additional -DKDE_INSTALL_USE_QT_SYS_PATHS=ON argument:

cmake -DKDE_INSTALL_USE_QT_SYS_PATHS=ON ..

Install to custom location

When running cmake, you can set the install prefix to whatever directory you want to install Ark in. For example

cmake -DCMAKE_INSTALL_PREFIX=/home/foo/whatever -DKDE_INSTALL_LIBDIR=lib ..

This way you can run make install without having to type the sudo password. However, you will need to set a bunch of environment variables, in order to have everything working:

# Install prefix, replace with any folder you want
export KF5=~/foo/whatever

export XDG_DATA_DIRS=$KF5/share:$XDG_DATA_DIRS
export XDG_CONFIG_DIRS=$KF5/etc/xdg:/etc/xdg
export PATH=$KF5/bin:$PATH
export QT_PLUGIN_PATH=$KF5/lib/plugins:$QT_PLUGIN_PATH

You can wrap the above exports in a bash script, for convenience. Then you just need to source this script before running the usual cmake/make commands.

Note

The KDE_INSTALL_LIBDIR cmake argument is not really necessary. If you don't use it, cmake will install the plugins in a lib64 folder and you will just need a different QT_PLUGIN_PATH variable:
export QT_PLUGIN_PATH=$KF5/lib64/plugins:$QT_PLUGIN_PATH

Warning

If you want to install Ark in a custom location, do not pass the KDE_INSTALL_USE_QT_SYS_PATHS option to cmake. It's not necessary and it conflicts with CMAKE_INSTALL_PREFIX.


Step 3 - Run the Ark tests

Ark's unit tests are built by default (unless you pass -DBUILD_TESTING=OFF to cmake). Once Ark is built and installed, you should run the tests to check that all of them are passing. You can do so by running the ctest command from the build directory:

ctest --output-on-failure


Build with Clazy

Clazy is a useful tool for static-analysis of Qt projects. It is recommended to use it if you use a recent-enough clang compiler. To install clazy, please referer to its README: https://phabricator.kde.org/diffusion/CLAZY/

Once you have installed clazy, it is very simple to use it. Just set clang as your C++ compiler and tell cmake to enable clazy:

export CXX=$(which clang++)
cmake -DENABLE_CLAZY=ON ..

You will see the clazy warnings as soon as you start compiling Ark.

Build with debug symbols

Debug symbols are useful to debug Ark with GDB. To build Ark with debug symbols enabled, just pass the -DCMAKE_BUILD_TYPE=Debug option to cmake. This will also make Ark crash if a Q_ASSERT fails to validate at runtime. So it is highly recommended to enable this option while hacking on Ark.

Enable debug output

The Ark debug output is useful to understand what's going on while Ark is running. If you are going to work with Ark, is a good idea to enable it, by setting the following environment variable:

export QT_LOGGING_RULES=ark.*.debug=true

How to contribute to Ark

See CONTRIBUTING.md in the project repository.