1.Check the prerequisites


-- Supported systems


SikuliX can be used on systems with
  • Windows XP and later including Windows 8 and 10 (32-Bit or 64-Bit)
  • Mac OSX 10.6 and later including 10.10 and 10.11 (64-Bit only)
  • Linux/Unix systems depending on the availability of the prerequisites (32-Bit or 64-Bit) (look here for more information)
Mobile OS (like Android, iOS, ...) are currently NOT supported in native mode (VNC solutions might apply).

-- Valid Java installation


In any case you must have a valid Java installation of at least Java 7 (JRE (runtime only) or JDK (runtime + development kit)). Up to SikuliX version 1.1.0 you can use it with Java 6 too.
It is highly recommended, to always have the latest stable Oracle/Sun Java version on your system (currently Java 8, does not work with Java 9). Equivalent versions of OpenJDK should work as well and are recommended on Linux systems..

On 64-Bit capable systems a Java 64-Bit version is strongly recommended. SikuliX will detect Java's bitness at runtime and select the fitting native library set automatically. So you might freely switch between different Java versions with the same SikuliX on one machine.

— How to check your Java version
On a command line entering
java -version
should yield an output similar to that
java version "1.7.0_45"
Java(TM) SE Runtime Environment (build 1.7.0_45-b18)
Java HotSpot(TM) 64-Bit Server VM (build 24.45-b08, mixed mode)


-- Real Screen needed


The system running SikuliX scripts or any apps using SikuliX features must have a real screen connected. So called headless systems are not supported (Java restriction). While using SikuliX features, the screen should not be in sleep mode nor show a screen saver. It must be in a state, that a user could work with the system and watch on the screen what is going on.

-- Using Virtual Machines


Running it in VM guest systems as the above mentioned should usually work, but might have quirks.

-- Machine not useable in parallel while SikuliX scripts or programs are running


While running SikuliX scripts or any apps using SikuliX features on a system, usually one cannot work on this system in parallel, not even on another monitor, since normally SikuliX will "use" mouse and/or keyboard and watches the screen according to the running SikuliX workflow. User actions on this system will normally corrupt the SikuliX workflow, except this is intended and supported by the workflow.

— back to top —


2.How do I download SikuliX

(valid for version 1.1.x)

Go to the download page and follow the instructions you find there.
After having completed the downloads come back here and continue with step 3.

BE AWARE:
What you download is a sikulixsetup....jar, which is only intended to support setting up useable artifacts of SikuliX and keeping them up-to-date, configured to run on your current system according to the selected setup options (see next section: How do I set up SikuliX).

The head of development might be available as a nightly build with bug fixes and enhancements.

— back to top —


3.How do I set up SikuliX

(valid for version 1.1.x)

After having downloaded sikulixsetup….jar you should consider the following recommendations, before doing anything:
  • select a prominent folder that is intended, to permanently contain all artifacts making up SikuliX
  • the path to this folder and its name should not contain any blanks or special characters (example: C:\SikuliX)
  • the folder should not be a program or application folder with special system access restrictions (must be freely user writeable)
  • into this folder copy/move sikulixsetup....jar
  • if this folder contains any content belonging to an earlier version of Sikuli(X), do some backup to be prepared to revert
  • to avoid odd situations you should always start with an empty folder (except sikulixsetup....jar and maybe a Downloads folder)
Again: take care, that you have a valid Java installation.

Double clicking sikulixsetup....jar should start the setup.

On Linux systems it might be necessary to switch on the executable bit in the file properties and you should have read this information.

If double-clicking does not work, you can try on a command line:
java -jar sikulixsetup....jar or
java -cp sikulixsetup....jar org.sikuli.setup.RunSetup

setup_dialog

You have to at least select option 1 or 2 (the [ H ] buttons provide some more information) and you might select both.

— Option 1
will setup sikulix.jar, which contains the SikuliX IDE and can be used to run scripts from command line (see next section 4). As a sub-option you have to select the scripting languages you want to use
  • Python (Jython) (preselected) allows scripting using Python language level 2.7 (internally used interpreter Jython 2.7 )
  • Ruby: scripting using Ruby language level 1.9 (internally used interpreter JRuby 1.7.x )

You might select both, since in the IDE you can select the scripting language per script.

On Mac you get a real Mac application SikuliX.app, that should be moved to the /Applications folder.

Additionally you get a command file runSikulix(.cmd) to run scripts from command line (see the docs).

— Option 2
will setup sikulixapi.jar, which is intended to be used with Java programming or programming with any Java aware language. It is much smaller, since it does not contain the IDE stuff nor the big packages for the scripting support (see section 8 below).

