Maven Project Workflow

Codename One uses Maven as the standard way to create, run, and maintain applications. This chapter consolidates the workflow guidance that used to live in the standalone Maven manual so the developer guide provides a single source of truth for building apps, updating projects, and managing add-ons.

Codename One uses Maven as its primary build tool. This guide aims to be the definitive source of information for this project structure.

The instructions throughout this chapter provide parallel guidance for the supported development environments. Each subsection heading identifies the target tooling so you can follow the directions that match your workflow:

When you reach environment-specific sections later in the guide, follow the subsection corresponding to your preferred tools.

Codename One supports JDK 11 through 25 for running the simulator and the "Run as desktop app" target. Eclipse Temurin is the easiest source of a supported JDK on macOS, Windows, and Linux.

After installing the JDK, point JAVA_HOME at it and confirm with:

Both should report Java 11 or newer. The Codename One Maven plugin checks the runtime JDK version when you invoke mvn cn1:run or mvn cn1:debug and fails fast with a friendly message if it’s older than 11. Build-only goals (such as -Pexecutable-jar) still work on older JDKs.

The easiest way to create a new project is to use the Codename One initializr.

This tool will allow you to choose from a growing selection of project templates, and download a starter project that you can open in your preferred IDE (IntelliJ IDEA, NetBeans, etc.), or build directly on the command-line using Maven.

The starter projects are based on the Codename One application project archetype (cn1app-archetype).

Codename One releases are published to the Codename One Maven repository at https://repo.codenameone.com/maven2, not to Maven Central. A generated project declares that repository in its own pom.xml, so once you have a project nothing further is needed.

The commands in this section run before there is a project, so Maven has no pom.xml to read the repository from and searches only Maven Central. Central still serves every version published before the move, so these commands keep working, but they can’t see a release published after it. Add the repository to your Maven settings once, in ~/.m2/settings.xml (%USERPROFILE%\.m2\settings.xml on Windows), and they can:

Both lists are needed. Maven resolves ordinary dependencies through <repositories> and build plugins through <pluginRepositories>, and the commands below invoke the Codename One plugin directly, which is the second list.

If you prefer to generate your projects directly on the command-line, you can use the Codename One application project archetype (cn1app-archetype) to generate the project directly on the command-line:

This will generate a project in the current directory. The project’s directory will have the same name as the artifact ID you specified here. For example, If your command had -DartifactId=myapp, then the project will be located in a newly created directory named "myapp."

This command uses the Codename One application project archetype (cn1app-archetype) which has the following Maven coordinates:

This archetype generates a bare-bones Java project (the same one described in Getting Started with the Bare-bones Java App Template).

You can learn more about using the archetype in the appendix.

The bare-bones Kotlin App project template is an alternative starter project that uses Kotlin as the primary language instead of Java. It’s built on the cn1app-archetype at its core, but it includes some more configuration settings and sources to change the template. You can use such templates as starter projects by using the generate-app-project goal of the Codename One Maven plugin.

Here is an example which generates a project based on the bare-bones Kotlin template:

Like the archetype:generate goal, this will create the project in a directory named after your specified artifact ID. For example, If your command included -DartifactId=myapp, then the project would be in a newly created directory named "myapp."

Some notes here:

If you have an existing Codename One application project that uses the old Ant project structure, you can use the generate-app-project goal to migrate the project over to maven. This goal doesn’t make any changes to the Ant project. It creates a new Maven project and copies over all the project sources and libraries, reorganized to fit the new project structure.

A minimal invocation of this goal would look like:

This will generate the new project in the current directory inside a folder named after the artifactId parameter.

After building the project, try running it to make sure that the migration worked. For example, Assuming that your artifactId was myapp:

If All goes well, your app should open in the Codename One simulator.

Open the myapp folder in IntelliJ. Then press the "Run" button in the upper right of the toolbar.

If All goes well, your app should open in the Codename One simulator.

Open the myapp folder as a project in NetBeans. Then press the "Run" button on the toolbar.

If all goes well it should open in the Codename One simulator.

Open Eclipse, and select "File" > "Import…​"

In the Import dialog, expand Maven, select Existing Maven Projects, and press Next.

In the next panel, press the Browse button, and, in the file dialog, select the "myapp" directory, and press Next.

The next panel should look like the one below. Make sure all the projects are "checked," and press Finish.

Almost there, but not quite…​

