Mascali
/
piston
mirror of https://github.com/engineer-man/piston.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

pkg(contributing): update guide for new format

This commit is contained in:
Thomas Hobson 2021-03-06 00:27:24 +13:00
parent 34fbda0772
commit 4732681864
No known key found for this signature in database
GPG Key ID: 9F1FD9D87950DB6F
1 changed files with 33 additions and 51 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

84
packages/CONTRIBUTING.MD
View File

@ -1,66 +1,33 @@
# Contributing packages to the Piston Repository
## Naming Lanaguages
## Naming Languages
Some languages have multiple different wide-spread interpreters (node/deno for example) which need to be accounted for.
If the given language has multiple incompatiable interpreters (e.g. deno/node/v8), these should be named as `[language]-[interpreter]`.
For cases where the language has many compatable interpreters (e.g. gcc/llvm), pick one and name it `[language]`.
For languages with only 1 wide-spread interpreter (e.g. Kotlin), name it `[language]`
## File Naming Rules
Different versions of interpreters require different steps to build, and in this case they should be given 2 different files, but keep the same language name.
Use `[language-name].mk` (see naming languages) for languages with a common build script.
When the build steps become obsolete, create a new file named `[language-name]-[version].mk`, with the first version where the new build steps were required.
Languages should be named after their interpreters, and the command line binaries you call.
For example, the full name of the standard python interpreter is `CPython`, however we would name it `python`, after the main binary which it provides.
In the example of NodeJS, we would call this `node`, after the main binary.
## Creating new languages
See [python.mk](python.mk) or any other `.mk` file (except `common.mk`) for an example.
Please note that this is a regular Makefile, with a few extra varibles added by `common.mk`, any additional variables not listed here can be located in there.
See [deno-1.7.5/](deno-1.7.5/) or any other directory for examples.
1. Create a new branch on your fork of engineer-man/piston
2. Create a new file for your language, following the naming rules as listed above
2. Create a directory named `[language]-[version]`. See Naming Languages for how to determine the name for your language
3. Add `NAME=[language name]` to this file, replacing `[language name]` with the language name all in lowercase, removing any punctuation and numbers (e.g. 05AB1E becomes osabie).
3. Create a file named `build.sh`, adding a shebang for bash `#!/bin/bash` on the first line.
In this file put any steps to compile the specified langauge.
It is allowed to use 2 directories, `output` and `build`, the former which contains files which should get packaged into the final output, and the latter containing intermediate build files.
4. Add `AUTHOR=[author]` to this file, replacing `[author]` with your name and email address in the format `Full Name <your@email.address>` (standard git format).
4. Create a file named `run`, containing bash script to run the interpreter.
The first argument given to this script (`$1`) is the name of the main file, with the remaining ones as program arguments.
STDIN is piped directly into the run file, and as such nothing special is required to deal with STDIN, except leaving it open.
5. Add `DEPENDENCIES=[dependencies list]` to this file, replacing `[dependencies list]` with a list of dependencies, seperated by spaces in the format `[language]==[version]`. If there are none, simply leave this as `DEPENDENCIES=`
5. Create a file named `compile`, containing bash script to compile sources into binaries. This is only required if the language requires a compling stage.
The first argument is always the main file, followed the names of the other files as additional arguements. If the language does not require a compile stage, don't create a compile file.
6. Add `COMPILED=[true/false]` to this file, set this to true if the language requires the compile stage, and false if it only requires run.
6. Create a file named `environment`, containing `export` statements which edit the environment variables accordingly. The `$PWD` variable should be used, and is set inside the `output` directory, but when running on the target system.
7. Add `VERSIONS=[version list]` to this file, replacing `[version list]` with a list of [SemVer](https://semver.org/) compilant version numbers for the language which this build file can build. This value will be passed in as `${VERSION}` for you to access
8. Add `include common.mk`, to include all the common Makefile rules and variables.
9. Create the target for the run file by adding `${RUN_FILE}:`, followed by steps on new lines, indented by a tab (`\t`) to create a bash script, which is run for every job (`/execute` endpoint) for this language and returns on STDOUT/STDERR the output of the run.
The script is expected to take in the first argument (`$1`) as the main code file, with subsequent arguments being passed in from the execute endpoint.
The script is passed STDIN as specified in the job, and expects output on STDOUT/STDERR. It should also pass through the exit code from the interpreter.
It is recommended to use `echo` statements, redirecting output to `$@` (a special Makefile variable expanding to the target file, in this case RUN_FILE).
Make sure to escape any `$` with `$$`, as `$` will expand make variables.
10. (optional, only use if language requires compliation)
Create the target for the compile file by adding `${COMPILE_FILE}:`, followed by steps on new lines, indented by a tab (`\t`) to create a bash script, which is run for every job (`/execute` endpoint) for this language, if it requires compilation.
This script is expected to take all code files in as arguements, and output binary files. STDERR/STDOUT are captured and passed out, along with error code. The job STDIN and args are not passed in to this script.
This script should compile source code into a binary, and has a seperate time limit from run, and thus should split the stages.
Follow all priciples from step 9, using echo statements and escaping `$`.
11. Create the target for the environment file by adding `${ENV_FILE}:`, followed by steps on new lines, indented by a tab (`\t`) to create a bash script, which modifies environment variables exactly how you would a `.profile` or `.bashrc` file. Note that this file is only run at install time, and thus cannot dynamicly adjust to the arguements passed into it.
The environment file is also appended with all dependencies before being cached.
You should add in the path to any binaries. The current working directory for the script is contained within the `${BIN_DIR}` folder.
12. Create the target for the binaries by adding `${BIN_DIR}:`, followed by steps on new lines, indented by a tab (`\t`) which will download sources, compile and output binaries in to the `${BIN_DIR}` (`$@`)
13. Locally test your Makefile builds with `make build-[language]-[version]`.
If everything went well, you should now have a `[language]-[version].pkg.tar.gz` file sitting in the root.
If not, read through your error logs, and if in doubt ask for help in #emkc-felix-piston in Discord.
14. Create a source file for the app, which outputs `OK`, naming the file `[language-name].test`
For example, `mono` would have a file named `csharp-mono.test` containing:
7. Create a test script starting with test, with the file extension of the language. This script should simply output the phrase `OK`. For example, for mono we would create `test.cs` with the content:
```cs
using System;
@ -73,7 +40,22 @@ public class Test
}
```
15. Commit your changes, using message format of `pkg([language]): Added [language] [version]`
8. Create a `metadata.json` file which contains metadata about the language and interpreter. This simply contains the language name, as in the folder name, the version as in the folder name, the author's name and email address, aliases that can be used to call this package, and finally a dependencies map.
The dependencies map contains the keys as language names, and the values as semver selectors for packages.
```json
{
"language": "deno",
"version": "1.7.5",
"author": "Thomas Hobson <thomas@hexf.me>",
"dependencies": {},
"aliases": ["deno-ts", "deno-js"]
}
```
9. Test your package builds with running `make [language]-[version].pkg.tar.gz`.
If it all goes to plan, you should have a file named `[language]-[version].pkg.tar.gz`, in this case your good to go!
10. Commit your changes, using message format of `pkg([language]): Added [language] [version]`
Any additional commits regarding this package should start with `pkg([language]): `
16. Create a pull request (currently to v3), referencing an Issue number (if there is one associated).
11. Create a pull request (currently to v3 branch), referencing an Issue number (if there is one associated).