diff --git a/README.md b/README.md index ebe9aa0..77536f4 100644 --- a/README.md +++ b/README.md @@ -1,50 +1,96 @@ # Riju -For now, this README just has some miscellaneous notes about the build -architecture that I'm planning to set up. Later, it will be converted -back into a proper README. +Riju is a very fast online playground for every programming language. +In less than a second, you can start playing with a Python interpreter +or compiling INTERCAL code. -Steps to build Riju from scratch locally: +Check out the [live application](https://riju.codes/)! -* Build the packaging Docker image. -* Generate a Debian package for each language. -* Build the runtime Docker image. -* For each language, install its Debian package into a fresh copy of - the runtime Docker image and run its tests. -* Install every language's Debian package into a single copy of the - runtime Docker image and run all the tests. +**You should not write any sensitive code on Riju, as NO GUARANTEES +are made about the security or privacy of your data. (No warranty etc +etc.)** -Build artifacts: +This project is a work in progress, and I don't intend on thoroughly +documenting it until it has reached feature-completeness. -* Packaging image -* Runtime image -* Debian packages -* Application image +## Criteria for language inclusion -Steps to build Riju from cache locally: +I aspire for Riju to support more languages than any reasonable person +could conceivably think is reasonable. That said, there are some +requirements: -* *To run:* Pull application image. -* *To build application image:* Pull runtime image and all Debian - packages. -* *To build Debian packages:* Pull packaging image. -* *To build runtime image:* Build from scratch. -* *To build packaging image:* Build from scratch. +* **Language must have a clear notion of execution.** This is because + a core part of Riju is the ability to execute code. Languages like + [YAML](https://yaml.org/), [SCSS](https://sass-lang.com/), and + Markdown are fine because they have a canonical transformation (into + [JSON](https://www.json.org/json-en.html), + [CSS](https://developer.mozilla.org/en-US/docs/Web/CSS), and + [HTML](https://developer.mozilla.org/en-US/docs/Web/HTML) + respectively) that can be performed on execution. However, languages + like JSON, CSS, and HTML are not acceptable, because there's nothing + reasonable to do when they are run. +* **Language must not require input or configuration.** This is + because, in order to avoid bloating the interface, Riju provides a + way to supply code but not any other data. Of course, it's possible + to supply input interactively, so reading stdin is allowed, but if a + language can only reasonably be programmed with additional input, + it's not a candidate for inclusion. Thus, many templating languages + are excluded, since they don't do anything unless you are + substituting a value. However, some languages such as + [Pug](https://pugjs.org/) are allowed, because they implement a + significant syntax transformation outside of template substitution. + Also, languages like [Sed](https://www.gnu.org/software/sed/) and + [Awk](https://www.gnu.org/software/gawk/) are allowed, because it's + straightforward to test code written in them even without a + pre-prepared input file. +* **Language must not require a graphical environment.** This is + because we use a pty to run code, and there is no X forwarding. As + such, we can't use languages like + [Scratch](https://scratch.mit.edu/), + [Alice](https://www.alice.org/), and + [Linotte](http://langagelinotte.free.fr/wordpress/). +* **Language must be available for free under a permissive license.** + This is because we must download and install all languages + noninteractively in the Docker image build, so anything that + requires license registration is unlikely to work (or be legal). We + can't use [Mathematica](https://www.wolfram.com/mathematica/) or + [MATLAB](https://www.mathworks.com/products/matlab.html), for + example, but we can use [Mathics](https://mathics.github.io/) and + [Octave](https://www.gnu.org/software/octave/), which provide + compatible open-source implementations of the underlying languages. +* **Language must be runnable under Docker on Linux.** This is because + that's the execution environment we have access to. + [AppleScript](https://en.wikipedia.org/wiki/AppleScript) is out + because it only runs on macOS, and [Docker](https://www.docker.com/) + is out because it can't be run inside Docker (without the + `--privileged` flag, which has unacceptable security drawbacks; see + [#29](https://github.com/raxod502/riju/issues/29)). Note, however, + that many Windows-based languages can be used successfully via + [Mono](https://www.mono-project.com/) or + [Wine](https://www.winehq.org/), such as + [Cmd](https://en.wikipedia.org/wiki/Cmd.exe), + [C#](https://en.wikipedia.org/wiki/C_Sharp_(programming_language)), + and [Visual Basic](https://en.wikipedia.org/wiki/Visual_Basic). -To manipulate published artifacts we basically want to do atomic -updates which keep the integration tests passing. Possible operations: +Here are some explicit *non-requirements*: -* *Rebuild packaging image:* This can be done at any time. -* *Rebuild runtime image:* Rebuild application image and verify - integration tests are still passing. Do not rebuild any Debian - packages. -* *Rebuild Debian package:* Verify unit tests are passing. Rebuild - application image and verify integration tests are still passing. If - rebuilding multiple Debian packages, then we can run the integration - tests only once. If rebuilding enough Debian packages, the - probability that at least one will fail is very high. We can then - trigger a more targeted update. This process could be automated. -* *CI:* Rebuild packaging and runtime images if needed. Rebuild Debian - packages for any changed languages. Fetch everything unchanged from - registry. Rebuild application image and verify integration tests are - still passing. If yes and operating on main branch, publish all - artifacts and deploy. +* *Language must be well-known.* Nope, I'll be happy to add your pet + project; after all, [Kalyn](https://github.com/raxod502/kalyn) and + [Ink](https://github.com/thesephist/ink) are already supported. +* *Language must be useful.* I would have no objection to adding + everything on the esolangs wiki, if there are interpreters/compilers + available. +* *Language must be easy to install and run.* Well, it would be nice, + but I've seen some s\*\*\* when adding languages to Riju so it will + take a lot to surprise me at this point. + +If you'd like to request a new language, head to the [language support +meta-issue](https://github.com/raxod502/riju/issues/24) and add a +comment. Of course, if you actually want it to be added anytime soon, +you should submit a pull request :) + +## Project setup + +I have recently completely rearchitected the build system of Riju. I +will update the documentation on development workflow here as soon as +CI is passing once more.