This document provides an overview of the Codename One source code structure. It explains that the source code is split into several GitHub repositories that should be cloned locally. The main repositories are Codename One, cn1-binaries, and codenameone-skins. It then describes some of the key directories and projects within the Codename One repository, including the CodenameOne API sources, CodenameOneDesigner, the ParparVM source code, and ports to different platforms like Android and JavaSE.

1. Hacking the Source - Part I
Working with the Codename One sources is not for the faint of heart. You can learn a lot from going through the process. However, if your only goal is to avoid the build
servers you might find it harder to work with.
In fact I personally use the build servers when building apps and testing them. I almost never use offline build or the sources directly. Instead I hack and test things via
the include source options. However, learning this is still valuable and I'm aware of a few people who don't share my opinion on this matter...

2. Who is this For?
© Codename One 2017 all rights reserved
✦You like doing everything manually
✦You want to learn low level underpinnings
✦Future proofing
Still, why would I write a guide for something like this?
There are 3 individuals I can think of who might benefit from this guide
If you are the type of person who needs to do everything yourself then this is pretty much it
If you want to understand the underpinning of Codename One at a deeper level than the more abstract descriptions. Then this is a good first step
If you want to feel secure that you can hack Codename One manually if our service changes or becomes unavailable in the future then the mere existence of this guide
should help calm some of those concerns

3. Basics
© Codename One 2017 all rights reserved
✦VM
✦API
✦Ports
To understand how to work with the Codename One code we first need to understand what Codename One does. For this case I'll remove the build servers from the
equation and focus on the portability aspect.
Codename One includes 3 distinct pieces for portability:
VM - for some platforms such as Android the VM is natively included. However, we work on top of ParparVM in iOS, iKVM in Windows & TeaVM for JavaScript
API represents the actual calls to the com.codename1 classes
Ports are the implementations of the API for the various platforms
This is all pretty trivial. The API is always the same, we change the VM and ports to support all the platforms. So if you understand this then the simulator is simple too. In
the simulator the VM is just the standard Java VM. And the port is just a port of Codename One to JavaSE.
There is a bit more to that though. The port to JavaSE includes a lot of specialized glue code to show the simulator and other features such as the network monitor etc.
But lets start with this and move on.

4. Plugin & Tools
© Codename One 2017 all rights reserved
✦You don’t need the plugin for this module
✦But it will make things easier
✦JDK 8 (not newer)
✦Apache Ant
✦Git
✦Android Studio 3.x
✦xcode 9.x
All of the instructions that follow will work regardless of whether you have the plugin installed. I will focus on using the command line and assume that you can translate
that to your IDE of choice.
Technically you don't really need the plugin if you are working from the source code. However, it's convenient to work with. It means that selecting New Project and
picking Codename One “just works”. It means that double clicking a resource file launches the designer tool. But technically you don't really need it.
What you do need is JDK 8 notice that newer versions might not work! We generally use the Oracle JDK because it comes bundled with JavaFX and that makes
everything simpler as the simulator needs JavaFX for some features (specifically media and browser). If you choose to use Open JDK it might work if you install it with
OpenJFX but it's not something we tried.
Apache Ant can be downloaded from the Apache website. Make sure ant is in your system path and that the command runs. Note that you will need to define the
JAVA_HOME environment variable properly.
Git is optional. You can just download the zip from github but if you'd like to contribute pull requests back into the project this can be useful.
For Android development we’ll use Android Studio 3.x which you can download from Google
For iOS development we will use xcode 9.x from Apple

5. git clone https://github.com/codenameone/CodenameOne.git cn1
git clone https://github.com/codenameone/cn1-binaries.git
git clone https://github.com/codenameone/codenameone-skins.git
or download:
https://github.com/codenameone/CodenameOne/archive/master.zip
https://github.com/codenameone/cn1-binaries/archive/master.zip
https://github.com/codenameone/codenameone-skins/archive/master.zip
The Code
We need to clone these repositories or just download the source zips of these repositories and expand them. These repositories should reside in the same hierarchy and I
will rely on that later on when giving out instructions.
you will notice we have 3 repositories to start with. Codename One is the main repo, the skins make sense as we use them to show the phone skins. But why have
binaries?

6. Binaries
© Codename One 2017 all rights reserved
✦svg
✦ikvm.zip
✦rim5/rim4
✦jfxrt.jar
✦javase/Filters.jar
✦javase/sqlite*
✦vm/asm*
✦android
✦j2me
✦designer
✦JavaDocSourceEmbed.jar
✦CLDC11.jar
✦corevm.jar
✦uwp
The immediate question would be why do we need binaries for an open source project?
The answer is that they are harder to build on their own in some cases and in others we need stubs of native platforms so we can compile against them without
downloading the full SDK. Lets go over the files & directories in the binaries project and explain them one by one:
The svg directoryis from the open source Batik project. It's unmodified. We need it for the Designer tool for SVG support.
The iKVM project is hard to compile without windows so we have a pre-compiled version here.
These are legacy stubs of the blackberry OS I won't cover blackberry here so these aren't really needed.
We need stubs to compile JavaFX code we don't embed this
This is the jhlabs project for Java SE image filters. We use this to implement gaussian blur in the simulator
These are used by the SQLite implementation in the simulator
these are a part of the open source ASM project which we use in ParparVM
Everything here is stubs which we use to compile the Android native implementation without downloading the full Android SDK. We don't run any of this just use it for
compilation

7. cn1 Directory Sources
© Codename One 2017 all rights reserved
✦CodenameOne
✦CodenameOneDesigner
✦vm
✓ ByteCodeTranslator
✓ JavaAPI
✦Factory
✦Themes
✦tests
✦Ports
✓ Android
✓ iOSPort
✓ JavaSE
✓ UWP
✓ CLDC11
✓ retro/rim/j2me/
winphone7
Before we go into building the project lets inspect the separate pieces. Most of the pieces we fetched in the Codename One repository are NetBeans projects. Notice
that NetBeans projects are just specific folder structures with an Ant build.xml file. That means you don't need NetBeans in order to build or run them.
The CodenameOne folder includes the Codename One API's. This is just a standard NetBeans ant project that contains 100% portable code. Notice that at this time this
project still uses Java 5 syntax due to some technical constraints.
CodenameOneDesigner contains the designer tool which is a Swing application built with the Swing App Framework. It's a standard NetBeans project too with major
pieces written using the NetBeans Matisse GUI builder.
The VM directory hosts the ParparVM source code. It includes two sub folders each of which is a standalone NetBeans ant project
The BytecodeTranslator is a Java NetBeans project that reads Java bytecode and generates C code. It includes a couple of builtin C files but most of the C code is
generated
The portion of the VM that isn't a part of the Codename One API. This is a NetBeans project that includes implementations of all the java packages needed by ParparVM
Factory is a simple project that contains one class com.codename1.impl.ImplementationFactory. That lets us decouple the implementation of Codename One from the
ports
Themes are the native OS theme files which we load when a theme derives from native. These are embedded into the ports and into the skins