### Install Package from Directory or Archive

Source: https://context7.com/kde/kpackage/llms.txt

Installs a package from a local directory or a compressed archive file.

```bash
kpackagetool6 -t Plasma/Applet -i /path/to/my-applet/
```

```bash
kpackagetool6 -t Plasma/Theme -i /path/to/my-theme.tar.gz
```

--------------------------------

### Install a Package using PackageJob

Source: https://context7.com/kde/kpackage/llms.txt

Use KPackage::PackageJob::install to asynchronously install a package from a local file or directory. Connect to the KJob::result signal to handle success or failure, including specific error codes like PackageAlreadyInstalledError.

```cpp
#include <KPackage/PackageJob>
#include <KPackage/Package>
#include <KJob>
#include <QDebug>
#include <QCoreApplication>

// Install a package from a local file or directory
void installPackage()
{
    QString packagePath = QStringLiteral("/path/to/my-theme.tar.gz");
    QString packageType = QStringLiteral("Plasma/Theme");

    // Optional: specify custom installation root (defaults to type's default root)
    QString customRoot = QString(); // Use default: ~/.local/share/plasma/desktoptheme/

    KPackage::PackageJob *job = KPackage::PackageJob::install(packageType, packagePath, customRoot);

    QObject::connect(job, &KJob::result, [job]() {
        if (job->error() == KJob::NoError) {
            KPackage::Package installed = job->package();
            qDebug() << "Successfully installed:" << installed.metadata().name();
            qDebug() << "Installed to:" << installed.path();
        } else {
            qDebug() << "Installation failed:" << job->errorString();

            // Handle specific error codes
            switch (job->error()) {
                case KPackage::PackageJob::PackageAlreadyInstalledError:
                    qDebug() << "Package already installed, use update() instead";
                    break;
                case KPackage::PackageJob::PluginIdInvalidError:
                    qDebug() << "Invalid plugin ID in metadata.json";
                    break;
                case KPackage::PackageJob::PackageFileNotFoundError:
                    qDebug() << "Package file not found";
                    break;
                default:
                    break;
            }
        }
        QCoreApplication::quit();
    });
}

```

--------------------------------

### Initialize and Use PackageLoader

Source: https://context7.com/kde/kpackage/llms.txt

Demonstrates how to get the singleton instance of PackageLoader and use it to load packages by type and set their paths.

```cpp
#include <KPackage/PackageLoader>
#include <KPackage/Package>
#include <KPluginMetaData>
#include <QDebug>

// Get the singleton instance
KPackage::PackageLoader *loader = KPackage::PackageLoader::self();

// Load a blank package of a specific type (no path set yet)
KPackage::Package package = loader->loadPackage(QStringLiteral("Plasma/Applet"));

// Set the path to a specific package by plugin ID
package.setPath(QStringLiteral("org.kde.plasma.digitalclock"));
if (package.isValid()) {
    qDebug() << "Loaded:" << package.metadata().name();
}
```

--------------------------------

### Install Package Globally

Source: https://context7.com/kde/kpackage/llms.txt

Installs a package for all users. This operation requires root privileges.

```bash
sudo kpackagetool6 -t Plasma/Theme -g -i /path/to/theme/
```

--------------------------------

### List Installed Packages

Source: https://context7.com/kde/kpackage/llms.txt

Lists installed packages of a specific type. Use '-l' for a more detailed list.

```bash
kpackagetool6 -t Plasma/Applet --list
```

```bash
kpackagetool6 -t Plasma/Theme -l
```

--------------------------------

### Get Full Package Objects and Access Files

Source: https://context7.com/kde/kpackage/llms.txt

Illustrates how to retrieve full KPackage::Package objects instead of just metadata, and how to access files within a package.

```cpp
// Get full Package objects instead of just metadata
QList<KPackage::Package> packages = loader->listKPackages(QStringLiteral("Plasma/Applet"));
for (const KPackage::Package &pkg : packages) {
    qDebug() << pkg.metadata().pluginId() << "at" << pkg.path();
    // Access files within each package
    QString mainScript = pkg.filePath("mainscript");
}
```

--------------------------------

### Install KF6Package Targets

Source: https://github.com/kde/kpackage/blob/master/src/kpackage/CMakeLists.txt

Installs the KF6Package targets and related export files for build system integration.

```cmake
install(TARGETS KF6Package EXPORT KF6PackageTargets ${KF_INSTALL_TARGETS_DEFAULT_ARGS})
if (NOT BUILD_SHARED_LIBS)
    install(TARGETS kpackage_common_STATIC EXPORT KF6PackageTargets ${KF_INSTALL_TARGETS_DEFAULT_ARGS})
endif()
```

--------------------------------

### Install kpackagetool6 Target

Source: https://github.com/kde/kpackage/blob/master/src/kpackagetool/CMakeLists.txt

Installs the kpackagetool6 target and its export definitions.

```cmake
install(TARGETS kpackagetool6 EXPORT KF6PackageToolsTargets ${KF_INSTALL_TARGETS_DEFAULT_ARGS})
```

--------------------------------

### Install KPackage Logging Categories

Source: https://github.com/kde/kpackage/blob/master/src/CMakeLists.txt

Installs KPackage logging categories using the ecm_qt_install_logging_categories CMake function. Requires KPackage export and specifies the destination directory.

