We have loads of demo Codename One apps hosted on Github, however cloning and running a project can be a little tricky because we generally don’t publish the dependent jar files (e.g. CodenameOne.jar) in the Github repository. This helps keep the repository lean, but it adds some steps to the process of cloning and running the project.
For use cases like this, you may want to try the Codename One CLI tool, as it provides many useful functions directly on the command line. In this post I’ll demonstrate how you can easily clone a Codename One project from Github and run it in the Codename One simulator using a single line of code.
Consider the KitchenSink demo. We can clone this repository using the following command
$ cn1 git-clone https://github.com/codenameone/KitchenSink
Cloning into 'KitchenSink'...
Installing jars into KitchenSink...
Downloading 11606508 bytes
Project ready at KitchenSink
cn1 git-clone command is a thin wrapper around
git clone (which implies that you need to have
git clone in your PATH). Therefore you can pass it the same parameters as you pass to
git clone. After cloning the repository,
cn1 git-clone downloads the latest Codename One libs and adds them to the project so that it is ready to roll.
Now that the project is cloned, we can run the demo in the Codename One simulator by running the "run" target of the project. E.g.
$ cd KitchenSink
$ ant run
Combining it into a Single Line
If you are on Mac/Linux, it is easy to use the '&&' operator to combine all this into a single line:
$ cn1 git-clone https://github.com/codenameone/KitchenSink && cd KitchenSink && ant run
This clones it, changes to the KitchenSink directory, and runs it.
Finding Existing Demos
You can also use the
cn1 list-demos command to find existing Codename One demos on Github that you can clone. E.g.
This will produce a list of all of the repositories on Github that are tagged with both the "codenameone" topic, and the "demo" topic. The output will look like
shannah/GeoVizDemo : A demo app using the Codename One GeoViz Library
codenameone/KitchenSink : Rewrite of the kitchen sink demo to match design aesthetics of 2016
You can filter the results by adding a parameter.
$ cn1 list-demos "GeoViz"
This will only show demos that also match the GeoViz search. We have only just started tagging our demos so for now there aren’t very many listed there. But the list will grow as time goes on.
| || |
cn1 list-demos uses the Github search API, so you can use any filters that you would put into searches on the Github website.
Once we see a demo that we want to run, we can pass its full name to
cn1 git-clone. E.g.
$ cn1 git-clone shannah/GeoVizDemo
| || This demonstrates that git-clone allows you to omit the |
https://github.com from the repository name, and just provide the full repository name of the form
Adding Your Own Demos
Adding your own demos so that they will be included in the
cn1 list-demos results is easy. If your project is already hosted on Github, you simply need to add the
demo topics to the repository.
| || When hosting a project on Github I recommend stripping out all of the jar files just as we do in our demos. You can do this by simply copying the following directives into your |
.gitignore contents from the KitchenSink repository
A shortcut would also be to use
cn1 git-init instead of
git init when you initialize the repository.
Thus far, I’ve skipped the step of actually installing the CLI tool. It is distributed using
npm, which is included when you install NodeJS, which has a simple installer for Windows, Linux, and Mac.
Installing globally on Windows (Requires Admin permissions)
npm install -g codenameone-cli
Installing globally on Mac/Linux
sudo npm install -g codenameone-cli
If you don’t have admin permissions, or you just want to install it in the current directory, you can omit the
-g flag. Then installation becomes
npm install codenameone-cli
This will install the command at
I’ve create a short screencast demonstrating the use of the
cn1 git-clone command.