Jump to content

Craft: Difference between revisions

From KDE Community Wiki
← Older editNewer edit →
Nmariusp (talk | contribs)
991 edits
KDE Craft Qt6 KDE Frameworks 6
tidying up
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'', ''FreeBSD'' and ''Android''.
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 ==
== Setting up Craft ==
Line 15: Line 15:
== Common Craft commands ==
== Common Craft commands ==


====== Searching for a package ======
=== Searching for a package ===
  craft --search packagename
  craft --search ''packagename''


====== Installing a package (and dependencies) ======
=== Installing a package and its dependencies ===
  craft packagename
  craft ''packagename''


====== Uninstalling a package ======
=== Uninstalling a package ===
  craft --unmerge packagename
  craft --unmerge ''packagename''


====== Updating a package ======
=== Updating a package ===
  craft -i packagename
  craft -i ''packagename''


====== Switching to the source directory of a package ======
==== Updating Craft itself ====
cs packagename
 
====== Switching to the build directory of a package ======
cb packagename
 
====== Compiling a package ======
if you just modified the source code and want to test-compile:
craft --compile packagename
 
====== Creating an installer ======
 
To create a <code>.dmg</code> bundle, <code>.exe</code> setup, ... for a specific package run
craft --package packagename
The option <code>Packager/PackageType</code> in <tt>CraftSettings.ini</tt> controls which type of installer is created.
 
If you have modified the source code, then run
craft --compile --install --qmerge packagename
before creating the installer.
 
==== Developing with Craft ====
 
====== Installing a library ======
When developing on a specific application, you may want to develop on its library as well.
  craft -i --no-cache <somelib>
<code>--no-cache</code> also disables the cache for all missing/outdated dependencies.
 
This will also be necessary if the library is in the sourcetree of the program you try to develop on.
 
====== Testing new changes ======
For the applications to run with changes to the source of the package:
  craft --compile --install --qmerge <somelib>
 
===== Examples =====
 
====== Updating Craft itself ======
  craft -i craft
  craft -i craft


====== Updating the blueprints ======
==== Updating Craft's KDE blueprints ====
  craft -i craft-blueprints-kde
  craft -i craft-blueprints-kde


====== Updating all installed packages ======
==== Updating all installed packages ====
  craft --upgrade
  craft --upgrade


== Adding new blueprints ==
=== Changing to the source directory of a package ===
If you want to build an application by Craft you need a blueprint for it (and all its dependencies) first.
cs ''packagename''


Learn about how to write blueprints here: [[Craft/Blueprints]]
=== Changing to the build directory of a package ===
cb ''packagename''


== KDE Craft Qt6 KDE Frameworks 6 ==
=== Compiling a package ===
To compile and install a package for testing after modifying its source code, run
craft --compile --install --qmerge ''packagename''


Until there are available source code release tarballs for KDE Frameworks 6, KDE Plasma 6 and KDE Gear 6, we need to build from git.
=== 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''


<pre>
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.
craft --set qtMajorVersion=6 libs/qt
craft --set version=master kde/frameworks
craft --set version=master kcalc
craft kcalc
</pre>


== Advanced tips ==
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.


=== Hardcode versions of packages ===
=== Installing a library ===
Packages are by-default installed from the cache. To build a non default version (or to build from master)
When working on a package, you may want to work on one of its libraries as well. To install it, run
<pre> craft --set version=some_version packagename</pre>
craft -i --no-cache ''libraryname''
The version can also be set for an entire category.
<code>--no-cache</code> disables the cache for all missing/outdated dependencies.
For example you can build the KDE Frameworks from a specific version:
<pre> craft --set version=some_version kde/frameworks</pre>


Here, replace <code>some_version</code> with the branch name of the source git repository of the package (like <code>master</code>) or version number (for eg: 0.57.0, 0.58.0).
This will be necessary even if the library is in the source tree of the program you're working on.
Alternatively ,edit <tt>$CraftRoot/etc/BlueprintSettings.ini</tt> and add:


<pre> [category/packagename]
== Adding new blueprints ==
version = branch
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]].
</pre>


Specifically for Qt6 setup, the following is available <pre> craft --set qtMajorVersion=6 libs/qt</pre>
== Advanced tips ==
and on top of that, for KF6 master, <pre> craft --set version=master kde/frameworks</pre>. As of medio August 2023, qt-libs/phonon is also needs master.