```cmake
ecm_qt_install_logging_categories(
    EXPORT KPACKAGE
    FILES kpackage.categories
    DESTINATION ${KDE_INSTALL_LOGGINGCATEGORIESDIR}
)
```

--------------------------------

### Install Package Headers

Source: https://github.com/kde/kpackage/blob/master/src/kpackage/CMakeLists.txt

Installs package-related header files, including export headers, to the development destination.

```cmake
install(FILES
        ${Package_HEADERS}
        ${CMAKE_CURRENT_BINARY_DIR}/kpackage/package_export.h
        DESTINATION ${KDE_INSTALL_INCLUDEDIR_KF}/KPackage/kpackage COMPONENT Devel)

install(FILES
        ${Package_CamelCase_HEADERS}
        DESTINATION ${KDE_INSTALL_INCLUDEDIR_KF}/KPackage/KPackage COMPONENT Devel)
```

--------------------------------

### KPackage Metadata File Example

Source: https://context7.com/kde/kpackage/llms.txt

The metadata.json file describes a KPackage using the KPluginMetaData format. It includes essential information like Id, Name, Description, Authors, License, Version, and Category, with support for translations.

```json
{
    "KPlugin": {
        "Id": "org.kde.mypackage",
        "Name": "My Package",
        "Name[de]": "Mein Paket",
        "Name[fr]": "Mon paquet",
        "Description": "A sample KPackage with translations",
        "Description[de]": "Ein Beispiel-KPackage mit Übersetzungen",
        "Icon": "preferences-desktop-theme",
        "Authors": [
            {
                "Name": "Developer Name",
                "Email": "developer@example.org"
            }
        ],
        "License": "GPL-2.0-or-later",
        "Version": "1.0.0",
        "Website": "https://example.org/mypackage",
        "Category": "Appearance"
    },
    "KPackageStructure": "Plasma/Theme",
    "X-KDE-ParentApp": "org.kde.plasmashell"
}

```

--------------------------------

### Create Static Plugin

Source: https://github.com/kde/kpackage/blob/master/autotests/CMakeLists.txt

Defines a static plugin using kcoreaddons_add_plugin. This snippet shows how to specify source files and the installation namespace for the plugin.

```cmake
kcoreaddons_add_plugin(plasmoidstructure_plugin STATIC SOURCES packagestructures/plasmoidstructure.cpp INSTALL_NAMESPACE kf6/packagestructure)
target_link_libraries(plasmoidstructure_plugin KF6::Package)
```

--------------------------------

### Define Executable Target

Source: https://github.com/kde/kpackage/blob/master/autotests/mockdepresolver/CMakeLists.txt

Defines the 'mockhandler' executable and links it against Qt6::Core. Ensure Qt6 is installed and configured for CMake.

```cmake
add_executable(mockhandler main.cpp)
ecm_mark_nongui_executable(mockhandler)
target_link_libraries(mockhandler Qt6::Core)
```

--------------------------------

### KPackage Directory Structure Example

Source: https://context7.com/kde/kpackage/llms.txt

A typical KPackage follows a standardized directory layout. The metadata.json file is required in the root, with contents organized under the 'contents/' prefix, including UI, configuration, images, and code.

```text
my-plasma-applet/
├── metadata.json              # Package metadata (required)
└── contents/
    ├── ui/
    │   ├── main.qml           # Main script (typically required)
    │   └── ConfigPage.qml     # Configuration UI
    ├── config/
    │   ├── config.qml         # Configuration model
    │   └── main.xml           # KConfigXT schema
    ├── images/
    │   ├── icon.svg
    │   └── background.png
    └── code/
        └── helper.js          # JavaScript helper scripts

```

--------------------------------

### Upgrade Existing Package

Source: https://context7.com/kde/kpackage/llms.txt

Upgrades an already installed package using a new version provided in a directory.

```bash
kpackagetool6 -t Plasma/Applet -u /path/to/my-applet-v2/
```

--------------------------------

### Load and Inspect KPackage Structure

Source: https://context7.com/kde/kpackage/llms.txt

Loads a specific KPackage and lists its registered directories, required directories, files, and required files. Also demonstrates checking if a key is required, retrieving MIME types for a directory, getting content prefix paths, checking external path settings, and retrieving the default package root.

```cpp
#include <KPackage/Package>
#include <KPackage/PackageLoader>
#include <QDebug>

KPackage::Package package = KPackage::PackageLoader::self()->loadPackage(
    QStringLiteral("Plasma/Applet"),
    QStringLiteral("org.kde.plasma.analogclock")
);

// List all registered directory definitions
QList<QByteArray> dirs = package.directories();
qDebug() << "Directories:" << dirs;
// Output: ("config", "data", "images", "scripts", "ui", ...)

// List only required directories
QList<QByteArray> requiredDirs = package.requiredDirectories();
qDebug() << "Required directories:" << requiredDirs;

// List all registered file definitions
QList<QByteArray> files = package.files();
qDebug() << "Files:" << files;
// Output: ("mainscript", "mainconfigui", "mainconfigxml", ...)

// List only required files
QList<QByteArray> requiredFiles = package.requiredFiles();
qDebug() << "Required files:" << requiredFiles;
// Output: ("mainscript")

// Check if a specific key is required
bool isRequired = package.isRequired("mainscript");
qDebug() << "mainscript required:" << isRequired;

// Get MIME types for a key
QStringList imageMimes = package.mimeTypes("images");
qDebug() << "Image MIME types:" << imageMimes;
// Output: ("image/svg+xml", "image/png", "image/jpeg")

// Get contents prefix paths
QStringList prefixes = package.contentsPrefixPaths();
qDebug() << "Contents prefixes:" << prefixes;
// Output: ("contents/")

// Check external paths setting
bool allowExternal = package.allowExternalPaths();
qDebug() << "Allow external paths:" << allowExternal;

// Get the default package root
QString root = package.defaultPackageRoot();
qDebug() << "Default root:" << root;
// Output: "plasma/plasmoids/"

```

