Ceylon toolset configuration
ceylon tools use a
git-like configuration file format for configuring
Example configuration file
# Put the cache on the huge disk [repository "CACHE"] url=/huge-disk/tom/ceylon/repocache # Define the company repo [repository "CompanyRepo"] url=http://repo.example.com password-alias=company-repo-password # Append the company repo to the "remote" [repositories] global=/usr/local/ceylon/repo remote=+CompanyRepo # define a keystore to put my passwords in [keystore] file=/home/tom/toms-keys # define a proxy for accessing the network [proxy] host=webproxy port=8000 user=tom password-alias=proxy-password
Configuration file location
There are several configuration files that can affect the configuration of the Ceylon tool chain. They go from least specific at the level of the system itself which affect all projects and all users to most specific at the level of a single project affecting only that project.
The first configuration file that gets read is the one at the system level which:
- on Linux and Mac OS is
- on (modern) Windows something like
After that comes the user's own configuration file which holds those values which only apply to that specific user:
- on Linux it is
- on Mac OS it is
- on (modern) Windows it is something like
Finally comes the most specific configuration file which is located in a subfolder
of the current working directory:
.ceylon/config. This means it depends on the
working directory where you are executing the
ceylon command! (When using an IDE
the current working directory is the project folder itself.)
Now in reality it's a bit more complex than this, because before reading that local
file Ceylon will first see if a configuration file exists in the
.ceylon folder of
the parent folder of the current working directory. And before reading that one
it will see if one exists in its parent folder, etc, etc, all the way up to the
root of the file system (it will ignore the user's and system configuration files
if it happens to encounter them while traversing the file system). This provides us
with the possibility to set configuration options for a group of projects.
Configuration file structure
A configuration file consists of sections with key/value pairs and comments. A section consists of a name surrounded by square brackets:
These names must start with a letter and for the rest can only contain letters and digits (and periods as we'll see later, but they are not part of the name).
We can also add comments, either on their own line or at the end of an existing line:
# A comment on its own line [examplesection] # Another comment
Within sections we can define key/value pairs, each on their own line:
More about keys
Key names can only contain letters, digits and dashes. To unambiguously refer to
a certain key in a certain section you can use the "complete name" which for the
above setting is
example-section.some-setting. Its value is
300. In this form all
leading and trailing spaces and tabs are ignored (as are comments), so the
following is exactly the same as the above:
[ example-section ] some-setting = 300 # Some comment
Key names and main section names can never contain spaces or tabs, but values can. In those cases that you need to specify leading or trailing spaces and tabs as part of the value you need to quote the value like this:
[example-section] text=" An example text "
Spaces and tabs within the quotes are part of the value, any spaces and tabs outside them are ignored.
Sometimes it is necessary to specify values that span multiple lines, the easiest way to do that is like this:
[lines] long-text-unquoted=A very\ very\ long line. long-text-quoted= "Another very\ very\ long line."
And the final item on the topic of values are escapes, sometimes it's necessary to be able to specify special character that cannot (easily) be entered in another way:
[escapes] escape1=\t # A single TAB character escape2=\n # A single NEWLINE character escape3="\"" # A double-quote character, so you can use them in quoted values escape4=\\ # A single backslash, so you can use backslashes in values
NB: using escapes the above
[lines] example could be rewritten like:
[lines] long-text-unquoted=A very\nvery\nlong line. long-text-quoted= "Another very\nvery\nlong line."
And that would be exactly the same. It's up to you to decide what you prefer.
More about sections
Now back to sections. For complex configurations it is possible to divide sections into sub-sections (and sub-sub-sections or sub-sub-sub-etc if necessary). This can be done in two different ways, either quoted or unquoted:
[examplesection "Sub section 1"] some-setting=300
[examplesection "Sub section 2"] some-setting=400
In the quoted version the name sub-section can contain almost any characters you want and is meant to give more human-friendly names, in the unquoted version the name of the sub-section must adhere to the same rules as for the main section name (starts with a letter and only letters and digits after that) and names are separated by a period.
Configuration file contents
[defaults] section is used to change the default behaviour of the ceylon
tool chain. Recognized settings include:
encoding— The character set (e.g.
UTF-8) to use when reading source files. If not specified, the default file encoding for the platform is assumed.
offline— Prevents the tool chains from trying to download modules from remote repositories. Accepts
no). Defaults to
timeout— The number of seconds to wait while connecting to a remote host before giving up. Platform specific default.
overrides— A file specifying module overrides.
[compiler] section is mainly used to change the default behaviour of the
compile tool. The possible settings include:
source— Equivalent to supplying
--sourceon the command line. It takes a path to a folder containing sources. May be specified multiple times.
resource— Equivalent to supplying
--resourceon the command line. It takes a path to a folder containing resources. May be specified multiple times.
Note: although it appears in the
[compiler] section these settings actually
affect any tools that take
--resource options. If a tool normally
takes only a single of these options the first in the list will be used.
module— Equivalent to supplying a
modulename on the command line. May be specified multiple times.
These are a special sections for the compile tool that are specific to each
backend. So there is a
compiler.jvm section for the Java backend and a
option for these sections is:
module and it has the same meaning as above.
arg— Equivalent to supplying arguments to the Ceylon application being run using
ceylon run-js. Can be specified multiple times. Only taken into account when the
moduleoption is also specified, otherwise ignored.
These are a special sections for the run tool that are specific to each backend.
So there is a
runtool.jvm section for the Java backend and a
arg and they have the same meaning as above.
Ceylon uses a set of local and remote repositories for its modules. The order and significance of the lookup (which is fixed) is:
system— Essential system modules
cache— A cache of modules that were previously downloaded from remote repositories
output— Where the compiler stores newly created modules
lookup— Other local repositories
global— Predefined user and system global repositories
remote— User defined remote repositories
other— Predefined remote repositories
[repositories] section can be used to override the default values for those
entries thereby changing or extending the lookup order. Take a look at the
[repositories] output=./output # Store new modules in the local `output` folder cache=/huge-disk/tom/ceylon/repocache # Store the cached modules on a bigger disk lookup=./modules lookup=./extra-modules lookup=/usr/local/ceylon/even-more-modules remote=http://ceylon.example.com # An external site with Ceylon modules
First of all, the values for
cache (as well as
system, but you should
normally never try overriding it) can only be specified once, while the others
remote) can be specified multiple times, Ceylon will try them
one by one in the order you specify in this list.
NB: When we say "in the order you specify" we refer to the ones with the same key
name, so if you add several
remote repositories they will be tried in the order
you specify, but you cannot change the main ordering:
lookup repositories will
always be tried before
global, which will always be tried before
Now looking at
lookup we see that it's specified 3 times, but one of those lines
contains a path to the local
modules folder, which (as we will see later) is
actually already part of the default
lookup list. So why is it specified here again?
Well, it is important to realize that in the configuration file we can only override
existing values, we cannot change them or append to them, so when overriding a value
lookup without changing the default behavior we must take care to include
remote entry doesn't have any default value, so it can be easily used without
having to worry about pre-existing values. It's specifically meant to add extra
(normally remote) repositories that will be tried after all other options have been
other entry isn't mentioned in the above example because in general it is
advisable to leave it alone, it contains a list of predefined repositories, among
which is the main Ceylon repository itself that contains most of the interesting
3rd party modules. You should only need to override it if for some reason you do
not want the default behaviour.
So far when specifying respositories we have been using simple files system paths and HTTP URLs, but this might not be enough in certain cases. You might want to refer to a complex URL from the command line for example without having to type it each time. Or, in the case of a remote output repository, it might be necessary to authenticate before you will be allowed to push anything to that server.
For that porpose we can create a
[repository] definition. Because all respository
definitions are actually sub-sections of
[repository] they require a name. An example
[repository "CompanyRepo"] url=http://ceylon.example.com user=fubar password=secret!
Supported properties include:
url— the URL of the repository. May be:
- a remote URL like
- a reference to a folder on the local file system, either absolute like
/huge-disk/tom/ceylon/repocache, or relative to the project folder like
This property is required.
- a remote URL like
user— the user name if the repository requires authentication
password— the plain text password if the repository allows plain text authentication
password-alias— the name of an alias in a
[keystore]which holds the password, an alternative to using the
password-keystore— the name of the
[keystore]which holds the
password-alias, or, if not, the default
[repository] definitions like the above you can now refer to it from within the
[repositories] section like this (pay attention to the
+ sign which is required):
You can now also refer to this repository from the command line, for example when pushing a compiled module to the secure company repository:
$ ceylon compile --out +CompanyRepo com.example.mymodule
There are a few built-in repository names, as follows:
The system repository holds the modules necessary to use the ceylon tools, for example,
the compiler and language module. By default it is located in the
repo directory of
the ceylon installation.
[repository "SYSTEM"] url=CEYLON_HOME/repo
The cache repository contains all modules fetched from remote repositories, so they
don't have to be downloaded each time they're needed. By default it is located in the
.ceylon/cache folder located in the user's home directory.
[repository "CACHE"] url=~/.ceylon/cache
The local repository is where modules are stored that are created by compiling local
projects. By default it is specified as the folder
modules relative to the current
[repository "LOCAL"] url=./modules
The user repository is where a user can store modules that will be available to them
for execution regardless of the current folder the user runs the program. By default
it is located in the
.ceylon/repo folder located in the user's home directory.
This can be overridden by setting the
ceylon.config system property to point to
the file that should be used.
[repository "USER"] url=~/.ceylon/repo
The remote repository points to the official Ceylon module repository ("The Herd")
that contains all the official Ceylon SDK modules and all other freely available
3rd party modules. By default this is
[repository "REMOTE"] url=https://herd.ceylon-lang.org
The remote repository points to the official Maven module repository that contains
so much of the Java ecosystem's finest contributions. By default this is
[repository "MAVEN"] url=maven:
[repositories] section revisited
This paragraph doesn't really contain any information necessary to be able to work with the Ceylon tool chain, but it might be interesting for completeness sake.
Looking at the above list we now have sufficient information to be able to know
what the default
[repositories] section would look like:
[repositories] system=+SYSTEM cache=+CACHE output=+LOCAL lookup=+LOCAL global=+USER other=+REMOTE other=+MAVEN
This also means that if you define your own
[repository] section with one of the
above predefined names you will override the default location for that
repository. (So in fact there are two ways to override predefined repositories.)
Although the config file supports specifying passwords in plain text, it also
supports them being stored in external keystores. The default keystore is defined
[keystore] section. Additional named
[keystore]s can also be defined. Each
keystore corresponds to a
Supported properties include:
file— the name of a keystore file, for those keystores which are file based.
[proxy] section defines a HTTP proxy to use when accessing the network.
Supported properties include:
host— the hostname of the proxy server
port— the TCP port number of the proxy server. Default:
user— the proxy user name, if authenticating to the proxy is required
password— the proxy password, in plain text, or
password-alias— the alias of a
[keystore]entry which holds the password, an alternative to using the
non-proxy-hosts— a host name which can be accessed directly, without going via the proxy.
Tools should use the OS's default proxy settings automatically. If you want the
tools to not use any proxy, you can do us using an empty