Next you need to import the Eclipse launch configurations located inside the tools/eclipse directory.

Select File > Import…​ again, but this time, in the Import dialog, select Run/Debug > Launch Configurations and click Next.

In the next panel, press Browse…​ then select the tools/eclipse directory.

Then check the eclipse option, and press Finish

The "Run" button menu should now include options for all the major build targets. You can see them by pressing on the Run button in the toolbar:

Select the MyApp - Run Simulator option from this menu.

If all goes well it should open in the Codename One simulator.

Consider a concrete example, now. Download the KitchenSink Ant project from here and extract it.

The following is a bash script that uses curl to download this project as a zip file, and then converts it to a fully functional Maven project:

This will generate the maven project in a directory named "kitchensink" in the current working directory because of the -DartifactId=kitchensink directory.

One of the reasons to use Maven as the build tool is because it makes the management of project dependencies almost trivial. If the library you want to add is on Maven central, then you can copy and paste its <dependency> snippet into your pom.xml file and you’re good to go. Maven does the rest.

With Codename One projects, there are a few caveats (see The compliance check), and a few added niceties that make it easier to find and install add-on libraries in your project (see Managing add-ons in Codename One Settings).

Suppose you have a Maven <dependency> snippet that you’ve copied from Maven central, and it’s burning a hole in your clipboard while you’re trying to figure out where to paste it into your project. Codename One application projects, being multi-module projects, have more than one pom.xml file; One per module.

Question: Which pom.xml file should you paste the snippet into?

Answer: common/pom.xml (almost always).

The "common" module is where all your Codename One application resides. It houses your Java and Kotlin files, your CSS files, your GUI builder files, your Codename One configuration files (that is, codenameone_settings.properties). Pretty much everything. The things you’d place in the other modules (for example, Java SE, ios, etc.) are your platform-specific native interface implementations; And in many applications you won’t need any of that.

When adding dependencies into your app, you’ll therefore almost always place them inside the pom.xml file for the "common" module.

Add the GoogleMaps library to your app as a maven dependency.

As described in the GoogleMaps cn1lib README, the dependency snippet is:

You should, but, look on Maven central to see what the latest version number is, and substitute that version into the <version> tag of the snippet.

Copy and paste this snippet into the <dependencies> section of your common/pom.xml file. And save it.

You can paste any Maven dependency snippet you like into your project, but libraries that haven’t been specifically developed for Codename One might not be compatible. See Appendix C, API. If you’re unsure whether a library is compatible, you could add the dependency and try to use it in your app. If it isn’t compatible, it will fail when you try to build the app, during the compliance check.

The easiest way to find Codename One libraries is to use the Extensions view in Codename One Settings. These libraries were built specifically for Codename One. Settings warns before installing catalog entries known to target older Codename One releases.

All application code in the common module of your Codename One project must be compatible with Codename One. This includes all dependencies. When you build your project, it will perform a compliance check to ensure that no code uses unsupported APIs. (See Appendix C, API).

If the compliance check fails (that is, the app uses unsupported APIs), the build will fail. The error log should provide some clues about where the offending code resides.

Launch Codename One Settings from the project root, then select Extensions in the left navigation rail:

As an example, install the "Google Maps" library.

Type Maps in the search field and locate Codename One Google Native, the Google Maps library.

Click Install or Download, depending on how the catalog entry is distributed.

Settings shows progress while it installs the extension. For an installed extension, click the same action area and confirm Uninstall to remove it.

Settings is a Codename One app hosted in a native window, so a window that opens but shows nothing can come from the window layer, the display scale, the theme, or font loading. Capture the render state and attach it to a bug report rather than guessing:

The file records the OS and JDK, the HiDPI scale the JVM reports, the window and canvas geometry, the size Codename One laid the form out at, and the colours and font metrics resolved for the theme. Add -Dsettings.screenshot=shot.png to also write the window contents; a second shot.onscreen.png captures the pixels actually on screen, which can differ from the offscreen paint. The launch log is at ~/.codenameoneSettings/settings.log.

The recommended approach for installing add-ons is to use Codename One Settings or add the Maven dependency to common/pom.xml. In some situations neither method is available. For example, you might have a legacy cn1lib file that isn’t listed in the extension catalog or deployed to Maven Central.

In cases like this you can use the install-cn1lib Maven goal to install it as follows:

