Get Involved/development: Difference between revisions

From KDE Community Wiki
(Add section about installation before creating a patch (to make sure runtime works before working on patch, also do some test need installation))
(Rewrite much of the page to recommend using kdesrc-build and show you how to do it)
Line 4: Line 4:
KDE runs or participates in several mentoring programs to help new developers, including an informal list of people who are willing to help newcomers get started. See the [[Mentoring]] page for more details.
KDE runs or participates in several mentoring programs to help new developers, including an informal list of people who are willing to help newcomers get started. See the [[Mentoring]] page for more details.


== New to C++/Qt software development? ==
Most KDE software is written in C++ using the [https://www.qt.io Qt toolkit] and [[Frameworks | KDE Frameworks]]. Though prior experience with these technologies or other programming languages is helpful, you don't need to be a C++ programmer to get started!


== Choosing what to do ==
{{Note|The Qt wiki contains [https://wiki.qt.io/Books a list of online books for learning Qt] programming. Qt also provides [http://doc.qt.io/qt-5/qtexamplesandtutorials.html lots of examples] you can look at. Information about KDE Frameworks can be found on the [https://techbase.kde.org TechBase wiki] has documentation about using these libraries, and a [[Books | book]] is available. See also [[Guidelines and HOWTOs/Development]]}}
A good place to start is with a small bug or feature in an existing piece of software that affects you personally ("scratch your own itch"). Get in touch with the existing developers (see [[#Communicating with the team|Communicating with the team]], below) and they can help you out, by pointing you to the right place in the code and giving advice about how to tackle the problem
 
Try not to start by proposing or working on major features or significant design changes. These can be controversial, and the smoothest way to get going is by working on relatively non-controversial bug-fixes.
 
Other ideas for starting points are:


* [https://bugs.kde.org/buglist.cgi?bug_status=UNCONFIRMED&bug_status=CONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&keywords=junior-jobs&list_id=1340815 Junior Jobs] are small tasks that are suitable for beginners (both bugs and features)
* [https://bugs.kde.org/buglist.cgi?bug_status=UNCONFIRMED&bug_status=CONFIRMED&bug_status=ASSIGNED&bug_status=REOPENED&keywords=usability&keywords_type=allwords&list_id=1493316&order=product%2Cchangeddate%20DESC%2Cbug_status%20DESC%2Cresolution%2Cpriority%2Cassigned_to%2Cbug_id&query_format=advanced Bugs related to] KDE's [[Goals/Usability_%26_Productivity | Usability & Productivity initiative]], many of which are small and easy
* [http://www.englishbreakfastnetwork.org/ The English Breakfast Network] searches out simple, common issues in code that should be fixed, and going through the problems on there can provide a good overview of the code


== New to (C++/Qt) software development? ==
== Set up the development environment ==
Most KDE software is written in C++ using the [https://www.qt.io Qt framework]. There are many guides to C++ online, and which one works for you will depend on how you learn best and what previous programming experience you have.
 
For learning Qt, you can find [https://wiki.qt.io/Books a list of books for learning Qt] on the Qt wiki. Qt also provides [http://doc.qt.io/qt-5/qtexamplesandtutorials.html lots of examples] you can look at.
 
Most KDE software is also built on other KDE software, particularly the KDE Frameworks. The [https://techbase.kde.org TechBase wiki] has documentation about using these libraries, and a [[Books | book]] is available. See also [[Guidelines and HOWTOs/Development]].
 
== Get the code ==
First you will need to use your distro's package manager to install some basic tools:
First you will need to use your distro's package manager to install some basic tools:
* Arch/Antergos/Manjaro: <pre>sudo pacman -S git cmake</pre>
* Arch/Antergos/Manjaro: <code>sudo pacman -S git cmake dialog</code>
* Debian/Ubuntu/KDE Neon: <pre>sudo apt install git cmake</pre>
* Debian/Ubuntu/KDE Neon: <code>sudo apt install git cmake dialog</code>
* Fedora: <pre>sudo dnf install git cmake</pre>
* Fedora: <code>sudo dnf install git cmake dialog</code>
* openSUSE: <pre>sudo zypper install git cmake</pre>
* openSUSE: <code>sudo zypper install git cmake dialog</code>


{{Note|If you are not familiar with the [https://git-scm.com/ Git] source control system, the [https://git-scm.com/book Git Book] is a good introduction, but you will learn what you need here if you're new to <tt>git</tt>.}}
{{Note|The online [https://git-scm.com/book Git Book] is a good introduction to the [https://git-scm.com/ Git] source control system if you're not familiar with it, but you will learn what you need here if you're new to it. No special CMake knowledge is required.}}


Next, create a folder to hold all the source code repositories you're going to be downloading!
Next, create a folder to hold all the source code repositories you're going to be downloading!
<pre>
<pre>
mkdir ~/repos
mkdir ~/kde
cd ~/repos
cd ~/kde
</pre>
</pre>


Now download the source code for the project you would like to work on. All the KDE git repositories can be found at https://cgit.kde.org/. Find the official project/repository name of the software you want to work on. Most are identical to the software's name; e.g. the repository name for Okular is okular; the repository name for Breeze Icons is breeze-icons. Once you've identified the correct repository, download it locally:
Most Linux distros do not provide development packages that are up-to-date enough for working on KDE software, so we will compile all the KDE dependencies ourselves. To do this, we use a command-line tool called <code>kdesrc-build</code> to download, manage, and build KDE source code repositories. Let's set it up now:
 
<pre>
<pre>
git clone git://anongit.kde.org/<repository name>.git
git clone git://anongit.kde.org/kdesrc-build.git
cd kdesrc-build
</pre>
</pre>


== Set up your development environment ==
We want to add <code>kdesrc-build</code> to your system's <tt>$PATH</tt> variable so you can access it from anywhere. Use a text editor to open <tt>~/.bashrc</tt> file and add <tt>export PATH=~/kde/kdesrc-build:$PATH</tt>. Then save the file and close it.
First of all, don't worry about this process destabilizing your machine. Your existing software is installed to <tt>/usr</tt>, and when you produce own patched software, it will be installed to <tt>/opt/kde</tt> leaving the original software untouched.


In order to compile a piece of KDE software, you will first need to use your distro's package manager to download the dependencies for the project you would like to patch, so that it will compile.  
Next, set up <code>kdesrc-build</code> using its built-in wizard. The default options should be ok, but feel free to customize anything:
 
The way to do this varies according to your distro (If you don't see it listed below, it is not a recommended development platform):
 
=== Arch/Antergos/Manjaro ===
<pre>
<pre>
sudo pacman -S git <repo/package name>
kdesrc-build-setup
</pre>
</pre>
{{Note|Do not quote or escape any file paths entered in the wizard}}


=== Fedora ===
First add the <insert thing here> Copr, which will upgrade your system to use newer KDE software:
{{Warning|Due to the nature of package dependencies, this will upgrade the entire KDE software stack. Do not proceed unless you are okay with this.}}
<pre>
[Insert method of updating KDE packages in Fedora here]
</pre>
Then install the dependencies for the software you want to work on:
<pre>
sudo dnf builddep <repo/package name>
</pre>


=== KDE Neon ===
== Set up the runtime environment ==
<pre>
Copy the following text to a new file called <tt>~/kde/.setup-env</tt>:
sudo apt build-dep <repo/package name>
 
</pre>
<syntaxhighlight lang="sh">
export KF5=$HOME/kde/usr
export QTDIR=/usr 
export CMAKE_PREFIX_PATH=$KF5:$CMAKE_PREFIX_PATH 
export XDG_DATA_DIRS=$KF5/share:$XDG_DATA_DIRS:/usr/share 
export XDG_CONFIG_DIRS=$KF5/etc/xdg:$XDG_CONFIG_DIRS:/etc/xdg 
export PATH=$KF5/bin:$QTDIR/bin:$PATH 
export QT_PLUGIN_PATH=$KF5/lib/plugins:$KF5/lib64/plugins:$KF5/lib/x86_64-linux-gnu/plugins:$QTDIR/plugins:$QT_PLUGIN_PATH 
# (lib64 instead of lib on some systems, like openSUSE)
export QML2_IMPORT_PATH=$KF5/lib/qml:$KF5/lib64/qml:$KF5/lib/x86_64-linux-gnu/qml:$QTDIR/qml 
export QML_IMPORT_PATH=$QML2_IMPORT_PATH 
export KDE_SESSION_VERSION=5 
export KDE_FULL_SESSION=true
export SASL_PATH=/usr/lib/sasl2:$KF5/lib/sasl2
# (lib64 instead of lib on some systems, like openSUSE)
PS1="(kdesrc) $PS1"
</syntaxhighlight>


=== Kubuntu ===
'''This only needs to be done once.'''
First add the [https://launchpad.net/~kubuntu-ppa/+archive/ubuntu/backports Kubuntu Backports PPA], which will upgrade your system to use newer KDE software:
{{Warning|Due to the nature of package dependencies, this will upgrade the entire KDE software stack. Do not proceed unless you are okay with this.}}
<pre>
sudo add-apt-repository ppa:kubuntu-ppa/backports
sudo apt update
sudo apt full-upgrade
</pre>
Then install the dependencies for the software you want to work on:
<pre>
sudo apt build-dep <repo/package name>
</pre>


=== openSUSE Leap ===
openSUSE Leap does not ship the latest release of KDE software. As that is recommended or even necessary for development, you need to add extra repositories to get later releases. Read [https://en.opensuse.org/SDB:KDE_repositories#KDE_Frameworks_5.2C_Plasma_5_and_Applications the openSUSE wiki page] for instructions.
{{Warning|Due to the nature of package dependencies, this will upgrade the entire KDE software stack. Do not proceed unless you are okay with this.}}
Then install the dependencies for the software you want to work on:
<pre>
sudo zypper si -d <repo/package name>
</pre>


=== openSUSE Tumbleweed ===
== Compile and install a test project ==
First enable the source repository:
Now let's use <code>kdesrc-build</code> to download, compile, and install a simple KDE project with no dependencies so we can be sure it's working properly.
<pre>
sudo zypper mr -e repo-source
</pre>
Then install the dependencies for the software you want to work on:
<pre>
<pre>
sudo zypper si -d <package name>
cd ~/kde
kdesrc-build extra-cmake-modules
</pre>
</pre>


<br/>
Did that work? Great! Now let's build Dolphin. To do this, we will first need to get some external dependencies...


== Compile the software ==
== Get external dependencies ==
We will use <code>kdesrc-build</code> to manage KDE dependencies, but most pieces of KDE software also depend on system libraries that are not owned or controlled by KDE. We will use the distro's package manager to get these:
* Arch/Antergos/Manjaro: <code>sudo pacman -S git <repo/package name></code>
* Fedora: <code>sudo dnf builddep <repo/package name></code>
* KDE Neon/Kubuntu/Ubuntu/Debian <code>sudo apt build-dep <repo/package name></code>
* openSUSE Leap & Tumbleweed: <code>sudo zypper si -d <repo/package name></code>


Before you work on your patch, try to compile the software to make sure that your development environment is set up properly:


== Compile and install Dolphin ==
Now that we have the dependencies, we can use <code>kdesrc-build</code> to compile and install Dolphin:
<pre>
<pre>
mkdir build
cd ~/kde
cd build
kdesrc-build dolphin
cmake -DCMAKE_INSTALL_PREFIX=/opt/kde/ ..
make
</pre>
</pre>
(Notice how we are telling CMake to install to <tt>/opt/kde/</tt> instead of <tt>/usr/</tt> (which is the normal location). This is because we don't want to overwrite the software provided by your distro, which could destabilize the system.
Did the project compile? Great! Move onto the next section. If you run into problems, see this page for what to do about it.
== Install the software ==


After compilation, try to also install and run the software to make sure that your development environment is also set up properly for the runtime:


You will call this to install your compiled software:
== Run your custom-compiled software ==
Now <tt>source</tt> the <tt>~/kde/.setup-env</tt> file every time you want to run your custom-compiled KDE software:
<pre>
<pre>
sudo make install
source ~/kde/.setup-env
~/kde/usr/dolphin
</pre>
</pre>


This will install the software to <tt>/opt/kde/</tt>.
Did it run? If so, then '''congratulations, you just compiled your own version of Dolphin from source code!'''


Note: If you install into a user controlled directory e.g. ~/build you might have to set DESTDIR environment variable:
== Choosing what to do ==
<pre>
Now that you can compile and deploy custom versions of KDE software, you can open your editor and get hacking! A good place to start is with a small bug or feature in an existing piece of software that affects you personally ("scratch your own itch"). Get in touch with the existing developers (see [[#Communicating with the team|Communicating with the team]], below) and they can help you out, by pointing you to the right place in the code and giving advice about how to tackle the problem
env DESTDIR=~/build make install
</pre>


To actually run the software, you will need to set some environment variables to account for the non-standard location. First, create a file with the environment variables ('''this only needs to be done once'''):
Try not to start by proposing or working on major features or significant design changes. These can be controversial, and the smoothest way to get going is by working on relatively non-controversial bug-fixes.
<pre>
cat > ~/.kderc << "EOF"
export KF5=/opt/kde
export QTDIR=/usr
export CMAKE_PREFIX_PATH=$KF5:$CMAKE_PREFIX_PATH
export XDG_DATA_DIRS=$KF5/share:$XDG_DATA_DIRS:/usr/share
export XDG_CONFIG_DIRS=$KF5/etc/xdg:$XDG_CONFIG_DIRS:/etc/xdg
export PATH=$KF5/bin:$QTDIR/bin:$PATH
export QT_PLUGIN_PATH=$KF5/lib/plugins:$KF5/lib64/plugins:$KF5/lib/x86_64-linux-gnu/plugins:$QTDIR/plugins:$QT_PLUGIN_PATH
export QML2_IMPORT_PATH=$KF5/lib/qml:$KF5/lib64/qml:$KF5/lib/x86_64-linux-gnu/qml:$QTDIR/qml
export QML_IMPORT_PATH=$QML2_IMPORT_PATH
export KDE_SESSION_VERSION=5
export KDE_FULL_SESSION=true
export SASL_PATH=/usr/lib/sasl2:$KF5/lib/sasl2
EOF
</pre>


Now <tt>source</tt> it to pick up the new environment variables:
Other ideas for starting points are:
<pre>
source ~/.kderc
</pre>


Now you're ready to run your installed software!
* [https://bugs.kde.org/buglist.cgi?bug_status=UNCONFIRMED&bug_status=CONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&keywords=junior-jobs&list_id=1340815 Junior Jobs] are small tasks that are suitable for beginners (both bugs and features)
<pre>
* [https://bugs.kde.org/buglist.cgi?bug_status=UNCONFIRMED&bug_status=CONFIRMED&bug_status=ASSIGNED&bug_status=REOPENED&keywords=usability&keywords_type=allwords&list_id=1493316&order=product%2Cchangeddate%20DESC%2Cbug_status%20DESC%2Cresolution%2Cpriority%2Cassigned_to%2Cbug_id&query_format=advanced Bugs related to] KDE's [[Goals/Usability_%26_Productivity | Usability & Productivity initiative]], many of which are small and easy
/opt/kde/bin/<the program>
* [http://www.englishbreakfastnetwork.org/ The English Breakfast Network] searches out simple, common issues in code that should be fixed, and going through the problems on there can provide a good overview of the code
</pre>


== Make your patch ==
Now you can open your editor and get hacking! As before, make sure it compiles:
<pre>
make
</pre>


== Test your patch ==
== Test your patch ==
At this point, you have a patch, and the project still compiles. Now it's time to run the project's unit tests:
At this point, you have a patch, and the project still compiles and installs. Now it's time to run the project's unit tests:
<pre>
<pre>
source ~/kde/.setup-env
cd ~/kde/<project>
make test
make test
</pre>
</pre>


Note that with many software developed in the KDE community the tests might rely on installed resources, so before you might want to also update the installation:
If any test fails, that needs to be investigated and fixed before you can proceed. Once the tests pass, then run the software again to make sure it still behaves properly. If it doesn't, then go back and work on your patch some more, then re-compile and re-deploy, and test again, until the program does what you'd like it to do and all tests pass.
<pre>
sudo make install
</pre>
In that case you also need to make sure you are running the tests in an environment as also created for the program. So if not yet called, do now:
<pre>
source ~/.kderc
</pre>
 
If any test fails, that needs to be investigated before you can proceed. If the tests pass, then it's time to run the software again, as shown above:
<pre>
/opt/kde/bin/<the program>
</pre>


Does it behave as you expect? Great! If not, go back and work on your patch some more, then re-compile and re-deploy, and test again, until the program does what you'd like it to do.


== Submitting your first patch ==
== Submitting your first patch ==

Revision as of 22:13, 2 November 2018

By joining the ranks of KDE developers, you will get to implement new features and defeat bugs both daunting and simple, all while collaborating to make coherent and stable releases. Developers collaborate in teams based on what area they are working in. These can be small teams working on a single application, up to large teams working on a group of related pieces of software. Many developers are in more than one team.

KDE runs or participates in several mentoring programs to help new developers, including an informal list of people who are willing to help newcomers get started. See the Mentoring page for more details.

New to C++/Qt software development?

Most KDE software is written in C++ using the Qt toolkit and KDE Frameworks. Though prior experience with these technologies or other programming languages is helpful, you don't need to be a C++ programmer to get started!

Note

The Qt wiki contains a list of online books for learning Qt programming. Qt also provides lots of examples you can look at. Information about KDE Frameworks can be found on the TechBase wiki has documentation about using these libraries, and a book is available. See also Guidelines and HOWTOs/Development


Set up the development environment

First you will need to use your distro's package manager to install some basic tools:

  • Arch/Antergos/Manjaro: sudo pacman -S git cmake dialog
  • Debian/Ubuntu/KDE Neon: sudo apt install git cmake dialog
  • Fedora: sudo dnf install git cmake dialog
  • openSUSE: sudo zypper install git cmake dialog

Note

The online Git Book is a good introduction to the Git source control system if you're not familiar with it, but you will learn what you need here if you're new to it. No special CMake knowledge is required.


Next, create a folder to hold all the source code repositories you're going to be downloading!

mkdir ~/kde
cd ~/kde

Most Linux distros do not provide development packages that are up-to-date enough for working on KDE software, so we will compile all the KDE dependencies ourselves. To do this, we use a command-line tool called kdesrc-build to download, manage, and build KDE source code repositories. Let's set it up now:

git clone git://anongit.kde.org/kdesrc-build.git
cd kdesrc-build

We want to add kdesrc-build to your system's $PATH variable so you can access it from anywhere. Use a text editor to open ~/.bashrc file and add export PATH=~/kde/kdesrc-build:$PATH. Then save the file and close it.

Next, set up kdesrc-build using its built-in wizard. The default options should be ok, but feel free to customize anything:

kdesrc-build-setup

Note

Do not quote or escape any file paths entered in the wizard


Set up the runtime environment

Copy the following text to a new file called ~/kde/.setup-env:

export KF5=$HOME/kde/usr
export QTDIR=/usr  
export CMAKE_PREFIX_PATH=$KF5:$CMAKE_PREFIX_PATH  
export XDG_DATA_DIRS=$KF5/share:$XDG_DATA_DIRS:/usr/share  
export XDG_CONFIG_DIRS=$KF5/etc/xdg:$XDG_CONFIG_DIRS:/etc/xdg  
export PATH=$KF5/bin:$QTDIR/bin:$PATH  
export QT_PLUGIN_PATH=$KF5/lib/plugins:$KF5/lib64/plugins:$KF5/lib/x86_64-linux-gnu/plugins:$QTDIR/plugins:$QT_PLUGIN_PATH  
# (lib64 instead of lib on some systems, like openSUSE)
export QML2_IMPORT_PATH=$KF5/lib/qml:$KF5/lib64/qml:$KF5/lib/x86_64-linux-gnu/qml:$QTDIR/qml  
export QML_IMPORT_PATH=$QML2_IMPORT_PATH  
export KDE_SESSION_VERSION=5  
export KDE_FULL_SESSION=true
export SASL_PATH=/usr/lib/sasl2:$KF5/lib/sasl2
# (lib64 instead of lib on some systems, like openSUSE)
PS1="(kdesrc) $PS1"

This only needs to be done once.


Compile and install a test project

Now let's use kdesrc-build to download, compile, and install a simple KDE project with no dependencies so we can be sure it's working properly.

cd ~/kde
kdesrc-build extra-cmake-modules

Did that work? Great! Now let's build Dolphin. To do this, we will first need to get some external dependencies...

Get external dependencies

We will use kdesrc-build to manage KDE dependencies, but most pieces of KDE software also depend on system libraries that are not owned or controlled by KDE. We will use the distro's package manager to get these:

  • Arch/Antergos/Manjaro: sudo pacman -S git <repo/package name>
  • Fedora: sudo dnf builddep <repo/package name>
  • KDE Neon/Kubuntu/Ubuntu/Debian sudo apt build-dep <repo/package name>
  • openSUSE Leap & Tumbleweed: sudo zypper si -d <repo/package name>


Compile and install Dolphin

Now that we have the dependencies, we can use kdesrc-build to compile and install Dolphin:

cd ~/kde
kdesrc-build dolphin


Run your custom-compiled software

Now source the ~/kde/.setup-env file every time you want to run your custom-compiled KDE software:

source ~/kde/.setup-env
~/kde/usr/dolphin

Did it run? If so, then congratulations, you just compiled your own version of Dolphin from source code!

Choosing what to do

Now that you can compile and deploy custom versions of KDE software, you can open your editor and get hacking! A good place to start is with a small bug or feature in an existing piece of software that affects you personally ("scratch your own itch"). Get in touch with the existing developers (see Communicating with the team, below) and they can help you out, by pointing you to the right place in the code and giving advice about how to tackle the problem

Try not to start by proposing or working on major features or significant design changes. These can be controversial, and the smoothest way to get going is by working on relatively non-controversial bug-fixes.

Other ideas for starting points are:


Test your patch

At this point, you have a patch, and the project still compiles and installs. Now it's time to run the project's unit tests:

source ~/kde/.setup-env
cd ~/kde/<project>
make test

If any test fails, that needs to be investigated and fixed before you can proceed. Once the tests pass, then run the software again to make sure it still behaves properly. If it doesn't, then go back and work on your patch some more, then re-compile and re-deploy, and test again, until the program does what you'd like it to do and all tests pass.


Submitting your first patch

Once you're happy with your patch and have verified that it does what you want, you need to send it to other KDE developers for review. KDE uses Phabricator for this. Learn how to submit a patch with Phabricator


Communicating with the team

There are several ways to get in touch with KDE developers, and developers for a specific project. The two most important are:

Both of these are general KDE development communication channels, and you may get directed to a more appropriate place for the project you are interested in. There is a list of mailing lists if you want to find a mailing list for a specific team directly. Many teams have their own Telegram rooms, too.

You can also try looking for the team's section on the Main Page of this wiki. Many teams have information there for new contributors.


Next steps

After you have had several patches accepted, a KDE developer is likely to suggest you get a Developer account, which will allow you to commit directly to KDE projects. With very few limits on where you can commit, you will be expected to act responsibly. At this point, congratulations! You are officially a KDE developer!

You may also want to set up a more permanent or advanced development environment, which will be very handy to start working on KDE Frameworks or Plasma itself. See Guidelines and HOWTOs/Build from source