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
Download completed!
Project ready at KitchenSinkWhat just happened?
The 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.
Running the Demo
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 runCombining 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 runThis 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.
$ cn1 list-demosThis 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
... etc..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 ownername/repositoryname
|
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 codenameone and 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 file
|
.gitignore contents from the KitchenSink repository*.jar
nbproject/private/
build/
nbbuild/
dist/
lib/CodenameOne_SRC.zip
*.p12
*.mobileprovisionA shortcut would also be to use cn1 git-init instead of git init when you initialize the repository.
Appendix: Installing the CLI Tool
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
npm install -g codenameone-clisudo npm install -g codenameone-cliInstalling Locally
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-cliThis will install the command at ./node_modules/.bin/cn1
Screencast
I’ve create a short screencast demonstrating the use of the cn1 git-clone command.
2 Comments
Nice one. Makes the demo projects much more accessible.
Steve, excellent, just done this now .. better late than never! Many thanks for that, saved me lots of times.