--------------------------------

### Define Custom Wallpaper Package Structure

Source: https://context7.com/kde/kpackage/llms.txt

Subclass KPackage::PackageStructure to define a custom package format for wallpapers. This includes setting default installation paths, defining required image directories with specific MIME types, and adding optional files like screenshots and previews. It also demonstrates how to conditionally add definitions based on package metadata.

```cpp
#include <KPackage/PackageStructure>
#include <KPackage/Package>
#include <KPluginFactory>

class WallpaperPackageStructure : public KPackage::PackageStructure
{
    Q_OBJECT

public:
    using KPackage::PackageStructure::PackageStructure;

    void initPackage(KPackage::Package *package) override
    {
        // Set the default installation root directory (relative to XDG data paths)
        // Packages will be installed to ~/.local/share/wallpapers/ or /usr/share/wallpapers/
        package->setDefaultPackageRoot(QStringLiteral("wallpapers/"));

        // Define a required directory for images
        package->addDirectoryDefinition("images", QStringLiteral("images"));
        package->setRequired("images", true);

        // Set allowed MIME types for the images directory
        QStringList mimetypes{
            QStringLiteral("image/svg+xml"),
            QStringLiteral("image/png"),
            QStringLiteral("image/jpeg")
        };
        package->setMimeTypes("images", mimetypes);

        // Define optional file definitions
        package->addFileDefinition("screenshot", QStringLiteral("screenshot.png"));
        package->addFileDefinition("preview", QStringLiteral("preview.png"));

        // Define a directory for theme variants
        package->addDirectoryDefinition("theme", QStringLiteral("theme"));

        // Optionally allow external paths (symlinks) - disabled by default for security
        // package->setAllowExternalPaths(true);
    }

    // Called when Package::setPath() changes the package path
    void pathChanged(KPackage::Package *package) override
    {
        // Perform custom validation or adjustments based on the loaded package
        if (!package->metadata().isValid()) {
            return;
        }

        // Example: Add conditional file definitions based on metadata
        QString variant = package->metadata().value(QStringLiteral("X-Wallpaper-Variant"));
        if (variant == QStringLiteral("animated")) {
            package->addFileDefinition("animation", QStringLiteral("animation.qml"));
            package->setRequired("animation", true);
        }
    }
};

// Export the PackageStructure as a plugin
K_PLUGIN_CLASS_WITH_JSON(WallpaperPackageStructure, "wallpaperstructure.json")

#include "wallpaperstructure.moc"
```

--------------------------------

### Define Package Structure with KPackage::Package

Source: https://github.com/kde/kpackage/blob/master/README.md

Initializes a PackageStructure subclass to define the expected file and directory layout for a package. Use addDirectoryDefinition and addFileDefinition to register paths. Set required files using setRequired. This example demonstrates setting a default package root, defining image and code directories, and specifying a required main script.

```cpp
// ...
void MyStructure::initPackage(KPackage::Package *package)
{
    package->setDefaultPackageRoot(QStringLiteral("myapp" "/packages/"));

    package->addDirectoryDefinition("images", QStringLiteral("images"));
    QStringList mimetypes{QStringLiteral("image/svg+xml"), QStringLiteral("image/png"), QStringLiteral("image/jpeg")};
    package->setMimeTypes("images", mimetypes);
    package->addDirectoryDefinition("code", QStringLiteral("code"));
    package->addFileDefinition("mainscript", QStringLiteral("scripts/main.js"));
    //this way, the package will not be considered valid if mainscript is not present
    package->setRequired("mainscript", true);
}
...
```

--------------------------------

### CMake Build Configuration for PackageStructure Plugin

Source: https://context7.com/kde/kpackage/llms.txt

CMakeLists.txt to build a custom PackageStructure plugin and install it for automatic discovery by PackageLoader.

```cmake
# CMakeLists.txt for a custom PackageStructure plugin

find_package(KF6Package REQUIRED)

# Build the plugin and install to the kf6/packagestructure directory
kcoreaddons_add_plugin(myapp_wallpaper_packagestructure
    SOURCES wallpaperstructure.cpp
    INSTALL_NAMESPACE kf6/packagestructure
)

target_link_libraries(myapp_wallpaper_packagestructure
    KF6::Package
)
```

--------------------------------

### CMake for PackageStructure Plugin

Source: https://github.com/kde/kpackage/blob/master/README.md

