Skip to content
Permalink
Browse files

Start documenting the build process.

Also make changes to language versions documentation. The last section
of it has been removed as outdated and as something which better belongs
to a blog post rather than to a documentation paper.
  • Loading branch information...
vrurg committed May 31, 2019
1 parent c8b5bd3 commit 6ee37f8b5356bc680160d38969aeee2a6222c951
Showing with 106 additions and 22 deletions.
  1. +104 −0 docs/Building-Rakudo.md
  2. +2 −22 docs/language_versions.md
@@ -0,0 +1,104 @@
# Things To Know About Rakudo BUILD

## SYNOPSIS

Start with:

```
cd <your Rakudo sources directory>
./Configure --gen-moar --gen-nqp
make install && make test
```

## Configure.pl

### Developing on own forks of repositories.

One of the best modes of development is to have the project you work with forked from the original repository into your
own. Often this is the only possible way if a developer doesn't have commit access. `Configure.pl` supports such mode of
development via following command line options:

- `--github-user=<user>` defines the GitHub account where cloned repositories of `MoarVM`, `NQP`, and `Rakudo` are all
located. With this option sources of `NQP` will be cloned from `git@github.com:<user>/nqp` instead of the default
`git@github.com:perl6/nqp`.
- `--[rakudo|moar|nqp|roast]-repo` command line options allow to define particular URL for each individual repository.

### nqp-configure submodule

`Configure.pl` is based on modules implemented by [nqp-configure](https://github.com/perl6/nqp-configure) repository.
This repo is included as a submodule into `rakudo` source repository. To set a user free of manual update of submodules
upon each update of `nqp-configure` `Configure.pl` does a few things under the hood upon startup:

- First is checks if the submodule has been checked out already. If not then it'll be automatically initialized and
pulled in.
- If local copy of `rakudo` repository hasn't been _initialized_ yet then `Configure.pl` sets `submodule.recurse` `git`
configuration variable to _true_. It is also set _initialized_ status by setting `rakudo.initialized` `git`
configuration variable.

Any consequent run of `Configure.pl` won't be trying to set `submodule.recurse` again unless _initialized_ state is
reset by deleting `rakudo.initialized`. This allows anyone who wants to update submodules manually to reset
`submodule.recurse` without worrying that it'll be overridden.

## Templates

_... needs documenting ..._

See documentation on macros in
[nqp-configure repository](https://github.com/perl6/nqp-configure/blob/master/doc/Macros.md).

## Language Revisions

Language revisions supported by current `Rakudo` version are defined in `tools/templates/PERL6_SPECS` file. At the
moment of writing this section it has the following look:

```
# [*]version [modifier]
# * defines the current spec
# modifiers can be prefixed with the following flags:
# ! required. Means that revision cannot be used without this modifier.
# - deprecated. Use of this modifier will result in a language warning.
c
# TEST and TESTDEPR modifiers are to be kept for roast.
*d -PREVIEW TEST -TESTDEPR # TODO: It's about time to drop PREVIEW
e !PREVIEW
```

The life cycle of a release modifier `PREVIEW` must follow these rules:

1. For a revision being developed it has to be marked as required. In this status use of the revision letter in a
language version is not possible without the modifier. With the file in the example if we try `use v6.e;` the
compiler must die with _'Perl v6.e requires modifier PREVIEW'_ message.
1. When revision gets released the modifier status changes into normal status for a couple of monthly releases of
`Rakudo` to allow graceful transition for modules which were built specifically for the just released revision.

_Note_ that at this stage corresponding changes are to be done to `roast` repository.
1. When the transiotion period is considered over the `PREVIEW` modifier must be marked as _deprecated_. With this
status it's still possible to use it. But the compiler will generate a warning message.
1. The _deprecation_ period should be over after another few releases and followed by complete removal of `PREVIEW`
modifier from `PERL6_SPECS` file. At this point its use is considered illegal and compiler will be dying whenever
find it in a code.

### Steps to add a new revision

1. Edit `PERL6_SPECS` to add a line containing the new revision letter similar to this:

```<revision letter> !PREVIEW```
_Note_ that here and below `<revision letter>` must be replaced with the next letter to be used.
1. Change the status of `PREVIEW` modifier of the previous release from _required_ to _normal_. Save `PERL6_SPECS`.
1. Create `src/core.<revision letter>` directory.
1. Create file `src/core.<revision letter>/core_prologue.pm6` with the following lines in it:
```
use nqp;

# This dynamic is purely for testing support.
PROCESS::<$CORE-SETTING-REV> := '<revision letter>';

# vim: ft=perl6 expandtab sw=4
```
1. Edit file `t/02-rakudo/14-revisions.t` to reflect all changes done in `PERL6_SPECS` on the previous steps: add one
more test for the new revision, remove `PREVIEW` from the previous revision, etc.
1. Change `VERSION` file in `roast` repository.
@@ -133,26 +133,6 @@ likely be kind enough to give deprecation cycles.

## Trying out the "next version"

To try out v6.d before the compiler officialy supports it, you can write:
To try out v6.e before the compiler officialy supports it, you can write:

use v6.d.PREVIEW;

## If anyone asks about 6.d and beyond...

About Perl 6.d, expect an incremental update.

* It'll focus heavily on broadening test coverage to tighten up the language
definition
* It will include various small things we wished we could have done in 6.c,
but just didn't have time: the missing regex backtracking controls, the
sub-byte int types, non-parameter cases of coercion types, things we
discover people miss especially in IO, etc.
* Goal is sometime in 2017; we'll judge it based upon what we see (like, if
there is a strong desire to get an incremental update out the door to cover
things people really block on not having, we can do so)

A lot of effort in 2016 was focused on performance engineering and making things
more robust. This work will continue until the eventual feature freeze and release.
Macros and slangs are the biggest post-6.c project language wise;
if they happen to be in great shape by 6.d then they can make it in, but if
not they'd be a reasonable target for 6.e.
use v6.e.PREVIEW;

0 comments on commit 6ee37f8

Please sign in to comment.
You can’t perform that action at this time.