Downloads
/
/
Java Reference

Ref: 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

  • Installation and sign-in to KOS Studio are required 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.

Further Reading

For more detailed tutorials involving these plugins, refer to the rack tutorial.

Previous
Next
On this page
Java Development
Seamlessly transition from Legacy+ systems to Freestyle microdosing and advanced distributed dispense systems.
Learn More
UI Development
Using KOS SDKs, integrating Consumer and Non-consumer facing UIs becomes seamless, giving you less hassle and more time to create.
Learn More
Video Library
Meet some of our development team, as they lead you through the tools, features, and tips and tricks of various KOS tools.
Learn More
Resources
Familiarize yourself with KOS terminology, our reference materials, and explore additional resources that complement your KOS journey.
Learn More
Copyright © 2024 TCCC. All rights reserved.