Codename One releases new versions weekly to the Codename One Maven repository. It’s recommended that you stay up to date with the latest version as much as possible to ensure compatibility with the Codename One build server, which is always running the latest version.

You can use the update goal to update both the Codename One libraries, and the Codename One dependencies in your project.

For example:

Or you can use the run.sh/run.bat script to run this goal as follows:

Or you can click on the "Configuration" menu, and select "Tools" > "Update Codename One" as shown here:

Then press the button.

Or you can right-click on the project in the project inspector, and select "Run Maven" > "Update Codename One" as shown here:

Then press the button.

You can also update your Codename One dependencies manually by modifying the cn1.version and cn1.plugin.version properties defined in your project’s pom.xml file.

For example, Open the pom.xml file, and look for the following:

Change these values to reflect the latest version of the codenameone-maven-plugin, listed as <release> in the repository metadata. The update goal reads the same metadata and edits both properties for you.

A project template is a Codename One application project that can be used as a starting point for building a Codename One application. Codename One initializr uses project templates to generate starter projects for Codename One applications. You can also use the Generate app project (generate-app-project) goal to generate starter projects from templates directly in Maven.

Any Codename One project can be converted into a project template.

If you have an existing maven Codename One application project, you can convert it into a project template by adding a file named generate-app-project.rpf in the root directory of the project.

The contents of this file should look like:

Where you make the following substitutions:

See Sample generate-app-project.rpf file for a more concrete example of the generate-app-project.rpf.

You can test your project template by using it as the sourceProject parameter for the generate-app-project goal. See Generate app project (generate-app-project).

A Codename One Library (cn1lib) is a module that can be distributed and added to Codename One applications to add functionality. It can be distributed as a self-contained bundle (a file with the.cn1lib extension), or deployed on Maven central to be included in application projects as a pom dependency.

A cn1lib may contain any of the following:

Use the cn1lib-archetype for generating a new Codename One library project as follows:

In the above snippet you would change the groupId, artifactId, and version properties to reflect your project settings.

This will create a new project for you in the current directory, in a newly created directory named after the artifactId that you entered.

At this point you will be prompted to open the project.

This will create a new library project for you at the location you specified.

This will create a new library project for you at the location you specified.

Take a look at the project that was created. It’s a multi-module Maven project with the following modules:

The project inspector will look like:

This top-level view of the module structure may seem daunting. Most of your development will occur inside the "common" module. If you expand that module it will look more familiar to developers who have used the old Ant project structure:

Your cross-platform Java source would go in the common/src/main/java directory. Your CSS files go in the common/src/main/css directory.

The project inspector will look like:

This top-level view of the modules doesn’t provide a clear view of the project landscape, but, since 99% of your development will occur inside the common submodule. Open that "common" sub-module project as well and take a peek.

Right-click on the "Common" sub-module, and select "Open Project" as shown below:

With the common subproject open, the project inspector will look like:

In this screenshot, "Source Packages" and "Other Sources/css" are expanded to highlight where your Java source files and CSS source files will be located.

The project inspector hides a few important files, but, so here is a screenshot of the File inspector for the common project:

The package explorer will look like:

In this screenshot, the common/src/main/css and common/src/main/java directories are expanded since this is where most of your module source will go.

If you do a file listing on the project directory, it shows the following:

This may seem daunting at first, but it’s important to realize that 99% of the time, you’ll be working in the "common" module - most of the other stuff is boilerplate.

A few key files in this project that you’ll be using more than the others.

As mentioned earlier, 99% of all your development will likely occur inside the "common" module. The other modules are for native implementations of Native interfaces.

To build the library, run the "install" goal on the root module as follows:

Press the "build" button on the toolbar.

Right-click on the "root" module in the project explorer and select Build.

Or you could have selected the "root" module in the project explorer and pressed the "build" button on the toolbar.

Right-click on the "root" module in the project explorer and select Run as > Maven Install

When using the Maven build tool, you no longer require the.cn1lib file at all. Your library projects can be handled entirely via Maven’s dependency mechanism. The preferred way to distribute your libraries is on Maven central, and the preferred way to add a library to an application is via a Maven "pom" dependency.

That being said, you may still want to distribute your library as a.cn1lib file for the sake of users who are still using Ant as their build tool. For that reason, when you build a library project, the cn1lib is automatically built as well. After running a build, you can look in the common/target directory and find your.cn1lib file ready to be distributed.

