Most of you have heard by now that ColdFusion MX templates are compiled into Java. Some may wonder what the big deal is.

Many more of you may be surprised to learn that you can precompile CFMX templates. Do you know why you might want to? And if you've known previously about how to precompile CFMX templates, did you find that trying to do so with code outside the default\coldfusionmx\wwwroot directory (or \inetpub\wwwroot for IIS users) was troublesome?

I've got the solution to that problem as well. First, some background to bring everyone up to speed on the subject of compilation and precompilation in CFMX.

CFMX Templates Are Compiled
One of the great new benefits of ColdFusion MX is that, because it's built on an underlying Java platform, our ColdFusion templates are actually compiled into Java classes. They're not really executables, though, and they're not self-sufficient programs that can run on any Java (or even J2EE) platform, but the compilation takes place nonetheless.

Unlike in Java and many other languages, however, this compilation takes place automatically. Just as with previous releases of ColdFusion, you can create or edit your templates, and ColdFusion simply runs them as soon as they're changed. (Actually, JSP templates in the J2EE world work the same way.)

You needn't really concern yourself with the mechanisms of automatic compilation. It works without your doing anything. So why this article?

The Onetime Cost of Compilation to a User
Each of these features, the automatic compilation and the automatic detection of code changes, is a two-edged sword. There's the cost borne by the first user to execute a page after it's been created or edited. The request for that Web page will be delayed for a few seconds while CFMX compiles the code the first time. Some find this cause for concern.

The benefit of compiling, of course, is that once this "cost" has been paid by the first user to hit the page, each subsequent page hit is very fast; this is a onetime cost and recurs only if the file is later changed. That compiled code is saved and stored on disk (as a .class file that CF knows how to find and execute), and even if the server is restarted, that previously compiled file will be reused by the server to serve that template. There won't be any more waits for compilation until a developer changes the template again. (Well, almost. More about that in Part 2.)

But what if you deploy a large number of newly created or edited templates in your application? Or what if you frequently change them throughout the day? Then the number of automatic compilations grows. Consider the impact on the first users who hit such changed pages, or the first user hitting your multipage site after you've deployed a number of new templates. That first user may suffer delays on every page as he or she traverses through your site. Ouch.

Anyone who has gone through the ColdFusion Administrator for the first time after installing CFMX will understand the experience. At least that code doesn't change again after CFMX is installed. But you may hit a page some days later that no one else has hit yet, and you'll wait for that compilation then.

First-Time Wait Not Entirely New
Actually, the penalty borne by the first user to run a template after it's created or edited isn't exclusive to CFMX. In CF5 and before, CF also "interpreted" any new or changed CF template, saving the resulting p-code to memory in CF's template cache. But since the process was writing to memory rather than disk, it wasn't quite as noticeable.

Then again, because it wasn't saved to disk, this first-time interpretation had to take place whenever the ColdFusion server was restarted. (The template cache will be discussed further in Part 2.) This need to reinterpret templates on restart led many to complain about the need for real compilation of code to disk.

So compilation is good. But is there anything you can do to avoid the wait by the first executing user? Is this just the price to be paid for the power of automatic compilation?

Precompilation: Avoiding First-User Cost
Part of the answer lies in the question itself. We're relying on the automatic compilation that occurs when the first user runs the template after it's created or edited. What if you could somehow tell ColdFusion to perform that compilation manually? Wouldn't it be useful if there were a command you could issue against your template directory to say "compile all those templates"?

Macromedia didn't provide us with that, and there may be very good reasons (put the conspiracy theories on hold - we're talking about the same compilation that takes place automatically, so protecting intellectual property is not what kept them from offering it).

But a simple three-line batch file has been making the rounds of various mailing lists and blogs (mine included, www.cfmxplus.blogspot.com). The initial version of this batch file seemed to give us the apparent silver bullet we've sought for slaying the first-time delay. The problem was, it only worked for code that was in the default webroot if you followed its original instructions.

I present here a version that does work for CFMX code in any directory. I've also reduced it to just two lines. Simply create a file called precompile.bat with the following lines:

set MX_INSTALL=c:\cfusionmx
%MX_INSTALL%\lib\cfusion.jar coldfusion.tools.Compiler
-webroot %1 -webinf %MX_INSTALL%\wwwroot\WEB-INF %1

Just to be clear, there should be two lines in the file: one starting with "set" and one starting with "%MX_INSTALL%".

Replace the first line's c:\cfusionmx value with the location of the CFMX installation. Again, don't worry if your code isn't stored under the wwwroot in that directory. I'll show in a moment that the batch file will accept a parameter that tells it where your code is actually stored, so you can use this over and over to precompile code in different directories.

Save this file as precompile.bat anywhere on your system. Then, from the DOS command prompt, run it from whatever directory you saved the batch file in. If you're not familiar with getting to the DOS command prompt or running .bat files from a specific directory, please seek help from someone with that knowledge.

Now you can execute it, naming the directory whose files (and subdirectories of files) you want to compile, as in:

precompile c:\cfusionmx\wwwroot\mydir

or

precompile d:\inetpub\wwwroot\somedir

or

precompile d:\myotherdir

That third example demonstrates the compilation of code that isn't stored in the normal webroot. To learn how to be able to access such a directory using the built-in CFMX Web server, see the entry at my blog site, http://cfmxplus.blogspot.com/2002_08_11_ cfmxplus_archive.html#85347963.

The point is, this version of the batch file will compile any directory of CF templates as long as you specify the complete path to the file (see the next section for other differences between this batch file and the one that was passed around the community a couple of months ago).