CMakeLists.txt configuration to build a PackageStructure implementation as a plugin. It uses kcoreaddons_add_plugin to compile the source files and install the plugin into the appropriate directory for PackageLoader. Ensure to link against KF6::Package.

```cmake
# build the PackageStructure implementation and install it where PackageLoader looks for plugins
kcoreaddons_add_plugin(myapp_packagestructure_mystructure SOURCES mystructure.cpp INSTALL_NAMESPACE kf6/packagestructure)
target_link_libraries(myapp_packagestructure_mystructure KF6::Package)
```

--------------------------------

### Load and Access KPackage Package

Source: https://context7.com/kde/kpackage/llms.txt

Demonstrates how to load a package by type and plugin ID, check its validity, retrieve file paths, access metadata, and list directory contents. Ensure the package type and ID are correct for your system.

```cpp
#include <KPackage/Package>
#include <KPackage/PackageLoader>
#include <QDebug>

// Load a package of type "Plasma/Applet" with plugin ID "org.kde.plasma.analogclock"
KPackage::Package package = KPackage::PackageLoader::self()->loadPackage(
    QStringLiteral("Plasma/Applet"),
    QStringLiteral("org.kde.plasma.analogclock")
);

// Check if the package is valid (all required files exist)
if (package.isValid()) {
    // Get the path to a specific file by key
    QString mainScript = package.filePath("mainscript");
    qDebug() << "Main script path:" << mainScript;
    // Output: "/usr/share/plasma/plasmoids/org.kde.plasma.analogclock/contents/ui/main.qml"

    // Get a file within a directory definition
    QString iconPath = package.filePath("images", "icon.png");
    qDebug() << "Icon path:" << iconPath;

    // Get package metadata
    KPluginMetaData metadata = package.metadata();
    qDebug() << "Package name:" << metadata.name();
    qDebug() << "Plugin ID:" << metadata.pluginId();
    qDebug() << "Description:" << metadata.description();

    // Get the root path of the package
    qDebug() << "Package root:" << package.path();

    // List all files in a directory
    QStringList images = package.entryList("images");
    for (const QString &img : images) {
        qDebug() << "Image:" << package.filePath("images", img);
    }

    // Generate a cryptographic hash of the package contents
    QByteArray hash = package.cryptographicHash(QCryptographicHash::Sha1);
    qDebug() << "Package SHA1:" << hash.toHex();
}

```

--------------------------------

### List Packages from a Custom Directory

Source: https://context7.com/kde/kpackage/llms.txt

Demonstrates listing packages of a specific type from a custom root directory.

```cpp
// List packages from a specific root directory
QList<KPluginMetaData> customPackages = loader->listPackages(
    QStringLiteral("MyApp/Theme"),
    QStringLiteral("/opt/myapp/themes/")
);
```

--------------------------------

### Load Package by Type and Plugin ID

Source: https://context7.com/kde/kpackage/llms.txt

Shows how to load a specific package using its type and unique plugin ID.

```cpp
// Load a package directly by type and plugin ID
KPackage::Package clockPackage = loader->loadPackage(
    QStringLiteral("Plasma/Applet"),
    QStringLiteral("org.kde.plasma.analogclock")
);
```

--------------------------------

### Show Package Information

Source: https://context7.com/kde/kpackage/llms.txt

Displays detailed information about a specific package.

```bash
kpackagetool6 -t Plasma/Applet -s org.kde.plasma.analogclock
```

--------------------------------

### List All Packages of a Specific Type

Source: https://context7.com/kde/kpackage/llms.txt

Illustrates how to retrieve metadata for all packages of a given type.

```cpp
// List all packages of a type
QList<KPluginMetaData> allApplets = loader->listPackages(QStringLiteral("Plasma/Applet"));
for (const KPluginMetaData &meta : allApplets) {
    qDebug() << "Found applet:" << meta.pluginId() << "-" << meta.name();
}
```

--------------------------------

### Configure Fallback Packages

Source: https://context7.com/kde/kpackage/llms.txt

Sets up a fallback package to provide default files when the primary package is missing them. This is useful for themes or configurations.

```cpp
#include <KPackage/Package>
#include <KPackage/PackageLoader>

// Load the main theme package
KPackage::Package theme = KPackage::PackageLoader::self()->loadPackage(
    QStringLiteral("Plasma/Theme"),
    QStringLiteral("org.kde.custom.theme")
);

// Load the default/fallback theme
KPackage::Package defaultTheme = KPackage::PackageLoader::self()->loadPackage(
    QStringLiteral("Plasma/Theme"),
    QStringLiteral("org.kde.breeze")
);

// Set the fallback - if a file isn't found in theme, it will search defaultTheme
theme.setFallbackPackage(defaultTheme);

// Now filePath will search both packages
QString iconPath = theme.filePath("icons", "dialog-information.svg");
// Returns from custom theme if exists, otherwise from breeze

// Check which package is set as fallback
KPackage::Package fallback = theme.fallbackPackage();
if (fallback.isValid()) {
    qDebug() << "Fallback:" << fallback.metadata().pluginId();
}

```

--------------------------------

### Use Custom Package Root Directory

Source: https://context7.com/kde/kpackage/llms.txt

Lists packages while specifying a custom root directory for package lookups.

```bash
kpackagetool6 -t Plasma/Theme -p /opt/custom/themes/ --list
```

