Ceylon CLI plugin
The ceylon tools use a
git-like plugin scheme for declaring new subcommands.
What is a Ceylon CLI plugin?
If you have any executable in your path (
$PATH on Unices,
%PATH% on Windows) whose
name starts with
ceylon- and is executable, then the
ceylon command will detect it
and make it available as a subcommand.
For example, the
ceylon-format executable will be picked up by the
ceylon CLI tool
format subcommand, which means you can invoke it with
$ ceylon --help format NAME 'ceylon format' - format Ceylon source code SYNOPSIS ceylon format [OPTION]... ( FILE [--and FILE]... [--to FILE] )... ...
Installing new CLI plugins
You can install the CLI plugin scripts packaged for the module
$ ceylon plugin install ceylon.formatter/1.2.1
This will install the
ceylon-format plugin script to
where the ceylon CLI will look for plugins, as well as from your
PATH environment variable.
Naturally, you can also manually install plugins in your
You can list every plugin installed with:
$ ceylon plugin list ceylon-build (ceylon.build.engine) ceylon-format (ceylon.formatter)
And finally, you can uninstall plugins with:
$ ceylon plugin uninstall ceylon.formatter
Writing Ceylon CLI plugins
Suppose we want to write a
compile-doc plugin which runs the JVM and JS compilers, then the
We actually have two options: using a "command scripts" or a "plugin file".
Using command scripts
Command scripts are OS dependent, they use shell scripts on Unix-derived systems like Linux and MacOS and they use batch files on Windows.
We will start with Unices and create a file
ceylon-compile-doc, with the following
#!/bin/sh USAGE='[any option valid for compile, compile-js and doc]' DESCRIPTION='Runs both compilers and the doc tool' LONG_USAGE='This will run the `compile`, `compile-js` and `doc` subcommands. OPTIONS Any option that is accepted by all of the `compile`, `compile-js` and `doc` subcommands.' . $CEYLON_HOME/bin/ceylon-sh-setup $CEYLON compile $@ $CEYLON compile-js $@ $CEYLON doc $@
As you can see, you need to specify a number of shell variables:
USAGEwill be used to document the command-line arguments your plugin accepts,
DESCRIPTIONwill be used to describe your plugin in
ceylon --help, and
LONG_USAGEwill be used to document your plugin in
ceylon compile-doc --help.
These variables will then be used in the
ceylon-sh-setup script which you should invoke,
which will handle exiting from your script when there are
--help parameters on the command-line
to pass them back to the command-line system.
Once you’ve defined those documentation variables and invoked the
ceylon-sh-setup script, you can
what you want in the script.
On Windows, your script will be named
ceylon-format.bat and look like:
@echo off set "USAGE=[any option valid for compile, compile-js and doc]" set "DESCRIPTION=Runs both compilers and the doc tool" set "LONG_USAGE=This will run the `compile`, `compile-js` and `doc` subcommands." set "LONG_USAGE=%LONG_USAGE%" set "LONG_USAGE=%LONG_USAGE%OPTIONS" set "LONG_USAGE=%LONG_USAGE%" set "LONG_USAGE=%LONG_USAGE%Any option that is accepted by all of the `compile`, `compile-js` and `doc`" set "LONG_USAGE=%LONG_USAGE%subcommands." call %CEYLON_HOME%\bin\ceylon-sh-setup.bat %* if "%errorlevel%" == "1" ( exit /b 0 ) %CEYLON% compile %* %CEYLON% compile-js %* %CEYLON% doc %*
Environment variables given to your script
There are a number of predefined environment variables that the
ceylon CLI will pass to your
CEYLON_HOMEwill point to the Ceylon distribution root folder,
JAVA_HOMEwill point to the current JDK/JRE root folder,
CEYLON_VERSION_MAJORcontains the current Ceylon version major part (
CEYLON_VERSION_MINORcontains the current Ceylon version minor part (
CEYLON_VERSION_RELEASEcontains the current Ceylon version release part (
CEYLON_VERSIONcontains the current Ceylon version major part (
CEYLON_VERSION_NAMEcontains the current ceylon version code name,
SCRIPTis the absolute path to your plugin script, and
SCRIPT_DIRis the absolute path to the directory containing your plugin script.
Using plugin files
Plugin files are used when the code you're trying to run is available as a Ceylon module and
contains at least one class that implements the
Right now the best way to learn how to write a command using
Tool is to look at the
included in the distribution.
Writing the plugin file itself is easier luckily: you just need a simple text file, in the case
of our example called
ceylon-compile-doc.plugin with the following contents:
summary=Runs both compilers and the doc tool module=your.module/1.0.0 ;class=your.module.CeylonCompileDocTool # This is the default
The first line contains the summary, a short description of the plugin that will show up in the
list of available commands when you just type
ceylon without any arguments or when you type
The second line is the name and version of the module that contains the code for your plugin.
And the last line is the fully qualified name of the class that is the entry point of your
plugin. This class must implement the above mentioned
interface. You can leave this line out (or comment it out as in this example) if the name
adheres to the correct rules (basically you start with the plugin file name, remove the
.plugin extension, remove all the dashes and capitalize the separate words and add
on the end. So
Packaging scripts to make them available for users
CLI plugin scripts for the module
your.module should be put in the
by convention, although you can override this with the
You can generate a script package for the module
$ ceylon plugin pack your.module
Naturally, you can publish your plugins as part of your module to Herd, so that they are available to users.