The Working Programmer - Getting Started with Oak

By Ted Neward | October 2013

Ted Neward It’s interesting, sometimes, to look at the changes that have occurred within our industry over the past 50 years. A college graduate in 1960 could, quite reasonably, have gotten a job as a programmer and, across the breadth of her career, watched her job go from filling out punch cards to programming a machine the size of a room with a whopping 4K of active memory (and no online storage); seen the rise of programming languages such as COBOL on mainframes, and then minicomputers such as the IBM PC; experienced changes in UI technology such as the GUI; watched the laptop become the standard computer of choice; witnessed the “birth” of the Internet and the Web—and eventually retire right about the time that tablets and mobile devices are becoming the consumer computing devices of choice.

But it’s also equally true that changes occur within certain pockets of the industry, and the same kinds of “revolutions” take place within a smaller circle of technology or domain. One such swiftly changing circle of technology is that of the ubiquitous Web site: from Common Gateway Interface (CGI) scripts written in Perl or C; to Web server extensions such as ISAPI; to “page-oriented” tools such as ASP; to more powerful underpinnings behind those page-oriented tools (ASP.NET, backed by the CLR instead of native code); and so on. Increasingly, the approach of choice for these tools is moving away from “statically typed” languages, such as C#, to more “dynamically typed” languages, such as Ruby or Python. Debates rage, however, over the severity of penalties to programming with a dynamic language (wherein the compiler can’t catch common mistakes) and how they trade off against the overhead (the compilation process and having to work with or around the type system) of a static language. These debates have yet to yield an overwhelming “winner,” and as a result, some developers are starting to look at ways to take the best of both worlds.

Oak, an open source project from Amir Rajan (Twitter: @amirrajan; Web: amirrajan.net), is one such attempt to leverage the dynamic capabilities inherent within C# (via the “dynamic” keyword/type and the Dynamic Language Runtime, or DLR, both introduced in Visual Studio 2010) and gain the productivity benefits of a system such as Ruby on Rails, but keep it all in a language (C#) that offers static type checking and verification.

Setting Up

Oak is available as a NuGet package, but one thing that developers coming to Oak must understand is that, before all other things, Oak is more of a development lifestyle approach than “just” a library. Oak will take a different approach to building applications from what the traditional ASP.NET MVC developer may be used to. For example, emphasis on extremely rapid feedback will mean Oak wants to be continuously building in the background (or at least appear to be), such that simply saving the .cs file will be enough to view the results in the browser—no explicit “build” step should be necessary. (How Oak accomplishes this actually isn’t rocket science, as you’ll see.) The end result of Oak development will be a “traditional” ASP.NET application, so the operations guys will never know you built it differently from how you used to, fortunately.

Tooling

Part of this lifestyle adjustment is that Oak isn’t just a NuGet download, but also requires the use of some other tools, which must be installed on your machine in order to get started. IIS Express is one such tool, which many Microsoft .NET Framework developers will already have if they’ve experimented with Visual Studio LightSwitch at all. Another such tool is Ruby, which is used in some of the build automation and tooling. Again, Ruby won’t be needed on the production servers once development is done, but you’ll need it to get started and to develop in Oak. As of this writing, Ruby just released version 2.0, but the 1.9 release works just as well (and, for my money, gives me more comfort that I won’t run into a weird 2.0 bug that nobody else has ever seen). Finally, as part of its rapid, interactive style, Oak wants to be able to flash messages at you from the continuous compilation system in the background, so Oak wants Growl for Windows, a notification system that will pop little messages to you onto the desktop (such as MSN Messenger used to) when events happen—such as a successful or unsuccessful build in the background. (I’ll explore the Growl API in a later column, by the way, because it’s a useful tool to have in your back pocket.)

Once those are installed, there’s one more step Oak requires: The Ruby scripts it uses need some packages available through the Ruby package manager, gem. (Ruby gem was, by the way, much of the inspiration for NuGet and other language package managers such as Node npm and Haskell Cabal.) Fire up a command prompt with Ruby on the PATH, and fire off this command from the command line:

C:\Projects\Exploration\Oak\Blog>gem install warmup

The warmup gem (bit.ly/15e51Lx) is actually how you’ll get an Oak project started—it will pull down a template containing all the major moving parts Oak requires.

You can tell already that this is a long way away from the “File | New | Project” with which you’re probably familiar.

Starting Oak

Getting a new Oak project up and running consists of using the warmup gem from the command line to pull down the seed template from its home online, like so:

C:\Projects\Exploration\Oak\Blog>warmup https://github.com/amirrajan/loam Blog

