The Programming Scala code examples and what breaks when the compiler moves

One repository, two branches, and a frozen copy of the book

The repository contains all the code examples in O'Reilly's Programming Scala, Third Edition, and the project description also mentions the second and third editions. The author notes that there are many code files in the distribution that are not included in the book, so the repository is larger than the printed text.

The branch layout is the first thing to understand. The main branch and the 3.X.Y tag releases are for the third edition, and the code examples for the second edition are still available, either by downloading the release tagged 2.1.0 or by checking out the release-2.1.0 branch. The second edition was published for Scala 2.11, and the latest 2.1.0 release and the release-2.1.0 branch are updated for 2.12 and 2.13, with no more release-2.X.Y releases planned.

The main branch, by contrast, is not frozen. The README carries a warning that Scala 3 is evolving, as are the tools that support it, and that the author tries to keep the main branch up to date with the latest versions, including changing the examples as required to handle new and changed features, with a reference to issue #131 as an example of that kind of change. The consequence it names is that sometimes an example, or how to run it, will be different from what you see in the book.

So there are two reading experiences available, and the README tells you how to choose. If you are reading the book and want the examples exactly as they appear there, with the same tool versions used at that time, you grab the 3.0.0-final release.

The primary language is Scala, the default branch is main, the repository is not archived, and the last push was on 2026-10-18. There are no GitHub releases listed for the project itself, and the licence is recorded as one GitHub cannot classify, with the terms in the LICENSE file.

The scala command line gained a required flag in 3.5.0

The README spends a lot of its attention on one specific breakage, and it is worth reading in full because it is the concrete reason the frozen tag exists.

At the top of page 12 of the book, the command shown for running a program at the shell prompt is:

$ cp="target/scala-3.0.0/classes/"
$ scala -classpath $cp progscala3.introscala.Hello2 Hello Scala World!

As of version 3.5.0 the way you run a scala command line program changed. The newer form is:

$ cp="target/out/jvm/scala-3.8.4/programming-scala-3rd-ed-code-examples/classes"
$ scala -classpath $cp --main-class progscala3.introscala.Hello2 -- Hello Scala World!

Two things changed. The output path for compiled files changed, from a target/scala-3.0.0/classes directory to a target/out/jvm/scala-3.8.4 layout with the project name in the path, and the class to run now has to be named explicitly with a required --main-class, or -M, flag, with a -- separating the scala command arguments from your program's arguments. The README's instruction is to change all other command-line examples in the book the same way.

What did not change is sbt syntax when using runMain at the sbt prompt, so the book form still works:

runMain progscala3.introscala.Hello2 Hello Scala World!

That asymmetry is the useful detail. The sbt path is stable across the compiler change, and the raw scala command path is not, which is a reasonable argument for using sbt for the examples even though the book shows the direct command.

Path comments are the index into the source tree

The mechanism that connects the printed book to the repository is a comment convention, and it is the single most useful thing in the README for a reader.

In the book's text, when an example corresponds to a file in the repository, the listing begins with a path in a comment of this form:

// src/main/scala/progscala3.introscala.UpperMain1

Following the usual conventions, tests are in src/test, and the repository also contains MUnit and ScalaCheck unit tests to validate some of the code. So the book gives you a path and the repository gives you the file, and the two are the same thing.