--------------------------------

### Generate QDoc Configuration

Source: https://github.com/kde/kpackage/blob/master/src/kpackage/CMakeLists.txt

Generates the QDoc configuration file for the KF6Package library.

```cmake
ecm_generate_qdoc(KF6Package kpackage.qdocconf)
```

--------------------------------

### Declare KF6Package Logging Category

Source: https://github.com/kde/kpackage/blob/master/src/kpackage/CMakeLists.txt

Sets up a Qt logging category for the KPackage library, including identifiers and descriptions.

```cmake
ecm_qt_declare_logging_category(KF6Package
    HEADER kpackage_debug.h
    IDENTIFIER KPACKAGE_LOG
    CATEGORY_NAME kf.package
    OLD_CATEGORY_NAMES kf5.kpackage
    DESCRIPTION "kpackage (lib)"
    EXPORT KPACKAGE
)
```

--------------------------------

### Register Custom Package Structure

Source: https://context7.com/kde/kpackage/llms.txt

Demonstrates how to programmatically register a custom PackageStructure with the PackageLoader.

```cpp
// Register a custom PackageStructure programmatically
KPackage::PackageStructure *customStructure = new MyCustomStructure();
loader->addKnownPackageStructure(QStringLiteral("MyApp/Custom"), customStructure);
```

--------------------------------

### Set KF6Package Include Directories

Source: https://github.com/kde/kpackage/blob/master/src/kpackage/CMakeLists.txt

Configures public and interface include directories for the KF6Package library.

```cmake
target_include_directories(KF6Package PUBLIC
  "$<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/..;${CMAKE_CURRENT_BINARY_DIR}/KPackage>"
)
target_include_directories(KF6Package INTERFACE
  "$<INSTALL_INTERFACE:${KDE_INSTALL_INCLUDEDIR_KF}/KPackage>"
)
```

--------------------------------

### Define Package Structure with File Definitions

Source: https://context7.com/kde/kpackage/llms.txt

Configures the structure of a package by defining directories, files, requirements, and MIME type restrictions using the KPackage API.

```cpp
#include <KPackage/Package>
#include <KPackage/PackageStructure>

void initPackage(KPackage::Package *package)
{
    // Set the installation root (relative to QStandardPaths::GenericDataLocation)
    package->setDefaultPackageRoot(QStringLiteral("myapp/extensions/"));

    // Add directory definitions with keys for lookup
    package->addDirectoryDefinition("ui", QStringLiteral("ui"));
    package->addDirectoryDefinition("images", QStringLiteral("images"));
    package->addDirectoryDefinition("scripts", QStringLiteral("code"));
    package->addDirectoryDefinition("config", QStringLiteral("config"));
    package->addDirectoryDefinition("data", QStringLiteral("data"));

    // Add file definitions (specific named files)
    package->addFileDefinition("mainscript", QStringLiteral("ui/main.qml"));
    package->addFileDefinition("mainconfigui", QStringLiteral("ui/config.qml"));
    package->addFileDefinition("mainconfigxml", QStringLiteral("config/main.xml"));

    // Mark required files/directories (package.isValid() returns false if missing)
    package->setRequired("mainscript", true);

    // Set MIME type restrictions for directories
    package->setMimeTypes("images", {
        QStringLiteral("image/svg+xml"),
        QStringLiteral("image/png"),
        QStringLiteral("image/jpeg")
    });
    package->setMimeTypes("scripts", {
        QStringLiteral("text/plain"),
        QStringLiteral("application/javascript")
    });

    // Set default MIME types for definitions without explicit types
    package->setDefaultMimeTypes({QStringLiteral("text/plain")});

    // Customize contents prefix (default is "contents/")
    // Files are looked up under: <package-root>/<contents-prefix>/<path>
    package->setContentsPrefixPaths({QStringLiteral("contents/")});

    // Add multiple search alternatives for a key
    package->addFileDefinition("mainscript", QStringLiteral("code/main.js")); // Fallback path
}

```

--------------------------------

### Specify kpackagetool6 Source Files

Source: https://github.com/kde/kpackage/blob/master/src/kpackagetool/CMakeLists.txt

Lists the source files for the kpackagetool6 executable.

```cmake
target_sources(kpackagetool6 PRIVATE
    main.cpp
    kpackagetool.cpp
)
```

--------------------------------

### List Package Types with kpackagetool6

Source: https://context7.com/kde/kpackage/llms.txt

The kpackagetool6 command-line utility can be used to manage KPackages. Use the --list-types option to display all available package types supported by the system.

```bash
# List all available package types
kpackagetool6 --list-types

```

--------------------------------

### Add Sources to KF6Package

Source: https://github.com/kde/kpackage/blob/master/src/kpackage/CMakeLists.txt

Specifies the source files to be compiled into the KF6Package library.

```cmake
target_sources(KF6Package PRIVATE
    package.cpp
    packagestructure.cpp
    packageloader.cpp
    packagejob.cpp
    private/packages.cpp
    private/packagejobthread.cpp
)
```

--------------------------------

### Load a KPackage Package

Source: https://github.com/kde/kpackage/blob/master/README.md

Loads a specific package of a given type and identifier. Checks if the loaded package is valid and prints its file path. Use this to load a package when you know its type and name.

