How to use the KOS Maven plugin

Introduction

The kos-kab-maven-plugin is a Maven plugin that streamlines the process of creating KOS Archive Bundles (KAB ). It allows you to copy files directly from local directories into a KAB file, eliminating the need for intermediate steps like using the Maven Assembly Plugin to create a ZIP file first. The plugin supports various configurations to specify which files and directories to include, as well as setting file permissions within the KAB. It is backward compatible with the ZIP method, meaning you can still use it to create ZIP files if needed by setting the mode parameter to zip.

Understanding Key Configuration Tags

<copy>

Defines a copy instruction.Ref: Java Debugging Details

<include>

Specifies a single file, file pattern, or directory to include.

<includes>

Wraps multiple <include> tags.

<dir>

Specifies the directory inside the KAB where the files will be copied.

<content>

Encloses all <copy> tags.

Basic Configuration

<build>
    <plugins>
        <!-- KOS plugin for kab files -->
        <plugin>
            <groupId>com.kosdev.kos.maven</groupId>
            <artifactId>kos-kab-maven-plugin</artifactId>
            <executions>
                <execution>
                    <phase>package</phase>
                    <goals>
                        <goal>kabtool</goal>
                    </goals>
                    <configuration>
                        <mode>copy</mode> <!-- Optional: Defaults to copy if not specified -->
                        <type>kos.system</type>
                        <content>
                            <copy>
                                <includes>
                                    <include>${project.build.directory}/${project.artifactId}-${project.version}.jar</include>
                                    <include>${project.basedir}/descriptor.json</include>
                                </includes>
                            </copy>
                        </content>
                    </configuration>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

Advanced Configurations

Entire Directory Contents

<copy>
    <include>${project.basedir}/src/main/resources/</include>
    <dir>resources</dir>
</copy>

Wildcard Pattern for PNG Files

<copy>
    <include>${project.basedir}/src/main/resources/images/*.png</include>
    <dir>images</dir>
</copy>

Nested Wildcard Pattern for Specific File Types

<copy>
    <include>${project.basedir}/src/main/resources/**/*.txt</include>
    <dir>resources</dir>
</copy>

Specific File Types

