← Back to branch summary

~ubuntu-branches/debian/sid/scala/sid

« back to all changes in this revision

Viewing changes to README

  • Committer: Package Import Robot
  • Author(s): Emmanuel Bourg, Mehdi Dogguy, Lucas Satabin, Frank S. Thomas, Emmanuel Bourg
  • Date: 2015-06-05 23:52:59 UTC
  • mfrom: (1.2.11)
  • Revision ID: package-import@ubuntu.com-20150605235259-wk00vgk83dh8o19g
Tags: 2.10.5-1
http://bugs.debian.org/744278
http://bugs.debian.org/754935
http://bugs.debian.org/724704
* Team upload.

[ Mehdi Dogguy ]
* New upstream release (Closes: #744278).

[ Lucas Satabin ]
* Update patches
* Update the clean target
* Update paths of elements to install
* Update watch file

[ Frank S. Thomas ]
* Remove myself from Uploaders.

[ Emmanuel Bourg ]
* The package has been adopted by the Java Team (Closes: #754935)
* Patched the build to avoid downloading libraries from the Internet
* Replaced the minified JavaScript files with unobfuscated ones
* No longer build scala-partest.jar until diffutils is packaged or replaced
* debian/watch: Fixed the versions matched (x.y.z instead of x.y.z..z)
* debian/rules:
  - Added the missing get-orig-source target (Closes: #724704)
  - Improved the clean target
* debian/control:
  - Build depend on scala (>= 2.10) and bnd
  - Use canonical URLs for the Vcs-* fields
  - Standards-Version updated to 3.9.6 (no changes)
* Switch to debhelper level 9

Show diffs side-by-side

added added

removed removed

Lines of Context:
README
1
 
================================================================================
2
 
                              THE SCALA REPOSITORY
3
 
                           Structure and build system
4
 
================================================================================
5
 
 
6
 
This document describes the Scala core (core library and compiler) repository
7
 
and how to build it. For information about Scala as a language, you can visit
8
 
the web site http://www.scala-lang.org/
9
 
 
10
 
Part I. The repository layout
11
 
--------------------------------------------------------------------------------                            
12
 
 
13
 
Follows the file layout of the Scala repository. Files marked with a † are not
14
 
part of the Subversion repository but are either automatically generated by the
15
 
build script or user-created if needed.  This is not a complete listing.
16
 
 
17
 
scala/
18
 
      bin/                      Developer utilities.
19
 
      build/ †                  Temporary staging area for build products.
20
 
      build.excludes †          An optional build configuration file.
21
 
      build.number              The version number of the current distribution.
22
 
      build.properties †        An optional build configuration file.
23
 
      build.xml                 The main Ant build script.
24
 
      dist/ †                   The destination folder of Scala distributions.
25
 
      docs/                     Documentation of Scala. More in its own module.
26
 
           development/         Developer documentation.
27
 
           examples/            Scala source code examples.
28
 
      lib/                      Pre-compiled libraries for the build.
29
 
          fjbg.jar              The Java byte-code generation library.
30
 
          scala-compiler.jar    The stable reference version (aka 'starr')
31
 
                                of the Scala compiler
32
 
          scala-library.jar     The stable reference version (aka 'starr')
33
 
                                of the Scala library.
34
 
          scala-library-src.jar A snapshot of the source code which was used
35
 
                                to build starr.
36
 
          ant/                  Support libraries for the build tool.
37
 
              ant-contrib.jar   Provides additional features for Ant
38
 
              vizant.jar        Provides DOT graph generation for Ant
39
 
      project/                  All that is needed to use SBT for building
40
 
          boot/ †               SBT storage (for download,...)
41
 
          build/                The class files that defines the build project
42
 
          build.properties      Various SBT project variables
43
 
      README                    The file you are currently reading.
44
 
      sandbox/ †                A folder to test code etc.
45
 
      src/                      All the source files of Scala.
46
 
          actors/               The sources of the Actor library.
47
 
          compiler/             The sources of the Scala compiler.
48
 
          library/              The sources of the core Scala library.
49
 
          swing/                The sources of the Swing library.
50
 
      target/ †                 Temporary staging area for build products from the SBT script.
51
 
      test/                     The Scala test suite.
52
 
 
53
 
Part II. Building Scala with SABBUS
54
 
--------------------------------------------------------------------------------
55
 
 
56
 
SABBUS is the name of the Ant build script used to compile Scala. It is mostly
57
 
automated and takes care of managing the dependencies.
58
 
 
59
 
LAYERS:
60
 
 
61
 
In order to guarantee the bootstrapping of the Scala compiler, SABBUS builds
62
 
Scala in layers. Each layer is a complete compiled Scala compiler and library.
63
 
A superior layer is always compiled by the layer just below it. Here is a short
64
 
description of the four layers that SABBUS uses, from bottom to top:
65
 
 
66
 
'starr': the stable reference Scala release which is shared by all the
67
 
developers. It is found in the repository as 'lib/scala-compiler.jar' and
68
 
'lib/scala-library.jar'. Any committable source code must be compiled directly
69
 
by starr to guarantee the bootstrapping of the compiler.
70
 
 
71
 
'locker': the local reference which is compiled by starr and is the work
72
 
compiler in a typical development cycle. When it has been built once, it is
73
 
“frozen” in this state. Updating it to fit the current source code must be
74
 
explicitly required (see below).
75
 
 
76
 
'quick': the layer which is incrementally built when testing changes in the
77
 
compiler or library. This is considered an actual new version when locker is
78
 
up-to-date in relation to the source code.
79
 
 
80
 
'strap': a test layer used to check stability of the build.
81
 
 
82
 
DEPENDANT CHANGES:
83
 
 
84
 
SABBUS compiles, for each layer, the Scala library first and the compiler next.
85
 
That means that any changes in the library can immediately be used in the
86
 
compiler without an intermediate build. On the other hand, if building the
87
 
library requires changes in the compiler, a new locker must be built if
88
 
bootstrapping is still possible, or a new starr if it is not.
89
 
 
90
 
REQUIREMENTS FOR SABBUS:
91
 
 
92
 
The Scala build system is based on Apache Ant. Most required pre-compiled
93
 
libraries are part of the repository (in 'lib/'). The following however is
94
 
assumed to be installed on the build machine:
95
 
  - A Java runtime environment (JRE) or SDK 1.6 or above.
96
 
  - Apache Ant version 1.7.0 or above.
97
 
 
98
 
 
99
 
Part III. Using SBT as an alternative
100
 
--------------------------------------------------------------------------------
101
 
It is now possible to use SBT as an alternative to build Scala. This is still in beta stage.
102
 
More informations and usage instruction at http://lampsvn.epfl.ch/trac/scala/wiki/SBT 
103
 
 
104
 
Part IV. Common use-cases
105
 
--------------------------------------------------------------------------------
106
 
 
107
 
'ant -p'
108
 
  Prints out information about the commonly used ant targets. The interested
109
 
  developer can find the rest in the XML files.
110
 
 
111
 
'ant' or 'ant build'
112
 
  A quick compilation (to quick) of your changes using the locker compiler.
113
 
    - This will rebuild all quick if locker changed.
114
 
    - This will also rebuild locker if starr changed.
115
 
 
116
 
'ln -s build/quick/bin qbin' (once)
117
 
'ant && qbin/scalac -d sandbox sandbox/test.scala && qbin/scala -cp sandbox Test'
118
 
  Incrementally builds quick, and then uses it to compile and run the file
119
 
  'sandbox/test.scala'. This is a typical debug cycle.
120
 
 
121
 
'ant replacelocker'
122
 
  "unfreezes" locker by updating it to match the current source code.
123
 
    - This will delete quick so as not to mix classes compiled with different
124
 
      versions of locker.
125
 
 
126
 
'ant test'
127
 
  Tests that your code is working and fit to be committed.
128
 
    - Runs the test suite and bootstrapping test on quick.
129
 
    - You can run the suite only (skipping strap) with 'ant test.suite'.
130
 
 
131
 
'ant docs'
132
 
  Generates the HTML documentation for the library from the sources using the
133
 
  scaladoc tool in quick.  Note: on most machines this requires more heap than
134
 
  is allocate by default.  You can adjust the parameters with ANT_OPTS.
135
 
  Example command line:
136
 
    ANT_OPTS="-Xms512M -Xmx2048M -Xss1M -XX:MaxPermSize=128M" ant docs
137
 
 
138
 
'ant dist'
139
 
  Builds a distribution.
140
 
    - Rebuilds locker from scratch (to make sure it bootstraps).
141
 
    - Builds everything twice more and compares bit-to-bit the two builds (to
142
 
      make sure it is stable).
143
 
    - Runs the test suite (and refuses to build a distribution if it fails).
144
 
    - Creates a local distribution in 'dists/latest'.
145
 
 
146
 
'ant clean'
147
 
  Removes all temporary build files (locker is preserved).
148
 
 
149
 
'ant locker.clean'
150
 
  Removes all build files.
151
 
 
152
 
'ant all.clean'
153
 
  Removes all build files (including locker) and all distributions.
154
 
 
155
 
Many of these targets offer a variant which runs with -optimise enabled.
156
 
Optimized targets include build-opt, test-opt, dist-opt, fastdist-opt,
157
 
replacestarr-opt, replacelocker-opt, and distpack-opt.
158
 
 
159
 
Part V. Contributing to Scala
160
 
--------------------------------------------------------------------------------
161
 
 
162
 
If you wish to contribute, you can find all of the necessary information on
163
 
the official Scala website: www.scala-lang.org.
164
 
 
165
 
Specifically, you can subscribe to the Scala mailing lists, read all of the
166
 
available documentation, and browse the live SVN repository.  You can contact
167
 
the Scala team by sending us a message on one of the mailing lists, or by using
168
 
the available contact form.
169
 
 
170
 
In detail:
171
 
 
172
 
- Scala website (links to everything else):
173
 
  http://www.scala-lang.org
174
 
 
175
 
- Scala documentation:
176
 
  http://www.scala-lang.org/node/197
177
 
 
178
 
- Scala mailing lists:
179
 
  http://www.scala-lang.org/node/199
180
 
 
181
 
- Scala Trac bug and issue tracker:
182
 
  https://lampsvn.epfl.ch/trac/scala
183
 
 
184
 
- Scala live SVN source tree:
185
 
  http://www.scala-lang.org/node/213
186
 
 
187
 
- Building Scala from the source code:
188
 
  http://www.scala-lang.org/node/217
189
 
 
190
 
- Contact form:
191
 
  http://www.scala-lang.org/node/188
192
 
 
193
 
 
194
 
If you are interested in contributing code, we ask you to complete and submit
195
 
to us the Scala Contributor License Agreement, which allows us to ensure that
196
 
all code submitted to the project is unencumbered by copyrights or patents.
197
 
The form is available at:
198
 
http://www.scala-lang.org/sites/default/files/contributor_agreement.pdf
199
 
 
200
 
Thank you!
201
 
The Scala Team
202