This seed project, once it’s pulled down to your machine, contains a bare-bones “weblog” implementation (and I put weblog in quotes because if this can be called a weblog, then my NBA basketball aspirations are alive and well, despite the fact that I can’t dribble, shoot or dunk). Once the disk stops spinning, open the downloaded Blog.sln Visual Studio Solution file (so you have the comfortable Visual Studio environment in front of you). Then, from the command line in which you issued the warmup command, run these two commands:

C:\Projects\Exploration\Oak\Blog>rake
C:\Projects\Exploration\Oak\Blog>rake server

Rake is the Ruby “build” tool, in much the same way that “make” was the C/C++ build tool for so many years; it will issue a sequence of steps according to a target. The first command will build the solution, and the second will tell Rake to deploy the code to the IIS Express directory and start IIS Express. Port 3000 (by default) will now be ready to accept incoming HTTP requests.

If you’re curious to see the complete list of targets that the Rakefile supports, call “rake -T,” and you’ll see the command-line output shown in Figure 1. (Note: A much longer, complete listing of targets is available with “rake -D,” for those who want to see the full help text for each task.)

Figure 1 List of Supported Rakefile Targets from the Command Line

C:\Projects\Exploration\Oak\Blog>rake -T
rake build                  # builds the solution
rake default                # builds and deploys website to directories iis...
rake deploy                 # deploys MVC app to directory that iis express...
rake export                 # if you have the nuget package oak installed, ...
rake reset                  # if you have the nuget package oak installed, ...
rake sample                 # if you have the nuget package oak installed, ...
rake server                 # start iis express for MVC app
rake simulate_load_balance  # simulate the web application as if it were lo...
rake stop_nginx             # stops nginx
rake sync[file]             # synchronizes a file specfied to the website d...
rake tests                  # run nspec tests
rake ui                     # run ui automation tests
rake ui_tests               # runs ui tests (without building)

Once IIS Express is up and running, kick off the continuous-build tool, sidekick:

C:\Projects\Exploration\Oak\Blog>sidekick

Sidekick is actually a batch file that uses the command-line C# compiler to compile a small .exe program (sidekickapp.exe) that will set up a file-system watcher to see when files in the directory tree change, and—if they are source files—trigger an MSBuild to recompile the project. (Glenn Block’s recent experiments with Roslyn to create a C# REPL environment, ScriptCS, could also be used to accomplish the same thing, most likely.)

A quick aside before I go further: Notice in Figure 1 how Rake offers an option to run “rake simulate_load_balance.” This is—exactly as its name implies—a simulation of how the application will behave behind a simple round-robin load balancer, so you can test your application (and, specifically, how the application state will behave) in a load-balanced environment without having to fiddle around with virtual machines (VMs), load-balancer hardware or software, and IIS. It’s a nifty little add-on to the whole project that almost justifies learning Oak entirely by itself.

At this point, Oak is up and running—and you can open a browser to localhost:3000 to prove it, as shown in Figure 2.

Figure 2 Browsing to localhost:3000 to Ensure Oak Is Running

Don’t stress about what Oak is telling you right now—that will be what I start exploring next. For now, it’s enough to ensure that Oak is up and running.

Troubleshooting

If that doesn’t work, it might be that Rake doesn’t know where your IIS Express is expecting Web sites to reside; the Rakefile that Oak sets up uses a configuration file, dev.yml, to know where to install the ASP.NET-compiled files. In that file (in the same directory as the Blog.sln file), set the following lines to match what’s on your system:

website_port: 3000
website_deploy_directory: c:\Prg\iisexpress\Blog
solution_name: Blog # just the name, no .sln extension
mvc_project: Blog # just the folder name,
  no .csproj extension
test_project: Blog.Tests # just the folder name,
  no .csproj extension
iis_express: C:\Program Files\IIS Express

On 64-bit systems, for example, IIS Express will be installed in “C:\Program Files (x86)\IIS Express.”

More to Explore

There’s a great deal of Oak yet to explore—in fact, the title of this article probably should’ve been “Acorn,” given that this is the necessary seed from which the rest of the framework (and article series) will be born. Oak’s got a lot yet to show you, starting with its integration into traditional ASP.NET MVC development structure (controllers, views and models), and carrying through into its database interactions. Plus, you have yet to see what all this additional tooling (Ruby and Growl) buys you. Hang out for a while longer—the real fun begins next time.

Happy coding!

Ted Neward is the principal of Neward & Associates LLC. He has written more than 100 articles and authored and coauthored a dozen books, including “Professional F# 2.0” (Wrox, 2010). He’s an F# MVP and speaks at conferences around the world. He consults and mentors regularly—reach him at ted@tedneward.com if you’re interested in having him come work with your team, or read his blog at blogs.tedneward.com.

Thanks to the following technical expert for reviewing this article: Amir Rajan (Oak project creator)