1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
|
# Things To Know About Rakudo Build
## SYNOPSIS
Start with:
```
cd <your Rakudo sources directory>
./Configure.pl --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:Raku/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/Raku/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 it 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/Raku/nqp-configure/blob/master/doc/Macros.md).
## Language Revisions
Language revisions supported by current `Rakudo` version are defined in `tools/templates/RAKU_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 _'Raku 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 transition 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 `RAKU_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 `RAKU_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 `RAKU_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=raku expandtab sw=4
```
1. Edit file `t/02-rakudo/14-revisions.t` to reflect all changes done in `RAKU_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.
|
