Note: please check the tools page on the wiki for the latest information on Cappuccino’s tools.

In the third installment of the build tools series we tackle one of the most advanced build tools: “press”. Recall from the overview that “press” is a tool for stripping code and other optimizations. Additionally, it can convert an entire Objective-J application into a single pure JavaScript file, which we’ll see can be useful.

press

The primary goal of “press” is to strip unused code from your application and frameworks and perform other optimizations. It needs to know about the entire application, including your application code and the Cappuccino frameworks, in order to determine the dependencies and remove unused files. It is called with two parameters, the path to your application, and the output directory:

press root_directory output_directory

This will run “press” on your application located at root_directory, and output a similar but smaller version (with unused files stripped) at output_directory.

Additionally, there are several useful options:

• ‐‐main path: The relative path (from root_directory) to the main file (default: ‘main.j’)
• ‐‐frameworks path: The relative path (from root_directory) to the frameworks directory (default: ‘Frameworks’)
• ‐‐png: Run pngcrush on all PNGs (pngcrush must be installed!)
• ‐‐flatten: Flatten all code into a single Application.js file and attempt to add script tag to index.html (useful for Adobe AIR and CDN deployment)
• ‐‐nostrip: Don’t strip any files. Mostly useful for debugging.

‐‐flatten

The most interesting of these options is “‐‐flatten”, which converts your application into a single pure JavaScript file that can be imported with a standard “script” tag. While the Objective-J load system is great in most scenarios, there are currently a few limitations that a pure JavaScript file helps overcome. Namely that the load system doesn’t work in Adobe AIR due to strict security restrictions, and the load system doesn’t work across domains, such as with a CDN, also due to browser security restrictions. By flattening all Objective-J code into a JavaScript file, we can use a standard script tag to load our application, which works cross-domain and in Adobe AIR.

Internals

If you’re interested in how “press” works, read on. It starts by loading your application while noting which global variables are defined in each file. It then “walks” along the dependency “graph”, including every imported file, with one important exception: framework imports like “import <AppKit/AppKit.j>” and “import <Foundation/Foundation.j>” are ignored since these types of imports would result in the entire framework (including unused files) being imported. Instead, press looks at the global dependencies, and only keeps the files that are referenced by any other file that has been imported.

Conclusion

“press” is a already a great tool, but there is much room for improvement. In the future we would like to add finer-granularity code stripping, such as method-level rather than file-level. Additionally, we’re working on an automatic image spriting and optimization feature which determines exactly which images are required for your application and includes them in a single image, vastly reducing the number of HTTP requests to load your application.

Note: please check the tools page on the wiki for the latest information on Cappuccino’s tools.

In our previous post on the Cappuccino build tools we summarized the purpose of four of the tools. In this article we’ll dive deeper into two of them, objjc and steam.

To review, the purpose of these tools is to prepare your application for deployment by pre-compiling all application Objective-J code into JavaScript, thereby reducing the load time for clients. Additionally, since most developers won’t need to modify Cappuccino itself, we always compile Cappuccino’s AppKit and Foundation frameworks to further reduce load time.

The only time you’ll need to run steam (which handles running objjc for you) is when you’re deploying your application, or if you’re making changes to the Cappuccino frameworks themselves. In the latter case, the easiest way to recompile the frameworks is to run the default ant task in the Cappuccino source tree:

cd /path/to/cappuccino
ant

To use the freshly built frameworks simply replace the “Frameworks” directory in your application with a symbolic link to the Release directory in the directory pointed to by your $STEAM_BUILD environment variable:

cd /path/to/your_application
mv Frameworks Frameworks-Original
ln -s $STEAM_BUILD/Release Frameworks

(if you’re loading your project through a webserver like Apache make sure to enable the FollowSymLinks option)

objjc

objjc, the Objective-J compiler, is the most important of the build tools, but you’ll likely never invoke it directly. objj can take any number of parameters as input filenames and output filenames (preceded by the “-o” flag). For example:

objj Class1.j -o Class1.o Class2.j -o Class2.o

This will invoke the Objective-J compiler (which is identical to the one used by Objective-J in the browser) on each input file, outputting JavaScript plus some metadata to each specified output file. Next we need to combine all of these individual output files into a single “.sj” archive that contains the JavaScript and import dependency metadata for the entire framework. It would be possible to do this by hand, but steam takes care of it for you.

steam

steam is the general Cappuccino build tool that manages the creation and compilation of your Cappuccino applications.

To create a basic Cappuccino application, simply run steam with the “create” command:

steam create ApplicationName

This will create a new Cappuccino application in the directory “ApplicationName”. This application can be modified and run (by opening index.html in the browser) without any further usage of the build tools.

When you’re ready to compile the application code for deployment, add a .steam file to your application, like the following:

This file defines the targets and configurations for your project. This one defines a single target, YourApplication, and two configurations, Release and Debug. To compile your application, simply execute steam with the build command, the .steam filename, and the configuration name:

steam build -f MyApp.steam -c Release

If a .steam filename is not provided it will look for a file with the extension “.steam”. Likewise, if a configuration name is not provided, it will use the first one defined in the file. The following will run the “Debug” configuration in your .steam file:

steam build

steam gathers all “.j” files in your application, compiles them, and combines them into a single “.sj” file (“static Objective-J”), along with a new “Info.plist” which tell Objective-J which files are contained in the “.sj”.

