Usage docs now on ReadTheDocs (work in progress)

Tools I use for developement:
IDE with Maven support: NetBeans 7.4 (using Java 7 on all systems)
GitHub support: SourceTree (Mac + Windows)
CI Service: Travis CI
Doc Service: Read the Docs
Main WebSite Service: Weebly
Private complementing Websites: Host Europe

to build the ready-to-use packages available on Launchpad
(this is at least the intention at time of final release end January 2014).

Forking and/or downloading this repo only makes sense:

• if you want to get a knowledge about the internals of Sikuli
• if you want to create your own packages containing Sikuli features
• if you want to contribute.

If you "only" want to use the SikuliX features developing in Java or any Java aware scripting language (Jython, JRuby, Scala. Closure, ...) it is strongly recommended to start with sikuli-java.jar (run Sikuli setup with option 4).

To get the ready-to-use packages (IDE, Script, Java/Jython support)
it is still recommended to start here.

Each folder (module) in this repo is a Maven project by itself with its own POM, but it needs to be in this folder and POM structure, since there is a super POM on the first level, that is the parent POM for all the other child POMs and installs all modules into your local Maven repo. For detailed usage information look further below.

--- The top level modules (representing the Sikuli features) ---

Module API

The Java implementation comprising the API to access the top elements (Screen, Region, Pattern, Match, Image, ...) and their methods allowing to search for images and to act on points and matches simulating mouse and keyboard.

The ready-to-use package sikulixapi.jar provides this API for Java programming and any Java aware scripting languages.

Module IDE

Implements a GUI using Java, that allows to edit and run Sikuli scripts (currently only Jython is supported). It is an easy to use IDE focusing on the handling of the screenshots and images used in the typical Sikuli workflows.

The package sikulix.jar is the top level package containing all other options (hence the follow up of sikuli-ide.jar known from former releases).

This package sikulix.jar comes bundled with the Jython interpreter, thus allowing to run Sikuli scripts out of the box from the commandline and providing an interactive Sikuli aware Jython shell (hence it includes the functionality known from the sikuli-script.jar of former Sikuli(X) releases and is used the same way).

--- The helper/utility modules (intended for internal use only) ---

Module Jython

Implements Jython support for the IDE and for running scripts using Jython as scripting language.
(contained in package sikulix.jar)

Module JRuby

Implements JRuby support for the IDE and for running scripts using JRuby as scripting language.
(optionally contained in package sikulix.jar)

Module Basics

Implements basic utility and helper features used in the top level packages (basic file and folder handling, download features, jar access and handling, export of native libraries, parameter and preferences handling, update and extension handling, ...) and hence it is contained in all packages.

As a special feature it comprises the sikuli-setup.jar, which is run after download to build the wanted Sikuli packages and make them ready-to-use on the specific system (Windows, Mac or Linux).

Module OpenCV4SikuliX

Sikuli's image search is based on respective features of OpenCV. Starting with version 2.4.6 OpenCV provides a self-contained JNI interface to the OpenCV native libraries, allowing to use OpenCV features directly in Java (and hence making C++ programming obsolete for this).

This module contains a specially configured Java/JNI OpenCV package (built using the standard OpenCV configure/make workflow) for use with the OpenCV features currently needed by Sikuli (core, imgproc, feature2d and highgui). The corresponding native library pack (currently Mac only) is contained in the module Libs.

With the final availability of version 1.1.0 the implementation of the OpenCV usage will be moved completely to the Java level. Until then the historical implementation in C++ is activated in the standard. The usage of the new implementation (in the new classes ImageFinder and ImageFind) can be switched on optinally for testing and developement.

For Windows and Mac the native packages will again be pre-built and ready-to-use. For Linux there will be advices and scripts available to get the needed libraries ready.

For more information on preparation and usage of the new OpenCV Java API look here ...

Module Tesseract4SikuliX

This is an adaption of the work Tess4J to the needs of this project, to allow the use of relevant Tesseract features directly from the Java level. The implementation is on level Tesseract 3.02 and uses JNA direct mapping to access the native functions in the library libtesseract.

For Windows and Mac the native packages will again be pre-built and ready-to-use. For Linux there will be advices and scripts available to get the needed needed libraries ready.

For more information on preparation and usage of the new Tesseract Java API look here ...

Module Natives

Contains the Java sources interface classes (JNI based, mainly SWIG generated) and the C++ sources providing the implementation of the OpenCV and Tesseract usage and the implementation of some system specific features (HotKeyHandling, App class support,...).

A maven based build workflow for the native libraries (libVisionProxy, lib...Util and hotky support on Mac) is available in the module Libs, which is also the target module for the prebuilt libraries finally bundled with the top level packages.

