Craft - KDE Community Wiki
Jump to content
From KDE Community Wiki
Craft is an open source meta-build system and package manager. It manages dependencies and builds libraries and applications from source on Windows, Mac, Linux, FreeBSD and Android.
Setting up Craft
Start crafting on Windows
Start crafting on Linux
Start crafting on macOS
Start crafting on FreeBSD
Start crafting on Android
Common Craft commands
Searching for a package
craft --search
packagename
Installing a package and its dependencies
craft
packagename
Note that installing prebuilt packages (libraries and some apps which are common dependencies of others) won't immediately generate their
source directories
. If you need them, see
Installing a prebuilt package
Uninstalling a package
craft --unmerge
packagename
Updating a package
craft -i
packagename
Updating Craft itself
craft -i craft
Updating Craft's KDE blueprints
craft -i craft-blueprints-kde
Updating all installed packages
craft --upgrade
Changing to the source directory of a package
cs
packagename
Changing to the build directory of a package
cb
packagename
Compiling a package
To compile and install a package for testing after modifying its source code, run
craft --compile --install --qmerge
packagename
Creating an installer
To create a MacOS
.dmg
bundle, Windows
.exe
installer or Linux
.AppImage
for a package, run
craft --package
packagename
When packaging for Windows, the
PackageType
option in
CraftSettings.ini
controls the type of installer created. Read the comments above it for more information.
If the package's source code has been modified, don't forget to
compile and install
it before creating a new installer.
Installing a prebuilt package
Libraries and certain apps which are common dependencies of other packages (such as
Kate
) will be pulled as prebuilt binaries from the "cache"
stored on
and built by KDE's servers, instead of their sources being cloned and built on your system. This is done to shorten compile times. The
--no-cache
option overrides this behavior, in case modifying the sources of prebuilt packages is necessary:
craft -i --no-cache
packagename
Adding new blueprints
If you want to build a new application using Craft, you'll need a blueprint for it and all its dependencies first. Learn more about writing blueprints at
Craft/Blueprints
Advanced tips
Hard-code versions of packages
For non-prebuilt packages, the last release compatible with your environment is built by default. To build a non-default version, run
craft --set version=
versionname
packagename
Replace
versionname
with the desired branch name (like
master
) or a specific version number (like
0.57.0
).
The version can also be set for an entire category, for example, for the KDE Frameworks, run
craft --set version=
versionname
kde/frameworks
Alternatively, you may also edit
BlueprintSettings.ini
[category/packagename]
version
versionname
Using Craft with an IDE
Using Craft with Qt Creator
To compile packages from within Qt Creator, we'll need to start it from a shell with the Craft environment set up:
$ source
CraftRoot
/craft/craftenv.sh
$ qtcreator
Now fire up another shell with the Craft environment set up as well. If you haven't already,
install
the package you want to work on. Now
change to its source directory
and take note of the path you've been switched to.
Back in Qt Creator, press
Ctrl+O
to open a project, and navigate to the aforementioned source directory. Inside of it, select the
CMakeLists.txt
file. Ensure you're looking at the
Projects
tab by pressing
Ctrl+5
and make sure only the kit ending in
in PATH (CraftRoot)
is selected, then press the
Configure Project
button and let Qt Creator finish importing everything.
You can now try to start a build to see if everything went well!
Using Craft with VS Code
Note that this example demonstrates working on
KDEConnect
, but the same instructions should apply to other packages as well.
To use the debugging capabilities of VS Code, we will create a
.code-workspace
file and update it according to our use case. Create
kde.code-workspace
and paste one of the following example workspace configurations into it:
Windows development
Linux development
Now
edit
it according to your setup. Additional information can be found at
Debugging a standalone app with symbols
Craft uses the
RelWithDebInfo
build type by default. As such, every library and executable is compiled with the release symbols stripped from its main file and saved separately in a corresponding
.pdb
file on Windows or
.dSYM
package on MacOS.
These symbols will not be included in the final redistributable package generated by Craft using the
--package
option, however, if
PackageDebugSymbols
is enabled in
CraftSettings.ini
, a separate archive will be created containing all the debug symbols.
If an issue you're trying to debug is specific to the packaged app only, you can use Qt Creator's
Start and Debug External Application
option to run the packaged app and automatically attach to it.
Example for packaged MacOS apps:
In
Local Executable
, provide a path to the executable file inside the
.app
container, such as
/Volumes/External/CraftRoot/build/extragear/kmymoney/archive/Applications/KDE/kmymoney.app/Contents/MacOS/kmymoney
In
Debug information
provide a path to the folder containing the debug symbols package (
kmymoney.app.dSYM
) generated by Craft, such as
/Volumes/External/CraftRoot/build/extragear/kmymoney/image-RelWithDebInfo-master/Applications/KDE
Check
Break at main
if this is your initial setup to make sure everything works as expected
Optionally add the
Source Paths Mapping
under
Preferences -> Debugger
if your local source code location doesn't match the one used to generate the package being debugged, resulting in the
main()
break showing disassembled code.
Troubleshooting
If a package fails to build, you'll probably be greeted with something similar to:
craft warning: while running make cmd: jom
craft warning: Action: compile for libs/qt5/qtbase FAILED
*** Craft all failed: all of libs/qtbase failed after 0:07:25 ***
craft error: fatal error: package libs/qtbase all failed
In order to figure out what failed, grep the command line output for errors, or have a look at the log file located in
$HOME/.craft
on MacOS/Linux and
%USERPROFILE%\.craft
on Windows, which should contain more details. You can additionally grep this file for the phrase
error
, narrowing down your search.
Getting in Touch
Matrix:
#kde-craft:kde.org
(bridged to IRC)
IRC:
#kde-craft
on Libera Chat (
web chat
Bugzilla
Mailing list:
[email protected]
archives
Retrieved from "