<copy>
    <includes>
        <include>${project.basedir}/src/main/resources/config/*.properties</include>
    </includes>
    <dir>config</dir>
</copy>

All Files in Directory (excluding directory itself)

<copy>
    <include>${project.basedir}/src/main/resources/temp/*</include>
    <dir>tempContents</dir>
</copy>

Complex Nested Directory Copying

<copy>
    <include>${project.basedir}/src/main/resources/nested/</include>
    <dir>nested</dir>
</copy>
<copy>
    <include>${project.basedir}/src/main/resources/nested/images/</include>
    <dir>nested/images</dir>
</copy>

Copying Hidden Files to Root

<copy>
    <include>${project.basedir}/.env</include>
    <include>${project.basedir}/.gitignore</include>
    <dir>hidden_files</dir>
</copy>

Permissions Feature

The permissions feature in the kos-kab-maven-plugin allows you to set file permissions for the files being added to the KAB. This is useful for controlling access and execution rights within the KAB.

Defining Permissions

Permissions are specified using the <permissions> tag, with each permission defined using UNIX-like syntax followed by a pattern.

Format: <permission>octal_permissions:::pattern</permission>

Example:

<permissions>
    <!-- Set executable permissions for shell scripts -->
    <permission>755:::*.sh</permission>
    <!-- Set read-write permissions for bash files -->
    <permission>644:::*.bash</permission>
</permissions>

In this example:

755:::*.sh sets executable permissions for all shell script files (*.sh).
644:::*.bash sets read-write permissions for all bash files (*.bash).

By using the permissions feature, you can ensure that files within your KAB have the appropriate access rights.

Mode

Overview

The mode tag allows you to set the method by which files are copied into the KAB. When set to copy or when not set, files are directly copied into the KAB. When set to zip, files are first packaged into a ZIP file before being added to the KAB.

Defining Mode

<configuration>
    <mode>copy</mode> <!-- Set to 'copy' to directly copy files into the KAB -->
    <type>kos.system</type>
    <permissions>
        <permission>755:::*.sh</permission>
    </permissions>
    <content>
        <copy>
            <include>${project.basedir}/descriptor.json</include>
        </copy>
        <copy>
            <includes>
                <include>${project.build.directory}/${project.artifactId}-${project.version}.jar</include>
                <include>${project.basedir}/descriptor.json</include>
            </includes>
        </copy>
        <copy>
            <include>${project.basedir}/src/main/resources/</include>
            <dir>resources</dir>
        </copy>
        <!-- Additional examples and configurations as needed -->
    </content>
</configuration>

Complete Plugin Configuration Example

<build>
    <plugins>
        <!-- KOS plugin for kab files -->
        <plugin>
            <groupId>com.kosdev.kos.maven</groupId>
            <artifactId>kos-kab-maven-plugin</artifactId>
            <executions>
                <execution>
                    <phase>package</phase>
                    <goals>
                        <goal>kabtool</goal>
                    </goals>
                    <configuration>
                        <mode>copy</mode> <!-- Optional: Defaults to zip if not specified -->
                        <type>kos.system</type>
                        <permissions>
                            <permission>755:::*.sh</permission>
                        </permissions>
                        <content>
                            <!-- Single File Inclusion -->
                            <copy>
                                <include>${project.basedir}/descriptor.json</include>
                            </copy>
                            <!-- Multiple File Inclusions -->
                            <copy>
                                <includes>
                                    <include>${project.build.directory}/${project.artifactId}-${project.version}.jar</include>
                                    <include>${project.basedir}/descriptor.json</include>
                                </includes>
                            </copy>
                            <!-- Directory Inclusion -->
                            <copy>
                                <include>${project.basedir}/src/main/resources/</include>
                                <dir>resources</dir>
                            </copy>
                            <!-- Wildcard Pattern for PNG Files -->
                            <copy>
                                <include>${project.basedir}/src/main/resources/images/*.png</include>
                                <dir>images</dir>
                            </copy>
                            <!-- Nested Wildcard Pattern for Specific File Types -->
                            <copy>
                                <include>${project.basedir}/src/main/resources/**/*.txt</include>
                                <dir>resources</dir>
                            </copy>
                            <!-- Specific File Types -->
                            <copy>
                                <includes>
                                    <include>${project.basedir}/src/main/resources/config/*.properties</include>
                                </includes>
                                <dir>config</dir>
                            </copy>
                            <copy>
                                <include>${project.basedir}/src/main/resources/**/*.xml</include>
                                <dir>xml_files</dir>
                            </copy>
                            <!-- All Files in Directory (excluding directory itself) -->
                            <copy>
                                <include>${project.basedir}/src/main/resources/temp/*</include>
                                <dir>tempContents</dir>
                            </copy>
                            <!-- Complex Nested Directory Copying -->
                            <copy>
                                <include>${project.basedir}/src/main/resources/nested/</include>
                                <dir>nested</dir>
                            </copy>
                            <copy>
                                <include>${project.basedir}/src/main/resources/nested/images/</include>
                                <dir>nested/images</dir>
                            </copy>
                            <!-- Copying Hidden Files to Root -->
                            <copy>
                                <include>${project.basedir}/.env</include>
                                <include>${project.basedir}/.gitignore</include>
                                <dir>hidden_files</dir>
                            </copy>
                        </content>
                    </configuration>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

Example Output

Upon successful build, you will see the resulting JAR, ZIP, and KAB files in the specified output directory.

Depending on your file systems, this is the expected KAB Structure

The expected KAB structure for the provided pom configuration is:

KAB/
├── resources/
│   ├── config/
│   │   └── example.properties
│   ├── images/
│   │   ├── example.png
│   │   └── another_example.png
│   ├── nested/
│   │   ├── nested_file.txt
│   │   └── nested_directory/
│   │       └── nested_nested_file.txt
│   ├── tempContents/
│   │   └── temp_file.txt
│   └── resources/
│       ├── example.txt
│       └── another_example.txt
├── hidden_files/
│   ├── .env
│   └── .gitignore
├── xml_files/
│   └── example.xml
├── descriptor.json
└── your-artifact.jar

Important Notes

You must install and sign in to KOS Studio for the plugin to work.

Summary

Overview

This guide explained how to configure and use the kos-kab-maven-plugin to generate KAB files.

Usage

To use the kos-kab-maven-plugin, follow the configuration examples provided in this guide to set up your POM file and define the desired file copying instructions.