```cpp
KPackage::Package p = KPackage::PackageLoader::self()->loadPackage("Plasma/Applet", "org.kde.plasma.analogclock");
if (p.isValid()) {
    qDebug() << p.filePath("mainscript");
}
```

--------------------------------

### Find Packages Using a Filter Function

Source: https://context7.com/kde/kpackage/llms.txt

Shows how to find packages of a specific type within the default package roots, using a lambda function to filter results based on package metadata.

```cpp
// Find packages with a filter function
QList<KPluginMetaData> clockApplets = loader->findPackages(
    QStringLiteral("Plasma/Applet"),
    QString(), // Use default package root
    [](const KPluginMetaData &meta) {
        // Filter: only packages with "clock" in name or description
        return meta.name().contains(QStringLiteral("clock"), Qt::CaseInsensitive)
            || meta.description().contains(QStringLiteral("clock"), Qt::CaseInsensitive);
    }
);
qDebug() << "Found" << clockApplets.count() << "clock-related applets";
```

--------------------------------

### Define Static Plugins

Source: https://github.com/kde/kpackage/blob/master/autotests/CMakeLists.txt

Uses kcoreaddons_target_static_plugins to define static plugins for specific targets. This is used here for 'querytest' and 'plasmoidpackagetest' with a specified namespace.

```cmake
kcoreaddons_target_static_plugins(querytest NAMESPACE kf6/packagestructure)
kcoreaddons_target_static_plugins(plasmoidpackagetest NAMESPACE kf6/packagestructure)
```

--------------------------------

### Loop Through Test Cases

Source: https://github.com/kde/kpackage/blob/master/autotests/CMakeLists.txt

Iterates through a list of test case names and calls the 'kpackagetooltest' function for each. This is a common pattern for setting up multiple similar tests.

```cmake
foreach(var "testfallbackpackage" "testpackage" "testpackage-nodisplay" "testpackagesdep" "testpackagesdepinvalid") # "customcontent" "simplecontent"
    kpackagetooltest(${var})
endforeach()
```

--------------------------------

### Add KPackage Subdirectory

Source: https://github.com/kde/kpackage/blob/master/src/CMakeLists.txt

Includes the KPackage subdirectory into the build system. This is a standard CMake command.

```cmake
add_subdirectory(kpackage)
```

--------------------------------

### Add KPackageTool Subdirectory

Source: https://github.com/kde/kpackage/blob/master/src/CMakeLists.txt

Includes the KPackageTool subdirectory into the build system. This is a standard CMake command.

```cmake
add_subdirectory(kpackagetool)
```

--------------------------------

### Define KF6Package Library

Source: https://github.com/kde/kpackage/blob/master/src/kpackage/CMakeLists.txt

Defines the KF6Package library and its alias for use within the build system.

```cmake
add_library(KF6Package)
add_library(KF6::Package ALIAS KF6Package)
```

--------------------------------

### Set KF6Package Target Properties

Source: https://github.com/kde/kpackage/blob/master/src/kpackage/CMakeLists.txt

Sets versioning and export name properties for the KF6Package library.

```cmake
set_target_properties(KF6Package PROPERTIES
    VERSION     ${PACKAGE_VERSION}
    SOVERSION   ${PACKAGE_SOVERSION}
    EXPORT_NAME Package
)
```

--------------------------------

### Uninstall a Package using PackageJob

Source: https://context7.com/kde/kpackage/llms.txt

Use KPackage::PackageJob::uninstall to asynchronously remove a package by its plugin ID and type. Connect to the KJob::result signal to monitor the operation's success or failure.

```cpp
#include <KPackage/PackageJob>
#include <KPackage/Package>
#include <KJob>
#include <QDebug>
#include <QCoreApplication>

// Uninstall a package by plugin ID
void uninstallPackage()
{
    QString pluginId = QStringLiteral("org.kde.breeze.desktop");
    QString packageType = QStringLiteral("Plasma/Theme");

    KPackage::PackageJob *job = KPackage::PackageJob::uninstall(packageType, pluginId);

    QObject::connect(job, &KJob::result, [job]() {
        if (job->error() == KJob::NoError) {
            qDebug() << "Successfully uninstalled package";
        } else {
            qDebug() << "Uninstall failed:" << job->errorString();
        }
    });
}

```

--------------------------------

### Generate Export Header for KF6Package

Source: https://github.com/kde/kpackage/blob/master/src/kpackage/CMakeLists.txt

Generates an export header file for the KF6Package library, managing symbols and versioning.

```cmake
ecm_generate_export_header(KF6Package
    EXPORT_FILE_NAME kpackage/package_export.h
    BASE_NAME KPackage
    GROUP_BASE_NAME KF
    VERSION ${KF_VERSION}
    USE_VERSION_HEADER
    DEPRECATED_BASE_VERSION 0
    DEPRECATION_VERSIONS
    EXCLUDE_DEPRECATED_BEFORE_AND_AT ${EXCLUDE_DEPRECATED_BEFORE_AND_AT}
)
```

--------------------------------

### Configure Header File

Source: https://github.com/kde/kpackage/blob/master/autotests/CMakeLists.txt

Configures a header file by processing a template. This is typically used to inject build-time information into configuration headers.