The results are placed in a subdirectory of $STEAM_BUILD named the same as the configuration, i.e. Debug or Release. Alternatively, pass the “-b” flag and a build directory to specify where it should be built.

The compiled application or framework can then be used in place of the original uncompiled collection of .j files. If it was an application, copy or symlink your Frameworks directory to it’s directory. If it was a framework, copy it to your application’s Frameworks directory.

Conclusion

This article covered the core Cappuccino build tools, objjc and steam. Remember that you will probably never want to call objjc directly, but rather rely on the “steam build” command to manage the build process for you. Additionally, remember the build process is entirely optional (except if you’re editing the Cappuccino frameworks themselves), and is only necessary as a deploy-time optimization.

In subsequent articles we’ll cover the remaining more advanced build tools, press and bake, as well as further deployment optimizations.

Note: please check the tools page on the wiki for the latest information on Cappuccino’s tools.

This article is a high level overview of the current Cappuccino and Objective-J build tools. Subsequent posts will cover each tool in more detail.

One of our primary design goals with Cappuccino and Objective-J was to keep the simple development cycle web developers are used to: edit your code, save, refresh the browser. At the same time we wanted to add powerful language features to JavaScript without requiring the user install a plugin like Flash or Silverlight. At first glance it seemed like only two of these three requirements could be satisfied simultaneously, until we had the key realization that we could simply write our compiler in JavaScript itself, and perform the compilation at runtime on the client.

In reality the Objective-J “compiler” is more like a preprocessor, performing a relatively simple transformation from Objective-J code to JavaScript code, which is then interpretted by the browser’s native JavaScript engine. We don’t do full parsing and compiling, nor do we have a separate interpreter on top of JavaScript. The result is that the compiler and resulting code run very fast.

This turned out to work great. Simply download the starter package, load index.html in your browser, and start editing away! If you’re just getting started with Objective-J and Cappuccino you don’t even need to worry about the build tools, they’re entirely optional.

When it comes time to deploy your application you may want to optimize it. There’s no reason for your customers to wait any longer than necessary, even if the overhead is minimal. That’s where the build tools come in. Each tool has a specific purpose, and they all work together to produce an optimized Cappuccino application:

• objjc – the Objective-J compiler
• steam – a general tool for managing the build process, creating new Cappuccino applications, etc.
• press – code stripping and other optimizations
• bake – deployment tool

objjc

At the lowest level is “objjc”, the Objective-J compiler. It’s equivalent to gcc or javac, except it converts Objective-J code to JavaScript. Because we can run the same JavaScript code in the browser and Rhino the core of objjc is identical to the in-browser compiler.

Currently objjc’s implementation is closer to a simple preprocessor than a compiler, much like the original Objective-C compiler was implemented as a preprocessor on top of C. The preprocessor simply looks for the few Objective-J syntax additions and replaces it with the raw JavaScript equivalent. A big reason this is possible is that Objective-J is a strict superset of JavaScript, thus all JavaScript code is valid Objective-J code.

Typically you don’t call objjc directly, but rather let steam manage the build process.

steam

Next up is steam, which is the main Objective-J and Cappuccino build tool. Currently it serves two purposes: “steam build” (similar to Xcode’s “xcodebuild”) and “steam create” (similar to Ruby on Rail’s “rails” command).

“steam build” runs the compilation process on an entire application or framework and outputs a single “.sj” file, vastly decreasing the number of HTTP requests required to load an application. These “.sj” files are archives of the compiled input “.j” files, along with information detailing each file’s required imports. This allows the Objective-J loading system to efficiently and asynchronously load a large application.

“steam create” copies all the files required for a new project to the directory specified.

press

The “press” tool takes in a full application and attempts to determine which code files are unecessary. It then strips those files and writes the results to another directory. This could be thought of as a “linker” though it works very differently than a traditional linker. On a simple project it will reduce the AppKit and Foundation frameworks size by approximately 30%, and we expect further improvements.

Optionally, it can run the pngcrush utility on all your png graphics, attempting to reduce their size. Eventually press will also automatically sprite images, further reducing the number of HTTP requests required to load your images.

bake

Finally, we have “bake”, the Cappuccino deployment tool (like “Capistrano” but specialized for Cappuccino applications). Bake orchestrates all the above tools to produce, and optionally deploy, a highly optimized Cappuccino application. First it can pull both Cappuccino and your application code from git, svn, or a local or remote directory via rsync.

It then copies pieces of the various “checkouts” to the “products” directory, first running a build process like “steam” or ant, if specified. For example, it can run steam on your application code, and copy the results to the product directory, then do the same for AppKit and Foundation, copying the results to the Frameworks/AppKit and Frameworks/Foundation directories to build the complete application.

Once an application is assembled, bake can run “press”, optimizing the application’s size.

Then bake sets up a directory structure and index.html file which allows for several important tricks: aggressive caching, keeping the client application in sync with the server backend, and atomic deployments, all while preserving a single user-facing URL for the application.

Finally, the application is archived and gzipped, scp’d to one or more servers, and atomically deployed to the specified path(s).

Conclusion

Cappuccino’s build tools are great at optimizing your deployed application, but there are further web server specific optimizations possible as well, including enabling gzipping and caching. These will be discussed in subsequent articles.