path: root/README.md
diff options
authorPatrick Spek <p.spek@tyil.nl>2020-03-22 11:48:23 +0100
committerPatrick Spek <p.spek@tyil.nl>2020-03-22 11:48:23 +0100
commit1d983e9f934bf6aeb9333c763fe1a603b8d8e5c4 (patch)
treeff96afaf569e8669a28ba35e85a1441621117d0b /README.md
Initial commit
Diffstat (limited to 'README.md')
1 files changed, 107 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..e68318d
--- /dev/null
+++ b/README.md
@@ -0,0 +1,107 @@
+# Rakudo Star
+A user-friendly distribution of the Raku programming language.
+## Quickstart
+After downloading and extracting the tarball (or cloning the git repository),
+run `./bin/rstar install`. Follow any on-screen instructions as they appear.
+That is all!
+If you happen to find any bugs, please refer to the **Bugs, Feedback and
+Patches** section later on in this document to find out how you can get help.
+## Advanced usage
+This section is intended for maintainers of the Rakudo Star distribution.
+### The `rstar` utility
+To help maintainers build the distribution tarball, and end-users to make
+effective use of the tarball, a utility has been created, called `rstar`. This
+utility depends on the `bash` shell being available. Run it with `-h` to see
+what it can do.
+Depending on what action you're trying to run, additional dependencies may be
+required. If any of these are missing, `rstar` will throw an error about it.
+#### Exit codes
+- ` 1` - die() was encountered. This is always a bug;
+- ` 2` - The program was invoked incorrectly;
+- ` 3` - Some required dependencies are missing.
+#### Environment Variables
+The `rstar` utility can be affected by environment variables. These may help
+out when debugging issues.
+- `RSTAR_DEBUG` - If set to a non-null value, additional debugging output will
+ magically appear;
+- `RSTAR_MESSY` - If set to a non-null value, the `tmp` directory will not be
+ cleaned when `rstar` exits.
+### Community Modules
+One of Rakudo Star's main features is in supplying users with a number of
+popular community modules. This section details the mechanics of how these are
+*You should always prefer to use a pinned version of a module!*
+#### modules.txt
+This file contains references to all community modules to be bundled with
+Rakudo Star. It is a space-separated format. The first column is the name of
+the module, the second the protocol to use, with the third column being the
+URL to fetch it from. Columns following the third have different meaning
+depending on the protocol.
+##### `git`
+The git protocol clones a single ref, with a depth of 1. Which ref is going to
+be cloned is specified in the 4th column of its `modules.txt` entry. After
+cloning, the `.git` directory is removed.
+##### `http
+The http protocol is the most straightforward, it downloads a tarball
+(`.tar.gz`) and unpacks it. If a value is specified in the 4th column of the
+entry, this will be used as prefix, and will be stripped away when the
+extracted sources are moved into the `dist` directory.
+### Quickstart to Releasing Rakudo Star
+Your first step will be to prepare a new tarball.
+ rstar clean # Clean up old sources
+ $EDITOR etc/dist_moarvm.txt # Update values as necessary
+ $EDITOR etc/dist_nqp.txt # Update values as necessary
+ $EDITOR etc/dist_rakudo.txt # Update values as necessary
+ $EDITOR etc/modules.txt # Update values as necessary
+ rstar fetch # Download new sources
+ rstar install # Compile and install Rakudo Star
+ rstar test # Run tests
+ rstar dist # Create a new distribution tarball
+Once you have a tarball, you should upload it to be available to others. Common
+places include:
+- rakudo.org (ask around in #raku-dev for someone to help you if needed);
+- Your personal website.
+Next up, you will have to tell people of the new distribution tarball existing.
+There are several places to announce this at. The most "official" one would be
+the `perl6-compiler@perl.org` mailing list. The `perl6-users@perl.org` mailing
+list is also a good choice, as are public places such as Reddit.
+## Bugs, Feedback and Patches
+Bugs, feedback or patches for this project can be sent to
+`p.spek+rakudo-star@tyil.work`. Alternatively, you can reach out to `tyil` on
+Freenode, DareNET or Matrix.
+## License
+The software in this repository is distributed under the terms of the Artistic
+License 2.0, unless specified otherwise.