KDE PIM/Docker: Difference between revisions

From KDE Community Wiki
(Initial documentation on using the KDE PIM Docker)
 
 
(29 intermediate revisions by 6 users not shown)
Line 1: Line 1:
{{Construction}}
To make developing KDE PIM as easy as possible we have prepared a Docker image based on the KDE Neon distribution. It contains all the dependencies necessary to compile KDE PIM, the environment for running self-compiled KDE PIM and pre-configured tool (kdesrc-build) used to build latest KDE PIM from sources.
 
== Set up Docker ==
If you use KDE Neon, Ubuntu or Debian, run the following commands to install Docker and add yourself to the <code>docker</code> group, so you can use it:
 
sudo apt install docker.io xserver-xephyr
sudo usermod -aG docker $(whoami)
newgrp docker


To make developing KDE PIM as easy as possible we have prepared a Docker image based on the KDE Neon distribution. It contains all the dependencies necessary to compile KDE PIM, the environment for running self-compiled KDE PIM and pre-configured tool (kdesrc-build) used to build latest KDE PIM from sources.
{{Warning|It's important to note that any user added to the docker group is root equivalent. More information [https://github.com/docker/docker/issues/9976 here] and [https://docs.docker.com/engine/security/security/ here].}}


== Building the Docker image ==
On other distributions, please follow your distro's guide on how to set up Docker there, since the steps can differ slightly on different distributions.
git clone git://anongit.kde.org/scratch/dvratil/kdepim-docker.git
cd kdepim-docker
sudo docker build . --label kdepim-image
# Now go make a coffee, this will take a while...


Next, create a directory where you want the sources code, build folders and everything else related to KDE PIM development to be stored. We will then expose this directory to the Docker container at runtime.
== Preparations ==
Clone the git repository with the Dockerfile and support scripts.


  mkdir ~/kdepim-dev
  git clone [email protected]:pim/kdepim-docker.git
cd kdepim-docker


== Making OpenGL work in the container ==
== Making OpenGL work in the container ==
Line 19: Line 24:
The easiest way is to use NVIDIA's nvidia-docker from [https://github.com/NVIDIA/nvidia-docker nvidia-docker Github]. You can follow the instructions on the Github page regarding how to install it. The nvidia-docker will automatically find your installed NVIDIA drivers and will expose them into the Docker container at runtime, so you don't have to rebuild your container whenever you upgrade your NVIDIA drivers.
The easiest way is to use NVIDIA's nvidia-docker from [https://github.com/NVIDIA/nvidia-docker nvidia-docker Github]. You can follow the instructions on the Github page regarding how to install it. The nvidia-docker will automatically find your installed NVIDIA drivers and will expose them into the Docker container at runtime, so you don't have to rebuild your container whenever you upgrade your NVIDIA drivers.


Note that if you do this, you need to use <code>docker-nvidia run</code> command instead of <code>docker run</code>.
Note that if you do this, you must pass <code>-n</code> switch to the <code>build.sh</code> and <code>run.sh</code> scripts from the kdepim-docker.git repository.


=== Nouveau (NVIDIA opensource drivers) ===
=== Nouveau (NVIDIA opensource drivers) ===
Line 25: Line 30:


=== Intel ===
=== Intel ===
TODO
Works out of the box


=== AMD/ATI ===
=== AMD/ATI ===
TODO
TODO


== Running the container ==
== Building Docker image ==
  sudo docker run --rm \
 
                  -e DISPLAY=$DISPLAY \
In order to build the Docker image, run the <code>build.sh</code> script. If you are
                  -v=/tmp/.X11-unix:/tmp/.X11-unix:rw \
using proprietary NVIDIA drivers, run the script with the <code>-n</code> switch.
                  -v=$HOME/kdepim-dev:/home/neon/kdepim:rw \
 
                  --privileged \ #TODO: needed?
The command will create a Docker image called kdepim:dev.
                  kdepim-image
 
== Running the Docker container ==
 
Create a directory where you want the source code, build folders, and everything else related to KDE PIM development to be stored. This is also where runtime data and configuration of Akonadi, Kontact and other apps you run inside the container will be stored. You will then expose this directory to the Docker container at runtime.  The content of the directory will be available in the container in its
<code>/home/neon/kdepim</code> directory.
 
mkdir $HOME/kdepim-dev
 
To run the container, use the <code>run.sh</code> script. When you run it for the first time, you must give it the path to the storage directory:
 
run.sh $HOME/kdepim-dev
 
If you are using proprietary NVIDIA drivers, run the script with the <code>-n</code> switch:
 
run.sh -n $HOME/kdepim-dev
 
The first run will create a container named after the storage directory.  After the first run you can just use the name instead of the full path:
 
run.sh kdepim-dev
 
If you want to get another terminal window opened inside the same container, just run <code>run.sh</code> again. It will automatically create a new terminal on the already running container.
 
{{note|In some systems, the container's <code>/home/neon/kdepim</code> directory may not be writable. If so, edit <code>run.sh</code> to remove the parameter <code>:rw,z</code> from the <code>-v</code> options. Then delete the container with the command <code>docker rm kdepim-dev</code>, and run the container again.}}
 
=== Running Multiple Containers ===
 
You can have more than one container, each with its own state.  For example, KDE PIM bug fixing mostly occurs on the current Release git repository branches, while new development occurs on the master branches.  Switching between them (with <code>kdesrc-build --branch</code>) requires lengthy recompilation.  Instead of switching, you can have one container for each.
 
mkdir $HOME/kdepim-stable    # Storage for second container.
run.sh $HOME/kdepim-stable  # Create second container.
 
== Building and updating KDE PIM ==
 
Once inside the container, you can use the following commands to compile the
entire KDE PIM suite:
 
sudo apt update
sudo apt full-upgrade
kdesrc-build kde-pim
 
This will take a lot of time the first time, but all subsequent builds will be
faster thanks to incremental builds and use of ccache. You can also use a specific repository name instead of the
<code>kde-pim</code> group.
 
Check the [https://kdesrc-build.kde.org kdesrc-build documentation] for more
details about using kdesrc-build. For a start, you may want to customize the <code>-j</code> option in the <code>make-options</code> option group in /home/neon/.kdesrc-buildrc.
 
kdesrc-build will clone all the repositories into <code>/home/neon/kdepim/src/kde/pim</code>.
Build directories (where you can run <code>make</code> and <code>ctest</code> manually) are in <code>/home/neon/kdepim/build/kde/pim</code>.
Two command-line aliases, <code>cb</code> and <code>cs</code>, switch back and forth between them.
 
The binaries are installed to <code>/home/neon/kdepim/install</code>. The environment
of the container is adjusted to work with the custom installation prefix.
 
=== Fixing build errors ===
If kdesrc-build cannot build from a repository, it will write a log file in <code>/home/neon/kdepim/logs/latest/''repository''/error.log</code>.


Remember to replace <code>docker</code> with <code>docker-nvidia</code> if you are using NVIDIA proprietary drivers.
It is often the case that some system has added a dependency on some package that is not installed.
In that case, error.log will contain messages like


We recommend you [https://shapeshed.com/unix-alias/#why-create-a-shell-alias create an alias] or a shell script to run this command so that you don't have to type it every time you want to start the container.
  Could not find a package configuration file provided by "Qt5Location" with
  any of the following names:
 
    Qt5LocationConfig.cmake
    qt5location-config.cmake


If you are not familiar with Docker, here's an explanation of the individual switches:
If the system you are trying to build is normally distributed in some KDE Neon package, you can try to install all of its dependencies at once:


<code>--rm</code> The container will be deleted when you stop it and will be created freshly from the image when you start it again
  sudo apt update
  sudo apt build-dep <em>package</em>


<code>-e</code> Expose the host's $DISPLAY environment variable as DISPLAY into the Docker
Another way to find a missing package is to visit [https://packages.ubuntu.com/ Ubuntu Packages Search] and use the "Search the contents of packages" form to search for the cmake file, then use <code>sudo apt install</code> to install the package.


<code>-v=HOSTDIR:CONTAINERDIR:options</code> Mount the HOSTDIR directory as CONTAINERDIR inside the container, with the specified options
== Development tools ==


<code>kdepim-image</code> Name of the image to create the container from
There's [https://www.kdevelop.org KDevelop] and [https://www.qt.io/ide/ QtCreator]
preinstalled in the container and you can run them from there. You can also use
them from outside of the container, but code completion might not work perfectly then.


You can also use any other IDE of your choice either by installing it into the container
with apt-get or use it from outside of the container.


== Using the container ==
== Contributing ==


[TODO]
You can find more details in the [[KDE_PIM/Development|Development]] section of our wiki. If you have any issues or questions, feel free to stop by on our IRC channel (#kontact) on Libera Chat, or talk to us on the [[KDE_PIM/Development#Mailing_Lists|kde-pim mailinglist]].

Latest revision as of 22:56, 28 February 2022

To make developing KDE PIM as easy as possible we have prepared a Docker image based on the KDE Neon distribution. It contains all the dependencies necessary to compile KDE PIM, the environment for running self-compiled KDE PIM and pre-configured tool (kdesrc-build) used to build latest KDE PIM from sources.

Set up Docker

If you use KDE Neon, Ubuntu or Debian, run the following commands to install Docker and add yourself to the docker group, so you can use it:

sudo apt install docker.io xserver-xephyr
sudo usermod -aG docker $(whoami)
newgrp docker

Warning

It's important to note that any user added to the docker group is root equivalent. More information here and here.


On other distributions, please follow your distro's guide on how to set up Docker there, since the steps can differ slightly on different distributions.

Preparations

Clone the git repository with the Dockerfile and support scripts.

git clone [email protected]:pim/kdepim-docker.git
cd kdepim-docker

Making OpenGL work in the container

Several parts of KDE PIM depend on OpenGL - this is due to our use of QtWebEngine, which is based on Blink and has a hard dependency on OpenGL for rendering web pages. There's no way around that and so we need to make OpenGL work in the container. Unfortunately, that is not a very straightforward process and it differs for each GPU vendor and drivers used.

NVIDIA proprietary drivers

The easiest way is to use NVIDIA's nvidia-docker from nvidia-docker Github. You can follow the instructions on the Github page regarding how to install it. The nvidia-docker will automatically find your installed NVIDIA drivers and will expose them into the Docker container at runtime, so you don't have to rebuild your container whenever you upgrade your NVIDIA drivers.

Note that if you do this, you must pass -n switch to the build.sh and run.sh scripts from the kdepim-docker.git repository.

Nouveau (NVIDIA opensource drivers)

TODO

Intel

Works out of the box

AMD/ATI

TODO

Building Docker image

In order to build the Docker image, run the build.sh script. If you are using proprietary NVIDIA drivers, run the script with the -n switch.

The command will create a Docker image called kdepim:dev.

Running the Docker container

Create a directory where you want the source code, build folders, and everything else related to KDE PIM development to be stored. This is also where runtime data and configuration of Akonadi, Kontact and other apps you run inside the container will be stored. You will then expose this directory to the Docker container at runtime. The content of the directory will be available in the container in its /home/neon/kdepim directory.

mkdir $HOME/kdepim-dev

To run the container, use the run.sh script. When you run it for the first time, you must give it the path to the storage directory:

run.sh $HOME/kdepim-dev

If you are using proprietary NVIDIA drivers, run the script with the -n switch:

run.sh -n $HOME/kdepim-dev

The first run will create a container named after the storage directory. After the first run you can just use the name instead of the full path:

run.sh kdepim-dev

If you want to get another terminal window opened inside the same container, just run run.sh again. It will automatically create a new terminal on the already running container.

Note

In some systems, the container's /home/neon/kdepim directory may not be writable. If so, edit run.sh to remove the parameter :rw,z from the -v options. Then delete the container with the command docker rm kdepim-dev, and run the container again.


Running Multiple Containers

You can have more than one container, each with its own state. For example, KDE PIM bug fixing mostly occurs on the current Release git repository branches, while new development occurs on the master branches. Switching between them (with kdesrc-build --branch) requires lengthy recompilation. Instead of switching, you can have one container for each.

mkdir $HOME/kdepim-stable    # Storage for second container.
run.sh $HOME/kdepim-stable   # Create second container.

Building and updating KDE PIM

Once inside the container, you can use the following commands to compile the entire KDE PIM suite:

sudo apt update
sudo apt full-upgrade
kdesrc-build kde-pim

This will take a lot of time the first time, but all subsequent builds will be faster thanks to incremental builds and use of ccache. You can also use a specific repository name instead of the kde-pim group.

Check the kdesrc-build documentation for more details about using kdesrc-build. For a start, you may want to customize the -j option in the make-options option group in /home/neon/.kdesrc-buildrc.

kdesrc-build will clone all the repositories into /home/neon/kdepim/src/kde/pim. Build directories (where you can run make and ctest manually) are in /home/neon/kdepim/build/kde/pim. Two command-line aliases, cb and cs, switch back and forth between them.

The binaries are installed to /home/neon/kdepim/install. The environment of the container is adjusted to work with the custom installation prefix.

Fixing build errors

If kdesrc-build cannot build from a repository, it will write a log file in /home/neon/kdepim/logs/latest/repository/error.log.

It is often the case that some system has added a dependency on some package that is not installed. In that case, error.log will contain messages like

 Could not find a package configuration file provided by "Qt5Location" with
 any of the following names:
 
   Qt5LocationConfig.cmake
   qt5location-config.cmake

If the system you are trying to build is normally distributed in some KDE Neon package, you can try to install all of its dependencies at once:

 sudo apt update
 sudo apt build-dep package

Another way to find a missing package is to visit Ubuntu Packages Search and use the "Search the contents of packages" form to search for the cmake file, then use sudo apt install to install the package.

Development tools

There's KDevelop and QtCreator preinstalled in the container and you can run them from there. You can also use them from outside of the container, but code completion might not work perfectly then.

You can also use any other IDE of your choice either by installing it into the container with apt-get or use it from outside of the container.

Contributing

You can find more details in the Development section of our wiki. If you have any issues or questions, feel free to stop by on our IRC channel (#kontact) on Libera Chat, or talk to us on the kde-pim mailinglist.