A Caché of tips: Class Compilation
Emily Haggstrom
This tip will cover class compilation and the options available to you. Most people have a particular set of flags that they use and a particular method of kicking off the compilation, but there is actually a wealth of choices out there that can be beneficial in certain situations.
First, let’s take a look at what the class compiler does.
- It checks dependencies. Any classes that are referred to in property types or method signatures are compiled if they haven’t been already.
- It resolves inheritance. Any members of super classes are either added to the class code, or information on how to find them is. Many methods no longer need to be written into the compiled code of a subclass.
- It generates tables for persistent classes.
- It compiles classes into .int and .mvi routines.
- It compiles routines into .obj code.
Whenever you call a method of a class this .obj code is what is actually executed.
There are two main ways to kick off a compilation
- In Studio through the Build menu
- Programmatically using $SYSTEM.OBJ->Compile() and related methods
It’s important to note that the result you get may be different between these two methods since Studio sessions tend to have a different set of compilation flags set, and some options that are available through the command line are not available through Studio.
In Studio, you can modify your compilation options by going to Tools->Options… and selecting Compiler. In the 2012.2 version, there are three checkboxes on this page:
- Keep generated source code
o This determines whether the compiled .int and .mvi routines are preserved on the server. This can be very helpful for debugging applications, but it may be disabled on stable production systems where space is a concern.
- Compile dependent classes
o This determines whether to add subclasses of the current class to the compile list. This is not usually necessary, but it can be a good idea if you are making signature changes to a super class that could cause problems for a subclass.
- Skip related up-to-date documents
o This tells the compiler whether to skip related classes that have not been marked as modified. This can greatly decrease compilation time. Occasionally updates to a super class or related class can cause problems for a class without marking it as modified, so it’s a good idea to uncheck this option if you’re running into unexpected errors.
These options correspond to the compilation flags k, b, and u respectively. As you check and uncheck the boxes you will see these flags added and removed from the Flags box below. You can also edit this box directly to add flags or qualifiers not represented by the checkboxes.
To get a complete list of all of the options available to you when compiling, you can use these two methods:
$SYSTEM.OBJ->ShowFlags()
$SYSTEM.OBJ->ShowQualifiers()
Show flags will give you a summary of the one letter flags you can apply to compilation and other functions. Bear in mind not all of these apply to compilation. For instance, the i flag means “Validate XML export format against schema on Load.” This does not apply to compilation. This flag comes into play when you are importing XML data. However, most of these options are related to compilation in some way.
Show qualifiers contains a more complete listing of compilation and other options. All of the flags are also represented by a qualifier word, but you will notice some of the qualifiers do not have corresponding flags. This method will also show you what the defaults are on your system. These defaults will be used in $SYSTEM.OBJ->Compile(classname) with no parameters, but they will be overridden by the Studio settings when compiled through Studio.
It’s important to review these options on your current version of Cache, since most major releases come with some changes to the compiler. You’ll see on the ShowFlags() list that a number of the flags are now deprecated. Do a search in the documentation for “Class Compilation” and you will see entries in the Upgrade Checklists detailing the differences between each of the versions.
Here are some resources that may be helpful when dealing with compilation issues:
This section explains the various steps involved in the compilation process that I’ve covered briefly here.
This section describes some of the key flags and qualifiers, and how to set up system-wide defaults.
Any time you see an error message in brackets like this <> you can find details about it on this page. If this doesn’t give you enough information to determine the source of the problem, give the WRC a call at 617-621-0700. Not only will we help you figure it out, but we might improve the documentation, too.
Until next time,
Emily