Update README
This commit is contained in:
Radon Rosborough
parent
b02c2ebe77
commit
fc1372a263
126
README.md
126
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.
|
||||
|
|
|
|||
Loading…
Reference in New Issue