The naming conventions exist because the repository mixes kinds of Scala files that cannot all be built the same way, and it uses four prefixes to keep them apart. The src/main/scala/.../*.scala files are all Scala 3 source files built with sbt. The src/test/.../*.scala files are all Scala 3 test source files built and executed with sbt. The src/script/.../*.scala files are script files that will not compile with scalac but can be interpreted with the scala REPL or used as a worksheet. And the src/*/scala-2/.../*.scala files are some Scala 2 source files that will not compile with Scala 3, and they are not built with sbt.

That last category is the one to think about. The third edition is a Scala 3 book, but the repository still carries a set of Scala 2 sources that are deliberately excluded from the build, which means the compiled artefacts cover the Scala 3 code and the Scala 2 leftovers are source-only.

The scripts are the interactive part. The examples include scripts intended for interactive use in the scala command line REPL, for example using sbt console, and sbt is described as the de facto build tool for Scala that the author uses.

Comment markers control what appears in the book

The repository uses asciidoc-style region markers to select which parts of a file appear in the printed text, and the README explains the convention in one short section.

You will not find many comments in the code, except of the form // <1>, which get converted into markers corresponding to notes in the book. The stated reason is that all the descriptions of the code are in the book, so they are not repeated as code comments. That is a design decision with a practical effect: the source files are terse, and a reader who only has the repository will not find the explanation inline.

The region markers look like this:

// tag::section1[]
// end::section1[]

They mark sections that are selectively included in the book. Sometimes the whole file is included in sections, and other times the file has extra bonus content that does not appear in the book at all. So the repository is a superset of the book, and the markers are how the book selects from it.

That design is what makes the repository usable as more than a companion download. With the markers in place, the same source tree can be turned into the book listings mechanically, which is why the file headers exist at all, and why they are in the form of a path rather than a file name: the path is a stable identifier that both the text and the reader can use to find the file.

Building needs a JDK and sbt, and sbt bootstraps the rest

The tools section is short and the requirement is short. To build and run the examples, all you need is a recent version of the Java SDK and sbt. When you run sbt, it will bootstrap itself with the correct version of itself, Scala, and the project dependencies, which are specified in the build.sbt file in the root directory and other build files in the project directory.

That last sentence is the useful one. The Scala version used by the examples is not something you configure, it comes from the build definition, and sbt fetches it. So the toolchain requirement is deliberately low, a JDK and sbt, and everything else is pinned by the repository.

Installing Scala separately, and the Scaladocs, is optional, and the README points at the scala-lang.org getting started guide for that, noting that it is not required.

There is one optional extra, and it is a good example of how a book example is scoped. If you want to play with the Spark example, the file src/script/scala-2/progscala3/bigdata/SparkWordCount.scala, you need to download a Spark distribution from spark.apache.org. Assuming that $SPARK_HOME refers to the root directory of your Spark installation, the command to start the Scala REPL with Spark enabled, run in the root directory of the repository, is:

$ $SPARK_HOME/bin/spark-shell
...
scala>

Note the file path. It lives under src/script and under scala-2, which means it is in both of the categories the conventions describe as not built by sbt, and it is a script interpreted in the REPL rather than a compiled unit. That is why it needs a Spark installation and an interactive shell instead of the normal build.

The helper scripts in the repository root

The top level of the repository contains a set of shell scripts that are not mentioned in the README, and their names describe what a maintainer of this kind of repository actually has to do.

There is check-head-comment.sh, which by its name checks the head comment convention that the README documents, and check-mains.sh and check-scripts.sh, which by their names check the two categories of runnable files, the ones with a main method and the interactive scripts. There is inline-perf.sh, which suggests a mechanism for running performance examples inline, and make-worksheets.sh, which fits the repository's mention of worksheets as a way to use the script files.

There is also a misc directory, a project directory for the sbt build files, and a src directory for the sources. A .gitignore is present, as is the LICENSE file.

None of this is documented in the README, and that is a fair criticism of the project for a newcomer. The scripts are the maintenance infrastructure of a book repository: they keep the examples consistent with the conventions, and they exist because the conventions need enforcing as the Scala versions change underneath them.

For a reader, the practical advice is that these scripts are for the maintainer, not for you. You clone, you pick a tag or the main branch, and you run sbt.

Where this repository is the wrong place to look

The first wrong case is expecting a library. This is book source code. There is no published artifact, no API surface to depend on, and the code is organised to be read in the order a book presents it rather than to be imported. If you want a Scala utility library, this is the wrong repository, and the second edition's release tags are definitely the wrong place to look for one.

The second wrong case is a second edition reader who wants current tooling. The 2.1.0 release and the release-2.1.0 branch are updated for Scala 2.12 and 2.13, and no more release-2.X.Y releases are planned. So the second edition line is in maintenance, not development, and the third edition line is where the current Scala 3 work happens. A reader on the older book should use the older branch and accept that it is not being updated for new tools.

The third wrong case is expecting the code to match the book by default. This is the one the README warns about most directly. On the main branch, an example or how to run it will sometimes differ from what the book shows, because the author is continuously adapting the examples to new compiler behaviour. If you are trying to reconcile a line in the book with a file in the repository and they disagree, the likely explanation is that you are on main and the book is not.

The alternative worth naming is the book itself, or the official Scala documentation and example code, and the difference in approach is that the book is a narrative that happens to contain compilable code, while a documentation example set is organised by topic. The book's advantage is that the examples are chosen to make a point, so the awkward ones are the ones that illustrate something. The repository's advantage over a book is that it runs. What it cannot do is stay in sync with a printed edition while the language moves, which is exactly why the frozen 3.0.0-final tag exists, and why a reader who cares about matching the text should use it rather than the branch.

Release tags, licence and who maintains the examples

The release history of the repository is the Scala release history. Recent tags include 3.8.1 on 2026-02-04, described as a Scala 3.8.1 compatible release, 3.8.4 on 2026-06-27, described as Scala 3.8.4 and SBT 2.0.0 support, and 3.9.0 on 2026-09-05, named for Scala 3.9.0.

So the tags track the Scala version, not the book edition, and each one is a point at which the examples were verified against a specific compiler and toolchain combination. That is the granularity you want when you are reporting a problem with an example, because it identifies the toolchain that produced the failure.

The author is Dean Wampler, and the README links his book page at programming-scala.org, his blog about Scala 3, the repository discussions, and his social accounts. The maintainership is personal rather than institutional, which is a factor worth weighing for a repository that is effectively the companion code for a book: the continuity of the examples depends on one person keeping them in step with the compiler, and the 3.0.0-final tag and the 2.1.0 branch show what happens when that effort is deliberately frozen.

The licence is the one thing you should read directly. The project metadata lists it as a custom licence that GitHub cannot classify, and the terms are in the LICENSE file at the root. For a repository of example code that people copy into their own projects, which is exactly what this one is for, the terms are worth reading rather than assuming.

The project also carries a Scala Steward badge, which is the mechanism where a maintainer registers as a steward for a dependency so that version bumps are tracked for them. For a repository whose entire purpose is to track Scala version bumps, that is a small but telling detail.

Editorial conclusion

The repository fits a reader working through Programming Scala who wants the code that matches the book exactly, and it fits a developer who wants idiomatic Scala 3 examples that track the current compiler. It is the wrong choice if you need a maintained library of Scala utilities, because this is book source code rather than a published package, and it is the wrong choice if you are on the second edition toolchain unless you check out the 2.1.0 release. Before you run anything, read the warning about the Scala 3.5.0 command line change, and pick either the frozen 3.0.0-final tag or the main branch deliberately rather than drifting into one.

Frequently asked questions

Official sources

1. deanwampler/programming-scala-book-code-examples on GitHub
2. Issues
3. README
4. Releases