Note: information on this page refers to Ceylon 1.2, not to the current release.
Dealing with repositories on the command line
Quite a number of the
ceylon sub commands deal with Module Repositories
and all of them support at least a basic set of options to change the default behavior
for dealing with them.
But let's first start by detailing what exactly is the default behavior.
Default repository lookup
Almost all tools that deal with repositories will either have to look up specific modules
or they need to search for modules using certain search criteria.
Ror example you typed
ceylon run my.module/1.2.3 so the system will go look for a
module named "my.module" with version "1.2.3" and see if there's a artifact containing
compiled code for the Java Virtual Machine.
Now by default Ceylon goes looking in a fixed list of repositories in the exact order as shown below, choosing the first module that matches:
SYSTEM - The distribution repository which is located wherever Ceylon
is installed at
$CEYLON_HOME/repo. It contains the modules required by Ceylon itself and all its tools.
CACHE - The cache repository which by default is located in
$HOME/.ceylon/cacheand contains all the modules that were at some point downloaded from remote servers.
LOCAL - The local repository refers to the repository that can be found
in the current directory where the tool is executed. By default this will be in a
USER - The user repository normally located in
$HOME/.ceylon/repoholds the modules that are available to the user anywhere on their system regardless of the current folder they are in when executing a Ceylon tool.
- REMOTE - The Herd, the official remote Ceylon repository that contains all the official Ceylon SDK modules and all other freely available 3rd party modules. By default this is https://herd.ceylon-lang.org.
- MAVEN - The Maven repository where Maven artifacts are looked up.
If the module you need is in any of these repositories you won't have to do a thing to run it, copy it, query it or whatever else you want. All the tools that deal with repositories will be able to find it by default.
But what if your module is stored somewhere else?
To specify that you want to add another repository that isn't in the above list
you use the
--rep command line argument, for example:
Of course you can refer to remote servers as well:
And it's perfectly acceptable to specify as many
--rep arguments as you need.
NB: You have to be aware of the fact that specifying any
--rep argument on the command
line overrides all of the predefined local repositories. In the case of the list above
this means that the
modules repository will be overridden in favor of the one(s) provided
Another important argument for specifying a repository is used by those tools that need to
create or copy modules. These use the argument
--out to specify a destination repository,
And finally there are two other, more specialized, arguments for specifying repositories:
--cacherepcan be used to change the location where downloaded modules will be stored and looked up
--sysrepcan be used to change the location where the system modules needded for Ceylon itself are looked up. You should never need to use this.
But what if you want to specify your repositories to the exclusion of everything else?
What if you don't want to make sure none of the predefined repositories are searched?
For that you can use the argument
--no-default-repositories, meaning that with this:
--no-default-repositories --rep /the/one/and/only
the tools will only look in the path(s) you specified with the
NB: This is not entirely true. The tools will still use the
We can't do anything about
SYSTEM, Ceylon needs it to function correctly, but if you really want
to get rid of even the
CACHE you can specify
--offline along with
In the list above where all the repositories were introduced each of them was given a name.
This name is the repository's "alias" as defined by Ceylon's configuration. We'll get back
to that but it's important to explain what those aliases are for: you can use an alias
everywhere you can use a path or url to a repository by using a plus sign (
by the alias. So an argument like this:
would mean that we want any modules to be written to the "USER" repository (which by default points
$HOME/.ceylon/repo as mentioned earlier).
So far we've only seen and talked about the predefined aliases like
but it's entirely possible to create your own aliases in the Ceylon configuration file. You can
read in detail how to do that here