Craft
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
Common Craft commands
Searching for a package
craft --search packagename
Installing a package and its dependencies
craft packagename
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 library
When working on a package, you may want to work on one of its libraries as well. To install it, run
craft -i --no-cache libraryname
--no-cache disables the cache for all missing/outdated dependencies.
This will be necessary even if the library is in the source tree of the program you're working on.
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
Packages are installed from the cache by default. To build a non-default version, run
craft --set version=versionname packagename
The version can also be set for an entire category, for example for the KDE Frameworks, run
craft --set version=versionname kde/frameworks
Replace versionname with the desired branch name (like master) or a version number (like 0.57.0). 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 with in PATH (CraftRoot) is selected, then press the Configure Project button and let Qt Creator finish importing it.
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:
Now edit it according to your setup. Additional information can be found at https://code.visualstudio.com/docs/editor/workspaces.
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
.appcontainer, 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)
- Mailing list: [email protected] (subscribe, archives)