piston/packages/CONTRIBUTING.MD

Contributing packages to the Piston Repository

Naming Languages

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 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 directory named [language]-[version]. See Naming Languages for how to determine the name for your language

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. 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. 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. 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. 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:

using System;

public class Test
{
    public static void Main(string[] args)
    {
        Console.WriteLine("OK");
    }
}

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.

{
    "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]):

11. Create a pull request (currently to v3 branch), referencing an Issue number (if there is one associated).