The build servers can build native iOS apps without a Mac and native Windows apps without a Windows machine. They remove the need to install and update complex toolchains and simplify the process of building a native app to a right click.

Even though the build servers streamline delivery, Codename One also supports fully local builds. You can install the toolchain on your own hardware and follow the workflows in Chapter 2, Maven Project Workflow and Chapter 96, Working with Codename One sources to compile, package, and test apps without leaving your desktop environment.

For example, because native iOS applications require a Mac with a recent version of Xcode, Codename One maintains such machines in the cloud. When developers send an iOS build, that Mac generates C source code using ParparVM, then compiles the C source code using Xcode and signs the resulting binary using Xcode. You can install the binary on your device or build a distribution binary for the App Store. Since C code is generated, your app is also future-proof against changes from Apple. You can also inject Objective-C native code into the app while keeping it 100% portable thanks to Codename One’s native interfaces capability.

Subscribers can receive the C source code back using the include-sources feature of Codename One and use those sources for benchmarking and debugging on devices.

The same is true for most other platforms. On Android and Java SE, Codename One runs the standard Java code, unchanged.

Codename One uses a SaaS-based approach so the information in this appendix might (and probably will) change in the future to accommodate improved architectures. This appendix includes this information for reference, you don’t need to understand this to follow the content of the book…​

Since Android is already based on Java, Codename One is already native to Android and works with the Android VM (ART/Dalvik).

On iOS, Codename One built and open-sourced ParparVM, which is a conservative VM. ParparVM features a concurrent, non-blocking GC and is written entirely in Java/C. ParparVM is a transpiler that generates C source code matching the given Java bytecode. This means that an Xcode project is generated and compiled on the build servers. It’s as if you hand-coded a native app and is thus future-proof against changes that Apple introduces. For example, Apple migrated to 64-bit, then introduced bitcode, then withdrew bitcode again. ParparVM needed no modifications for any of those changes.

Codename One earlier offered a UWP (Universal Windows Platform) target based on iKVM. That target was discontinued in release 7.0.229 and is preserved as historical context in older documentation and blog posts.

JavaScript build targets translate the bytecode statically with ParparVM, the same translator that generates the C sources for iOS. Cloud builds keep the original TeaVM-based compiler as a compatibility fallback, which you select with the javascript.port build hint. To support the complex UI Codename One uses the HTML5 Canvas API which allows absolute flexibility for building applications.

Desktop builds are packaged on the same cloud machines, a Mac for the macOS installer and a Windows machine for the Windows one. The build originally used javapackager, which was abandoned because it couldn’t package a ZuluFX runtime reliably; installers are now produced directly with third-party packaging tools.

Density is also known as DPI (Dots Per Inch) or PPI (pixels or points per inch). Density is confusing, unintuitive and might collide with common sense. For example, an iPhone 7 plus has a resolution of 1080x1920 pixels and a PPI of 401 for a 5-inch screen. But, an iPad 4 has 1536x2048 pixels with a PPI of 264 on a 9.7 inch screen…​ Smaller devices can have higher resolutions!

As the following figure shows, if a Pixel 2 XL had pixels the size of an iPad, it would have been twice the size of that iPad. While in reality, it’s half the height of the iPad!

Differences in density can be extreme. A second generation iPad has 132 PPI, where modern phones have PPI that’s over 600 dpi.

Low resolution images on high PPI devices will look either small or pixelated. High resolution images on low PPI devices will look huge, overscaled (artifacts) and will consume too much memory.

The exact same image will look different on each device, sometimes to a comical effect. One of the solutions for this problem is multi-images. All OS’s support the ability to define different images for various densities. Chapter 2 discusses multi-images later in detail.

This also highlights the need for working with measurements other than pixels. Codename One supports millimeters (or dips) as a unit of measurement. This is highly convenient and is a better representation of size when dealing with mobile devices.

However, there is a bigger conceptual issue involved. You need to build a UI that adapts to the wide differences in form factors. You might have fewer pixels on an iPad, but because of its physical size, you would expect the app to cram more information into that space so the app won’t feel like a blown-up phone application. Many strategies to address that, but one of the first steps is in the layout managers.