Again, note that I said it will compile the files in the named directory and any subdirectories. That's useful if you're expecting it, but annoying if you aren't. I haven't figured out how to keep it from recursing through the subdirectories. If anyone has figured that out, please let me know by e-mail or via the online version of this article at the www.sys-con.com/coldfusion Web site.

If the command is successful, you'll see a display (perhaps a lengthy one) indicating that it's compiling each file, one at a time, and reporting how long it takes. It also reports any syntax errors in the code. Very nifty!

It even repeats the list of errors at the end of the display for easy review. Depending on your operating system, you may be able to scroll up and down in the command window to review the results that have scrolled off the page. Of course, the compiler is smart enough not to try to compile anything other than .cfm and .cfc files.

Note that you could use this to precompile all the files in your entire wwwroot (including subdirectories), using the command:

precompile c:\cfusionmx\wwwroot\

as an example, assuming that's where the default webroot is, or on IIS:

precompile c:\inetpub\wwwroot\

Just be aware that this will also ask it to compile such things as the CFDOCS and CFIDE directories that come installed with CFMX. That's over 2,000 files, not counting your own! Use the tool wisely.

And it may be useful to some to be able to compile just a single file, rather than an entire directory and its subdirectories. You can do that, too, as in:

precompile c:\cfusionmx\wwwroot\myfile.cfm

Finally, I haven't been able to get it to accept a pattern, at least not in this simple two-line version of the batch file.

As an aside, you may wonder if the compiler called by the precompile batch file knows to skip files it's already compiled. It doesn't skip them, but you'll notice that as it reports on each template it finds, the compilation time reported will usually be zero seconds for a file that hasn't changed since the last compile.

Indeed, I've learned from Spike Washburn's blog (thanks to a pointer from Dave Watts) that there's an available "-f" directive to force a compilation of the templates even if they've already been compiled once. One possible use for this is when something seems stuck in the way CF is interpreting a template and you want to force a recompile.

You could modify the script to add a -f argument before the -webroot argument. You could also enable it as a parameter to be passed with a few extra lines of batch file code.

Other Versions of precompile.bat
As I mentioned, the batch file I offer above is slightly different from one that was passed around among beta testers and early users of CFMX a couple of months ago. That version used a value for the -webroot directive on the compiler command line (the "java" line) that caused it not to work for compiling code outside the default webroot.

Some learned that they could change that value to point to their desired directory, but then they learned that in order for it to work, they had to go through some more hoops. What was lacking was two things. First, the critical -webinf compiler directive, a hidden gem I learned from Harry Klein of CONTENS Software in Germany.

As my batch file code above shows, it names the path to the wwwroot\WEB-INF directory where CFMX is installed. Without this, if you pointed the -webroot directive at some location other than the default wwwroot, the compiler would fail because it expected to find that WEB-INF directory and several subdirectories of it under the directory you named in the -webroot directive.

Furthermore, I've set the -webroot directive to be whatever directory you pass on the call to the precompile.bat, rather than pointing it at the default webroot. These two things were the missing pieces that kept the previous versions of this precompile.bat file from working against any directory.

I've also changed it so that you must provide the complete path to the directory containing the code you want to compile (whereas the older one worked with relative paths depending on where you placed the precompile.bat file). This makes mine more robust for a few reasons, at the cost of a few extra keystrokes when passing directory names to the precompile batch file.

Readers familiar with batch file variables will notice that I've also set it up to accept only a single argument naming the directory path or file holding the code to be compiled. The older version allowed specification of multiple directories or files. Again, it worked fine with code in the default webroot, but in order to support code in any directory in just two lines, that feature had to be eliminated.

Indeed, you could change it to accept multiple directories, but with the way the batch file is currently written, they'd have to be subdirectories of the first one named, and that's not useful since it already compiles all the subdirectories of any provided. You couldn't name a parent and only one of its children, for instance, since the naming of the parent would already compile all the children.

One other minor change in this version and others offered previously is that I'm prefixing the call to the java interpreter (in the second line of the batch file) with the location within the CFMX install directory where the default Java Virtual Machine is installed. This might prevent some confusion if multiple JVMs are installed.

With more tweaking and some additional DOS commands and conditional tests, the batch file code could be made to provide additional functionality and address some of these issues. I think most will be glad simply to be able to precompile code at all, in more than just the default webroot, and in just two simple lines of code.

Finally, for those working on Solaris and Linux, ColdFusion developer Matt Liotta has offered a version of that batch file as a shell script:

#!/usr/bin/sh

MX_INSTALL=/opt/coldfusionmx
PATH=$MX_INSTALL/runtime/bin:
$PATH
$MX_INSTALL/jre/bin/java -class
path\$CLASSPATH:$MX_INSTALL/
lib/cfusion.jar \coldfusion.
tools.Compiler -webroot $1\
-webinf $MX_INSTALL/wwwroot/
WEB-INF $1

Just to be clear, there should be three lines of code in the file, one starting with "MX_INSTALL", one starting with "PATH", and one starting with "$MX_INSTALL/jre/bin/java".

Again, be sure to change line one to the location where CFMX is installed. Thanks, Matt!

We could stop at this point - and will. The problem of precompiling code is solved. But there will be curious folks (and bit-twiddlers) among you who will want to know more, maybe lots more.

How much time is this really saving? If it's compiled to disk, how and when does CFMX read it into memory to execute it? What's the cost of that? What happens with CF-INCLUDEd files? Where does the compiled code go? Can I look at it? Can I just delete the generated class files instead? How do I determine which class file was generated for which CF template? Can I distribute the compiled code on other servers without the source code? (The answer to the last question, sadly, is no.)

We'll discuss that and the rest of these questions next month. Otherwise, you've got all you need to know to start precompiling code in CFMX.