Typesafe Activator, What *is* it? (and why should I care?)
A curious thing. At training events, hackathons and any chance I get I have started asking people what they think of Activator. There are a range of different answers, usually followed by questions once the subject has been broached.
The questions are varied, but over a large enough sample size, surprisingly consistent. It seems that Activator is a fairly misunderstood tool, and it’s not just me who noticed. This blog post will attempt to address those frequently asked questions and even if it doesn’t convince you that Activator is your new best friend, at least you might consider keeping it in your toolbox.
There’s a lot of detail in this post and hopefully you find it valuable. If you want the TL;DR version instead, here goes:
- Activator is built upon sbt and can do everything that sbt can do, plus more.
- The UI part of Activator is a very minor part of the overall tool and you don’t have to use it at all.
- Activator New is a fast way to create new Scala projects from a range of different templates and start building them immediately.
- It keeps itself up to date automatically.
- It replaces the Play command in the Play Framework (which was also a wrapper around sbt).
- It comes in a choice of two zip files: a 350 megabyte one with all dependencies bundled, and a 1 megabyte one that downloads dependencies lazily when they are needed.
- UI mode might be useful even to advanced users if you need to grok a new library or concept quickly.
- The Inspect functionality (also in the UI mode) lets you track Play requests, actor inboxes, and actor issues.
On to the FAQ:
Activator? That’s just for n00bs, right?
My first response to that is “So what do you think about sbt? Is that just for n00bs?”. The quicker folks guess quickly that this is a leading question, but the immediate response is almost always “sbt, oh no - that’s a real tool” or something along those lines. Some people think sbt is unfamiliar or hard, but no one makes the comment that it is just for n00bs.
Thing is, at its core Activator is a superset of sbt, as in, if you type a command into sbt you can use that same command in Activator. The build configuration files are the same (just the sbt files, plugins, etc.). There are the same useful tools: console, runMain, test, etc. You can run Activator on a command line only basis just like sbt. You can start an interactive shell, use tilde commands (~testQuick will run tests, wait for source file changes, and then re-run affected tests automatically) and so on.
OK - so why would I not just use sbt then?
Well you could, sbt has a wealth of functionality. Activator has all that, plus it has two more tricks up its sleeve at present (and more to come in the future).
Activator’s ui command is the first one, and the one most people know about. It fires up a web based GUI that you can use for a couple of things, but mostly for tutorials right now (and this is likely where Activator has obtained it’s n00bs only reputation). It’s a shame, because percentage wise the UI is a tiny (albeit useful) part of Activator, both in terms of bits and overall functionality. Being a species with a strong visual bias however, it’s not surprising that the visual part is what people have latched on to first about Activator.
The other command is new (by which I mean it’s not a new command but that the command is “new”). This is immediately useful to anyone who wants to create a new project. It doesn’t do anything you can’t do yourself when creating a new project, but it does it a heck of a lot quicker.
Activator new will create a new Scala (or Java) project from a selection of templates, including basics like minimal-java and minimal-scala. It will create the standard directory layout, build files, and so on. How quick is it - here’s what you have to type to get something started (dialog ommitted for brevity)?
$ activator new
$ cd quick-start
$ activator test
Voila - new Scala project ready to go (minimal-scala is number 2 in the list). You can also see a list of all the template choices by hitting tab when prompted. If you just want to see akka project templates, type akka<tab> and it will list anything with a name starting akka, and include all of the dependencies needed for akka and whatever else is in the project template. There are both examples that you can adapt to your needs, and seed templates that are intended to be used as a starting point for new projects.
Activator new is pretty nice, but I need a little more convincing…
How about Activator keeping itself up to date? Every time you run Activator (assuming you have a working network connection) Activator will check for updates and grab the latest bits if necessary. Activator is still very much a work in progress, even though it already does more than both sbt and Play, and you will see new features appearing over time (and not that much time, there are some very exciting new things coming down the pipe soon).
If you are worried that the updates will cause build problems, those fears can also be allayed. The version of sbt to use for the build can (and should) be specified in project/build.properties like this:
and an “Activator new” will set the version for your new project automatically so it won’t change for that project. If you do want a newer one, you should change this property.
What happened to Play? How come all I see there is an Activator download now?
Just like Activator, the Play command was an extension to sbt that made it easy to create new projects, specifically Play projects. Since Play offered a very limited set of new template options (options 3 and 4 in Activator new), and the functionality has been superseded by Activator which offers many more templates, both Play targeted and otherwise, the old Play wrapper was replaced by Activator.
If you really miss the Play command, stick this in your ~/.bashrc file (or equivalent shell file):
While you are at it, I recommend the following extra alias (it’s what I use, obviously skip this if you already have an “act” command that you use):
I don’t have many gripes about Activator, but one of them is that build tools should under no circumstances, ever, take more than three letters to invoke from the command line. Just look at all the greats out there: ant, mvn, sbt, make (OK, well that’s why I don’t use make any more :-) ). Activator can now join their lazy ranks with a simple shell alias.
OK - so Activator is the new Play, but it’s a huge download now. Why are you making me download all this UI stuff if I won’t use it? Grrrr
The full download of Activator is pretty big, yes, but have you ever noticed that the first thing that happens when you type “sbt compile” on a project, the first thing it does is download half of the internet (project dependencies).
Downloading the full package of Activator includes the most common dependencies in that download, meaning less downloading on the first “Activator compile” command. There will probably be some downloading still, but not as much. It’s an ideal package if you are running a hackathon or some other event and want to distribute something on a USB drive that will help save your network from an internal DDOS attack when everyone builds the first time.
And as for the UI - it’s a couple of megs of that whole download, a small percentage compared to the other dependencies in there.
Of course, there are still assumptions made in that big package about what you might want to run, and you might know better. In that case, just do what I do and grab the “mini-package” (1 meg ish) from the link right under the big download button on https://typesafe.com/platform/getstarted. That little link surprises a lot of people when I point it out. 1 Meg is a pretty quick download, but remember you aren’t getting anything for free here, the first time you run Activator it’s going to go and grab some of the dependencies that would have been included in the big bundle. However, if you never run “Activator ui”, it will save you that couple of megs of ui download.
Is there anything different between the activator and Play commands?
Other than the lack of a cute ASCII art Play banner when you start up the shell, I can only think of one thing I have noticed. The way you run Activator in remote debug mode is different than with the old Play wrapper. The good news is that remote debugging is now consistent for all Activator projects.
Running with remote debugging enabled in Activator:
activator -jvm-debug 9999 run (or runMain, etc.)
9999 is the port upon which the remote debugging connection monitor will allow debugging connections, then you just have to use your favorite IDE or debugging tool to connect a remote debugging session to that port.
So you are saying that if I am not a n00b, Activator might still be for me, but just ignore the ui stuff?
Well, kind of, but not exactly. While Activator is certainly a power user’s tool as well (as demonstrated by Josh Suereth in this excellent SBT in Action talk in which Josh uses Activator throughout the presentation), and while you can happily use Activator without ever touching the ui part of it, there are a couple of reasons you still might consider using Activator ui anyway.
Unless you know everything about everything (and my goodness, what a boring existence that would be), there are going to be some times you want to learn new stuff (yayyyy, learning).
There are plans to make the Activator ui useful for more than just tutorials and getting started, but right now it is quite good at those two activities, and there are a growing number of useful tutorials out there already. Despite having used Scala in all sorts of different places over the past 5 years or so, I still find myself in unfamiliar territory with it all the time.
A recent example is that I had to use oauth2 to connect to a ReST API. This was harder than it sounds (I am really not a web guy) and the tutorials out there were all over the place, contradictory and often without code examples.
This is where I now look for an Activator tutorial first. The way I look at them is as compile-checked executable examples with documentation that allow experimentation and can even be used to customize into your own project. In other words, the ideal solution to the problem of understanding a topic and getting something working in it as quickly as possible.
Unfortunately I didn’t find an Activator template for oauth2. Instead, James Ward and I got an example working against github and turned it into an Activator template so that now others can benefit from that too. The code can be used with or without the ui, but the tutorial covers the other, non-coding steps necessary to get the API keys set up and other matters. Running Activator ui is just a convenient, fast way to examine the code, follow the setup steps, and even links to points in the code that explain how the oauth2 process works. By the time you read this blog, the oauth2 template should be listed in the Activator templates.
It’s currently mostly for tutorials, but more is functionality is coming soon and it already has an extra feature that few people know about yet.
The Inspect feature in the UI lets you monitor Play requests and akka actors. It’s early days right now but you can use the inspect features to see incoming URL requests, the size of actor inboxes and maximum time to process messages — which can help you track down bottlenecks in your actor system (if the maximum time keeps going up on an actor, it’s likely to be a bottleneck in your system). There is also a log of actor issues which shows messages sent to dead letters and exceptional events like that.
Hopefully this article has demonstrated that Activator is not just a tutorial delivery mechanism, but a real, power tool with lots of useful functionality. That said, it’s just the start, with more being added all the time (and some really cool new stuff coming soon). For now, it’s the most functionality you can get in the Scala ecosystem for under a megabyte download (OK, so that’s cheating a little, but the command does work after that megabyte download :-) ). Stay tuned for more info on Activator as we update it.