To get acquainted with your project, add a "Hello World" Java class that you want to make available as part of your cn1lib.

Add a new class inside the "common/src/main/java" directory with package com.example, and name HelloWorld. Enter the following contents into the class:

Now build the library again. (See Building the library).

Now that you’ve built your library and added a Java class, try adding it as a dependency in an application project. If you haven’t yet created an application project, do that now. See Creating a new project for instructions on creating a new application project.

Open the common/pom.xml file of your application project.

This file may look a little hairy as there is a lot of configuration in there. You will be looking for the <dependencies> section.

The common/pom.xml file will have more than one <dependencies> tag, as it includes some profiles handling things like Kotlin support. There will be one particular <dependencies> tag that includes a comment like

You should add your dependencies before this comment.

For the sake of this example, suppose your library was set up with the following coordinates:

In this case you would add the following XML snippet to the <dependencies> section of your application’s common/pom.xml file:

Now try it out. Try adding the following code to your application project’s main class (or anywhere in the application project, for that matter):

This calls into the library you just built, so it isn’t one of the compiled examples:

And build the project. The project should build OK, and if you run it, you should see that the helloWorld() method works as designed.

A cn1lib can contribute menu items to the Codename One simulator’s menu bar. This is the same affordance the framework itself uses for the Skins / Native Theme / Simulate menus — opened up so library authors can expose backend-specific actions (for example, "Add a simulated peripheral," "Inject a push notification," or "Switch backend") without users having to write any Swing code or instrument their app.

Every menu item is also reachable from CN1 UnitTests (or any app code) through CN.execute("namespace:itemN") — the JavaSE port’s URL execute is overloaded to recognize a registered hook url and dispatch it on the EDT instead of opening it as a browser URL. On Android, iOS, JavaScript and other production targets no hooks are registered, so a hook-style URL falls through to the normal native execute and (almost always) becomes a no-op; tests should pair CN.execute with CN.canExecute for that reason. Hooks can also be declared with no menu label, which makes them callable from tests but invisible in the menu — useful for state-priming actions a human wouldn’t click.

Each cn1lib ships a properties file at a well-known classpath location. The simulator scans every jar on its classpath for this resource and merges the results, so multiple cn1libs coexist cleanly:

Required keys:

Optional keys:

No groups, no submenus, no priority — flat by design. If you need ordering relative to another cn1lib, you can’t have it: discovery order wins, and that’s intentional so the contract stays small and the future simulator UX can re-render this metadata however it likes.

The simulator dispatches every action on the Codename One EDT through Display.callSerially, so your method can call Display.getInstance(), Form.show(), Dialog.show(), ToastBar.showInfoMessage() and any other CN1 API. Reflection uses the same classloader that loaded Display, so cn1lib internals (including package-private classes) resolve normally:

This is a method in your own cn1lib, so it isn’t one of the compiled examples:

The Display.isInitialized() guard is a useful pattern when the same static methods are also called from JUnit tests that don’t run inside a live CN1 simulator — the state mutation runs in both contexts, only the UI feedback is skipped.

The cn1-bluetooth cn1lib ships a JavaSE port with two backends: a scriptable in-memory simulator and a real-hardware backend that talks to a native helper (CoreBluetooth on macOS, BlueZ on Linux, WinRT on Windows). Both are useful in different stages of development, and the menu lets the user choose between them and exercise the simulator without writing any test scaffolding.

Its simulator-hooks.properties looks like this:

When the user runs an app that depends on cn1-bluetooth, the simulator’s menu bar gets a Bluetooth menu with the three labeled items. Clicking Add demo peripheral drops a peripheral into the in-memory simulator that the running app can then scan for, connect to, and exchange data with — without any real hardware. item4 is callable from tests via CN.execute("bluetooth:item4") but never shows up in the menu.

CN1 unit tests (AbstractTest subclasses run via mvn cn1:test) compile under the same restrictions as the rest of the app — no reflection, no JavaSE-only imports. Drive a hook the same way you’d execute any URL — CN.execute recognizes registered hook urls and dispatches them on the EDT:

A common pattern: ship label-bearing hooks for actions a developer might want to fire manually (toggle adapter, inject notification), and ship label-less hooks for test-only state setup (primeReadFailure, seedFixture) that would just clutter the menu.

The recommended way to distribute your library is on Maven central. That way users will be able to install your library by copying and pasting a familiar <dependency> snippet into their pom.xml file.