ceylon/ceylon-1.3.3/README.md

# Ceylon

This is the 1.3.3 _"Contents May Differ"_ release of the Ceylon
command line tools. This is a production version of the platform.

Ceylon is a modern, modular, statically typed programming language
for the Java and JavaScript virtual machines. The language features
a flexible and very readable syntax, a unique and uncommonly elegant
static type system, a powerful module architecture, and excellent
tooling, including an awesome Eclipse-based IDE.

Ceylon enables the development of cross-platform modules which execute
portably in both virtual machine environments. Alternatively, a Ceylon
module may target one or the other platform, in which case it may
interoperate with native code written for that platform.

Read more about Ceylon at <http://ceylon-lang.org>.

## First steps

If you installed Ceylon using your system's or a third-party's package
manager like apt-get, dnf, sdkman or brew there's nothing more for you
to do, everything should just work fine.

If on the other hand you downloaded and extracted the ZIP file you
will see the following files and folders:

- `bin`            - Unix/Windows commands
- `contrib`        - Sample Ceylon command-line plugins
- `doc`            - Documentation about Ceylon including the spec in HTML and PDF format
- `lib`            - Required libraries for the Ceylon commands
- `repo`           - Required bootstrap Ceylon modules (language, tools)
- `samples`        - Sample Ceylon modules
- `templates`      - Templates for new Ceylon projects
- `BUILDID`        - The Git commit id used to build this distribution
- `LICENSE-ASL`    - The Ceylon ASL license
- `LICENSE-GPL-CP` - The Ceylon GPL/CP license
- `LICENSE-LGPL`   - The Ceylon LGPL license
- `NOTICE`         - 3rd party licenses
- `README.md`      - This file

The all-important `ceylon` command that is used for everything from
compiling and running code to creating projects and copying modules
can be found in the `bin` folder.

For ease of use you might want to consider adding the `ceylon` command
to your `PATH`.

- On Linux and Mac you can do this either by adding the `bin` folder
to your `PATH` environment variable or by creating a symbolic link to
`bin/ceylon` in an appropriate place like `~/bin`.

- On Windows you can search for "advanced system settings", click the
"Environment Variables" button and add the path to the `bin` folder to
the `PATH` variable.

NB: If you don't add Ceylon to your path you will have to always type
the path to the `bin/ceylon` command. So in every example that follows
you'll need to change `ceylon` to `/path/to/ceylon-1.3.3/bin/ceylon`.

## Trying it out

To see if Ceylon was installed correctly type (the `$` is an indication
of your command line prompt and should *not* be typed when trying these
examples):

    $ ceylon --version

You should see something like:

    ceylon version 1.3.3 1cac978 (Contents May Differ)

## Tool usage

To see the list of subcommand that `ceylon` supports just type:

    $ ceylon

You should see a short synopsis and then a list of subcommands like this
(you might see more options):

    * `bootstrap`  - Generates a Ceylon bootstrap script in the current directory
    * `browse`     - Open module documentation in the browser
    * `classpath`  - Print a classpath suitable for passing to Java tools to run a given Ceylon module
    * `compile`    - Compile a Ceylon program for the Java backend
    * `compile-js` - Compile a Ceylon program for the JavaScript backend
    * `config`     - Manage Ceylon configuration files
    * `copy`       - Copy modules from one module repository to another
    * `doc`        - Document a Ceylon program
    * `fat-jar`    - Generate a Ceylon executable jar for a given module
    * `help`       - Display help about another tool
    * `info`       - Print information about modules in repositories
    * `jigsaw`     - Tools to interop with Java 9 (Jigsaw) modules
    * `import-jar` - Import a Java `.jar` file into a Ceylon module repository
    * `new`        - Generate a new Ceylon project
    * `plugin`     - Package or install command-line plugins
    * `run`        - Run a Ceylon program on the Java VM
    * `run-js`     - Run a Ceylon program on node.js (JavaScript)
    * `src`        - Fetch source archives from a repository and extract them
    * `test`       - Test a Ceylon program on the Java VM
    * `test-js`    - Test a Ceylon program on node.js (JavaScript)
    * `version`    - Show and update version numbers in module descriptors
    * `war`        - Generate a WAR file from a compiled `.car` file

