Update README
This commit is contained in:
Radon Rosborough
parent
b02c2ebe77
commit
fc1372a263
126
README.md
126
README.md
|
|
@ -1,50 +1,96 @@
|
||||||
# Riju
|
# Riju
|
||||||
|
|
||||||
For now, this README just has some miscellaneous notes about the build
|
Riju is a very fast online playground for every programming language.
|
||||||
architecture that I'm planning to set up. Later, it will be converted
|
In less than a second, you can start playing with a Python interpreter
|
||||||
back into a proper README.
|
or compiling INTERCAL code.
|
||||||
|
|
||||||
Steps to build Riju from scratch locally:
|
Check out the [live application](https://riju.codes/)!
|
||||||
|
|
||||||
* Build the packaging Docker image.
|
**You should not write any sensitive code on Riju, as NO GUARANTEES
|
||||||
* Generate a Debian package for each language.
|
are made about the security or privacy of your data. (No warranty etc
|
||||||
* Build the runtime Docker image.
|
etc.)**
|
||||||
* 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.
|
|
||||||
|
|
||||||
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
|
## Criteria for language inclusion
|
||||||
* Runtime image
|
|
||||||
* Debian packages
|
|
||||||
* Application image
|
|
||||||
|
|
||||||
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.
|
* **Language must have a clear notion of execution.** This is because
|
||||||
* *To build application image:* Pull runtime image and all Debian
|
a core part of Riju is the ability to execute code. Languages like
|
||||||
packages.
|
[YAML](https://yaml.org/), [SCSS](https://sass-lang.com/), and
|
||||||
* *To build Debian packages:* Pull packaging image.
|
Markdown are fine because they have a canonical transformation (into
|
||||||
* *To build runtime image:* Build from scratch.
|
[JSON](https://www.json.org/json-en.html),
|
||||||
* *To build packaging image:* Build from scratch.
|
[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
|
Here are some explicit *non-requirements*:
|
||||||
updates which keep the integration tests passing. Possible operations:
|
|
||||||
|
|
||||||
* *Rebuild packaging image:* This can be done at any time.
|
* *Language must be well-known.* Nope, I'll be happy to add your pet
|
||||||
* *Rebuild runtime image:* Rebuild application image and verify
|
project; after all, [Kalyn](https://github.com/raxod502/kalyn) and
|
||||||
integration tests are still passing. Do not rebuild any Debian
|
[Ink](https://github.com/thesephist/ink) are already supported.
|
||||||
packages.
|
* *Language must be useful.* I would have no objection to adding
|
||||||
* *Rebuild Debian package:* Verify unit tests are passing. Rebuild
|
everything on the esolangs wiki, if there are interpreters/compilers
|
||||||
application image and verify integration tests are still passing. If
|
available.
|
||||||
rebuilding multiple Debian packages, then we can run the integration
|
* *Language must be easy to install and run.* Well, it would be nice,
|
||||||
tests only once. If rebuilding enough Debian packages, the
|
but I've seen some s\*\*\* when adding languages to Riju so it will
|
||||||
probability that at least one will fail is very high. We can then
|
take a lot to surprise me at this point.
|
||||||
trigger a more targeted update. This process could be automated.
|
|
||||||
* *CI:* Rebuild packaging and runtime images if needed. Rebuild Debian
|
If you'd like to request a new language, head to the [language support
|
||||||
packages for any changed languages. Fetch everything unchanged from
|
meta-issue](https://github.com/raxod502/riju/issues/24) and add a
|
||||||
registry. Rebuild application image and verify integration tests are
|
comment. Of course, if you actually want it to be added anytime soon,
|
||||||
still passing. If yes and operating on main branch, publish all
|
you should submit a pull request :)
|
||||||
artifacts and deploy.
|
|
||||||
|
## 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