Get Involved/development/Mac: Difference between revisions

From KDE Community Wiki
(Add screen recording version)
(Newer screen recording)
 
(13 intermediate revisions by 2 users not shown)
Line 1: Line 1:
A screen recording version is available https://www.youtube.com/watch?v=kjFUfZ3Lupo
A screen recording version is available https://www.youtube.com/watch?v=8WCVySIai_c


== Overview ==
== KDE Craft ==


Several methods of building KDE / KF5 on Mac are available, and it is not firmly established, yet, which one is "best". The two main approaches are using either a "stock" version of Qt, or a "patched" Qt. The latter has several patches meant to make KF5-applications work better on Mac. It also follows the file system layout of KDE on Linux, which should mean that KDE applications will be more likely to work correctly, without adjustments.
The recommended way to build KDE source code on macOS is to use the build framework KDE Craft.


There is some hope that the required patches will eventually become available in official Qt packages, but this is not the case as of this writing. The main drawback with this is that Qt has to be compiled on your computer, adding hours to your setup time. The main advantage is that most things can be expected to work out of the box.
See [[Craft]] and [[Mac]].


== Installation using patched version of Qt and MacPorts ==
=== Install KDE Craft ===
Install [https://www.python.org/downloads/ Python 3]
 
Install [https://developer.apple.com/xcode/ XCode] (at least developper command-line tools suffice):
xcode-select --install
 
Install KDE Craft from GitHub.
curl https://raw.githubusercontent.com/KDE/craft/master/setup/CraftBootstrap.py -o setup.py && python3 setup.py --prefix ~/CraftRoot
 
'''Note''': At the time of this writing, with a fresh installation of Python 3.7 or 3.8, this command will fail with "certificate verify failed: unable to get local issuer certificate". To fix this, run the following, ''once'':
  "/Applications/Python [Version]/Install Certificates.command"
 
=== Use KDE Craft ===
Every time you want to use KDE Craft in a new shell, you need to set up the KDE Craft environment, first:
source ~/CraftRoot/craft/craftenv.sh
 
In this shell, now craft is usable, e.g. to build the KDE desktop calculator app kcalc with all dependencies:
craft kcalc
 
If KDE Craft succeeds, it will build kcalc from source code and run the equivalent of ninja install. At the end of the output from the command line <code>craft kcalc</code> you can see something like:
/Users/administrator/CraftRoot/build/kde/kdeutils/kcalc/image-RelWithDebInfo-23.08.1/Applications/KDE/kcalc.app/Contents/MacOS/kcalc
 
You can now run the macOS GUI app kcalc either from the terminal:
open /Users/administrator/CraftRoot/build/kde/kdeutils/kcalc/image-RelWithDebInfo-23.08.1/Applications/KDE/kcalc.app
 
Or you can open the macOS app Finder which is the macOS file manager, from Finder main menu > Go > Go to Folder... > paste <code>/Users/administrator/CraftRoot/build/kde/kdeutils/kcalc/image-RelWithDebInfo-23.08.1/Applications/KDE</code>, press the Go button. It will show the app kcalc.app, double click on the app kcalc.app.
 
Run:
lsof | grep kcalc
 
It will output something like:
kcalc    32943 administrator    0r      CHR                3,2      0t0                324 /dev/null
kcalc    32943 administrator    1u      CHR                3,2      0t0                324 /dev/null
kcalc    32943 administrator    2u      CHR                3,2      0t0                324 /dev/null
 
That means that when you open kcalc.app from Finder or from the command line using the <code>open</code> command line, the STDOUT and STDERR of kcalc are connected to /dev/null, not to the terminal.
 
In order to have the standard streams of kcalc connected to the terminal, run:
/Users/administrator/CraftRoot/build/kde/kdeutils/kcalc/image-RelWithDebInfo-23.08.1/Applications/KDE/kcalc.app/Contents/MacOS/kcalc
 
In order to see Qt logs in the terminal (STDOUT), as per [[Guidelines_and_HOWTOs/Debugging/Using_Error_Messages]] run:
QT_LOGGING_RULES="*=true;qt.*=false" /Users/administrator/CraftRoot/build/kde/kdeutils/kcalc/image-RelWithDebInfo-23.08.1/Applications/KDE/kcalc.app/Contents/MacOS/kcalc
 
You can create a .dmg bundle:
craft --package kcalc
 
If the generated dmg file does not work correctly or if the dmg file contains files which are not needed, please help fixing these issues.
 
=== Case sensitive filesystem considerations ===
 
When building craft packages on case-sensitive filesystem, you will see errors in packages referencing some of the KF5 libraries:
    fatal error: 'sonnet/highlighter.h' file not found
 
This is a known upstream issue: https://bugs.kde.org/show_bug.cgi?id=419167
 
NOTE: The bug was closed due to a lack of information. If you run into this issue, please reopen it!
 
The workaround for now is either to create and mount a case-insensitive disk image for craft usage or to manually create symlinks as needed.
 
== Alternative to KDE Craft. Installation using a patched version of Qt and MacPorts ==


* [https://guide.macports.org/#installing.macports Install Macports]
* [https://guide.macports.org/#installing.macports Install Macports]
Line 35: Line 94:
  port variants kf5-kate      # list available variants
  port variants kf5-kate      # list available variants
  port notes kf5-kate            # show any notes
  port notes kf5-kate            # show any notes
== Installation using Craft ==
* Install [https://www.python.org/downloads/ Python 3]
* Install [https://developer.apple.com/xcode/ XCode] (at least developper command-line tools suffice):
xcode-select --install
=== Install Craft ===
  curl https://raw.githubusercontent.com/KDE/craft/master/setup/CraftBootstrap.py -o setup.py && python3 setup.py --prefix ~/CraftRoot
'''Note''': At the time of this writing, with a fresh installation of Python 3.7 or 3.8, this command will fail with "certificate verify failed: unable to get local issuer certificate". To fix this, run the following, ''once'':
  "/Applications/Python [Version]/Install Certificates.command"
=== Using craft ===
* Every time you want to use craft in a new shell, you need to set up the craft environment, first:
source ~/CraftRoot/craft/craftenv.sh
* In this shell, now craft is usable, e.g. to build Kate with all dependencies:
craft kate
=== Case sensitive filesystem considerations ===
When building craft packages on case-sensitive filesystem, you will see errors in packages referencing some of the KF5 libraries:
    fatal error: 'sonnet/highlighter.h' file not found
This is a known upstream issue: https://bugs.kde.org/show_bug.cgi?id=419167
The workaround for now is either to create and mount a case-insensitive disk image for craft usage or to manually create symlinks as needed.

Latest revision as of 18:50, 12 June 2024

A screen recording version is available https://www.youtube.com/watch?v=8WCVySIai_c

KDE Craft

The recommended way to build KDE source code on macOS is to use the build framework KDE Craft.

See Craft and Mac.

Install KDE Craft

Install Python 3

Install XCode (at least developper command-line tools suffice):

xcode-select --install

Install KDE Craft from GitHub.

curl https://raw.githubusercontent.com/KDE/craft/master/setup/CraftBootstrap.py -o setup.py && python3 setup.py --prefix ~/CraftRoot

Note: At the time of this writing, with a fresh installation of Python 3.7 or 3.8, this command will fail with "certificate verify failed: unable to get local issuer certificate". To fix this, run the following, once:

 "/Applications/Python [Version]/Install Certificates.command"

Use KDE Craft

Every time you want to use KDE Craft in a new shell, you need to set up the KDE Craft environment, first:

source ~/CraftRoot/craft/craftenv.sh

In this shell, now craft is usable, e.g. to build the KDE desktop calculator app kcalc with all dependencies:

craft kcalc

If KDE Craft succeeds, it will build kcalc from source code and run the equivalent of ninja install. At the end of the output from the command line craft kcalc you can see something like:

/Users/administrator/CraftRoot/build/kde/kdeutils/kcalc/image-RelWithDebInfo-23.08.1/Applications/KDE/kcalc.app/Contents/MacOS/kcalc

You can now run the macOS GUI app kcalc either from the terminal:

open /Users/administrator/CraftRoot/build/kde/kdeutils/kcalc/image-RelWithDebInfo-23.08.1/Applications/KDE/kcalc.app

Or you can open the macOS app Finder which is the macOS file manager, from Finder main menu > Go > Go to Folder... > paste /Users/administrator/CraftRoot/build/kde/kdeutils/kcalc/image-RelWithDebInfo-23.08.1/Applications/KDE, press the Go button. It will show the app kcalc.app, double click on the app kcalc.app.

Run:

lsof | grep kcalc

It will output something like:

kcalc     32943 administrator    0r      CHR                3,2       0t0                 324 /dev/null
kcalc     32943 administrator    1u      CHR                3,2       0t0                 324 /dev/null
kcalc     32943 administrator    2u      CHR                3,2       0t0                 324 /dev/null

That means that when you open kcalc.app from Finder or from the command line using the open command line, the STDOUT and STDERR of kcalc are connected to /dev/null, not to the terminal.

In order to have the standard streams of kcalc connected to the terminal, run:

/Users/administrator/CraftRoot/build/kde/kdeutils/kcalc/image-RelWithDebInfo-23.08.1/Applications/KDE/kcalc.app/Contents/MacOS/kcalc

In order to see Qt logs in the terminal (STDOUT), as per Guidelines_and_HOWTOs/Debugging/Using_Error_Messages run:

QT_LOGGING_RULES="*=true;qt.*=false" /Users/administrator/CraftRoot/build/kde/kdeutils/kcalc/image-RelWithDebInfo-23.08.1/Applications/KDE/kcalc.app/Contents/MacOS/kcalc

You can create a .dmg bundle:

craft --package kcalc

If the generated dmg file does not work correctly or if the dmg file contains files which are not needed, please help fixing these issues.

Case sensitive filesystem considerations

When building craft packages on case-sensitive filesystem, you will see errors in packages referencing some of the KF5 libraries:

   fatal error: 'sonnet/highlighter.h' file not found

This is a known upstream issue: https://bugs.kde.org/show_bug.cgi?id=419167

NOTE: The bug was closed due to a lack of information. If you run into this issue, please reopen it!

The workaround for now is either to create and mount a case-insensitive disk image for craft usage or to manually create symlinks as needed.

Alternative to KDE Craft. Installation using a patched version of Qt and MacPorts

  • Install Macports
    • Note: If you have an existing installation of MacPorts and installed ports that depend on Qt, see this mail.
  • Install git, if you don't have it yet:
sudo port install git 
  • Get the ports tree for patched qt and frameworks:
# We assume you're doing this in your home directory
cd ~
git clone https://github.com/mkae/macstrop.git
# create index
cd macstrop
portindex
  • Register the new ports with Macports. To do so, edit ${prefix}/etc/macports/sources.conf, where prefix is the root path of your MacPorts installation (/opt/local by default). Add the following line above any other path specifications (thus making sure it will take precedence):
file:///Users/YourUserName/macstrop

It is recommended that you build the patched Qt before any frameworks, in order to make extra sure all dependencies are resolved, correctly:

sudo port install qt5-kde

You can now start building frameworks or applications (if already packaged), using e.g.

sudo port install kf5-parts
sudo port install kf5-kate
sudo port install kf5-frameworkintegration     # will get the most common frameworks in one go

Many ports have additional variants, such as "+docs" for handbooks / API documentation:

sudo port install kf5-kate +docs
port variants kf5-kate       # list available variants
port notes kf5-kate            # show any notes