Building a dictionary

The build process involves creating a dictionary from scratch, based on the source files in the repository. Building a dictionary is typically performed by one person, and is done each time you create a production version of your dictionary.

The build process

A typical build process includes the following steps:

  1. Create an empty dictionary.

You must create a “clean” dictionary that will contain the resources read from the repository. This can be done either with Dexterity or from the command line. The following command will start Dexterity and create a new “clean” dictionary named RESM.DIC.

dex.exe /nc RESM.DIC
  1. Perform an update operation.

The update operation will retrieve source files from the repository and import them into your dictionary. Typically, you will be retrieving the latest version of each source file. However, if you label your source files, you can easily build versions of your dictionary based on the labels you’ve used in the repository.

When you perform the update operation, be sure that you use the index file. This ensures that resource IDs are used consistently in the dictionary.

  1. Update the index file.

After the new dictionary has been successfully built, be sure to update the index file. The updated index file will contain entries for any new resources that were added to this build of the dictionary.

  1. Label the source files in the repository (optional).

After the dictionary has been built, we recommend that you label all of the source files that were used to create the dictionary. This allows you to re-create this dictionary at any time simply by performing an update operation based on the label you supplied.

Automating the build process

Typically, you will want to perform the build process at a time when no developers are making changes to source files in the repository. Automating the build process allows it to be performed at any time, such as overnight, when no changes are being made to the repository.

The most basic automation of the build process involves creating a .BAT file that creates a new dictionary and runs a “build macro”. The build macro is a Dexterity macro that performs the update process that builds the dictionary.

The following is a build macro that performs an update from the currently selected repository into an empty dictionary. The most recent (tip) version of each source file is used for the update.

[spacer]

Macro

Build.mac 


# DEXVERSION=DEX 6.00
Logging file 'macro.log'
CheckActiveWin dictionary 'default'  form ResourceExplorer window ResourceExplorer 
  MenuSelect title Explorer entry 'Update...' 
NewActiveWin dictionary 'default'  form SCCUpdate window Update 
  ClickHit field '(L) RG_ModifiedResource' item 1  # 'Always Overwrite' 
  MoveTo field '(L) RG_Update' item 0  # 'Update Newer' 
  ClickHit field '(L) RG_Update' item 1  # 'Update All' 
  MoveTo field '(L) CB_IndexFile' 
  ClickHit field '(L) CB_IndexFile' 
  MoveTo field '(L) PB_Update' 
  ClickHit field '(L) PB_Update' 
NewActiveWin dictionary 'default'  form ResourceExplorer window ResourceExplorer 
NewActiveWin dictionary 'default'  form ResourceExplorer window ResourceExplorer 
NewActiveWin dictionary 'default'  form ResourceExplorer window ResourceExplorer 
NewActiveWin dictionary 'default'  form 'Script_Debug_Res' window CompileDebugInfo 
NewActiveWin dictionary 'default'  form ResourceExplorer window ResourceExplorer

This macro was created by recording the user actions necessary to perform the update process. Notice the second line of the macro. It was added using a text editor such as Notepad. This line prevents any message displayed by the macro, such as the total running time, from being displayed on the screen. Instead, all messages generated by the macro will be written to the MACRO.LOG file.

To use this build macro to perform a build, start Dexterity from the command line, create a new “clean” dictionary, and then run the build macro. The following is a batch file that will start Dexterity, create a new dictionary named RESM.DIC, and execute the macro named Build.mac.

dex.exe /nc RESM.DIC Build.mac

To further automate the process you could have the build macro update the index file. If you were using Visual SourceSafe as your source code control provider, you could also add the following line to the batch file to label the source files used to for the build:

ss Label $/RESM -L6.0b1 "-CBuild 6.0b1"

This adds the label “6.0b1” and the comment “Build 6.0b1” to the latest version of each source file in the RESM project. Be sure that the SS.EXE application is in your path, that you have the “Add” access right that allows you to use the Label command.

Documentation Feedback