This is valid for version 1.1.0+
In the following we use sikulix…...jar though the concrete artifact might have a version suffix like 1.1.0-some-more-suffix
In the following we use sikulix…...jar though the concrete artifact might have a version suffix like 1.1.0-some-more-suffix
1. Check the prerequisitesSupported systems
SikuliX can be used on systems with Windows XP and later including Windows 8 and 10 (32-Bit or 64-Bit) NO mobile OS
(like Android, iOS, ...) is supported. Real Screen needed The system running Sikuli 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. |
8. Special UsagesJava, Jython, other IDEs, ... |
Machine not useable in parallel while Sikuli is active
While running running Sikuli 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.
While running running Sikuli 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.
Valid Java installation
In any case you must have a valid Java installation (JRE (runtime only) or JDK (runtime + development kit) or both).
Supported are the version 6, 7 or 8 (preferably 7, version 6 is deprecated).
It is highly recommended, to have the latest version available.
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.
In any case you must have a valid Java installation (JRE (runtime only) or JDK (runtime + development kit) or both).
Supported are the version 6, 7 or 8 (preferably 7, version 6 is deprecated).
It is highly recommended, to have the latest version available.
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.
CHECK
On a command line entering
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)
GET IT
It is recommended, to use the Oracle/Sun Java (download from here).
though OpenJRE/JDK should work as well ...
... but it is not used for development nor testing of SikuliX
... you have to find out on your own, how to get and install it
... on Ubuntu or other Debian-type Linux systems use apt-get (e.g. Ubuntu 14.04: sudo apt-get default-jre)
... on Linux flavours using yum as package manager: google is your friend ;-)
It is recommended, to use the Oracle/Sun Java (download from here).
though OpenJRE/JDK should work as well ...
... but it is not used for development nor testing of SikuliX
... you have to find out on your own, how to get and install it
... on Ubuntu or other Debian-type Linux systems use apt-get (e.g. Ubuntu 14.04: sudo apt-get default-jre)
... on Linux flavours using yum as package manager: google is your friend ;-)
Special setup information for Linux systems
SikuliX internally uses OpenCV to support the image related features and Tesseract for the text features.
On Linux/Unix systems one has to provide OpenCV (recommended version 2.4+) and Tesseract (needed version 3.0.2+).
Additionally the package wmctrl is needed, which is used to implement the app related features.
On Linux systems based on the Debian package system (Debian, Ubuntu, ...) using the apt tools (apt-get to install a package) should do the job. On other Linux Systems (Fedora, RedHat, ...) you have to use the appropriate package manager, which in many cases should be yum.
To prepare for the now possible inline build of libVisionProxy.so you have to take care, that at least the following libraries are available:
libopencv_core.so.2.4
libopencv_imgproc.so.2.4
libopencv_highgui.so.2.4
libtesseract.so.3
... and they must be listed in the loader cache (check with ldconfig -p)
... and they must not have any unresolved items (check with ldd -r libsomething.so)
... it is not needed to install any dev/develop packages, just the libs is sufficient.
For more information consult the docs for the respective system and/or package.
During setup the availability and usability of these libraries is checked
together with the usability of the bundled or provided native library libVisionProxy.so.
So it is ok, to just run setup and look at the results you get: It either works or you have to correct something.
Case 1:
The bundled libraries are checked positive (should work): be happy.
These libraries are built on the latest LTS versions of Ubuntu (currently 14.04).
Case 2:
If you know, what you are doing, you might provide the ready built llibraries before starting setup.
Setup will detect and use artefacts found in the libs folder in the setup folder, but they might be checked negative (see case 3).
Case 3:
Neither the bundled nor the provided libraries are checked positive (not useable on this system): Setup will offer the possibility to build on the fly. Setup will tell you about the missing prerequisites.
The inline build
... will create a folder Build in the setup folder, that contains the sources, include files not present on your system, the created build script and the resulting libVisionProxy.so, that was already incorporated into the resulting jars.
In case of errors and other oddities, you might inspect the Build folder, to find out how to fix.
Suggestions for improvements are welcome.
SikuliX internally uses OpenCV to support the image related features and Tesseract for the text features.
On Linux/Unix systems one has to provide OpenCV (recommended version 2.4+) and Tesseract (needed version 3.0.2+).
Additionally the package wmctrl is needed, which is used to implement the app related features.
On Linux systems based on the Debian package system (Debian, Ubuntu, ...) using the apt tools (apt-get to install a package) should do the job. On other Linux Systems (Fedora, RedHat, ...) you have to use the appropriate package manager, which in many cases should be yum.
To prepare for the now possible inline build of libVisionProxy.so you have to take care, that at least the following libraries are available:
libopencv_core.so.2.4
libopencv_imgproc.so.2.4
libopencv_highgui.so.2.4
libtesseract.so.3
... and they must be listed in the loader cache (check with ldconfig -p)
... and they must not have any unresolved items (check with ldd -r libsomething.so)
... it is not needed to install any dev/develop packages, just the libs is sufficient.
For more information consult the docs for the respective system and/or package.
During setup the availability and usability of these libraries is checked
together with the usability of the bundled or provided native library libVisionProxy.so.
So it is ok, to just run setup and look at the results you get: It either works or you have to correct something.
Case 1:
The bundled libraries are checked positive (should work): be happy.
These libraries are built on the latest LTS versions of Ubuntu (currently 14.04).
Case 2:
If you know, what you are doing, you might provide the ready built llibraries before starting setup.
Setup will detect and use artefacts found in the libs folder in the setup folder, but they might be checked negative (see case 3).
Case 3:
Neither the bundled nor the provided libraries are checked positive (not useable on this system): Setup will offer the possibility to build on the fly. Setup will tell you about the missing prerequisites.
The inline build
... will create a folder Build in the setup folder, that contains the sources, include files not present on your system, the created build script and the resulting libVisionProxy.so, that was already incorporated into the resulting jars.
In case of errors and other oddities, you might inspect the Build folder, to find out how to fix.
Suggestions for improvements are welcome.
Special information on libJXGrabKey.so
At least on Ubuntu 14.04 ldd -r reports unresolved symbols pthread… It seems, that this can be ignored, since JXGrabKey works.
If you get problems, that are related to JXGrabkey, you have to build from the sources after having downloaded the package from here or other places and provide the ready built library before setup in the folder libs.
At least on Ubuntu 14.04 ldd -r reports unresolved symbols pthread… It seems, that this can be ignored, since JXGrabKey works.
If you get problems, that are related to JXGrabkey, you have to build from the sources after having downloaded the package from here or other places and provide the ready built library before setup in the folder libs.
2. How do I download SikuliX
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).
If you are interested in nightly builds, then look here
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).
If you are interested in nightly builds, then look here
3. How do I set up SikuliX
After having downloaded sikulixsetup.jar you should consider the following recommendations, before doing anything:
On Linux systems it might be necessary to switch on the executable bit in the file properties.
If double-clicking does not work, you can try on a command line: java -jar sikulixsetup....jar
- select a prominent folder that is intended, to permanently contain all artifacts making up SikuliX
- the path to this folder and it's name should not contain any blanks or special characters (e.g. C:\SikuliX)
- the folder should not be a program or application folder with special system access restrictions (freely user writeable)
- into this folder copy/move sikulixsetup....jar
- if this folder contains any content belonging to an earlier version of SikuliX, 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)
On Linux systems it might be necessary to switch on the executable bit in the file properties.
If double-clicking does not work, you can try on a command line: java -jar sikulixsetup....jar
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
You might select both, since in the IDE you can select the scripting language to use 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 (see docs).
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 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:
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 to use 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 (see docs).
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 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 (see below)
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.
OFFLINE SETUP (if the internal download is blocked on your system)
You might as well store the manually downloaded artefacts in the same folder as the sikulixsetup....jar.
During setup the artefacts will be moved to the SikuliX local application data folder.
Packages to download manually for version 1.1.0 (the link should directly start the download):
If the above links for some reason do not work: these are the pages to visit:
OFFLINE SETUP (if the internal download is blocked on your system)
- make a folder Downloads in the setup folder
- manually download the respective packages (see below)
- put them in the setup Downloads folder
- run setup and select the respective options
- when asked, confirm the usage of the already downloaded packages
You might as well store the manually downloaded artefacts in the same folder as the sikulixsetup....jar.
During setup the artefacts will be moved to the SikuliX local application data folder.
Packages to download manually for version 1.1.0 (the link should directly start the download):
- to get the IDE (option 1) download from Launchpad (sikulixsetupIDE....jar)
- to get the Java API (option 1 and 2) download from Launchpad (sikulixsetupAPI....jar)
- to get the native libraries for your system (always needed)
- for Windows download from Launchpad (sikulixlibswin....jar)
- for Mac download from Launchpad (sikulixlibsmac....jar)
- for Linux/Unix download from Launchpad (sikulixlibslux....jar)
- to get Jython 2.7 (option 1) download from MavenCentral (jython-standalone-2.7.....jar)
- to get Jython 2.5 (option 1 in special cases) download from MavenCentral (jython-standalone-2.5.....jar)
- to get JRuby 1.7 (option 1) download from MavenCentral (jruby-complete-1.7.....jar)
- to get basic Tesseract support (option 3) download from Tesseract home (tesseract-ocr-3.02.eng.tar.gz)
If the above links for some reason do not work: these are the pages to visit:
- Launchpad
- MavenCentral repository (not browsable)
- the tessdata file folder on googlecode (not browsable)
If you want to repeat the setup for some reason
The SikuliX local application data folder
SikuliX stores some information, that is needed during runtime in a system dependent special folder in the user home section:
Currently you might find the following subfolders there:
The stared folders * might be used by you as a user according to the docs.
The others should normally be left untouched, except in special problem or debug situations.
- 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)
The SikuliX local application data folder
SikuliX stores some information, that is needed during runtime in a system dependent special folder in the user home section:
- Windows: in a folder Sikulix in the folder pointed to by the environment variable %APPDATA%
- Mac: in ~/LibraryApplication Support/Sikulix
- Linux: in ~/.Sikulix
Currently you might find the following subfolders there:
- Extensions* - intended to contain extension and plugin artefacts (currently empty)
- Lib* - the stuff needed to support scripting with Jython and JRuby
- SikulixDownloads - non-SikuliX downloads needed for setup (Jython, JRuby, Tesseract-tessdata, ...)
- SikulixDownloads_201510060100 - SikuliX downloads (suffix is the timestamp of the active SikuliX version)
- SikulixLibs_201510060100 - SikuliX native libraries for this system (suffix is the timestamp of the active SikuliX version)
- SikulixStore* - contains other files, that are loaded/produced during runtime (debug, options, last script from net, ...)
- SikulixTesseract* - files to support the usage of Tesseract (currently tessdata)
The stared folders * might be used by you as a user according to the docs.
The others should normally be left untouched, except in special problem or debug situations.
4. How to get started with the 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) optional-parameters on a command line
special on Mac: open /Applications/SikuliX.app - use java -jar path-to-sikulix.jar optional-parameters on a command line
5. How to run my scripts outside the SikuliX IDE
6. How to deal with problems
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 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 to 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
When running SikuliX-IDE from command line 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 to 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
- set: Debug.on(3)
- switch off: Debug.off()
Try to get help
see next chapter 7. Getting Help
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.
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.
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.
A JavaDocs version can be found here (concentrating on the major public Java classes).
For special topics have a look at the Support page and for stories on the SikuliX blog.
... and you might contact RaiMan directly using one of the top right buttons.
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.
A JavaDocs version can be found here (concentrating on the major public Java classes).
For special topics have a look at the Support page and for stories on the SikuliX blog.
... and you might contact RaiMan directly using one of the top right buttons.
8. Special usages: Java, Jython, other IDE's, frameworks, ...
SikuliX Java API (sikulixapi.jar) is available for Maven(-aware) projects as a dependency from MavenCentral
<dependencies>
<dependency>
<groupId>com.sikulix</groupId>
<artifactId>sikulixapi</artifactId>
<version>1.1.0</version>
</dependency>
</dependencies>
... more information: Usage in Java Programming