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
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
|
################################################################################
NOTICE
################################################################################
The legacy/msil branch records the state of master at the point when
msil was removed. It is not under active development.
################################################################################
THE SCALA REPOSITORY
################################################################################
This document describes the Scala core (core library and compiler) repository
and how to build it. For information about Scala as a language, you can visit
the web site http://www.scala-lang.org/
Part I. The repository layout
--------------------------------------------------------------------------------
Follows the file layout of the Scala repository. Files marked with a † are not
part of the repository but are either automatically generated by the
build script or user-created if needed. This is not a complete listing. ::
scala/
+--build/ Build products output directory for ant.
+--build.xml The main Ant build script.
+--dist/ The destination folder for Scala distributions.
+--docs/ Documentation and sample code.
+--lib/ Pre-compiled libraries for the build.
| +--fjbg.jar The Java byte-code generation library.
| +--scala-compiler.jar The stable reference ('starr') compiler jar
| +--scala-library.jar The stable reference ('starr') library jar
| +--scala-library-src.jar A snapshot of the source used to build starr.
| ---ant/ Support libraries for ant.
+--pull-binary-libs.sh Pulls binary artifacts from remote repository.
+--push-binary-libs.sh Pushes new binary artifacts and creates sha.
+--README.rst The file you are currently reading.
+--src/ All the source files of Scala.
| +--actors/ The sources of the Actor library.
| +--compiler/ The sources of the Scala compiler.
| +--library/ The sources of the core Scala library.
| ---swing/ The sources of the Swing library.
+--target/ † Build products output directory for sbt.
+--test/ The Scala test suite.
---tools/ Developer utilities.
Part II. Building Scala with SABBUS
--------------------------------------------------------------------------------
SABBUS is the name of the Ant build script used to compile Scala. It is mostly
automated and takes care of managing the dependencies.
^^^^^^^^^^^^^^^^^^^^^^^^
LAYERS:
^^^^^^^^^^^^^^^^^^^^^^^^
In order to guarantee the bootstrapping of the Scala compiler, SABBUS builds
Scala in layers. Each layer is a complete compiled Scala compiler and library.
A superior layer is always compiled by the layer just below it. Here is a short
description of the four layers that SABBUS uses, from bottom to top:
- ``starr``: the stable reference Scala release which is shared by all the
developers. It is found in the repository as 'lib/scala-compiler.jar' and
'lib/scala-library.jar'. Any committable source code must be compiled directly
by starr to guarantee the bootstrapping of the compiler.
- ``locker``: the local reference which is compiled by starr and is the work
compiler in a typical development cycle. When it has been built once, it is
“frozen” in this state. Updating it to fit the current source code must be
explicitly requested (see below).
- ``quick``: the layer which is incrementally built when testing changes in the
compiler or library. This is considered an actual new version when locker is
up-to-date in relation to the source code.
- ``strap``: a test layer used to check stability of the build.
^^^^^^^^^^^^^^^^^^^^^^^^
DEPENDANT CHANGES:
^^^^^^^^^^^^^^^^^^^^^^^^
SABBUS compiles, for each layer, the Scala library first and the compiler next.
That means that any changes in the library can immediately be used in the
compiler without an intermediate build. On the other hand, if building the
library requires changes in the compiler, a new locker must be built if
bootstrapping is still possible, or a new starr if it is not.
^^^^^^^^^^^^^^^^^^^^^^^^
REQUIREMENTS FOR SABBUS:
^^^^^^^^^^^^^^^^^^^^^^^^
The Scala build system is based on Apache Ant. Most required pre-compiled
libraries are part of the repository (in 'lib/'). The following however is
assumed to be installed on the build machine:
- A Java runtime environment (JRE) or SDK 1.6 or above.
- Apache Ant version 1.7.0 or above.
- bash (via cygwin for windows)
- curl
Part III. Common use-cases
--------------------------------------------------------------------------------
- ``./pull-binary-libs.sh``
Downloads all binary artifacts associated with this commit. This requires
internet access to http://typesafe.artifactoryonline.com/typesafe.
- ``ant -p``
Prints out information about the commonly used ant targets. The interested
developer can find the rest in the XML files.
- ``ant`` or ``ant build``
A quick compilation (to quick) of your changes using the locker compiler.
- This will rebuild all quick if locker changed.
- This will also rebuild locker if starr changed.
- ``ln -s build/quick/bin qbin`` (once):
- ``ant && qbin/scalac -d sandbox sandbox/test.scala && qbin/scala -cp sandbox Test``
Incrementally builds quick, and then uses it to compile and run the file
``sandbox/test.scala``. This is a typical debug cycle.
- ``ant replacelocker``
"unfreezes" locker by updating it to match the current source code.
- This will delete quick so as not to mix classes compiled with different
versions of locker.
- ``ant test``
Tests that your code is working and fit to be committed.
- Runs the test suite and bootstrapping test on quick.
- You can run the suite only (skipping strap) with 'ant test.suite'.
- ``ant docs``
Generates the HTML documentation for the library from the sources using the
scaladoc tool in quick. Note: on most machines this requires more heap than
is allocate by default. You can adjust the parameters with ANT_OPTS.
Example command line::
ANT_OPTS="-Xms512M -Xmx2048M -Xss1M -XX:MaxPermSize=128M" ant docs
- ``ant dist``
Builds a distribution.
- Rebuilds locker from scratch (to make sure it bootstraps).
- Builds everything twice more and compares bit-to-bit the two builds (to
make sure it is stable).
- Runs the test suite (and refuses to build a distribution if it fails).
- Creates a local distribution in 'dists/latest'.
- ``ant clean``
Removes all temporary build files (locker is preserved).
- ``ant locker.clean``
Removes all build files.
- ``ant all.clean``
Removes all build files (including locker) and all distributions.
Many of these targets offer a variant which runs with -optimise enabled.
Optimized targets include build-opt, test-opt, dist-opt, fastdist-opt,
replacestarr-opt, replacelocker-opt, and distpack-opt.
Part IV. Contributing to Scala
--------------------------------------------------------------------------------
If you wish to contribute, you can find all of the necessary information on
the official Scala website: www.scala-lang.org.
Specifically, you can subscribe to the Scala mailing lists, read all of the
available documentation, and browse the live github repository. You can contact
the Scala team by sending us a message on one of the mailing lists, or by using
the available contact form.
In detail:
- Scala website (links to everything else):
http://www.scala-lang.org
- Scala documentation:
http://docs.scala-lang.org
- Scala mailing lists:
http://www.scala-lang.org/node/199
- Scala bug and issue tracker:
https://issues.scala-lang.org
- Scala live git source tree:
http://github.com/scala/scala
- Contact form:
http://www.scala-lang.org/node/188
If you are interested in contributing code, we ask you to complete and submit
to us the Scala Contributor License Agreement, which allows us to ensure that
all code submitted to the project is unencumbered by copyrights or patents.
The form is available at:
http://www.scala-lang.org/sites/default/files/contributor_agreement.pdf
Before submitting a pull-request, please make sure you have followed the guidelines
outlined in our `Pull Request Policy <https://github.com/scala/scala/wiki/Pull-Request-Policy>`_.
------------------
Thank you!
The Scala Team
|
