Craft: Difference between revisions

From KDE Community Wiki

Latest revision as of 19:12, 8 March 2024

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 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 .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] (subscribe, archives)

Retrieved from "https://community.kde.org/index.php?title=Craft&oldid=100301"

@@ Line 1: / Line 1: @@
-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'' and ''FreeBSD''.
+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 ==
-[https://community.kde.org/Guidelines_and_HOWTOs/Build_from_source/Windows Start crafting on Windows]
+[[Guidelines_and_HOWTOs/Build_from_source/Windows|Start crafting on Windows]]
-[https://community.kde.org/Guidelines_and_HOWTOs/Build_from_source/Mac Start crafting  on Mac]
+[[/Linux|Start crafting on Linux]]
-[https://community.kde.org/Guidelines_and_HOWTOs/Build_from_source/FreeBSD Start crafting  on FreeBSD]
+[[Guidelines and HOWTOs/Build from source/Mac|Start crafting on macOS]]
+[[Guidelines_and_HOWTOs/Build_from_source/FreeBSD|Start crafting on FreeBSD]]
+[https://develop.kde.org/docs/packaging/android/building_applications/ Start crafting on Android]
 == Common Craft commands ==
-Installing a package and its dependencies
+=== Searching for a package ===
-  craft packagename
+  craft --search ''packagename''
-Updating an installed package: Once you have ''packagename'' built, type:
- craft -i packagename
-Switching to the source directory of a package:
- cs packagename
-Switching to the build directory of a package:
- cb packagename
-Just compiling the package (i.e. if you just modified the source code and want to test-compile):
- craft --compile packagename
-Create an installer (or .dmg bundle, ...) for a specific package. The option Packager/PackageType in CraftSettings.ini controls which type of package is created:
- craft --package kdevelop
-Updating Craft itself:
+=== Installing a package and its dependencies ===
-  craft craft
+  craft ''packagename''
-Updating the blueprints:
- craft --fetch craft-blueprints-kde
-== Adding new blueprints ==
+Note that installing prebuilt packages (libraries and some apps which are common dependencies of others) won't immediately generate their [[Craft#Changing to the source directory of a package|source directories]]. If you need them, see [[Craft#Installing a prebuilt package|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 <code>.dmg</code> bundle, Windows <code>.exe</code> installer or Linux <code>.AppImage</code> for a package, run
+ craft --package ''packagename''
+When packaging for Windows, the <code>PackageType</code> option in <code>CraftSettings.ini</code> controls the type of installer created. Read the comments above it for more information.
-Blueprints are stored in separate repositories. At the moment there are these repositories:
+If the package's source code has been modified, don't forget to [[Craft#Compiling a package|compile and install]] it before creating a new installer.
-* https://cgit.kde.org/craft-blueprints-kde.git/tree/ (enabled by default)
-To navigate to this repository on your local file system, type in:
+=== Installing a prebuilt package ===
-  cs craft-blueprints-kde
+Libraries and certain apps which are common dependencies of other packages (such as [[Kate]]) will be pulled as prebuilt binaries from the "cache" [https://files.kde.org/craft/ 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 <code>--no-cache</code> option overrides this behavior, in case modifying the sources of prebuilt packages is necessary:
+  craft -i --no-cache ''packagename''
-Open a file browser in that folder and start adding new recipes by copying from existing ones. Note that the name of the package folder needs to match the blueprint name -- an example would be "kdegraphics-mobipocket\kdegraphics-mobipocket.py"
+== 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 ==
-=== Hardcode versions of packages ===
+=== 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 <code>''versionname''</code> with the desired branch name (like <code>master</code>) or a specific version number (like <code>0.57.0</code>).
-To build a non default version, append a line to $craftRoot/etc/CraftSettings.ini of form:
+The version can also be set for an entire category, for example, for the KDE Frameworks, run
+ craft --set version=''versionname'' kde/frameworks
- [BlueprintVersions]
+Alternatively, you may also edit <code>BlueprintSettings.ini</code>:
- category/packagename = branch
+<syntaxhighlight lang="ini">
+[category/packagename]
+version = versionname
+</syntaxhighlight>
-For example, to install master branch of kdevelop, the line to be appended should look like:
+== Using Craft with an IDE ==
-  [BlueprintVersions]
+=== Using Craft with Qt Creator ===
-  frameworks/khtml = master
+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
-Or if you want to hardcode the version of a "meta" group containing a ''version.ini'':
+Now fire up another shell with the Craft environment set up as well. If you haven't already, [[Craft#Installing a package and its dependencies|install]] the package you want to work on. Now [[Craft#Changing to the source directory of a package|change to its source directory]] and take note of the path you've been switched to.
- [BlueprintVersions]
- Qt5 = 5.9
-=== Finding packages ===
+Back in Qt Creator, press <code>Ctrl+O</code> to open a project, and navigate to the aforementioned source directory. Inside of it, select the <code>CMakeLists.txt</code> file. Ensure you're looking at the ''Projects'' tab by pressing <code>Ctrl+5</code> and make sure only the kit ending in <code>in PATH (CraftRoot)</code> is selected, then press the ''Configure Project'' button and let Qt Creator finish importing everything.
-To find the package you want to install, run this:
- craft --search packagename
-The second line of the output will be of form: <tt>category/packagename</tt>
+You can now try to start a build to see if everything went well!
-=== Using the Qt SDK===
+=== Using Craft with VS Code ===
-This will skip all Qt packages and use the official Qt builds instead.
+Note that this example demonstrates working on [[KDEConnect]], but the same instructions should apply to other packages as well.
-It will work fine for most CMake based recipes but definitely cause problems with QMake based projects.
-You will of course also miss all patches we usually apply to Qt.
-This is only recommended when you know what you are doing and you won't get support for in our channel.
-To activate the SDK mode adapt the [QtSDK] section in your etc/kdesettings.ini to something like:
+To use the debugging capabilities of VS Code, we will create a <code>.code-workspace</code> file and update it according to our use case. Create <code>kde.code-workspace</code> and paste one of the following example workspace configurations into it:
-    [QtSDK]
+:[https://gist.github.com/tm9k1/2312937dbdda73b366d02829078540af Windows development]
-    ## Whether to use prebuild Qt binaries.
+:[https://gist.github.com/tm9k1/6267b5013e4415a3bd02a026bb0c6393 Linux development]
-    Enabled = True
-    ## The path to the Qt sdk.
-    Path = C:\Qt
-    ## The version of Qt.
-    Version = 5.9
-    ## The compiler version, if you are not sure what to use, have a look into the derectory set in QtSDK/Path.
-    ## The compiler must be of the same type as General/KDECOMPILER.
-    ## If you are using mingw please make sure you have installed the mingw using the Qt installer.
-    Compiler = msvc2017_64
-== Troubleshooting ==
+Now [https://gist.github.com/tm9k1/2312937dbdda73b366d02829078540af?permalink_comment_id=3762477#gistcomment-3762477 edit] it according to your setup. Additional information can be found at https://code.visualstudio.com/docs/editor/workspaces.
-If a package fails to build, you'll be greeted with something like:
+== Debugging a standalone app with symbols ==
+Craft uses the <code>RelWithDebInfo</code> 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 <code>.pdb</code> file on Windows or <code>.dSYM</code> package on MacOS.
-  ...
+These symbols will not be included in the final redistributable package generated by Craft using the <code>--package</code> option, however, if <code>PackageDebugSymbols</code> is enabled in <code>CraftSettings.ini</code>, a separate archive will be created containing all the debug symbols.
-  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 ''above'' for errors.
+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.
-Or have a look at the log file located in <tt>$HOME/.craft</tt> (<tt>%USERPROFILE%\.craft</tt> on Windows) which will contain much more details.
+Example for packaged MacOS apps:
+* In ''Local Executable'', provide a path to the executable file inside the <code>.app</code> container, such as <code>/Volumes/External/CraftRoot/build/extragear/kmymoney/archive/Applications/KDE/kmymoney.app/Contents/MacOS/kmymoney</code>
+* In ''Debug information'' provide a path to the folder containing the debug symbols package (<code>kmymoney.app.dSYM</code>) generated by Craft, such as <code>/Volumes/External/CraftRoot/build/extragear/kmymoney/image-RelWithDebInfo-master/Applications/KDE</code>
+* 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 <code>main()</code> break showing disassembled code.
-Search for "error", or "error:" in the file.
+== 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
-== News ==
+In order to figure out what failed, grep the command line output for errors, or have a look at the log file located in <code>$HOME/.craft</code> on MacOS/Linux and <code>%USERPROFILE%\.craft</code> on Windows, which should contain more details. You can additionally grep this file for the phrase <code>error</code>, narrowing down your search.
-[https://the2ring.blogspot.de/search/label/Craft Blog]
 == Getting in Touch ==
+* Matrix: [https://matrix.to/#/#kde-craft:kde.org #kde-craft:kde.org] (bridged to IRC)
-* IRC: [irc://irc.freenode.net/kde-windows #kde-windows] on freenode (join via web chat: http://webchat.freenode.net/?channels=kde-windows)
+* IRC: [irc://irc.libera.chat/kde-craft #kde-craft] on Libera Chat ([http://web.libera.chat/#kde-craft web chat])
-* [https://bugs.kde.org/enter_bug.cgi?product=Craft Report bugs]
+* [https://bugs.kde.org/enter_bug.cgi?product=Craft Bugzilla]
 * Mailing list:  [mailto:[email protected] [email protected]] ([https://mail.kde.org/mailman/listinfo/kde-windows  subscribe], [http://lists.kde.org/?l=kde-windows&r=1&w=2 archives])