Then to see a more detailed explanation of a particular subcommand,
use the `help` subcommand. For example, to get help on the `compile`
subcommand type:

    $ ceylon help compile

## Running the sample programs

The `samples` folder contains several small sample programs. To compile
and run them, refer to the file `README.md` contained in the `samples`
folder for further instructions.

## Write some code

A very easy we to quickly set up a module to compile is to use the
`ceylon new` command which creates the basic folder structure with the
necessary files. Create an empty folder, change into it and type:

    $ ceylon new hello-world

It will then ask you a series of questions:

    Enter project folder name [helloworld]: .
    Enter module name [com.example.helloworld]: my.first.module
    Enter module version [1.0.0]:
    Would you like to generate Eclipse project files? (y/n) [y]:
    Enter Eclipse project name [my.first.module]:
    Would you like to generate an ant build.xml? (y/n) [y]:

In the above example we've accepted almost all the defaults except for
the project folder name which we've changed to the current folder `.`
and the name of the module where we've chosen "my.first.module". After
it has finished the command will have created some source files, an Ant
build file and will have prepared the project to be opened in Eclipse
if you want.

You can now type:

    $ ceylon compile my.first.module
    Note: Created module my.first.module/1.0.0
    $ ceylon run my.first.module/1.0.0
    Hello, World!

to compile and run the newly created module. (You can also type `ant`
if you let the tool create Ant build files).

We'll be making a small change to the code so you can see what files
are involved. For this run you favorite editor, here we'll just use
`vi`:

    $ vi source/my/first/module/run.ceylon

Now change the second line to read:

    shared void hello(String name = "Ceylon") {

and save and exit. When you now repeat the compile and run commands
the output should read:

    Hello, Ceylon

This is the very simplistic start of an interesting journey in learning
to program in Ceylon. For much more information continue to the next
section.

## Learn more

If you want to learn more about Ceylon you can go to the
[documentation][] section of the Ceylon web site, where you'll
find a [tour][], a [walkthrough][], and much more.

[documentation]: http://www.ceylon-lang.org/documentation/current/
[tour]: http://www.ceylon-lang.org/documentation/current/tour/
[walkthrough]: http://www.ceylon-lang.org/documentation/current/walkthrough/

## Source code

The source code for Ceylon is completely Open Source and freely
available from <http://github.com/ceylon>.

## Issues

If you find a bug or have a suggestion or request, you may report
it in the GitHub [issue tracker][].

[issue tracker]: http://github.com/ceylon/ceylon/issues

## Contributing

We're always looking for help, so if you would like to contribute
in any way look [here](http://www.ceylon-lang.org/code/contribute/)
for more information.

## The Community

If you have any questions or want to join the developers in their
discussions about current and future developments of the Ceylon
language or just chat with other users you can find a full list
of [possible channels][community] at the Ceylon web site. Good
options include:

- the [user mailing list][], and
- the [user Gitter channel][].

You can follow @ceylonlang on twitter.

[community]: http://www.ceylon-lang.org/community/
[user mailing list]: http://groups.google.com/group/ceylon-users
[user Gitter channel]: https://gitter.im/ceylon/user

## License

The Ceylon distribution is and contains work released

- partly under the ASL v2.0 as provided in the `LICENSE-ASL` file
  that accompanied this code, and
- partly under the GPL v2 + Classpath Exception as provided in the
  `LICENSE-GPL-CP` file that accompanied this code.

### License terms for 3rd Party Works

This software uses a number of other works, the license terms of
which are documented in the `NOTICE` file that accompanied this code.

## Acknowledgement

We're deeply indebted to the community volunteers who contributed a
substantial part of the current Ceylon code base, working often in
their own spare time.