--- The modules used to support package production (container jars) ---

Module Libs

The prebuilt native libraries for Windows, Mac and Linux (partially).
(contained in sikuli-setup.jar)

It contains a Maven workflow to execute build scripts for the native libraries on the system running on:

• Windows (not yet ready): WinUtil.dll, VisionProxy.dll
• Mac: libMacHotkeyManager.dylib, libMacUtil.dylib, libVisionProxy.dylib
• Linux: libVisionProxy.so

To run it from the project root folder:
mvn -f Libs/x*

The build scripts are in the respective system folder in folder build
The built libraries will directly go to the respective resources folder.
In case of errors you have to check the prerequisites: look here ...

For Linux there will still be a supplemental package available on the download page, that allows to build libVisionProxy.so

Module Tesseract

Currently as a convenience the standard tessdata folder needed for using Tesseract 3.0.
(will be downloaded on request during a Sikuli setup)

Module MacApp

A template Sikuli-IDE.app, that is downloaded on request and made ready-to-use during Sikuli setup.

Module Docs (not Maven-ized yet)

The source files for the textual documentation (built with PythonSphinx based on .rst files) and a ready-to-use HTML version as well as a HTML version of the JavaDocs of the main public Java API.
(is downloaded and made ready-to-use-locally during Sikuli setup)

--- Modules being AddOns or Extensions --

Module Guide

Module Remote

If you intend to compile and build the modules after having downloaded this repo, you need a valid Maven 3 installation and for editing, testing and integration some IDE, that is enabled for working with Maven projects.
(I myself use NetBeans 7.4, which supports Maven by default)

Take care Even if you only want to work on one of the modules (e.g. API), the modules should not be moved around, but stay in the structure of the downloaded repo. Each module depends on the parent POM in the root as well as the ready-to-use-jar-production POMs, that additionally depend on the assembly descriptors plain.xml and complete.xml.

--- Mandatory first step

In the root directory of the repo run
mvn clean install
which builds all modules and installs the artifacts into your local Maven repository.

If you want jars containing the sources of the respective modules and/or containing the javadocs you can use the following profile switches:
mvn clean install -PwithSource,withDocs
(but for local usages, there might not be any sense in that ;-)

Be aware This mandatory first step will add "tons" of additional stuff from Maven Central repository to your local Maven repository, especially when you are a first time Maven user.

--- Basic compile/package/install for each module

You have 3 options, to selectively run the POM of a specific module alone:

1. in the root folder run
   mvn -pl <ModuleName> [clean] [compile|package|install]
   where <ModuleName> is the respective folder name
2. in the module's folder run
   mvn [clean] [compile|package|install]
3. use the respective build steps in your IDE being in one of the module projects

You might additionally use the above mentioned profile switches.

--- Running the IDE or running scripts ---

In this Maven context the only runnable (means: should be run or makes sense to run) module is IDE (besides Basics with RunSetup), but this is sufficient, to get access to and test every aspect of Sikuli, since you can start the IDE, run scripts directly as well and start an interactive Jython session.

Being in module IDE firing the RUN button in an IDE should start the Sikuli IDE showing the splash screen, that allows to enter parameters (and thus allowing to run scripts using option -r).

The following Java settings are relevant for running Sikuli IDE from an IDE or using Maven:

• -Dsikuli.Debug=3 sets a higher debug level from beginning (to debug startup problems)
• -Dsikuli.console=false the equivalent of the option -c (script output goes to console)
• -Dsikuli.FromCommandLine suppresses the startup splash screen (set parameters in IDE project run setup instead)

Debugging should work without problems, when starting the module IDE in debug mode.

The mudule IDE POM contains the exec-maven-plugin, so to run the Sikuli IDE you can use being in the IDE folder
mvn exec:java -Dsikuli.FromCommandLine -Dexec.args="args for Sikuli"

or this being in the root folder
mvn -pl IDE exec:java -Dsikuli.FromCommandLine -Dexec.args="args for Sikuli"

As it is standard with Maven, all -D parameters go to Java system properties, wheras the content of -Dexec.args string will be given to the args array for the main method of the startup class.

--- How to produce the ready to use jars ---

... sikulix.jar and sikulixapi.jar

please look here

--- How to deploy to a private Maven repository ---

Edit/configure the repository in section distributionManagement in root pom.xml.
The current setting is to the local copy of the peer Git Repo SikuliX-Maven-Repo here (after deployment you have to run a commit and trigger a push, to get it on GitHub).
This approch comes from here ....

To make a deploy run
mvn deploy -PwithDocs,withSource

With Maven < 3.0 you might need -DaltDeploymentRepository=... additionally.

For usage hints look at the README of SikuliX-Maven-Repo