134 lines
3.4 KiB
Markdown
134 lines
3.4 KiB
Markdown
# Adding your own language to Riju
|
|
|
|
Hello and welcome! This tutorial guides you through the basics of
|
|
adding a new language to Riju, or modifying an existing language. The
|
|
other documentation in this repo has reference material that may be
|
|
helpful for advanced use cases, but this page should get you started.
|
|
|
|
If you run into any trouble following the guide, please do not
|
|
hesitate to open an issue!
|
|
|
|
## Project setup
|
|
|
|
Fork this repository to your account on GitHub, and clone it locally:
|
|
|
|
```
|
|
$ git clone https://github.com/yourname/riju.git
|
|
$ cd riju
|
|
```
|
|
|
|
Install [Docker](https://www.docker.com/). Then you can build and
|
|
start the admin shell:
|
|
|
|
```
|
|
$ make image shell I=admin
|
|
```
|
|
|
|
All future operations can be done inside the admin shell, where all
|
|
dependencies are installed automatically.
|
|
|
|
## Start tmux
|
|
|
|
Start a tmux session:
|
|
|
|
```
|
|
$ make tmux
|
|
```
|
|
|
|
If you don't know how to use tmux, see [a
|
|
cheatsheet](https://danielmiessler.com/study/tmux/). The useful
|
|
keybindings are:
|
|
|
|
* `control-b c`: open new tab
|
|
* `control-b p/n`: previous/next tab
|
|
* `control-b "`: split tab into top and bottom panes
|
|
* `control-b %`: split tab into left and right panes
|
|
* `control-b <arrows>`: move between panes
|
|
* `control-b control-b <something>`: if you have two tmuxes nested,
|
|
use `control-b` twice to do a command on the inner one instead of
|
|
the outer one
|
|
|
|
## Configure local project
|
|
|
|
Using your regular text editor (the Riju repository is synchronized
|
|
inside and outside of the container, so you can use whatever editor
|
|
you would like, it doesn't have to be something in the terminal),
|
|
create a file `.env` in the Riju repository with the following
|
|
contents:
|
|
|
|
```
|
|
DOCKER_REPO=raxod502/riju
|
|
S3_BUCKET=riju
|
|
```
|
|
|
|
This tells Riju to pull assets from the official registries that I
|
|
maintain, so that you don't have to build them yourself.
|
|
|
|
## Set up Docker images
|
|
|
|
Download the two Docker images needed for testing a new language:
|
|
|
|
```
|
|
$ make pull I=packaging
|
|
$ make pull I=runtime
|
|
```
|
|
|
|
Create a new tab in tmux (`control-b c`) and start the runtime image
|
|
with ports exposed:
|
|
|
|
```
|
|
$ make shell I=runtime E=1
|
|
```
|
|
|
|
Inside that shell, start another instance of tmux:
|
|
|
|
```
|
|
$ make tmux
|
|
```
|
|
|
|
Now within that tmux, start Riju in development mode:
|
|
|
|
```
|
|
$ make dev
|
|
```
|
|
|
|
You should now be able to navigate to <http://localhost:6119> and see
|
|
that Riju is running, although it does not have any languages
|
|
installed.
|
|
|
|
Finally, switch back to the admin shell (`control-b p`). We are ready
|
|
to start creating your new language.
|
|
|
|
## Create a language configuration
|
|
|
|
Create a file `langs/mylanguage.yaml` with the following contents:
|
|
|
|
```yaml
|
|
id: "mylanguage"
|
|
name: "My Language"
|
|
|
|
main: "TODO"
|
|
template: |
|
|
# Fill this in later
|
|
|
|
run: |
|
|
echo "Hello, world!"
|
|
```
|
|
|
|
Now from the admin shell, run `make repkgs L=mylanguage`. Once that
|
|
completes, you should see your language at <http://localhost:6119>.
|
|
Furthermore, you can switch to the runtime image (`control-b n`) and
|
|
run `make sandbox L=mylanguage` to test your language at the command
|
|
line (e.g. type `run` to print `Hello, world!`). Each time you modify
|
|
the language configuration, run `make repkgs L=mylanguage` to
|
|
reinstall the language.
|
|
|
|
Follow these steps to augment your language configuration:
|
|
|
|
* [Install your language](tutorial/install.md)
|
|
* [Provide run commands](tutorial/run.md)
|
|
* [Configure tests](tutorial/tests.md)
|
|
* [Provide metadata](tutorial/metadata.md)
|
|
* [Add code formatter](tutorial/formatter.md)
|
|
* [Add language server](tutorial/lsp.md)
|