====== Examples ======
=== 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


For example, to install master branch of khtml, the line to be appended should look like:
Replace <code>''versionname''</code> with the desired branch name (like <code>master</code>) or a version number (like <code>0.57.0</code>). Alternatively, you may also edit <code>BlueprintSettings.ini</code>:
<syntaxhighlight lang="ini">
[category/packagename]
version = versionname
</syntaxhighlight>


[frameworks/khtml]
== Using Craft with an IDE ==
version = master


To change the version of all packages of a category, like <code>libs/qt5</code> add
=== 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


  [libs/qt5]
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.
  version = 5.9.3


==Using Craft with an IDE==
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 with <code>in PATH (CraftRoot)</code> is selected, then press the ''Configure Project'' button and let Qt Creator finish importing it.


===Using Craft with Qt Creator===
You can now try to start a build to see if everything went well!


====Windows====
=== Using Craft with VS Code ===
To compile from within Qt Creator, I need to set up a kit.
Note that this example demonstrates working on [[KDEConnect]], but the same instructions should apply to other packages as well.
This is an example for mingw64.
* Add a cmake if none is set: C:\CraftRoot\dev-utils\cmake\bin\cmake.exe
* Add a debugger: C:\CraftRoot\mingw64\bin\gdb.exe
* Add a C++ compiler and a C compiler. Both: C:\CraftRoot\mingw64\bin\gcc.exe
** Ensure that the ABI is correctly set
* Add a Qt: C:\CraftRoot\bin\qmake.exe
* Add a kit with all of the above
* Edit the Environment:
** '''PATH=$(PATH);C:\CraftRoot\bin;C:\CraftRoot\dev-utils\bin\; C:\CraftRoot\mingw64\bin'''
* Use the kit on a project


