Tutorials

Project Setup

Introduction

In this section, we’ll walk you through setting up a Maven project to create and build a kOS-specific deployable file, known as a KAB, for deployment. We’ll cover the creation of a POM file for building the project and using a descriptor file to tell the kOS environment where to start. This tutorial assumes you are already familiar with Maven and POM files.

For now, just think of a KAB file as a collection of related files that serve as a universal container for all components of the operating system, from the kernel to applications. In a kOS release, EVERYTHING is a KAB. You can learn more about KAB files on the Concept: KAB Files KAB Files page.

Step One: Create the POM file

This section will guide you through the pom.xml file setup specifically for developing a kOS application for your bestselling books rack. For the complete source of pom.xml, download complete pom.

But let’s take a look at the elements that are crucial to building a kOS app.

Section 1: Properties

The <properties> section centralizes project-wide settings and versions, ensuring consistency and ease of updates. This includes specifying the version of kOS to target, the version of Java required by kOS, and the versions of essential plugins.

    <!-- properties -->
    <properties>
        <kos.version>0.0.0-SNAPSHOT</kos.version>
        <maven.compiler.source>17</maven.compiler.source>
        <maven.compiler.target>17</maven.compiler.target>
        <kos-kab-maven-plugin.version>1.3.4</kos-kab-maven-plugin.version>
        <lombok.version>1.18.28</lombok.version>
    </properties>

Section 2: Include the kOS SDK

Problem: kOS provides numerous SDKs for building your app, but how do we know which versions of those SDKs to use so that they are compatible with each other and the version of kOS we are using?

Solution: We use the configuration management concept of a Bill of Materials (BOM). Each version of kOS (1.0, 1.1, 1.2, etc.) has a BOM that manages the specific compatible versions of SDKs. That way, when we add an SDK dependency, we don’t have to know the specific SDK version. We place these special BOM dependencies in the <dependencyManagement> element to ensure version consistency across this Maven module. If this were a multi-module app, as will be used in future tutorials, it would ensure consistency across all modules.

In this example, we’ve added kos-bom as a <dependency> using the property kos.version from our properties section.

    <!-- include kOS SDK BOM -->
    <dependencyManagement>
        <dependencies>
            <!-- kOS SDK -->
            <dependency>
                <groupId>com.kosdev.kos.sdk.bom</groupId>
                <artifactId>kos-bom</artifactId>
                <version>${kos.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>

Then, in the <dependencies> element, we can add our core-api SDK without having to specify the version.

    <!-- project dependencies -->
    <dependencies>
        <dependency>
            <groupId>com.kosdev.kos.sdk.api</groupId>
            <artifactId>api-core</artifactId>
        </dependency>

Section 3: Plugin Management

The build and <pluginManagement> sections manage the versions of plugins used in the build process. This includes plugins for packaging your application JAR and data files into a ZIP file and converting the ZIP file into a KAB file for deployment. Remember, building jars and zips are just steps to build what a kOS environment really needs: KAB files.

    <build>
        <pluginManagement>
            <plugins>
                <!-- kOS plugin for kab files -->
                <plugin>
                    <groupId>com.kosdev.kos.maven</groupId>
                    <artifactId>kos-kab-maven-plugin</artifactId>
                    <version>${kos-kab-maven-plugin.version}</version>
                </plugin>
            </plugins>
        </pluginManagement>
    </build>

Section 4: Profiles

The <profiles> section defines build profiles that can be activated under specific conditions. The developer profile is activated by default and includes plugins for packaging your application into a KAB file, tailored for kOS development. Using the kos-kab-maven-plugin, you can specify which files you need in your KAB and in which directories they should be placed.

    <!-- ====== Profiles ============================================================= -->

    <profiles>
        <profile>
            <id>developer</id>
            <activation>
                <activeByDefault>true</activeByDefault>
            </activation>
            <build>
                <plugins>
                    <!-- Build KAB file -->
                    <plugin>
                        <groupId>com.kosdev.kos.maven</groupId>
                        <artifactId>kos-kab-maven-plugin</artifactId>
                        <executions>
                            <execution>
                                <phase>package</phase>
                                <goals>
                                    <goal>kabtool</goal>
                                </goals>
                                <configuration>
                                    <type>kos.system</type>
                                    <content>
                                        <copy>
                                            <dir>lib</dir>
                                            <include>${project.build.directory}/${project.artifactId}-${project.version}.jar</include>
                                        </copy>
                                        <copy>
                                            <dir>.</dir>
                                            <include>${project.basedir}/descriptor.json</include>
                                        </copy>
                                    </content>
                                </configuration>
                            </execution>
                        </executions>
                    </plugin>
                </plugins>
            </build>
        </profile>
    </profiles>

Complete pom.xml

Step Two: Create the Descriptor File

The descriptor.json file provides a standardized method for embedding metadata into KAB files for use in kOS. We will use it to describe the details of our applications to kOS. In later tutorials, we’ll see how descriptor.json can be used to support localization and even firmware updates. Developers can customize the descriptor.json while reserving the kos.* namespace for standardized sections.

The descriptor.json File

{
  "kos": {
    "app": {
      "appClass": "com.bookstore.rack.RackApp",
      "appId": "system"
    }
  }
}

appClass: Specifies to kOS the class that it should load to launch your application.

appId: Defines a unique ID for this application. Every application requires a unique ID to help allocate resources in kOS. We’re building a system application which always has an ID of system.

Step Three: Place the Content for the Image Rotator

Adding Images to Your Project

Add these four images to the src/main/resources/images directory.

Project Directory Structure

Your project directory should look like this:

rack/
├── src/
│   ├── main/
│   │   ├── java/
│   │   │   └── com/
│   │   │       └── bookstore/
│   │   │           └── rack/
│   │   │               ├── RackApp.java
│   │   │               └── RackIU.java
│   │   └── resources/
│   │       ├── images/
│   │       │   ├── all.png
│   │       │   ├── book1.png
│   │       │   └── book2.png
│   │       │   └── book3.png
├── descriptor.json
├── pom.xml
└── README.md

Summary

In this lesson, you learned how to set up a Maven project for a kOS application. We covered creating and configuring a POM file to manage your project, including specifying dependencies and plugins for building and deploying your app. We used a BOM to ensure compatibility between SDK versions. We also touched on the KAB plugin to package your project into a KAB file. By following these steps, you now have a fully configured Maven project ready for deploying a kOS application.

[prev]

[next]

On this page