diff --git a/README.md b/README.md new file mode 100644 index 0000000..18ca83c --- /dev/null +++ b/README.md @@ -0,0 +1,126 @@ +# Visual Studo Code Language Support for Ceylon + +Provides support for editing and compiling Ceylon projects in Visual Studio +Code. Initially, the Dart backend is supported. + +## Features + +- Zero-configuration: open any Ceylon project folder and start editing (`.ceylon/config` +will be used for configuration if present) +- Multithreaded compiles: the module you are editing is immediately recompiled after each +edit while dependent modules are compiled in the background +- Syntax highlighting +- As you type warning and error reporting +![errors](images/screeshot-errors.png) +- Auto completion +![errors](images/screeshot-autocomplete.png) +- Documentation on hover +![hover](images/screeshot-hover.png) + +## Requirements + +- [Ceylon 1.3.0](https://ceylon-lang.org) ([download](https://ceylon-lang.org/download/)) +- [Dart backend for Ceylon DP3](https://github.com/jvasileff/ceylon-dart). + Simple two step commandline installation: + `ceylon plugin install --force com.vasileff.ceylon.dart.cli/1.3.0-DP3` + then `ceylon install-dart --out +USER` +- [Visual Studio Code](https://code.visualstudio.com/Download) + +To run programs on the Dart VM (optional), either +[download](https://www.dartlang.org/downloads/) Dart or install it using +Homebrew as described in the Dart backend for Ceylon +[readme](https://github.com/jvasileff/ceylon-dart). + +## Installation + +After satisfying the requirements, simply download the preview version of the +extension +([vscode-ceylon-0.0.0.vsix](https://jvasileff.github.io/vscode-ceylon/vscode-ceylon-0.0.0.vsix)) +and open it in Visual Studio Code. + +The extension must be able to find the `ceylon` 1.3.0 executable using one of +the following methods: + +- Using `ceylon.home` configured within the Visual Studio Code settings (`⌘,` + on macOS) +- Using the `CEYLON_HOME` environment variable +- Using the system `PATH` + +## Extension Settings + +This extension contributes the following settings: + +* `ceylon.home`: The directory of the Ceylon installation to use. +* `ceylon.generateOutput`: Write compiled binaries to the output repository. + Note that output is produced regardless of whether or not the source files + have been saved. +* `ceylon.serverLogPriority`: The logging level for the language server. +* `ceylon.config.compiler.suppresswarning`: Override the suppresswarning + setting. +* `ceylon.config.compiler.dartsuppresswarning`: Override the + dartsuppresswarning setting. +* `ceylon.config.compiler.source`: Override the source repositories. Note that + this will not take effect without restart. +* `ceylon.config.compiler.resource`: Override the resource repositories. Note + that this will not take effect without restart. +* `ceylon.config.repositories.output`: Override the output repository +* `ceylon.config.repositories.lookup`: Override the lookup repositories + +Note that the `ceylon.generateOutput` and `ceylon.config.*` settings are +intended to be used as workspace settings, but are entirely optional. + +## Running and Testing Your Ceylon Program + +In order to quickly run and test a module, it's recommended to enabled +`ceylon.generateOutput`, which is disabled by default. New binaries will be +created after every change, even for unsaved source files. + +"Tasks" can easily be configured with Visual Studio Code to support calling +`ceylon compile-dart` (useful if `ceylon.generateOutput` is disabled) and +`ceylon run-dart`. It's of course possible to use tasks to call commands for other +backends too, for example, `compile-js`, `run-js`, and `test-js`. + +A sample `tasks.json` to get you started: + +```json +{ + // See https://go.microsoft.com/fwlink/?LinkId=733558 + // for the documentation about the tasks.json format + "version": "0.1.0", + "command": "ceylon", + "isShellCommand": true, + "suppressTaskName": true, + "showOutput": "always", + "tasks": [ + { + "taskName": "compile", + "args": ["compile-dart"], + "isBuildCommand": true + }, + { + "taskName": "run", + "args": ["run-dart", "com.example.mymodule"] + } + ] +} +``` + +## Known Issues + +This is pre-release software. Please report problems with steps to reproduce +using the [Github issue tracker](https://github.com/jvasileff/vscode-ceylon/issues). + +Known issues and limitations include: + +- Source directory configuration changes made in `.ceylon/config` and Visual + Studio Code settings will not take effect until restart +- Completion and hover are not synchronized with builds, so stale incorrect + information may be provided +- When `ceylon.generateOutput` is enabled, binaries are continuously produced, + even for unsaved edits. + +## Release Notes + +### 0.0.0 + +The initial preview release. diff --git a/client/README.md b/client/README.md index 0f84cd9..18ca83c 100644 --- a/client/README.md +++ b/client/README.md @@ -1,65 +1,126 @@ -# vscode-ceylon README +# Visual Studo Code Language Support for Ceylon -This is the README for your extension "vscode-ceylon". After writing up a brief description, we recommend including the following sections. +Provides support for editing and compiling Ceylon projects in Visual Studio +Code. Initially, the Dart backend is supported. ## Features -Describe specific features of your extension including screenshots of your extension in action. Image paths are relative to this README file. +- Zero-configuration: open any Ceylon project folder and start editing (`.ceylon/config` +will be used for configuration if present) +- Multithreaded compiles: the module you are editing is immediately recompiled after each +edit while dependent modules are compiled in the background +- Syntax highlighting +- As you type warning and error reporting +![errors](images/screeshot-errors.png) +- Auto completion +![errors](images/screeshot-autocomplete.png) +- Documentation on hover +![hover](images/screeshot-hover.png) -For example if there is an image subfolder under your extension project workspace: +## Requirements -\!\[feature X\]\(images/feature-x.png\) +- [Ceylon 1.3.0](https://ceylon-lang.org) ([download](https://ceylon-lang.org/download/)) +- [Dart backend for Ceylon DP3](https://github.com/jvasileff/ceylon-dart). + Simple two step commandline installation: + `ceylon plugin install --force com.vasileff.ceylon.dart.cli/1.3.0-DP3` + then `ceylon install-dart --out +USER` +- [Visual Studio Code](https://code.visualstudio.com/Download) -> Tip: Many popular extensions utilize animations. This is an excellent way to show off your extension! We recommend short, focused animations that are easy to follow. +To run programs on the Dart VM (optional), either +[download](https://www.dartlang.org/downloads/) Dart or install it using +Homebrew as described in the Dart backend for Ceylon +[readme](https://github.com/jvasileff/ceylon-dart). -## Requirements +## Installation -If you have any requirements or dependencies, add a section describing those and how to install and configure them. +After satisfying the requirements, simply download the preview version of the +extension +([vscode-ceylon-0.0.0.vsix](https://jvasileff.github.io/vscode-ceylon/vscode-ceylon-0.0.0.vsix)) +and open it in Visual Studio Code. -## Extension Settings +The extension must be able to find the `ceylon` 1.3.0 executable using one of +the following methods: -Include if your extension adds any VS Code settings through the `contributes.configuration` extension point. +- Using `ceylon.home` configured within the Visual Studio Code settings (`⌘,` + on macOS) +- Using the `CEYLON_HOME` environment variable +- Using the system `PATH` -For example: +## Extension Settings This extension contributes the following settings: -* `myExtension.enable`: enable/disable this extension -* `myExtension.thing`: set to `blah` to do something +* `ceylon.home`: The directory of the Ceylon installation to use. +* `ceylon.generateOutput`: Write compiled binaries to the output repository. + Note that output is produced regardless of whether or not the source files + have been saved. +* `ceylon.serverLogPriority`: The logging level for the language server. +* `ceylon.config.compiler.suppresswarning`: Override the suppresswarning + setting. +* `ceylon.config.compiler.dartsuppresswarning`: Override the + dartsuppresswarning setting. +* `ceylon.config.compiler.source`: Override the source repositories. Note that + this will not take effect without restart. +* `ceylon.config.compiler.resource`: Override the resource repositories. Note + that this will not take effect without restart. +* `ceylon.config.repositories.output`: Override the output repository +* `ceylon.config.repositories.lookup`: Override the lookup repositories + +Note that the `ceylon.generateOutput` and `ceylon.config.*` settings are +intended to be used as workspace settings, but are entirely optional. + +## Running and Testing Your Ceylon Program + +In order to quickly run and test a module, it's recommended to enabled +`ceylon.generateOutput`, which is disabled by default. New binaries will be +created after every change, even for unsaved source files. + +"Tasks" can easily be configured with Visual Studio Code to support calling +`ceylon compile-dart` (useful if `ceylon.generateOutput` is disabled) and +`ceylon run-dart`. It's of course possible to use tasks to call commands for other +backends too, for example, `compile-js`, `run-js`, and `test-js`. + +A sample `tasks.json` to get you started: + +```json +{ + // See https://go.microsoft.com/fwlink/?LinkId=733558 + // for the documentation about the tasks.json format + "version": "0.1.0", + "command": "ceylon", + "isShellCommand": true, + "suppressTaskName": true, + "showOutput": "always", + "tasks": [ + { + "taskName": "compile", + "args": ["compile-dart"], + "isBuildCommand": true + }, + { + "taskName": "run", + "args": ["run-dart", "com.example.mymodule"] + } + ] +} +``` ## Known Issues -Calling out known issues can help limit users opening duplicate issues against your extension. - -## Release Notes - -Users appreciate release notes as you update your extension. - -### 1.0.0 +This is pre-release software. Please report problems with steps to reproduce +using the [Github issue tracker](https://github.com/jvasileff/vscode-ceylon/issues). -Initial release of ... +Known issues and limitations include: -### 1.0.1 +- Source directory configuration changes made in `.ceylon/config` and Visual + Studio Code settings will not take effect until restart +- Completion and hover are not synchronized with builds, so stale incorrect + information may be provided +- When `ceylon.generateOutput` is enabled, binaries are continuously produced, + even for unsaved edits. -Fixed issue #. - -### 1.1.0 - -Added features X, Y, and Z. - ------------------------------------------------------------------------------------------------------------ - -## Working with Markdown - -**Note:** You can author your README using Visual Studio Code. Here are some useful editor keyboard shortcuts: - -* Split the editor (`Cmd+\` on OSX or `Ctrl+\` on Windows and Linux) -* Toggle preview (`Shift+CMD+V` on OSX or `Shift+Ctrl+V` on Windows and Linux) -* Press `Ctrl+Space` (Windows, Linux) or `Cmd+Space` (OSX) to see a list of Markdown snippets - -### For more information +## Release Notes -* [Visual Studio Code's Markdown Support](http://code.visualstudio.com/docs/languages/markdown) -* [Markdown Syntax Reference](https://help.github.com/articles/markdown-basics/) +### 0.0.0 -**Enjoy!** \ No newline at end of file +The initial preview release. diff --git a/images/screeshot-autocomplete.png b/images/screeshot-autocomplete.png new file mode 100644 index 0000000..71eacc2 Binary files /dev/null and b/images/screeshot-autocomplete.png differ diff --git a/images/screeshot-errors.png b/images/screeshot-errors.png new file mode 100644 index 0000000..deb77bf Binary files /dev/null and b/images/screeshot-errors.png differ diff --git a/images/screeshot-hover.png b/images/screeshot-hover.png new file mode 100644 index 0000000..0a924af Binary files /dev/null and b/images/screeshot-hover.png differ