* Setup cmake configuration (all case):
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:
** Extend CMAKE_PREFIX_PATH, add the Craft prefix path (ie: CMAKE_PREFIX_PATH:STRING=%{Qt:QT_INSTALL_PREFIX};C:\CraftRoot)
:[https://gist.github.com/tm9k1/2312937dbdda73b366d02829078540af Windows development]
:[https://gist.github.com/tm9k1/6267b5013e4415a3bd02a026bb0c6393 Linux development]


====MacOS====
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.
To be able to use Craft libs in your cmake project from QtCreator follow these steps:
* If the QtVersion used by Craft is not already registered in QtC, then create a new QtVersion by pointing it to the qmake used by Craft
* Create a new kit by duplicating an existing one or creating a new one from scratch
* Setup properties of the kit (for from scratch kit):
** Set cmake binary to the one used by Craft
** Set debugger binary to the one used by Craft
** Set C++ and C compiler to the one used by Craft
** Select the correct QtVersion
** Ensure abi is correct
* Setup cmake configuration (all case):
** Extend CMAKE_PREFIX_PATH, add the Craft prefix path (ie: CMAKE_PREFIX_PATH:STRING=%{Qt:QT_INSTALL_PREFIX};/Volumes/Projects/Developers/Craft)
* Edit the Environment:
** '''PATH=$(PATH):~/CraftRoot/bin:~/CraftRoot/dev-utils/bin/'''
** '''QT_PLUGIN_PATH=~/CraftRoot/bin/plugins'''
* Apply, and now use this Kit for your cmake project
 
===Using Craft with VS Code (or Code-OSS)===
{{Warning|This guide expects that you can successfully build the source code and test any changes to it.}}
 
Developing KDE Connect with VSCode is quite simple but can be tricky for new contributors. To use the debugging capabilities of VSCode, we will create a .code-workspace file and update it according to our own use case.
 
Create a file <code>kde.code-workspace</code> and copy the contents below to it:
 
<syntaxhighlight lang="JSON">
{
"folders": [
{
"name": "kdeconnect-kde",
"path": "FIX_ME-1"
}
],
"launch": {
"configurations": [
{
"name": "KDE C Daemon",
"type": "cppvsdbg",
"request": "launch",
"program": "FIX_ME-2",
"args": [],
"cwd": "${fileWorkspaceFolder}",
"stopAtEntry": false,
"preLaunchTask": "Build",
"console": "internalConsole",
"internalConsoleOptions": "openOnSessionStart",
"sourceFileMap": {
"FIX_ME-3": "FIX_ME-4"
}
}
],
"compounds": []
},
"tasks": {
"tasks": [
{
"label": "Build",
"type": "shell",
"command": "FIX_ME-5",
"args": [],
"runOptions": {
"reevaluateOnRerun": true
},
"dependsOn": "Cleanup"
},
{
"label": "Cleanup",
"type": "shell",
"command": "FIX_ME-6",
"args": [],
"runOptions": {
"reevaluateOnRerun": true
}
}
]
},
"settings": {
"[cpp]": {
"editor.wordBasedSuggestions": false,
"editor.suggest.insertMode": "replace",
"editor.semanticHighlighting.enabled": true,
"editor.quickSuggestions": true
},
"C_Cpp.default.includePath": [
"FIX_ME-7"
],
"C_Cpp.default.defines": [
"FIX_ME-8"
],
"files.associations": {
"qdebug": "cpp",
"qstandardpaths": "cpp",
"qicon": "cpp",
"qfile": "cpp"
}
}
}
 
</syntaxhighlight>
 
Now, update the following strings according to your dev env:
 
# "FIX_ME-1"    - "path/to/kdeconnect-kde/repository"
# "FIX_ME-2"    - "path/to/built/bin/kdeconnectd"
# "FIX_ME-3"    - "source/path/picked_up/incorrectly/by/the/debugger"
# "FIX_ME-4"    - "alternate/path/to/pick_up"
# "FIX_ME-5"    - "command_to_build_your_project"
# "FIX_ME-6"    - "cleanup_any_files_or_running_processes_before_Build"
# "FIX_ME-7"    - "additional/paths/to/files/to_include/by/IDE"
# "FIX_ME-8"    - "ANY_DEFINES_SPECIFIC_TO_YOUR_BUILD_ENV"
 
Example workspace files :
<br/>
# [https://gist.github.com/tm9k1/2312937dbdda73b366d02829078540af Windows dev] (uses [https://community.kde.org/craft Craft])
# [https://gist.github.com/tm9k1/6267b5013e4415a3bd02a026bb0c6393 Linux dev] (uses [https://community.kde.org/craft Craft])
 
More info at: https://code.visualstudio.com/docs/editor/workspaces


== Debugging a standalone app with symbols ==
== Debugging a standalone app with symbols ==
Craft by default uses RelWithDebInfo build type. As such, each library and executable is compiled with the release symbols stripped from the main file and saved separately in a corresponding .pdb file on Windows and .dSYM package on Mac.  
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.  


Those symbols will not be included in a final redistributable package generated by craft (--package option). However, if PackageDebugSymbols is enabled in CraftSettings.ini, a separate archive will be created will all the debug symbols combined.
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.


If an issue you're trying to debug is specific to a packaged app only, you can use Qt Creator's Debug -> Start and Debug External Application option to run the packaged app and automatically attach to it:
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.


* In "Local Executable" provide a path to executable file inside the .app container, e.g. /Volumes/External/CraftRoot/build/extragear/kmymoney/archive/Applications/KDE/kmymoney.app/Contents/MacOS/kmymoney
Example for packaged MacOS apps:
* In "Debug information" provide a path to a folder containing the debug symbols package (kmymoney.app.dSYM) generated by craft, e.g. /Volumes/External/CraftRoot/build/extragear/kmymoney/image-RelWithDebInfo-master/Applications/KDE  
* 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>
* check "Break at main" if it's your initial setup to make sure everything works as expected
* 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>
* Optionally add the Source Paths Mapping (Preferences -> Debugger) if your local source code location doesn't match the one used to generate the package debugged, resulting in the main() break showing a disassembled 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.


== Troubleshooting ==
== 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


If a package fails to build, you'll be greeted with something like:
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.
 
  ...
  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.
 
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.
 
Search for "error", or "error:" in the file.
 
== News ==
[https://the2ring.blogspot.de/search/label/Craft Blog]


== Getting in Touch ==
== Getting in Touch ==
* Matrix: [https://matrix.to/#/#kde-craft:kde.org #kde-craft:kde.org] (bridged to IRC)


* IRC: [irc://irc.libera.chat/kde-craft #kde-craft] on Libera Chat (join via web chat: http://web.libera.chat/#kde-craft)
* 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])
* 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])

Revision as of 15:24, 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

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:

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

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