```cmake
configure_file(config.h.cmake ${CMAKE_CURRENT_BINARY_DIR}/config.h)
```

--------------------------------

### Update a Package using PackageJob

Source: https://context7.com/kde/kpackage/llms.txt

Use KPackage::PackageJob::update to asynchronously update an existing package to a newer version from a local file. Handle the KJob::result signal for success or specific errors like NewerVersionAlreadyInstalledError.

```cpp
#include <KPackage/PackageJob>
#include <KPackage/Package>
#include <KJob>
#include <QDebug>
#include <QCoreApplication>

// Update an existing package to a newer version
void updatePackage()
{
    QString packagePath = QStringLiteral("/path/to/my-theme-v2.tar.gz");
    QString packageType = QStringLiteral("Plasma/Theme");

    KPackage::PackageJob *job = KPackage::PackageJob::update(packageType, packagePath);

    QObject::connect(job, &KJob::result, [job]() {
        if (job->error() == KJob::NoError) {
            qDebug() << "Successfully updated to:" << job->package().path();
        } else if (job->error() == KPackage::PackageJob::NewerVersionAlreadyInstalledError) {
            qDebug() << "Same or newer version already installed";
        } else {
            qDebug() << "Update failed:" << job->errorString();
        }
    });
}

```

--------------------------------

### Add Test Cases

Source: https://github.com/kde/kpackage/blob/master/autotests/CMakeLists.txt

Adds a set of C++ test files to the build system using ECMAddTests. It specifies the source files and links against necessary libraries like Qt6::Test and KF6 components.

```cmake
ecm_add_tests(
    fallbackpackagetest.cpp
    packagestructuretest.cpp
    plasmoidpackagetest.cpp
    querytest.cpp
    LINK_LIBRARIES Qt6::Test KF6::Package KF6::I18n KF6::Archive
)
```

--------------------------------

### Generate AppStream Metadata

Source: https://context7.com/kde/kpackage/llms.txt

Generates AppStream metadata for a package. Optionally specifies an output file.

```bash
kpackagetool6 -t Plasma/Applet --appstream-metainfo /path/to/applet/
```

```bash
kpackagetool6 -t Plasma/Applet --appstream-metainfo /path/to/applet/ --appstream-metainfo-output /output/applet.metainfo.xml
```

--------------------------------

### Configure kpackagetool6 Logging

Source: https://github.com/kde/kpackage/blob/master/src/kpackagetool/CMakeLists.txt

Declares the logging category for kpackagetool6 using ECM.

```cmake
ecm_qt_declare_logging_category(kpackagetool6
    HEADER kpackage_debug.h
    IDENTIFIER KPACKAGE_LOG
    CATEGORY_NAME kf.package
)
```

--------------------------------

### Generate SHA1 Hash for Package

Source: https://context7.com/kde/kpackage/llms.txt

Generates the SHA1 hash for a given package file, typically used for integrity checks.

```bash
kpackagetool6 --hash /path/to/package/
```

--------------------------------

### Link Libraries to KF6Package

Source: https://github.com/kde/kpackage/blob/master/src/kpackage/CMakeLists.txt

Specifies the public and private libraries required by the KF6Package library.

```cmake
target_link_libraries(KF6Package
PUBLIC
     KF6::CoreAddons
PRIVATE
     KF6::Archive
     KF6::I18n
)
```

--------------------------------

### Configure Package Header

Source: https://github.com/kde/kpackage/blob/master/src/kpackage/CMakeLists.txt

Configures a header file for package-specific settings during the build process.

```cmake
configure_file(${CMAKE_CURRENT_SOURCE_DIR}/config-package.h.cmake ${CMAKE_CURRENT_BINARY_DIR}/config-package.h)
```

--------------------------------

### Link Libraries for kpackagetool6

Source: https://github.com/kde/kpackage/blob/master/src/kpackagetool/CMakeLists.txt

Specifies the KF6 libraries required by kpackagetool6.

```cmake
target_link_libraries(kpackagetool6 KF6::Archive KF6::Package KF6::I18n KF6::CoreAddons)
```

--------------------------------

### Find Qt6 Test Module

Source: https://github.com/kde/kpackage/blob/master/autotests/CMakeLists.txt

Finds the Qt6 Test module, which is required for running tests. Ensures the specified Qt version is met.

```cmake
find_package(Qt6Test ${REQUIRED_QT_VERSION} REQUIRED NO_MODULE)
set_package_properties(Qt6Test PROPERTIES PURPOSE "Required for tests")
```

--------------------------------

### Define kpackagetool6 Executable

Source: https://github.com/kde/kpackage/blob/master/src/kpackagetool/CMakeLists.txt

Defines the kpackagetool6 executable target in CMake.

```cmake
add_executable(kpackagetool6)

ecm_mark_nongui_executable(kpackagetool6)
```

--------------------------------

### Package Structure Metadata

Source: https://github.com/kde/kpackage/blob/master/README.md

JSON file defining metadata for a PackageStructure plugin. It specifies the plugin's class name and its parent application. This file is essential for KPluginFactory to correctly identify and load the plugin.

```json
{
    "KPackageStructure": "MyApp/MyStructure",
    "X-KDE-ParentApp": "org.kde.myapp"
}
```