— Option 3
should be selected, if you plan to use the OCR features based on Tesseract later (not recommended for beginners). If needed later, then you might get it then. If selected, the feature must still be switched on at runtime of the IDE and when using sikulixapi.jar.

A Proxy might be specified for the internet access for the inline downloads during setup.

After having made your selections, click the button [Setup Now].

If everything works well, after successful internal download of the needed packages, you will get some intermediate yellow badges, hopefully positive popups from the tests and a final success message.

You might find the following files in your SikuliX setup folder:
  • SikuliX-1.1.0-SetupLog.txt --- contains debug information of setup workflow
  • sikulixsetup-1.1.0.jar (might have a lengthy version suffix)
  • runsikulix(.cmd) --- command script for commandline usages of SikuliX
  • sikulix.jar --- (non-Mac systems only) SikuliX IDE and scripting support (option 1)
  • SikuliX.app --- (Mac systems) Mac application, should be moved to /Applications (option 1)
  • sikulixapi.jar --- Java programming support (option2)

additionally you might have the optional folder
Downloads --- folder containing the manually downloaded artefacts

If you get any problems during setup, you should first have a look at the setup log file for any error messages or any information that helps to identify the cause of the problems.

If internal downloads are blocked on your system, you might try an Offline Setup.

If you want to repeat the setup for some reason
  • you should do some backup to be prepared to revert (existing files with the same name will be overwritten without notice)
  • setup will ask you to reuse already downloaded artefacts (say no if you want to download fresh copies)
  • Read carefully, what setup is asking you, before clicking anything!

Here you can read more about how SikuliX is setup on your system.

— back to top —


4.Getting started with SikuliX IDE


To start the SikuliX IDE, you have the following options:
  • start the respective application (on Mac: Sikulix.app, on Windows (if available): Sikulix.exe)
  • double click sikulix.jar (on Linux you might need to switch on the executable bit)
  • use runsikulix(.cmd) optionally with parameters on a command line
  • special on Mac commandline: open /Applications/SikuliX.app
  • use java -jar path-to-sikulix.jar optionally with parameters on a command line

— back to top —


5.How to run my scripts


Look here for more information.

— back to top —


6.How to deal with problems


Try to get help (see 7. Getting Help) or Switch on debugging

With an adequate debug level set, SikuliX might reveal more information on what is happening.

When running SikuliX IDE from command line (or a script) use as command line parameters
-d 3 sets the debug level to the recommended value.
-c will redirect the IDE output (normally shown in the IDE's message area) to the command line.

There is another special hack:
if you use the SikuliX apps or otherwise have no chance to set parameters:
before starting add an empty file named SikulixDebug.txt in your home folder.

This is detected and will internally switch to running with -d 3 -c and redirect all debug output to this file.
This is the only way to get debug output from the very beginning, when running SikuliX as .app on Mac or .exe on Windows.
Simply delete it, if it is not needed anymore, to get back to normal operation.

The debug level can also be set inline in scripts and code
... and will be used from this point on until switched off or reset to another value
  • Debug.on(3) — switch debugging on with level 3
  • Debug.off() — switch debugging off
Look here for more information about debugging and logging.

Post a bug
If you think, your problems are created by SikuliX malfunction in any way, you may post a bug on the SikuliX site on Launchpad.

For users of the SikuliX IDE:
Use the menu entry "Report a bug" in the Help menu, since it has special information, puts the version/system/java info to the clipboard, so it can be pasted and opens the Launchpad Bug site in your browser.

— back to top —


7.Getting help


You may ask questions and get answers from the SikuliX community and look at the FAQs on the SikuliX site on Launchpad.

For users of the SikuliX IDE:
Use the menu entry "Ask questions ..." in the Help menu, since it has special information, puts the version/system/java info to the clipboard, so it can be pasted and opens the Launchpad Question site in your browser.

The official SikuliX feature and API documentation is here.

JavaDocs can be found here (concentrating on the major public Java classes).

For special topics have a look at the Specials page and for stories on the SikuliX blog.

There are SikuliX groups on Facebook, Twitter, LinkedIn and Gitter, that might give a chance for information and questions.

Still not found a suitable answers on your question: Many people ask on StackOverflow and get answers.

... and you might contact RaiMan directly.

— back to top —


8.Using Java and other IDE's


SikuliX Java API (sikulixapi.jar) is available for Maven(-aware) projects on MavenCentral

  <dependencies>
<dependency>
<groupId>com.sikulix</groupId>
<artifactId>sikulixapi</artifactId>
<version>1.1.0</version>
</dependency>
</dependencies>

... more information: Usage in Java Programming

— back to top —