Skip to content

Commit 9efbf34

Browse files
AndreVanDelftAndreVanDelft
committed
Merge pull request #1 from adelbertc/markdown-readme
Formatted README file, changed from RST to Markdown
2 parents 3cfcec7 + 2eb2442 commit 9efbf34

File tree

2 files changed

+242
-267
lines changed

2 files changed

+242
-267
lines changed

‎README.md

Lines changed: 242 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,242 @@
1+
#The Scala Repository - Subscript Branch
2+
This document describes a branch of the Scala core (core library and compiler)
3+
repository and how to build it. This particular branch supports the language
4+
extension named SubScript.
5+
6+
This file has been derived from the README.rst of the main Scala branch;
7+
Items related to SubScript have been added.
8+
9+
For information about Scala and SubScript as languages, you can visit the
10+
web sites:
11+
12+
* [http://www.scala-lang.org](http://www.scala-lang.org)
13+
* [http://www.subscript-lang.org](http://www.subscript-lang.org)
14+
15+
##SubScript Compiler issues
16+
The current SubScript compiler (a branch of `scalac`) is good enough to compile
17+
the given example programs, but there are some limitations and bugs:
18+
19+
* Only language features used in the examples are present and tested.
20+
Other features, most notably communication, is TBD
21+
22+
* `here` and `there` are not yet implicit values. Therefore you would need
23+
to write things like `@{gui(there)}:` instead of `@gui`
24+
25+
* Local values and variables in scripts need both be typed and initialized.
26+
E.g., `val b=true` is not accepted yet; instead write `val b:Boolean = true`
27+
28+
* The "?" syntax for actual output parameters, actual constrained parameters and
29+
actual adapting parameters is not yet handled. For the time being use
30+
alternative notations. E.g.,
31+
32+
```
33+
p? ==> ActualOutputParameter (p, (v:Int)=>p=v)
34+
p?if?(cond) ==> ActualConstrainedParameter(p, (v:Int)=>p=v, (v:Int)=>cond)
35+
p?? ==> ActualAdaptingParameter (_p)
36+
Note the underscore in the latter line.
37+
```
38+
39+
* The compiler may crash on values in a script expression for which
40+
no implicit conversion to a script exist.
41+
This may for instance happen if you specify `x` in a script
42+
expression to denote an event that the `x` key is pressed, and if you forgot
43+
to provide an implicit script `key(c:Char)`
44+
45+
##Part I. The repository layout
46+
Follows the file layout of the Scala repository. Files marked with a † are not
47+
part of the repository but are either automatically generated by the
48+
build script or user-created if needed. This is not a complete listing.
49+
50+
```
51+
scala/
52+
build/ Build products output directory for ant.
53+
build.xml The main Ant build script.
54+
dist/ The destination folder for Scala distributions.
55+
docs/ Documentation and sample code.
56+
lib/ Pre-compiled libraries for the build.
57+
scala-compiler.jar The stable reference ('starr') compiler jar
58+
scala-library.jar The stable reference ('starr') library jar
59+
scala-library-src.jar A snapshot of the source used to build starr.
60+
ant/ Support libraries for ant.
61+
pull-binary-libs.sh Pulls binary artifacts from remote repository.
62+
push-binary-libs.sh Pushes new binary artifacts and creates sha.
63+
README.rst The file you are currently reading.
64+
src/ All the source files of Scala.
65+
actors/ The sources of the Actor library.
66+
compiler/ The sources of the Scala compiler.
67+
library/ The sources of the core Scala library.
68+
subscript/ The sources of the core SubScript library.
69+
subscript/examples The sources of SubScript example applications
70+
swing/ The sources of the Swing library.
71+
target/ Build products output directory for sbt.
72+
test/ The Scala test suite.
73+
tools/ Developer utilities.
74+
```
75+
##Building Scala with SABBUS
76+
SABBUS is the name of the Ant build script used to compile Scala. It is mostly
77+
automated and takes care of managing the dependencies.
78+
79+
###Layers
80+
In order to guarantee the bootstrapping of the Scala compiler, SABBUS builds
81+
Scala in layers. Each layer is a complete compiled Scala compiler and library.
82+
A superior layer is always compiled by the layer just below it. Here is a short
83+
description of the four layers that SABBUS uses, from bottom to top:
84+
85+
* starr: the stable reference Scala release which is shared by all the
86+
developers. It is found in the repository as `lib/scala-compiler.jar` and
87+
`lib/scala-library.jar`. Any committable source code must be compiled directly
88+
by starr to guarantee the bootstrapping of the compiler.
89+
90+
* locker: the local reference which is compiled by starr and is the work
91+
compiler in a typical development cycle. When it has been built once, it is
92+
“frozen” in this state. Updating it to fit the current source code must be
93+
explicitly requested (see below).
94+
95+
* quick: the layer which is incrementally built when testing changes in the
96+
compiler or library. This is considered an actual new version when locker is
97+
up-to-date in relation to the source code.
98+
99+
* strap: a test layer used to check stability of the build.
100+
101+
Note: the file `subscript.swing.Scripts` uses the SubScript syntax and can
102+
therefore not be compiled with the starr compiler; it needs to be compiled
103+
with the locker compiler or quick compiler.
104+
105+
SubScript examples are not built with the usual ant targets.
106+
107+
###Dependent Changes
108+
SABBUS compiles, for each layer, the Scala library first and the compiler next.
109+
That means that any changes in the library can immediately be used in the
110+
compiler without an intermediate build. On the other hand, if building the
111+
library requires changes in the compiler, a new locker must be built if
112+
bootstrapping is still possible, or a new starr if it is not.
113+
114+
###Requirements for SABBUS
115+
The Scala build system is based on Apache Ant. Most required pre-compiled
116+
libraries are part of the repository (in `lib/`). The following however is
117+
assumed to be installed on the build machine:
118+
119+
* A Java runtime environment (JRE) or SDK 1.6 or above.
120+
* Apache Ant version 1.7.0 or above.
121+
* bash (via cygwin for windows)
122+
* curl
123+
124+
125+
##Common use-cases
126+
* `./pull-binary-libs.sh`
127+
128+
Downloads all binary artifacts associated with this commit. This requires
129+
internet access to http://typesafe.artifactoryonline.com/typesafe.
130+
131+
* `ant -p`
132+
133+
Prints out information about the commonly used ant targets. The interested
134+
developer can find the rest in the XML files.
135+
136+
* `ant` or `ant build`
137+
138+
A quick compilation (to quick) of your changes using the locker compiler.
139+
140+
* This will rebuild all quick if locker changed.
141+
* This will also rebuild locker if starr changed.
142+
143+
* `ln -s build/quick/bin qbin` (once):
144+
* `ant && qbin/scalac -d sandbox sandbox/test.scala && qbin/scala -cp sandbox Test`
145+
146+
Incrementally builds quick, and then uses it to compile and run the file
147+
`sandbox/test.scala`. This is a typical debug cycle.
148+
149+
* `ant quick.subscript.examples`
150+
151+
Builds the SubScript example applications.
152+
153+
* `ant replacelocker`
154+
155+
"unfreezes" locker by updating it to match the current source code.
156+
157+
* This will delete quick so as not to mix classes compiled with different
158+
versions of locker.
159+
160+
* `ant test`
161+
162+
Tests that your code is working and fit to be committed.
163+
164+
* Runs the test suite and bootstrapping test on quick.
165+
* You can run the suite only (skipping strap) with `ant test.suite`.
166+
167+
* `ant docs`
168+
Generates the HTML documentation for the library from the sources using the
169+
scaladoc tool in quick. Note: on most machines this requires more heap than
170+
is allocate by default. You can adjust the parameters with ANT_OPTS.
171+
Example command line::
172+
`ANT_OPTS="-Xms512M -Xmx2048M -Xss1M -XX:MaxPermSize=128M" ant docs`
173+
174+
* `ant dist`
175+
176+
Builds a distribution.
177+
178+
* Rebuilds locker from scratch (to make sure it bootstraps).
179+
* Builds everything twice more and compares bit-to-bit the two builds (to
180+
make sure it is stable).
181+
* Runs the test suite (and refuses to build a distribution if it fails).
182+
* Creates a local distribution in 'dists/latest'.
183+
184+
* `ant clean`
185+
186+
Removes all temporary build files (locker is preserved).
187+
188+
* `ant locker.clean`
189+
190+
Removes all build files.
191+
192+
* `ant all.clean`
193+
194+
Removes all build files (including locker) and all distributions.
195+
196+
Many of these targets offer a variant which runs with `-optimise` enabled.
197+
Optimized targets include `build-opt`, `test-opt`, `dist-opt`, `fastdist-opt`,
198+
`replacestarr-opt`, `replacelocker-opt`, and `distpack-opt`.
199+
200+
##Contributing to Scala
201+
202+
If you wish to contribute, you can find all of the necessary information on
203+
the official [Scala website](www.scala-lang.org).
204+
205+
Specifically, you can subscribe to the Scala mailing lists, read all of the
206+
available documentation, and browse the live github repository. You can contact
207+
the Scala team by sending us a message on one of the mailing lists, or by using
208+
the available contact form.
209+
210+
In detail:
211+
212+
* [Scala website](http://www.scala-lang.org) (links to everything else):
213+
214+
* [Scala documentation](http://docs.scala-lang.org)
215+
216+
* [Scala mailing lists](http://www.scala-lang.org/node/199)
217+
218+
* [Scala bug and issue tracker](https://issues.scala-lang.org)
219+
220+
* [Scala live git source tree](http://github.com/scala/scala)
221+
222+
* [Contact form](http://www.scala-lang.org/node/188)
223+
224+
225+
If you are interested in contributing code, we ask you to complete and submit
226+
to us the Scala Contributor License Agreement, which allows us to ensure that
227+
all code submitted to the project is unencumbered by copyrights or patents.
228+
The form is available at:
229+
[http://www.scala-lang.org/sites/default/files/contributor_agreement.pdf](http://www.scala-lang.org/sites/default/files/contributor_agreement.pdf)
230+
231+
Before submitting a pull-request, please make sure you have followed the guidelines
232+
outlined in our [Pull Request Policy](https://github.com/scala/scala/wiki/Pull-Request-Policy>).
233+
234+
##Contributing to SubScript
235+
236+
Contributors are welcome. The official SubScript website is: [www.subscript-lang.org](www.subscript-lang.org).
237+
238+
As of writing there are no mailing lists, and bug and issue trackers.
239+
240+
Thank you!
241+
242+
The Scala Team + The SubScript Team

0 commit comments

Comments
 (0)