--------------------------------

### Conditional DBus Linking and Definitions

Source: https://github.com/kde/kpackage/blob/master/src/kpackage/CMakeLists.txt

Conditionally links the Qt::DBus library and sets compile definitions based on HAVE_DBUS.

```cmake
if (HAVE_DBUS)
    target_link_libraries(KF6Package
        PRIVATE
        Qt::DBus # notification
    )
    target_compile_definitions(KF6Package PRIVATE -DHAVE_QTDBUS=1)
else()
    target_compile_definitions(KF6Package PRIVATE -DHAVE_QTDBUS=0)
endif()
```

--------------------------------

### Include ECM Modules

Source: https://github.com/kde/kpackage/blob/master/autotests/CMakeLists.txt

Includes Essential CMake Modules (ECM) for build system functionalities. ECMMarkAsTest is used for marking tests, and ECMAddTests is for adding test cases.

```cmake
include(ECMMarkAsTest)
include(ECMAddTests)
```

--------------------------------

### Add Mock Dependency Resolver Subdirectory

Source: https://github.com/kde/kpackage/blob/master/autotests/CMakeLists.txt

Includes another CMake build subdirectory named 'mockdepresolver'. This is used to incorporate external or modular build components into the main project.

```cmake
add_subdirectory(mockdepresolver)
```

--------------------------------

### KPackageTool Test Function

Source: https://github.com/kde/kpackage/blob/master/autotests/CMakeLists.txt

Defines a CMake function 'kpackagetooltest' to create tests for the kpackagetool executable. It configures the test command to run a CMake script for appstream testing.

```cmake
function(kpackagetooltest testname)
    add_test(NAME ${testname}-appstream COMMAND cmake -Dkpackagetool=$<TARGET_FILE:kpackagetool6>
                                                      -Dgenerated=${CMAKE_CURRENT_BINARY_DIR}/${testname}.appdata.xml
                                                      -Dinput=${CMAKE_CURRENT_LIST_DIR}/data/${testname}/
                                                      -Doutput=${CMAKE_CURRENT_SOURCE_DIR}/data/${testname}/${testname}.testappdataxml
                                                      -P ${CMAKE_CURRENT_SOURCE_DIR}/kpackagetoolappstreamtest.cmake
    )
    set(XDG_DATA_DIRS "$ENV{XDG_DATA_DIRS}")
    if(NOT XDG_DATA_DIRS)
        set(XDG_DATA_DIRS "/usr/local/share:/usr/share")
    endif()
    set_property(TEST ${testname}-appstream PROPERTY ENVIRONMENT "XDG_DATA_DIRS=${CMAKE_SOURCE_DIR}/src/kpackage/data:${XDG_DATA_DIRS}")
endfunction()
```

--------------------------------

### PackageStructure Plugin JSON Metadata

Source: https://context7.com/kde/kpackage/llms.txt

JSON metadata file required for every PackageStructure plugin, identifying the package type and its parent application.

```json
{
    "KPackageStructure": "MyApp/Wallpaper",
    "X-KDE-ParentApp": "org.kde.myapp"
}
```

--------------------------------

### Generate CamelCase Headers

Source: https://github.com/kde/kpackage/blob/master/src/kpackage/CMakeLists.txt

Generates CamelCase versions of header files for the Package module.

```cmake
ecm_generate_headers(Package_CamelCase_HEADERS
    HEADER_NAMES
        Package
        PackageStructure
        PackageLoader
        PackageJob
        packagestructure_compat_p
    REQUIRED_HEADERS Package_HEADERS
    PREFIX KPackage
)
```

--------------------------------

### Set Test Properties

Source: https://github.com/kde/kpackage/blob/master/autotests/CMakeLists.txt

Sets properties for specific tests. RUN_SERIAL TRUE ensures that tests are run sequentially, which is important for tests that modify shared resources like the user's configuration directory.

```cmake
set_tests_properties(querytest PROPERTIES RUN_SERIAL TRUE) # it wipes out ~/.qttest/share
set_tests_properties(plasmoidpackagetest PROPERTIES RUN_SERIAL TRUE)
```

--------------------------------

### Export PackageStructure Plugin

Source: https://github.com/kde/kpackage/blob/master/README.md

Exports a PackageStructure subclass as a standalone plugin using KPluginFactory. This allows PackageLoader to discover and load the plugin dynamically. Ensure the plugin has a corresponding JSON metadata file and is built with CMake.

```cpp
K_PLUGIN_CLASS_WITH_JSON(MyStructure, "mystructure.json")
```

--------------------------------

### Remove Package by Plugin ID

Source: https://context7.com/kde/kpackage/llms.txt

Removes a package using its unique plugin identifier.

```bash
kpackagetool6 -t Plasma/Applet -r org.kde.myapplet
```

--------------------------------

### Remove Build Definitions

Source: https://github.com/kde/kpackage/blob/master/autotests/CMakeLists.txt

Removes specific preprocessor definitions that might interfere with build configurations. These are often related to strict iterator or casting behaviors in Qt.

```cmake
remove_definitions(-DQT_NO_CAST_FROM_ASCII -DQT_STRICT_ITERATORS -DQT_NO_CAST_FROM_BYTEARRAY -DQT_NO_KEYWORDS)
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.