You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: contribute/hacker-guide.md
+29-76Lines changed: 29 additions & 76 deletions
Original file line number
Diff line number
Diff line change
@@ -100,47 +100,25 @@ If you are new to Git and branching, read the [Branching Chapter](http://git-scm
100
100
101
101
The next step after cloning your fork is setting up your machine to build Scala.
102
102
103
-
* It is recommended to use Java `1.6` (not `1.7` or `1.8`, because they might cause occasional glitches).
104
-
* The build tool is `ant`. If you are behind a HTTP proxy, include [`ANT_ARGS=-autoproxy`](https://ant.apache.org/manual/proxy.html) in your environment.
105
-
* The build runs the `pull-binary-libs.sh` script to download bootstrap libs. This requires `bash` and `curl`.
106
-
* The majority of our team works on Linux and OS X, so these operating systems are guaranteed to work.
107
-
* Windows is supported, but it might have issues. Please report to [the issue tracker](https://issues.scala-lang.org/) if you encounter any.
103
+
You need the following tools:
108
104
109
-
Building Scala is as easy as running `ant` in the root of your cloned repository. Be prepared to wait for a while-- a full "clean" build
110
-
takes 8+ minutes depending on your machine (and up to 30 minutes on older machines with less memory). Incremental builds are usually within 30-120 seconds range (again, your mileage might vary
[mkdir] Created dir: /Users/xeno_by/Projects/scala/build/pack/bin
105
+
* A Java SDK. The baseline version is 6 for 2.11.x and 8 for 2.12.x. It's possible to use a later SDK for local development, but the continuous integration builds will verify against the baseline version.
106
+
*`sbt`, an interactive build tool commonly used in Scala projects. Acquiring sbt manually is not necessary -- the recommended approach is to download the [sbt-extras runner script](https://github.com/paulp/sbt-extras/blob/master/sbt) and use it in place of `sbt`. The script will download and run the correct version of sbt when run from the Scala repository's root directory.
107
+
*`curl` -- the build uses `curl` in the `pull-binary-libs.sh` script to download bootstrap libs.
130
108
131
-
pack.done:
109
+
The majority of our team works on Linux and OS X, so these operating systems are guaranteed to work. Windows is supported, but it might have issues. Please report to [the issue tracker](https://issues.scala-lang.org/) if you encounter any.
132
110
133
-
build:
134
-
135
-
BUILD SUCCESSFUL
136
-
Total time: 9 minutes 41 seconds
111
+
Building Scala is as easy as running `sbt dist/mkPack` in the root of your cloned repository. Be prepared to wait for a while -- a full "clean" build
112
+
takes 8+ minutes depending on your machine (and up to 30 minutes on older machines with less memory). Incremental builds are usually within 30-120 seconds range (again, your mileage might vary
113
+
with your hardware).
137
114
138
115
### IDE
139
116
140
117
There's no single editor of choice for working with Scala sources, as there are trade-offs associated with each available tool.
141
118
142
119
Both Eclipse and IntelliJ IDEA have Scala plugins, which are known to work with our codebase.
143
-
Both of those Scala plugins provide navigation, refactoring and error reporting functionality as well as integrated debugging.
120
+
Both of those Scala plugins provide navigation, refactoring, error reporting functionality, and integrated debugging.
121
+
See [the Scala README](https://github.com/scala/scala#ide-setup) for instructions on using Eclipse and IntelliJ IDEA with the Scala repository.
144
122
145
123
There also exist lighter-weight editors such as Emacs, Sublime or jEdit which are faster and much less memory/compute-intensive to run, while
146
124
lacking semantic services and debugging. To address this shortcoming, they can integrate with ENSIME,
@@ -155,8 +133,8 @@ When hacking on your topic of choice, you'll be modifying Scala, compiling it an
155
133
Typically you would want to first make sure that your changes work on a small example and afterwards verify that nothing break
156
134
by running a comprehensive test suite.
157
135
158
-
We'll start by creating a `sandbox` directory (this particular name doesn't bear any special meaning), which will hold a single test file and its compilation results. First, let's make sure that
159
-
[the bug](https://issues.scala-lang.org/browse/SI-6725) is indeed reproducible by putting together a simple test and compiling and running it with the Scala compiler that we built using `ant`. The Scala compiler that we just built is located in `build/pack/bin`.
136
+
We'll start by creating a `sandbox` directory (`./sandbox is listed in the .gitignore of the Scala repository), which will hold a single test file and its compilation results. First, let's make sure that
137
+
[the bug](https://issues.scala-lang.org/browse/SI-6725) is indeed reproducible by putting together a simple test and compiling and running it with the Scala compiler that we built using `sbt`. The Scala compiler that we just built is located in `build/pack/bin`.
@@ -178,31 +156,24 @@ Now, implement your bugfix or new feature!
178
156
Here are also some tips & tricks that have proven useful in Scala development:
179
157
180
158
* If after introducing changes or updating your clone, you get `AbstractMethodError` or other linkage exceptions,
181
-
try doing `ant clean build`. Due to the way how Scala compiles traits, if a trait changes, then it's sometimes not enough to recompile
182
-
just that trait, but it might also be necessary to recompile its users. The `ant` tool is not smart enough to do that, which might lead to
183
-
very strange errors. Full-rebuilds fix the problem. Fortunately that's rarely necessary, because full-rebuilds take a lot of time-- the same 8-30 minutes as mentioned above.
159
+
try doing `sbt clean`. Due to the way Scala compiles traits, if a trait changes, then it's sometimes not enough to recompile
160
+
just that trait; it might also be necessary to recompile its users. The `sbt` tool is not smart enough to do that, which might lead to
161
+
very strange errors. Fullrebuilds fix the problem. Fortunately that's rarely necessary, because fullrebuilds take a lot of time-- the same 8-30 minutes as mentioned above.
184
162
* Even on solid state drives packaging Scala distribution (i.e. creating jars from class files) is a non-trivial task. To save time here,
185
-
some people in our team do `ant quick.comp` instead of `ant` and then create custom scripts ([here](https://github.com/adriaanm/binfu/blob/master/scafu.sh) are some examples to get you started) to launch Scala from `build/quick/classes`.
163
+
some people in our team do `sbt compile` instead of `sbt dist/mkPack` and then create custom scripts using `sbt/mkBin` to launch Scala from `./build/quick/bin`. Also see [the Scala README](https://github.com/scala/scala#incremental-compilation) for tips on speeding up compile times.
186
164
* Don't underestimate the power of `print`. When starting with Scala, I spent a lot of time in the debugger trying to figure out how
187
165
things work. However later I found out that print-based debugging is often more effective than jumping around. While it might be obvious
188
-
to some, I'd like to explicitly mention that it's also useful to print stack traces to understand the flow of execution. When working with `Trees`, you might want to use `showRaw` to get the `AST` representation.
189
-
* You can publish your newly-built scala version locally to use it from sbt. Here's how:
166
+
to some, I'd like to explicitly mention that it's also useful to print stack traces to understand the flow of execution. When working with `Trees`, you might want to use the Scala `showRaw` to get the `AST` representation.
167
+
* You can publish your newly-built scala version locally using `sbt publishLocal`to use it from `sbt`. Here's how:
190
168
191
-
$ ant publish-local-opt -Dmaven.version.suffix="-test"
169
+
$ sbt publishLocal // This may take a while
170
+
...
192
171
$ sbt
193
-
[info] Set current project to test (in build file:/Users/georgii/workspace/test/)
194
-
> set resolvers += Resolver.mavenLocal
195
-
[info] Defining *:resolvers
196
-
[info] The new value will be used by *:externalResolvers
197
-
[info] Reapplying settings...
198
-
[info] Set current project to test (in build file:/Users/georgii/workspace/test/)
199
-
> ++2.12.0-test
200
-
[info] Setting version to 2.12.0-test
201
-
[info] Set current project to test (in build file:/Users/georgii/workspace/test/)
172
+
...
202
173
> console
203
174
[info] Starting scala interpreter...
204
-
[info]
205
-
Welcome to Scala version 2.12.0-20140623-155543-8bdacad317 (Java HotSpot(TM) 64-Bit Server VM, Java 1.7.0_51).
175
+
[info]
176
+
Welcome to Scala version 2.10.6 (OpenJDK 64-Bit Server VM, Java 1.8.0_91).
206
177
Type in expressions to have them evaluated.
207
178
Type :help for more information.
208
179
@@ -212,7 +183,7 @@ Here are also some tips & tricks that have proven useful in Scala development:
212
183
213
184
### Documentation
214
185
215
-
There are several areas that one could contribute to-- there is the Scala library, the Scala compiler, and other tools such as Scaladoc. Each area has varying amounts of documentation.
186
+
There are several areas that one could contribute to-- there is the Scala library, the Scala compiler, and other tools such as Scaladoc. Each area has varying amounts of documentation.
216
187
217
188
##### The Scala Library
218
189
@@ -263,22 +234,12 @@ but not tokens like `%n`. Looks like an easy fix.
263
234
start = idx + 1
264
235
}
265
236
266
-
After applying the fix and running `ant`, our simple test case in `sandbox/Test.scala` started working!
237
+
After applying the fix and running `sbt compile`, our simple test case in `sandbox/Test.scala` started working!
267
238
268
239
18:51 ~/Projects/scala/sandbox (ticket/6725)$ cd ..
Build step 'Execute shell' marked build as failure
342
-
Archiving artifacts
343
-
Notifying upstream projects of job completion
296
+
...
344
297
Finished: FAILURE
345
298
346
299
This means your change is backward or forward binary incompatible with the specified version (the check is performed by the [migration manager](https://github.com/typesafehub/migration-manager)). The error message is actually saying what you need to add to `bincompat-backward.whitelist.conf` or `bincompat-forward.whitelist.conf` to make the error go away. If you are getting this on an internal/experimental api, it should be safe to add suggested sections to the config. Otherwise, you might want to target a newer version of scala for this change.
@@ -349,7 +302,7 @@ This means your change is backward or forward binary incompatible with the speci
349
302
350
303
Now to make sure that my fix doesn't break anything I need to run the test suite using the `partest` tool we wrote to test Scala.
351
304
Read up [the partest guide](partest-guide.html) to learn the details about partest, but in a nutshell you can either
352
-
run `ant test` to go through the entire test suite (30+ minutes) or use wildcards to limit the tests to something manageable:
305
+
run `sbt test` to go through the entire test suite (30+ minutes) or use wildcards to limit the tests to something manageable:
353
306
354
307
18:52 ~/Projects/scala/sandbox (ticket/6725)$ cd ../test
0 commit comments