Building an XMetaL Customization
Understanding the XMetaL Build Process
In this lesson, you'll learn how to build an XMetal customization.
This lesson assumes you are familiar with the Visual Studio .NET Build functions and with best practices for source control. If not, please refer to the VS .NET online documentation before continuing.
The term "build" as used in the field of software development refers to two types of developer activities:
  1. The process of coding functionality into a program or solution
  2. The process of assembling the components of a project into an executable software tool.
For now, we'll focus on the second meaning - and leave the coding to you!
This lesson will take about 20 minutes to complete.
Configuring the Build Environment
Before building or testing your project for the first time, you must configure the build environment.
Build configurations provide a way to identify the components you want to build and exclude those you don't want to build. They also determine how the projects selected will be assembled and deployed.
Two levels of build configurations can be defined in Visual Studio .NET: solution build configurations, and project build configurations. For now, let's just configure the project build.
To configure your project build environment:
  1. If it's not already visible, open the Solution Explorer by choosing View>Solution Explorer.
  2. Locate and highlight the customization project you want to set the build properties for. The sample project from our previous lesson was called MiniJournalist.
  3. Right-click the project name, and from the pop-up menu, choose Properties. This opens the Property Pages window for this project.
You'll see a screen similar to the one below:
Setting General Properties
On the left side of the Property Pages window, you'll see the Configuration Properties tree view pane. When you click on any heading in the tree view, associated properties appear in the main view.
Click General. The only general property you can change is the Output Directory.
The output directory is the destination folder for customization files. The build process either compiles them and writes them to this folder, or just copies them to there from elsewhere in the project. If you don't specify an output directory, XMetaL creates a default directory called "\BuildProject".
For now, just type the name of a new, empty directory into the Output Directory field, and we'll move to setting other configuration properties.
NOTE: Do not store any unrelated files in the Output Directory. Some operations may delete these files permanently.
Setting the Command Property
Now click the Debugging heading. You'll see the Command, Command Arguments, and Working Directory properties in the main view.
The Command property is the call to the application you'll use to test your customization. The Working Directory property indicates the folder in which this application opens.
If you have selected XMetaL Author from the Configuration drop-down list, the default setting for the Command property is the latest version of XMetaL Author you have installed.
If you have selected XMetaL for ActiveX in the Configuration option menu, there is no default setting, so you'll have to specify it. You'll also need to indicate the container application that instantiates the XMetaL for ActiveX control, or if it's a Web page, the path to your local installation of Internet Explorer.
After you've set the Command property, identify the working directory in the Working Directory property field.
Setting the Command Arguments
The second property under the Debugging heading is the Command Arguments property.
If you have selected XMetaL Author from the Configuration drop-down list, the Command Arguments property should be the name of one or more XML documents based on your customization.
For instance, if all authors using this customization will be working on a single catalog XML document, you would name this document in this property.
NOTE: If you plan to open a document in XMetaL Author from the command line, surround the document path and name in quotation marks (""). XMetaL Author does not properly parse file paths or names containing spaces.
If you have chosen XMetaL for ActiveX in the Configuration drop-down list, and your customization has XMetaL for ActiveX embedded in an HTML page, this property should be set to the HTML page that contains the embedded XMetaL for ActiveX object.
If you have selected XMetaL for ActiveX from the Configuration drop-down list and you have a container application that instantiates XMetaL for ActiveX, command arguments will of course only have effect if your container application accepts command line arguments.
Setting the Post-Build Properties
Now click the Build heading in the Property Pages tree view. You'll see the Command, Description, and Exclude from Build properties in the main view.
The Post Build subheading allows you to set properties of the application or batch file to launch after testing of your customization is complete.
A typical post-build application might be a batch file moving objects to target folders or to an application for viewing debugging information.
The Command property is the call to the post-build application or batch file, plus any required command line arguments.
The Description property is just the descriptive text that Visual Studio .NET displays when running the post-build application.
When you've finished setting all configuration properties, click OK.
Building the Output
Now that we've configured everything, let's build the solution.
Close the Property Pages window, and Right-click the project name. In our ongoing example, the project name is "Minijournalist".
On the shortcut menu, there are three build-related options: Build, Rebuild, and Clean.
Build will affect only those files that have changed since last build.
Rebuild will build all files in the current customization, whether they have changed or not.
Clean removes all output files from this customization from the output directory.
For now, let's choose the Build option. You'll see the build executing and the Description property being displayed in the Output pane.
Viewing the Build Output
Now let's look at the build output.
Go to the directory you identified in the Output Directory property, and look for a file with the suffix ".xac". The XAC file is a compressed file containing customization objects. Think of it as a "zipped" file including all of your customization files.
Now go back for a moment to Solution Explorer, right-click on the project name, and choose Clean from the shortcut menu. Clean will clean out all output files from the designated output directory.
Return to the output directory, and look inside.
In Summary...
By setting a few build configurations, you can create an efficient development workflow that makes repeated building and testing easy.
In our next lesson, we'll take a look at setting up an XMetaL customization file.
Go to the next lesson: Setting Element Properties in a Customization...
Last modified: Thursday, May 20, 2004 1:16:01 PM