[websites/linux-kde-org] content: Overhaul dev docs
Nate Graham <[email protected]>
| Newsgroups | gmane.comp.kde.cvs |
|---|---|
| Message-ID | <[email protected]> |
Git commit beeb38b427499a9b88aecbc755b69c193605f4e1 by Nate Graham. Committed on 07/08/2026 at 01:14. Pushed by ngraham into branch 'master'. Overhaul dev docs Split more things into sub-pages to make their length manageable, and link to them all on the main dev page. M +1 -4 content/docs.md M +10 -6 content/docs/dev.md A +15 -0 content/docs/distrobox-dev.md A +53 -0 content/docs/flatpak-dev.md A +52 -0 content/docs/kde-dev-host.md D +0 -115 content/docs/kde-dev.md https://invent.kde.org/websites/linux-kde-org/-/commit/beeb38b427499a9b88aecbc755b69c193605f4e1 diff --git a/content/docs.md b/content/docs.md index b0eed46..82ea4b6 100644 --- a/content/docs.md +++ b/content/docs.md @@ -60,10 +60,7 @@ Life on a cutting-edge image-based OS can be unfamiliar! This page contains info ## Software development -* [Develop KDE software](kde-dev) -* [Develop or run Python scripts](python-dev) -* [Develop or debug the kernel](kernel-dev) -* [Develop other non-KDE software](dev) +* [Develop software](dev) * [Develop KDE Linux](kde-linux-dev) * [Test changes to KDE Linux with openQA](openqa) <!-- * Develop general-purpose GPU software using OpenCL/CUDA/etc. (coming soon) --> diff --git a/content/docs/dev.md b/content/docs/dev.md index b3c506c..2a5475d 100644 --- a/content/docs/dev.md +++ b/content/docs/dev.md @@ -8,14 +8,18 @@ scssFiles: [/scss/main.scss] hideMeta: true --- -Common build tools are pre-installed, so the hard part here is usually getting the software’s dependencies, since KDE Linux doesn’t include a package manager you can use to install them. +KDE Linux is a reasonable platform for developing software. -[Using Distrobox](../more-software/#distrobox) is currently the preferred option: follow the build instructions for the project itself using a Distrobox container for the project’s best-supported Linux distro. +Many common build tools are pre-installed; to show a few more (GammaRay, Heaptrack, and some internal Plasma dev apps), run <code>toggle-developer-mode</code> in a terminal window. -If the software you’re compiling needs to be installed systemwide, [set up a systemd extension (sysext) to hold it](../override-usr). +Choose a path based on what you want to develop: +* [KDE software that’s shipped on the base OS using kde-builder](kde-dev-host) +* [Any app that can be built using Flatpak](flatpak-dev) +* [Python software](python-dev) +* [The Linux kernel](kernel-dev) +* [Any other software using Distrobox](distrobox-dev) -To show additional build tools (GammaRay, Heaptrack, and some internal Plasma dev apps), run `toggle-developer-mode` in a terminal window. - -## See also +## Further information * [Install software not available in Discover](../more-software) +* [Add or override files in /usr](override-usr) diff --git a/content/docs/distrobox-dev.md b/content/docs/distrobox-dev.md new file mode 100644 index 0000000..348d1fd --- /dev/null +++ b/content/docs/distrobox-dev.md @@ -0,0 +1,15 @@ +--- +authors: + - SPDX-FileCopyrightText: 2026 Nate Graham <[email protected]> +SPDX-License-Identifier: CC-BY-4.0 + +title: "Develop Any Software Using Distrobox" +scssFiles: [/scss/main.scss] +hideMeta: true +--- + +If you need to develop some software not preinstalled on the base system (so dependencies are also not pre-installed) and that also does not or cannot be built as a Flatpak, you can build it in a *Distrobox* container. + +Follow the build instructions for the project itself using a Distrobox container for the project’s best-supported Linux distro. + +For example, instructions for building KDE software using Distrobox [can be found here](https://develop.kde.org/docs/getting-started/building/containers-distrobox/). diff --git a/content/docs/flatpak-dev.md b/content/docs/flatpak-dev.md new file mode 100644 index 0000000..54f6bf5 --- /dev/null +++ b/content/docs/flatpak-dev.md @@ -0,0 +1,53 @@ +--- +authors: + - SPDX-FileCopyrightText: 2026 Nate Graham <[email protected]> +SPDX-License-Identifier: CC-BY-4.0 + +title: "Develop an App with a Flatpak Manifest" +scssFiles: [/scss/main.scss] +hideMeta: true +--- + +This workflow is used for developing or testing changes to an app with a Flatpak manifest using <code>flatpak-builder</code>. + + +## Setup +Create a local user-level remote named “<tt>flathub-apps-built-locally</tt>” to hold your built-from-source Flatpak apps: + +<pre> +flatpak remote-add --user --if-not-exists flathub-apps-built-locally https://flathub.org/repo/flathub.flatpakrepo +</pre> + + +## Make changes to just the app +First check out the source code for the app you’d like to build. For example, KDE’s [Filelight](https://apps.kde.org/filelight) disk space analyzer app: + +<pre> +# Create folder to hold KDE source code. Skippable if it already exists +mkdir -p ~/kde/src/ + +# Go into that folder +cd ~/kde/src/ + +# Download source code for Filelight +git clone [email protected]:utilities/filelight.git + +# Go into Filelight’s source code folder +cd ~/kde/src/filelight + +# Build Filelight as a flatpak +flatpak-builder build --user --install-deps-from=flathub-apps-built-locally --force-clean --ccache --install .flatpak-manifest.json +</pre> + +<code>flatpak-builder</code> will create a Flatpak repo named <code>filelight-origin</code> and export the freshly built Filelight Flatpak to this repo. + +Now run it: + +<pre> +org.kde.filelight +</pre> + + +## Further information +* https://docs.flatpak.org/en/latest/getting-started.html +* https://develop.kde.org/docs/packaging/flatpak/packaging/ diff --git a/content/docs/kde-dev-host.md b/content/docs/kde-dev-host.md new file mode 100644 index 0000000..d06fdfd --- /dev/null +++ b/content/docs/kde-dev-host.md @@ -0,0 +1,52 @@ +--- +authors: + - SPDX-FileCopyrightText: 2026 Nate Graham <[email protected]> +SPDX-License-Identifier: CC-BY-4.0 + +title: "Develop KDE Software That’s Shipped on the OS Image" +scssFiles: [/scss/main.scss] +hideMeta: true +aliases: +- kde-dev +--- + +This workflow is used for developing KDE software that’s shipped on the base system — or even Qt. + +A list of such software [can be found here](https://invent.kde.org/kde-linux/kde-linux-packages/-/blob/master/targets.yaml) (note that “workspace” includes Plasma, KWin, and Plasma-aligned apps such as System Settings and Discover). + +The best way to do this is by using <code>systemd-sysext</code>, which allows overlaying built-from-source content on top of <code>/usr/</code> without impacting the base system. + + +## Setup +Run the setup script: + +<pre> +set-up-system-development +</pre> + + +## Use +In a nutshell, you’ll compile and install software using <code>kde-builder</code>, then refresh the systemd extension, and then finally restart any services that you changed (e.g. Plasma), or the entire system. + +For example, to compile and test a change to plasma-pa, do the following: + +<pre> +kde-builder plasma-pa +run0 systemd-sysext refresh --always-refresh=yes +systemctl restart --user plasma-plasmashell.service +</pre> + +If you replace a core system component and find that everything is crashing after the refresh is applied, try rebooting in order to fully reload the new dependency in all running software. + +When you’re finished developing or testing the change, disable (“un-merge”) the system extension: + +<pre> +run0 systemd-sysext unmerge +</pre> + +When you’re done with your built-from-source software (e.g. because it was accepted as a patch and merged), delete the installed files: + +<pre> +rm -r ~/kde/usr/* +# When you’re prompted to delete the read-only extension-release.kde file, answer 'n' +</pre> diff --git a/content/docs/kde-dev.md b/content/docs/kde-dev.md deleted file mode 100644 index 14438b9..0000000 --- a/content/docs/kde-dev.md +++ /dev/null @@ -1,115 +0,0 @@ ---- -authors: - - SPDX-FileCopyrightText: 2026 Nate Graham <[email protected]> -SPDX-License-Identifier: CC-BY-4.0 - -title: "Develop KDE Software" -scssFiles: [/scss/main.scss] -hideMeta: true ---- - -KDE Linux is an excellent development platform for KDE software. There are three primary paths, depending on how the KDE software you want to develop is shipped on KDE Linux: -* [Developing KDE software that’s shipped on the base image](#build-kde-software-thats-shipped-on-the-base-image) -* [Developing KDE software that can be built using Flatpak](#build-kde-app-with-a-flatpak-manifest) -* [Developing any KDE software using Distrobox](#build-any-kde-software-using-kde-builder-in-distrobox) - - - -## Build KDE software that’s shipped on the base image -This workflow is used for developing KDE software that’s shipped on the base system, or even Qt. A list of such software [can be found here](https://invent.kde.org/kde-linux/kde-linux-packages/-/blob/master/targets.yaml) (note that “workspace” includes Plasma, KWin, and Plasma-aligned apps such as System Settings and Discover). - -The best way to do this is by using <code>systemd-sysext</code>, which allows overlaying built-from-source content on top of <code>/usr/</code> without impacting the base system. - -### Setup -Run the setup script: - -<pre> -set-up-system-development -</pre> - -### Use -In a nutshell, you’ll compile and install software using <code>kde-builder</code>, then refresh the systemd extension, and then finally restart any services that you changed (e.g. Plasma), or the entire system. - -For example, to compile and test a change to plasma-pa, do the following: - -<pre> -kde-builder plasma-pa -run0 systemd-sysext refresh --always-refresh=yes -systemctl restart --user plasma-plasmashell.service -</pre> - -If you replace a core system component and find that everything is crashing after the refresh is applied, try rebooting in order to fully reload the new dependency in all running software. - -When you’re finished developing or testing the change, disable (“un-merge”) the system extension: - -<pre> -run0 systemd-sysext unmerge -</pre> - -When you’re done with your built-from-source software (e.g. because it was accepted as a patch and merged), delete the installed files: - -<pre> -rm -r ~/kde/usr/* -# When you’re prompted to delete the read-only extension-release.kde file, answer 'n' -</pre> - -## Build KDE app with a Flatpak manifest -To develop or test changes to the app code itself, build the app using <code>flatpak-builder</code>, so that the result is functionally identical to the app’s nightly Flatpak build. - -To develop or test changes to a KDE Framework or other library used by multiple apps, the only relatively painless approach at the moment is to use <code>kde-builder</code> to build them all. See [Developing KDE software that’s shipped on the base image](#build-kde-software-thats-shipped-on-the-base-image). - -### Setup -flatpak-builder will install flatpak packages from the remote flathub-apps-built-locally. This remote is the official Flathub store. - -<pre> -flatpak remote-add --user --if-not-exists flathub-apps-built-locally https://flathub.org/repo/flathub.flatpakrepo -</pre> - -### Make changes to just the app -First check out the source code for the KDE app you’d like to build. For example, here with Filelight: - -<pre> -# Create folder to hold KDE source code. Skippable if it already exists -mkdir -p ~/kde/src/ - -# Go into that folder -cd ~/kde/src/ - -# Download source code for Filelight -git clone [email protected]:utilities/filelight.git - -# Go into Filelight’s source code folder -cd ~/kde/src/filelight - -# Build Filelight as a flatpak -flatpak-builder build --user --install-deps-from=flathub-apps-built-locally --force-clean --ccache --install .flatpak-manifest.json -</pre> - -<code>flatpak-builder</code> will create a flatpak repo and remote named <code>filelight-origin</code> and export the freshly built Filelight flatpak to this flatpak repo. - -Now run it: - -<pre> -org.kde.filelight -</pre> - -For further information, see: -* https://docs.flatpak.org/en/latest/getting-started.html -* https://develop.kde.org/docs/packaging/flatpak/packaging/ - - -## Build any KDE software, using KDE Builder in Distrobox -If you need to work on some KDE software not preinstalled on the base system (so dependencies are also not pre-installed) that also does not or cannot build as a Flatpak, you can build it with <code>kde-builder</code> in a Distrobox: - -<pre> -# As per https://develop.kde.org/docs/getting-started/building/containers-distrobox -distrobox create --image docker.io/archlinux --name kdebuildercontainer --home ~/kdebuildercontainer_home -distrobox enter kdebuildercontainer -run0 pacman -Syu -run0 pacman -S nano -echo 'export PATH="$HOME/.local/bin:$PATH"' | tee --append ~/.{bash,zsh}rc -exit -distrobox enter kdebuildercontainer - -# Install kde-builder as usual. https://develop.kde.org/docs/getting-started/building/kde-builder-setup -</pre>