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:
- The process of
coding functionality into a program or solution
- 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:
- If it's not
already visible, open the Solution Explorer by choosing
View>Solution Explorer.
- Locate and
highlight the customization project you want to set the build properties for.
The sample project from our previous lesson was called
MiniJournalist.
- 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