New in version X1.0-rc2.
Extensions allow to implement new Sikuli features by adding packages to your current Sikuli installation. They are maintained at http://depot.sikuli.org/ by the developers of Sikuli (see Technical Details below). If you want to contribute a new extension or a modified exisiting one, please look at How to contribute an extension below.
The download of an extension is supported by the IDE through the menu Tools -> Extensions. You get a popup, that lists the available and already installed extensions and allows to download new packages or updates for installed ones.
This popup shows a new package not yet installed:
If you need more information about the features of the extension, just click More Info - this will open the related documentation from the web in a browser window.
If you want to install the extension, just click the Install... button. The package will be downloaded and added to your extensions repository.
This popup shows an installed package:
If a new version would be available at that time, the Install... button would be active again, showing the new version number. Now you could click and download the new version.
How to Use an Extension
To use the features of an installed extension in one of your scripts, just say from extension-name import *. For an usage example read Sikuli Guide.
For information about features, usage and API use menu Tools -> Extensions -> More Info in the IDE.
Extensions are Java JAR files containing some Java classes (usually the core functions) and/or Python modules, which define the API to be used in a script.
Sikuli maintains a local extensions directory, where downloaded extensions are stored together with a hidden list of the installed extensions (Windows: %APPDATA%\Sikuli\extensions, Mac: ~/Library/Application Support/Sikuli/extensions, Linux: ~/.sikuli/extensions).
Once an extension is imported using import extension-name, Sikuli automatically searches and loads the JAR file of that extension into the current context with load(path-to-jar-file).
The source structure of an extension named extension-name looks like this:
Java
- org/com
-- your-organization-or-company
--- extension-name
---- yourClass1.java
---- yourClass2.java
---- .... more classes
python
- extension-name
-- __init__.py
-- extension-name.py
The final structure of a JAR (filename extension-name-X.Y where X.Y is the version string) looks like this:
org/com
- your-organization-or-company
-- extension-name
--- yourClass1.class
--- yourClass2.class
--- .... more classes
extension-name
- __init__.py
- extension-name.py
META-INF
- MANIFEST.MF
The file __init__.py contains at least from extension-name import * to avoid one qualification level. So in a script you might either use:
import extension-name
extension-name.functionXYZ()
or:
from extension-name import *
functionXYZ()
The second case requires more investement in a naming convention, that avoids naming conflicts.
The file extension-name.py contains the classes and methods, that represent the API, that one might use in a Sikuli script.
As an example you may take the source of the extension Sikuli Guide.
Sikuli extensions can be Python/Jython modules or Java classes.
For Java classes, following the reverse URL convention of Java is a good idea (for example, org.foo.your-extension). However, DO NOT use Java’s convention for Python/Jython modules. You need to come up with a unique extension name that does not conflict with existing Python modules and other Sikuli extensions.
Please read Naming Python Modules and Packages to learn the details for naming a Python module.
While developing your extensions, you can put the JAR file in Sikuli’s extension directory or in the same .sikuli folder as your test script. The JAR file should not have a version number in its file name, e.g. extension-name.jar. Because Sikuli starts to search extensions in the .sikuli folder of the running script and then in the Sikuli extensions folder, it is usually a good idea to put your developing extensions in the .sikuli folder of your test script.
Another option is to use the load() function with an absolute path to your extension-name.jar. If this fails, Sikuli goes on searching in the current .sikuli folder and then in the Sikuli extensions folder. If load() succeeds, it returns True and puts absolute-path-to-your-extension-name.jar into sys.path, so you can use import extension-name afterwards.
Currently you have to contact the developers of Sikuli and agree on how to proceed.