Chapter 2 discusses the layout managers in depth, but the core concept is that they decide where a UI element is placed based on generic logic. That way, the user interface can adapt automatically to the huge variance in display size and density.

The fact that mobile devices use a touch interface today isn’t news…​ However, the implications of that aren’t obvious to some developers.

UI elements need to be finger sized and spaced. Otherwise, you risk the “fat finger” effect. That means spacing should be in millimeters and not in pixels due to device density.

Scrolling poses another challenge in touch-based interfaces. In desktop applications, it’s common to nest scrollable items. For example, in touch interfaces, the scrolling gesture doesn’t allow such a nuance. Furthermore, scrolling on both the horizontal and vertical axis (side scrolling) can be inconvenient in touch-based interfaces.

Some developers single out this wide range of resolutions and densities as “device fragmentation.” While it does contribute to development complexity, it isn’t a challenging problem to overcome.

Densities aren’t the cause of device fragmentation. Device fragmentation is caused by many OS versions with different behaviors. This is clear on Android and relates to the slow rollout of Android vendor versions compared to Google rollout. A new release reaches only a small fraction of devices in its first year, and handsets several major versions behind stay in circulation long after their vendor stops shipping updates for them.

This makes QA difficult as the disparity between these versions is pretty big. It’s hard to get all device manufacturers aligned, so this problem will probably remain in the foreseeable future despite everything.

Besides the obvious need for performance and smooth animation within a mobile app, there are a couple of performance related issues that might not be intuitive to new developers: size and power.

Apps installed on the device are "sandboxed" to a specific area so they won’t harm the device or its functionality. The filesystem of mobile applications is restricted so one application can’t access the files of another application. Things that most developers take for granted on the desktop such as a "file picker" or accessing the image folder don’t work on devices!

This means that when your application works on a file, it belongs to your application. To share the file with a different application, you need to ask the operating system to do that for you.

Furthermore, some features require a "permission" prompt and sometimes require special flags in system files. Apps need to request permission to use sensitive capabilities, for example, Camera, Contacts etc.
Historically, Android developers declared required permissions for an app and the user was prompted with permissions during installation. Android 6 adopted the approach used by iOS of prompting the user for permission when accessing a feature.

This means that in runtime a user might revoke a permission. A good example for an Uber app is the location permission. If a user revokes that permission, the app might lose its location.

Before you get to the code there are few important things you need to understand about Codename One applications.

Once Maven is set up you can run the HelloWorld application by selecting the Codename One Run in Simulator task from the IDE run menu. The Codename One simulator launches and you can use its menus to control and inspect details related to the device. You can rotate it, determine its location in the world, monitor networking calls etc.

With the Skins menu you can download device skins to see how your app will look on different devices.

Use your IDEs Debug button with the Run in Simulator task to launch the simulator under the debugger.

After clicking finish in the new project wizard you have a HelloWorld project with a few default settings. The following sections break the class down to small pieces and explain each piece starting with the enclosing class:

The four platform callbacks the Application Lifecycle Sidebar describes are already implemented for you by Lifecycle, which is why the generated class carries none of them:

Some complex ideas appear within this short snippet that this chapter addresses later when talking about layout. The gist of it’s that you create and show a Form, the top level UI element that takes over the whole screen. You add UI elements to it, here a Button that opens a Dialog when tapped, and the BoxLayout arranges them from top to bottom. The same action is attached to the side menu through the Toolbar, so the starter shows both ways of triggering one piece of code.

Override one when you need to run code at that point. What the super call protects differs by callback: in init it’s the whole list above, in start it’s the only thing that puts a Form on screen, and in stop it’s the record of which Form to come back to. destroy is empty, so super there is optional:

That’s it. You should now have a general sense of the code. It’s time to run on the device.

Use the standalone Codename One Settings editor to configure the application title, version, package, icon, build hints, and extensions. Launch it from the Maven project root:

Use the standalone Certificate Wizard for signing assets. Monitor Codename One Cloud builds and subscription information on the Codename One website.

Due to the way Kotlin works you can create a regular Java project and convert sources to Kotlin. You can mix Java and Kotlin code without a problem and Codename One would "work."

The Java source it converts from is the class shown in the walkthrough above: a Lifecycle subclass overriding runApp().

When you select that file and select the menu option Code → Convert Java file to Kotlin File you should get a familiar structure. The problem is that there are two bugs in the automatic conversion…​ That’s the code for Kotlin behaves differently from standard Java.

The first problem is that Kotlin classes are final unless declared otherwise so you need to add the open keyword before the class declaration.

This is essential as the build server will fail with weird errors related to instanceof.

The second problem only bites if you override init(Object), which the generated class doesn’t. Kotlin treats arguments as non-null by default, and the context passed to init can be null, so an override has to accept it as fun init(context: Any?) or it fails with an exception.

Once all that’s in place Kotlin should work. This should be possible for more JVM languages in the future.

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.

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:

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 Section 2.2.4.4, “The compliance check”), and a few added niceties that make it easier to find and install add-on libraries in your project (see Section 2.2.4.5, “Managing add-ons in Codename One Settings”).

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 Section B.5.4.2, “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 Section B.5, “Generate app project (generate-app-project)”.

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

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.

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.

In the Codename One initializr, set Build tool to Gradle. A Gradle project then offers three project types:

The download opens in IntelliJ IDEA, NetBeans, Eclipse or Visual Studio Code, and builds from the command line with the ./gradlew wrapper it contains.

The Maven plugin converts a Maven or Ant application to the Gradle layout, writing a new project beside the old one and leaving the old one untouched. In the commands in this chapter, VERSION stands for the Codename One release you use:

The conversion runs anywhere, with or without a project in the working directory. These properties control it:

The conversion moves sources, CSS, localization and resources to src/main/…​, each platform’s native implementations to src/<platform>/<lang>, and the dependencies of common/pom.xml into build.gradle.kts. It raises codename1.arg.java.version to 17 and says so. Ant projects that mix Java and Kotlin in src/ get their Kotlin sources in src/main/kotlin and the Kotlin Gradle plugin in build.gradle.kts.

A project that uses legacy .cn1lib files is refused, and the message names every one of them. Depend on each library’s Maven coordinates instead, or republish it as a Gradle cn1lib (see Section 3.6, “Libraries”), then convert again.

The generate-app-project goal, which migrates an Ant project or a project template, produces a Gradle project directly with -Dcn1.buildTool=gradle:

A build task accepts -Pautomated=true to wait for a cloud build and download its result, and -Popen=false (or -Pcodename1.open=false) to keep a generated Xcode or Android Studio project from opening.

Build hints come from codenameone_settings.properties, as in every Codename One project. The codenameone {} block in build.gradle.kts adds hints for every build of the project, without the codename1.arg. prefix:

A hint on the command line applies to that build only, and wins over both. -Pcodename1.arg.<hint> and -Dcodename1.arg.<hint> are equivalent:

The same block also sets version, the framework version the project builds against (it defaults to the plugin’s), and mainClass, which defaults to the package and main name in the settings file.

Declare a cn1lib by its -lib coordinates in build.gradle.kts, next to any plain Java library:

These are the coordinates a Maven project uses with <type>pom</type>. The library’s classes and CSS reach every build, and its platform-specific code reaches only that platform’s: Maven chooses those jars with profiles, and the plugin reads the same profiles from the library’s published pom.xml. The library’s build hints merge into the application’s, as they do under Maven.

A project that declares repositories of its own in build.gradle.kts keeps the Codename One repository too: the plugin adds it beside them.

A Gradle project with a codenameone_library_appended.properties file (and no codenameone_settings.properties) is a cn1lib. It uses the same settings file, src/main/java for the library, src/main/css for its CSS and src/<platform>/<lang> for native code, and generateNativeInterfaces works as it does for an application. The build script sets the coordinates and, to publish somewhere other than the local repository, a repository:

The library is published in the same shape the Maven cn1lib-archetype produces, so Maven and Gradle applications both consume it. For a project named N:

Gradle cn1libs don’t produce .cn1lib files.