The RadASM/HLA Integrated Development Environment
Integrated Development Environments
An integrated development environment (IDE) traditionally incorporates a text editor, a compiler/assembler, a linker, a debugger, a project manager, and other development tools under the control of a single main application. Integrated doesn't necessarily mean that a single program provides all these functions. However, the IDE does automatically run each of these applications as needed. An application developer sees a single "user interface" to all these tools and doesn't have to learn different sets of commands for each of the components needed to build an application.
The central component of most IDEs is the editor and project manager. A project in a typical IDE is a related collection of files that contain information needed to build a complete application. This could, for example, include assembly language source files, header files, object files, libraries, resource files, and binary data files. The point of an IDE project is to collect and manage these files to make it easy to keep track of them.
Most IDEs manage the files specific to a given project by placing those files in a single subdirectory. Shared files (such as library and shared object code files) may appear elsewhere but the files that are only used for the project generally appear within the project directory. This makes manipulation of the project as a whole a bit easier.
RadASM, created by Ketil Olsen, is a relatively generic integrated development environment. Many IDEs only work with a single language or a single compiler. RadASM, though designed specifically for assembly language development, works with a fair number of different assemblers. The nice thing about this approach is that you may continue to use RadASM when you switch from one assembler to another. This spares you the effort of having to learn a completely new IDE should you want to switch from one assembler to another (e.g., switching between FASM, MASM, NASM, TASM, and HLA is relatively painless because RadASM supports all of these assemblers. RadASM is extremely customizable, allowing you to easily set it up with different assemblers/compilers or even modify it according to your own personal tastes. Although the version of RadASM that ships with HLA has been specifically set up to work seamlessly with RadAsm, it's nice to know that you can customize RadASM however you choose..
HLA Project Organization
A RadASM/HLA project is a collection of all the files specific to a given executable program. This includes project-specific source files, resource files, object files, header files, makefiles, and so on. Share library, object, and header files are logically a part of an HLA project, though they generally are not physically present in the set of files that comprise a project (i.e., you don't make copies of these files for each project you produce). Whether a given file is physically a part of the project or just logically a part of a project, a RadASM/HLA project cannot compile correctly without all the files that make up the project.
This document will adopt the (reasonable) convention of placing each HLA project in its own subdirectory. A given project directory will contain the following files and directories:
- All source files specific to the project (this includes make files, .hla, .hhf, .rc, .rap [RadASM project] and other files created specifically for this project, but does not include any standard library header or generic library files that all projects use).
- A "makefile" file to be processed by a "make" program or a batch file to compile and combine all the files in a project.
- A "Tmp" subdirectory where HLA can place temporary files it creates during compilation (normally these files wind up in the same directory as the HLA source files; placing them in the "Tmp" directory prevents clutter of the main project directory).
A "Bak" subdirectory where backup files can be kept.
The RadASM IDE provides the ability to maintain projects directly. However, the combination of RadASM/HLA and a "make" program provides a superior solution to the standard RadASM project paradigm. Therefore, this document will assume that you're using makefiles in your RadASM projects (the next section describes the "make" program, so if you're not familiar with it, keep on reading...).
The drawback to using makefiles to maintain the project is that you've got to manually create the makefile; RadASM won't do this for you automatically (as it does with its own projects). Fortunately, 90% of your makefile creations will simply be copying an existing makefile to your project's directory, editing the file, and changing the filenames from the previous project to the current project (indeed, this operation is so common that you'll find a generic makefile in the "sniplets" RadASM directory accompanying the HLA download. You can easily create a copy of this generic makefile from RadASM's "Tools > Sniplets" menu, as you'll see soon enough).
Using Makefiles
Although RadASM provides a true IDE for HLA that supports projects, browsing, and other nice features, the best way to manage your Win32 assembly projects (even within RadASM) is via a makefile. Since the use of make is going to be a fundamental assumption in this book (e.g., most examples will include a makefile), it's probably wise to discuss the use of make here for those who may be unfamiliar with this program.
The main purpose of a program like make (or nmake, if you're using Microsoft's version of the program) is to automatically manage the compilation and linking of a multi-module project. Although it is theoretically possible to write a single, self-contained, assembly language source file that assembles directly to an executable file, in practice this is rarely done. Instead, programs are usually broken up into separate source files by logical function. In order to save time during development, you don't always have to recompile every source file that makes up the application. Instead, you need only recompile those source files that have been changed (or depend upon changes in other source files). This can save a considerable amount of time during development if your project consists of many different source files that you're compiling and linking together and you make a single change to one of these source files (because you will only have to recompile the file you've changed rather than all files in the system).
Note that you will have to obtain a make utility program in order to use make files. If you've got any Microsoft development tools, then you've probably got a copy of Microsoft's nmake.exe program lying around. Ditto for Borland tools. The Free Software Foundation (FSF - the GNU folks) have their own version of make as well. If you don't have a copy of a make utility, you can download Borland's version as part of their C++ command line compiler package that they distribute free on their website (though you do have to register with Borland to receive this). Check out the C++Builder Downloads page at
http://www.borland.com/products/downloads/download_cbuilder.html
Click on the "compiler" link in order to download Borland's command line C++ compiler (that includes the make.exe utility). If this link is broken, just visit http://www.borland.com and follow the downloads link.
Although separate compilation reduces assembly time and promotes code reuse and modularity, it is not without its own drawbacks. Suppose you have a program that consists of two modules: pgma.hla and pgmb.hla. Also suppose that you've already compiled both modules so that the files pgma.obj and pgmb.obj exist. Finally, you make changes to pgma.hla and pgmb.hla and compile the pgma.hla file but forget to compile the pgmb.hla file. Therefore, the pgmb.obj file will be out of date since this object file does not reflect the changes made to the pgmb.hla file. If you link the program's modules together, the resulting executable file will only contain the changes to the pgma.hla file, it will not have the updated object code associated with pgmb.hla. As projects get larger they tend to have more modules associated with them, and as more programmers begin working on the project, it gets very difficult to keep track of which object modules are up to date.
This complexity would normally cause someone to recompile all modules in a project, even if many of the object files are up to date, simply because it might seem too difficult to keep track of which modules are up to date and which are not. Doing so, of course, would eliminate many of the benefits that separate compilation offers. Fortunately, the make program can solve this problem for you. The make program, with a little help, can figure out which files need to be reassemble and which files have up to date .OBJ files. With a properly defined make file, you can easily assemble only those modules that absolutely must be assembled to generate a consistent program.
A make file is a text file that lists compile-time dependencies between files. An .EXE file, for example, is dependent on the source code whose assembly produce the executable. If you make any changes to the source code you will (probably) need to reassemble or recompile the source code to produce a new executable file1.
Typical dependencies include the following:
- An executable file generally depends only on the set of object files that the linker combines to form the executable.
- A given object code file depends on the assembly language source files that were assembled to produce that object file. This includes the assembly language source files (.HLA) and any files included during that assembly (generally .HHF files).
The source files and include files generally don't depend on anything.
A make file generally consists of a dependency statement followed by a set of commands to handle that dependency. A dependency statement takes the following form:
dependent-file : list of files
pgm.exe: pgma.obj pgmb.obj --Windows make/nmake example
This statement says that pgm.exe is dependent upon pgma.obj and pgmb.obj. Any changes that occur to pgma.obj or pgmb.obj will require the generation of a new pgm.exe file.
The make program uses a time/date stamp to determine if a dependent file is out of date with respect to the files it depends upon. Any time you make a change to a file, the operating system will update a modification time and date associated with the file. The make program compares the modification date/time stamp of the dependent file against the modification date/time stamp of the files it depends upon. If the dependent file's modification date/time is earlier than one or more of the files it depends upon, or one of the files it depends upon is not present, then make assumes that some operation must be necessary to update the dependent file.
When an update is necessary, make executes the set of commands following the dependency statement. Presumably, these commands would do whatever is necessary to produce the updated file.
The dependency statement must begin in column one. Any commands that must execute to resolve the dependency must start on the line immediately following the dependency statement and each command must be indented one tabstop. The pgm.exe statement above would probably look something like the following:
hla -e:pgm.exe pgma.obj pgmb.obj
(The "-e:pgm.exe" option tells HLA to name the executable file pgm.exe.)
If you need to execute more than one command to resolve the dependencies, you can place several commands after the dependency statement in the appropriate order. Note that you must indent all commands one tab stop. The make program ignores any blank lines in a make file. Therefore, you can add blank lines, as appropriate, to make the file easier to read and understand.
There can be more than a single dependency statement in a make file. In the example above, for example, executable (pgm.exe) depends upon the object files (pgma.obj and pgmb.obj). Obviously, the object files depend upon the source files that generated them. Therefore, before attempting to resolve the dependencies for the executable, make will first check out the rest of the make file to see if the object files depend on anything. If they do, make will resolve those dependencies first. Consider the following make file:
hla -e:pgm.exe pgma.obj pgmb.obj
The make.exe program will process the first dependency line it finds in the file. However, the files that pgm.exe depends upon themselves have dependency lines. Therefore, make will first ensure that pgma.obj and pgmb.obj are up to date before attempting to execute HLA to link these files together. Therefore, if the only change you've made has been to pgmb.hla, make takes the following steps (assuming pgma.obj exists and is up to date).
- The make program processes the first dependency statement. It notices that dependency lines for pgma.obj and pgmb.obj (the files on which pgm.exe depends) exist. So it processes those statements first.
- The make program processes the pgma.obj dependency line. It notices that the pgma.obj file is newer than the pgma.hla file, so it does not execute the command following this dependency statement.
- The make program processes the pgmb.obj dependency line. It notes that pgmb.obj is older than pgmb.hla (since we just changed the pgmb.hla source file). Therefore, make executes the command following on the next line. This generates a new pgmb.obj file that is now up to date.
- Having processed the pgma.obj and pgmb.obj dependencies, make now returns its attention to the first dependency line. Since make just created a new pgmb.obj file, its date/time stamp will be newer than pgm.exe's. Therefore, make will execute the HLA command that links pgma.obj and pgmb.obj together to form the new pgm.exe file.
Note that a properly written make file will instruct the make program to assemble only those modules absolutely necessary to produce a consistent executable file. In the example above, make did not bother to assemble pgma.hla since its object file was already up to date.
There is one final thing to emphasize with respect to dependencies. Often, object files are dependent not only on the source file that produces the object file, but any files that the source file includes as well. In the previous example, there (apparently) were no such include files. Often, this is not the case. A more typical make file might look like the following:
hla -e:pgm.exe pgma.obj pgmb.obj
Note that any changes to the pgm.hhf file will force the make program to recompile both pgma.hla and pgmb.hla since the pgma.obj and pgmb.obj files both depend upon the pgm.hhf include file. Leaving include files out of a dependency list is a common mistake programmers make that can produce inconsistent executable files.
Note that you would not normally need to specify the HLA Standard Library include files. the Standard Library ".lib" files, or any Windows library files (e.g., kernel32.lib) in the dependency list. True, your resulting executable file does depend on this code, but this code rarely changes, so you can safely leave it out of your dependency list. Should you make a modification to the Standard Library, simply delete any old executable and object files to force a reassembly of the entire system.
The make program, by default, assumes that it will be processing a make file named makefile. When you run the make program, it looks for makefile in the current directory. If it doesn't find this file, it complains and terminates2. Therefore, it is a good idea to collect the files for each project you work on into their own subdirectory and give each project its own makefile. Then to create an executable, you need only change into the appropriate subdirectory and run the make program.
The make program will only execute a single dependency in a make file, plus any other dependencies referenced by that one item (e.g., the pgm.exe dependency line in the previous example depends upon pgma.obj and pgmb.obj, both of which have their own dependencies). By default, the make program executes the first dependency it finds in the makefile plus any dependencies that are subservient to this first item. In particular, if a dependency line exists in the makefile that is not referenced (directly or indirectly) from the main dependency item, then make will ignore that dependency item unless you explicitly request it's execution.
If you want to execute some dependency other than the first dependency in the make file, you can specify the dependency on the make command line when running make from the Windows' command prompt. For example, a common convention in make files is to create a "clean" dependency that cleans up all the files the compile creates. A typical "clean" dependency line for an HLA compilation might look like the following:
The first thing you'll notice is that the "clean" item doesn't have a dependency list. When an item like "clean" appears without a dependency list, make will always execute the commands that follow. Another peculiarity to the "clean" dependency is that there (usually) isn't a file named clean in the current directory whose date/time stamp the make program can check. If a file doesn't exist, then make will assume that the file is always out of date. A common convention is to specify non-existent filenames (like clean) in a makefile as commands that someone would explicitly execute from within make. Of course, such usage (generally) assumes that you don't actually build a file named "clean" (or whatever name you choose to use).
Since, by default, you typically don't want to execute a command line "clean" when running make, you wouldn't usually place the clean dependency first in the make file (nor would you typically refer to clean within some other dependency list). Since make doesn't normally execute any dependency items that aren't "reachable" from the first dependency item in the make file, you might wonder how you'd tell make to execute the clean command. To specify the execution of some dependency other than the first (default) item in the make file, all you need to is specify the target you want to create (e.g., "clean") on the make command line. For example, to execute the clean command, you'd using a Windows command prompt statement like the following:
This command does not tell make to use a different make file. It will still open and use the file named makefile in the current directory3; however, instead of executing the first dependency it finds in makefile, it will search for the target "clean" and execute that dependency.
By convention, most programmers use the first dependency in a make file to build the executable based on the current build state of the program (that is, it will compile and link only those files necessary to create an up-to-date executable). Most programmers, by convention, will also include a "clean" target in their make file. The clean command deletes all object and intermediate files that the compiler generates; this ensures that the next build of the program will recompile every source file in the project, even if the original objects (and other targets) were up-to-date already. Doing a clean before building the application is useful when you've changed something that is not listed in the dependency lists but on which the final executable still depends (like the HLA Standard Library). Doing a clean is also a good way to do a sanity check when you're running into problems and you suspect that the dependency lists aren't completely correct.
Beyond clean there aren't too many "standard" target definitions you'll see programmers using in their make files, though it's common for different make files to have some additional commands beyond building the default target and cleaning up temporary compiler files. When using make with the RadASM/HLA package, however, there is an assumption that you've created the following dependencies in your make file:
build: This will be the default command (i.e., the first command appearing in the make file). It will build an executable by building any out-of-date files and linking everything together. A typical build dependency will look like this:
This tells make to go execute the dependency for pgm.exe (which would normally be the default dependency in the file).
buildall: This command will rebuild the entire application. It begins by doing a clean, and then it does a build. This command generally takes the following form:
compileRC: This command will compile any resource files into .RES files. Though the current example does not have any resource files, a typical entry in the make file might look like the following:
syntax: This command will compile any HLA files into .ASM files just to check their syntax. Using the pgma.hla/pgmb.hla example given earlier, a typical compile dependency line might look like the following:
run: This command will build the executable (if necessary) and then run it. The dependency line typically looks like the following:
pgm <<any necessary command line parameters>>
clean: This is the command that deletes any compiler/assembler/linker produced temporary files, backup files, and the executable file. A typical clean command is
One nice feature that a standard make program provides is variables. The make program allows you to create textual variables in a make file using the following syntax:
All text beyond the equals sign ("=") to the end of the physical line4 is associated with the identifier and the make program will substitute that text whenever it encounters "$(identifier)" in your text file. This behavior is quite similar to TEXT constants in the HLA language. As an example, consider the following make file fragment:
hla -e:$(executable) $(sources)
Because of the textual substitution that takes place, this is equivalent to the following make file fragment:
hla -e:pgm.exe pgma.hla pgmb.hla
You can even assign variable names from the make command line using syntax like the following:
make executable=pgm.exe sources="pgma.hla pgmb.hla"
This is an important fact we'll use because it allows us to create a generic makefile that RadASM can use to compile a given project by simply supplying the file names on the command line.
Although this section discusses the make program in sufficient detail to handle most RadASM projects you will be working on, keep in mind that the make program provides considerable functionality that this document does not discuss. For more details, consult the vendor's documentation accompanying the version of make that you're using. This document will assume that you're using Borland's make (version 4.0 or later) or some version of Microsoft's nmake. Every make file in this book has been tested with both of these versions of make. These make files may work with other versions of make as well. If you don't already have a copy of make, note that you can download Borland's make as part of the Borland C++ 5.5 compiler (see the directions for downloading this file earlier in this section).
Because of the variations in the way different make programs work, the makefiles appearing in this document will be relatively simple, not taking advantage of too many special make features. The generic makefile we'll usually start with looks like this:
buildall: clean $(hlafile).exe
echo No Resource Files to Process!
$(hlafile).exe: $(hlafile).hla
hla $(DEBUG) $(WINAPP) -p:tmp $(hlafile)
RadASM will fill in the $(hlafile) make variable with the project's (source file's) name. The "$(DEBUG)" variable will be filled in by RadASM (you'll see how later in this document) and will expand to an empty string if $(DEBUG) is not defined. The $(WINAPP) variable is another variable set by RadASM; it will contain the text "-w" if compiling a Windows GUI app, it will be the empty string if compiling a console application.
Installing RadASM
The easiest way to install RadASM/HLA is to run the hlasetup.exe program found on Webster (HLA v1.58 or later). This program automatically installs HLA and RadASM, sets up appropriate environment variables, and modifies various RadASM ini files for proper use on your system. Just run hlasetup.exe, answer a few questions about where you want the files placed, and you're in business.
For those who've already installed HLA and don't want to bother reinstalling everything, you can download the RadASM/HLA package from Webster, unzip that file, and install the code manually. The main thing you have to do is copy the RadASM directory into your x:\hla subdirectory and then execute the "PatchRadASM" application from within the "x:\hla" subdirectory. This goes in and patches all the *hla.ini files in the "x:\hla\radasm" subdirectory so that the know where the "x:\hla" subdirectory can be found. You may also edit these files manually and modify the line that says "$A=C:\HLA" so that it refers to the directory containing your HLA files and directories.
Note: Unless you're willing to learn how to customize RadASM and modify several files yourself, you must install the RadASM directory in the HLA subdirectory (wherever it is on the disk). If you're using RadASM with other assemblers and need to keep RadASM in some spot other than in the HLA subdirectory, please see the "RadASM customization" information at the end of this document and take a look at the *hla.ini files on Webster.
If you're an expert RadASM user and you only want to add HLA support to an existing RadASM setup, you can download the HLA-specific RadASM files directly from Webster and make the appropriate modifications yourself. This document will not describe how to do this; this is a task intended for advanced RadASM users only (for support, check out the RadASM forum at www.masmforum.com).
Running RadASM
Like most Windows applications, you can run RadASM by double-clicking on its icon or by double clicking on a "RadASM Project" file (".rap" suffix). Simply double-clicking on the RadASM icon brings up a window similar to the one appearing in See RadASM Opening Screen..
RadASM Opening Screen
The main portion of the RadASM window is broken down into three panes. The larger of the three panes is where text editing takes place. The upper right hand pane is the "project management" window. The pane in the lower right hand corner lists the properties of the currently opened project.
The RadASM Project Management Window
The project management window initially lists the project folders you've created; you can select an existing project by double-clicking on the project's folder in this window. For example, RadASM ships with two sample projects, Dialog (that creates a small dialog box application) and hw (that creates a small "Hello World" console application). Assuming you're running RadASM prior to creating any new projects beyond these two default projects, the Project pane will look something like See Default RadASM Project Pane..
Default RadASM Project Pane
Double-clicking on the hw folder opens the folder containing that project. This changes the pane to look something like that appearing in See RadASM Project Pane With hw Folder Opened..
RadASM Project Pane With hw Folder Opened
By default, RadASM does not show all the files present in the folder you've opened. Instead, RadASM filters out files that don't have a certain file suffix. By default, RadASM only displays files with the following suffixes:
.hhf
This list is actually designed to generically handle all file types for every assembler that RadASM works with. HLA users might actually want to drop ".asm" and ".inc" from this list as files with these suffixes are temporary files that HLA produces (much like ".obj" files, which don't normally appear in this list). You can change the filter suffixes in one of two places. The first place is in the radasm.ini file. Search for the " [FileBrowser] " section and edit the line that begins with " Filter=... ". You can delete or add suffixes to your heart's content on this line. The second way to change the default filters, arguably the easiest way, is within RadASM itself. From the application's menu, select "Option>File Browser" (that is, select the "File Browser" menu item from the "Option" menu). This brings up the dialog box appearing in See RadASM File Browser Options Dialog Box.. The text edit box at the bottom of this dialog window (labelled "Filter:") lets you edit the suffixes that RadASM uses for filtering files in the Project window pane.
RadASM File Browser Options Dialog Box
By default, RadASM only displays those files whose file suffixes appears in the filter list. If, for some reason, you need to see all files that appear in a project subdirectory, you can turn the file filtering off. There is a toolbar button at the top of the Project window pane that lets you activate or deactivate file filtering (this is the button in the middle of the project pane, if you let the mouse cursor hover over it for a few seconds the tool-tip help displays "file filter"). Clicking on this button toggles the display mode. So clicking on this button once will deactivate file filtering, to display all the files in the directory, clicking on this button a second time reactivates file filtering. See File Filtering in RadASM's Project Pane. shows the effects of clicking on this button.
File Filtering in RadASM's Project Pane
If you've descended into a subdirectory by double-clicking on it's folder icon and you decide to return to an upper level directory, you can move to that upper level directory by clicking on the "Up One Level" button in the RadASM Project pane (see See RadASM "Up One Level" Directory Navigation Button.).
RadASM "Up One Level" Directory Navigation Button
The left and right arrow buttons allow you to quickly scan through several different directories in the system (see See Project Folder Selection Arrows.). By default, RadASM displays a couple of interesting (HLA-related) subdirectories in the Project pane when you scan through the list using the left and right arrows in the Project pane. In general, however, you'll want to customize the directories RadASM visits when you press these two arrow buttons. You can add (or change) directory paths in the " [FileBrowser] " section of the radasm.ini file, though it's probably easier to select the "Option>File Browser" menu item to open up the File Browser Option dialog box and make your changes there (see See RadASM File Browser Options Dialog Box.). The "Folders:" list in the File Browser Option dialog box lists all the directories that RadASM will rotate through when you press the left and right buttons in the Project window pane. You can add, delete, edit, and rearrange the items in this list.
Project Folder Selection Arrows
To edit an existing entry, click on that entry with the mouse and then edit the directory path appearing in the text edit box immediately below the "Folders:" list (see See RadASM File Browser Options Dialog Box.). You may either type in the path directly, or browse for the path by pressing the "browse" button immediately to the right of the text entry box (see See The RadASM File Browser Option "Browse" Button.).
The RadASM File Browser Option "Browse" Button
To delete an entry from the File Browser Option list, select that item with the mouse and then press the "Delete" button appearing in the File Browser Option Window. To add a new entry to the list, press the "Add" button and then type the path into the text edit box (or use the browse button to locate the subdirectory you want to add). Note: do not type the new entry in and then press "Add". This sequence will change the currently selected item and then add a new, blank, entry. The correct sequence is to first press the "Add" button, and then edit the blank entry that RadASM creates.
The remaining buttons in the Project window are only applicable to open projects. Note that opening a project folder is not the same thing as opening a RadASM project. To open a RadASM project you must either create a new project or open an existing ".rap" file. For example, you can open the "Hello World" project in the hw directory by double-clicking on the hw.rap file that appears in the project window. Opening the hw.rap file does two things to the RadASM windows: first, it displays the hw.hla source file in the editor window and, second, it switches the Project window pane from "File Browser mode" to "Project Browser mode." In project browser mode RadASM displays only the files you've explicitly added to the project. Any incidental or generated files will not appear here (unless you explicitly add them). For example, whereas the "File Browser" mode displays several ".inc" and ".asm" files (assuming you've not removed these suffixes from the file filter), the "Project Browser mode" only displays the hw.hla file because this is the only file that was originally added to the project. Another difference between the file browser and project browser modes is the fact that RadASM displays the files in "pseudo-directories" according to the file's type. For example, it displays the hw.hla file under the sub-heading "Assembly" (see See Project Window "Project Browser Mode".). The hw.rap project is a relatively simple project, only having a single assembly file. The Dialog.rap project (that appears in the "Dialog" project folder) is a slightly more complex application, having a couple of resource files in addition to an assembly file (see See Dialog.rap Project Browser Display.). Note that you can "flatten" RadASM's view of these files by pressing the "Project Groups" button in the Project window pane (see See Effect of Pressing the "Project Groups" Button.). Pressing this button a second time restores the project groups display (remember, you can always determine which button is which by letting the mouse cursor float above each button for a few seconds).
Effect of Pressing the "Project Groups" Button
When you've got a project loaded, RadASM displays the project view by default. By pressing the "File Browser" and "Project Browser" buttons in the Project window pane, you can switch between these two views of your files (see See The Project Browser and File Browser Buttons.).
Compiling and Executing an Existing RadASM Project
To see how to use RadASM to compile and run a simple HLA program, begin by double-clicking on the hw.rap file. This is found in the ...Radasm\hla\projects\hw folder. When RadAsm opens up, you should see a display similar to See Selecting the HW.HLA Project.; if not, then press the project browser and project groups buttons.
Selecting the HW.HLA Project
Just for fun, bring up the hw.hla program into the main editor by double-clicking on the hw.hla file icon in the project manager window. Here's what that file looks like:
stdout.put( "Hello, World of Assembly Language", nl, nl );
To run the Hello World program from RadASM, simply select the "Run" entry from the Make menu (see See Running the Hello World Program From RadASM.). This produces the program output found in See HW.HLA Program Output.. When you press the enter key, the console window will close and control returns to RadASM.
HW.HLA Program Output
The other options in the RadASM "Make" menu have the following effect:
- Build- compiles the project; if you're using makefiles in your RadASM projects, this option will only compile those files absolutely necessary to create the executable.
- Build All- cleans out all the old object and executable files and rebuilds the executable from scratch.
- Compile Resource- Used to compile any resource files associated with this project (note that Build and Build All will also compile the resource files, if necessary).
- Syntax Check - does a syntax compile on the HLA files, without actually building the whole application. Faster than building the whole project if you simply want to check for typos in your source code.
- Run - Runs the executable (if you're using makefiles, this will also build the application if the executable is not current; if you're not using makefiles, you must manually build the application before running it).
Creating a New Project in RadASM
While the two default projects that RadASM supplies are useful for demonstrating the RadASM Project window pane, you're probably far more interested in creating your own RadASM/HLA projects. Creating your own project is a relatively straight-forward process using RadASM's project creation wizard. To begin this process, select the "File>New Project" menu item. This opens the project wizard dialog box (see See RadASM Project Wizard Dialog Box.).
RadASM Project Wizard Dialog Box
The "Assembler" pop-up menu list lets you select the assembler that you want to use for this project. Remember, RadASM supports a variety of different assemblers and the "rules" are different for each one. Because you're probably using HLA (if you're reading this document), you'll want to select the HLA assembler from this list. HLA should be the default (in fact, only) assembler in this list. If you're not using the radasm.ini file supplied on Webster, then you should make sure that HLA appears first in this list in the radasm.ini file.
The "Project Type" group is a set of radio buttons that let you select the type of project you're creating. RadASM populates this list of radio buttons from the " [Project] " section of the hla.ini file. The " Type=... " statement in this section specifies the valid projects that RadASM will create. RadASM creates the radio button items in the order the project type names appear in the " Type=... " list; the first item in the list is the one that will have the default selection. If you're going to be developing Windows' GUI applications most of the time, you'll probably want to change this list so that "Windows App" appears first in the list. This will slightly streamline the use of the Project Wizard because you won't have to explicitly select "Windows App" every time you create a new Windows application. The standard default is a Console App because that's the type of program most beginning HLA programmers create. You can actually add new project types to this list by modifying the hla.ini file. However, most HLA programmers will be creating either Win32 GUI apps or Win32 console apps, hence the standard release of RadASM/HLA supports these two application types. If you want to creat your own project types, see the discussion on customizing RadASM later in this manual.
The "Project Name:" text entry box is where you specify the name of the project you're creating. RadASM will create a folder by this name and any other default files it creates (within the project folder) will also have this name as their filename prefix. The text you enter at this point must be a valid Windows filename. Note that this should be a simple file name, not a path. You'll supply the path to this file/directory in a moment. This name should be a base filename (that is, no extension). RadASM will create other filenames by attaching appropriate extensions to the name you supply here (e.g., ".hla" and ".exe"). So if you specify a name like "myProject" here, RadASM will create a directory named "myProject" to hold your files and it will also create a "myProject.hla" file (among other files). When you actually build your program, RadASM (by default) will create an exectuable named "myProject.exe".
The "Project Description:" text entry box allows you to place a descriptive comment that describes the project. This is any arbitrary text you choose. It should be a brief (one-line) description of the project.
The "Projects Folder:" text entry box is where you select the path to the spot in the file system where RadASM will create the project folder. You can type the path in directly, or you can press the browse button to the right of this text entry box and use a Windows' dialog box to select the subdirectory that will hold the project's folder.
The "Template:" text entry box and browse button lets you select a template for your project. If you don't select a template, then RadASM will create an empty project for you (i.e., the main ".hla" file will be empty). If you select one of the templates (e.g., the ".tpl" files found in the RadASM\Hla\Templates directory) then RadASM will create a "skeletal" project based on the project template you've chosen. See RadASM/HLA Templates. lists some of the typical templates you will find.
RadASM/HLA Templates
Generally, it's a good idea to select one of these templates when creating a new project. These templates automatically create any extraneous files a project needs (such as batch files and make files) and inserts these files into your new project. This spares you the effort of manually creating these files and inserting them into the project.
The RadASM/HLA package provides (at least) 16 different templates5. There are four different template categories, each category containing four templates. Not all of these template files will be visible when you press the "template browse" button. The cons*.tpl files are only visible if you've selected the "Console App" radio button. The win32*.tpl, WPA*.tpl, and empty*.tpl files will only be visible if you've selected the "Windows App" radio button in the "Project Type" box.
Within a given template category (cons*, win32*, WPA*, empty*) there are four choices available to you. For example when selecting one of the console templates you could choose consApp.tpl, consAppBatch.tpl, consAppMake.tpl, or consNMake.tpl. The difference between these project types is how RadASM will build (compile/assemble) the project.
The *App.tpl template files tell RadASM to directly build your application (using commands found in the .tpl file). You can think of this as the "native" RadASM build mode. The only problem with this approach is that it is not very flexible (in terms of handling multi-filecompilations) and it always rebuilds the entire project. As a result, projects that use the native RadASM build scheme are really suitable only for small (usually single-file) projects.
The *AppBatch.tpl template files tell RadASM to invoke various batch files when building the application. The template will actually create simple versions of these batch files for you: build.bat, compilerc.bat, syntax.bat, and run.bat. These batch files correspond to the items in the RadASM Make menu (note that the "Build" and "Build All" menu items both run the build.bat file). By default, these batch files only support a the creation of an application built around a single HLA source file (just like a native RadASM build). However, you can always edit these batch files to do a more sophisticated compilation. A later section will describe how to edit these batch files.
The *AppMake.tpl and *AppNMake.tpl template files tell RadASM to invoke a make utility (a generic make.exe program or Microsoft's nmake.exe utility, based on which template you select). The template creates a generic makefile for you (automatically) that handles all the menu items in the RadASM Make menu. Using make is, without question, the best way to use RadASM. Make is far more efficient for larger projects than using batch files or RadASM's built-in compilation capabilities. However, there are two drawbacks to using make: first, you have to have a copy of the make.exe (or nmake.exe) program (though this utility is available for free, see how to get a copy of this program in the section on make, earlier in this document); the second drawback is that you will have to edit the makefile that these templates create before you can build anything complex with them, i.e., if you want to create a sophisticated multi-file project, you'll need to make other changes to the makefile that the template creates. See the section on make earlier in this document for the details associated with the make language.
Once you've selected the assembler type, project type, entered the project name and description, and optionally selected the folder and a template, press the "Next>" button to move on to the next window of the Project Wizard dialog. This dialog box appears in See Project Wizard Dialog Box #2.. In this dialog box you select the initial set of files and folders that RadASM will create in the project's folder for you. At the very least, you're going to want a ".hla" file and a "Tmp" subdirectory. It's probably a good idea to create a "BAK" subdirectory as well (RadASM will maintain backup files in that subdirectory, if it is present). More complex Windows applications will probably need a header file (".HHF") and if you're creating fancy GUI applications, you may need a resource file (".RC") as well. If you're creating a dynamically linked library (DLL), you'll probably want a definition file (".DEF") as well. If you plan on writing documentation, you might want to create a DOC subdirectory - the choice is yours. Check the files and folders you want to create and press the "Next >" button in the dialog box. Note that simple console applications (the type of applications most beginning HLA users create) require only a ".hla" file and a "Tmp" directory.
Project Wizard Dialog Box #2
The last dialog box of the Project Wizard lets you specify the options present in the Make menu and the commands each of these options executes (see See Project Wizard Dialog Box #3.). You should ignore all these options and just press the finish button. Generally, you will not customize this output; you will normally just hit the "finish" button to complete the construction of your project. If you do want to change these options, do it from the "Project>Project Options" menu item once you've created the project See Typical RadASM Window After Project Creation. shows what the RadASM window looks like after create a sample "Windows App" application based on the win32app.tpl template (this project was given the name "MyApp").
Working With RadASM Projects
Of course, once you've created a RadASM project, you can open up that project and continue work on it at some later point. RadASM saves all the project information in a ".rap" (RadAsm Project) file. This ".rap" file keeps track of all the files associated with the project, project-specific options, and so on. These project files are actually text files, you can load them into a text editor (e.g., RadASM's editor) if you want to see their format. As a general rule, however, you should not modify this file directly. Instead, let RadASM take care of this file's maintenance.
There are several ways to open an existing RadASM project file - you can double-click on the .rap file's icon within Windows and RadASM will begin running and automatically load that project. Another way to open a RadASM project is to select the "File>Open Project" menu item and open some ".rap" file via this open command. A third way to open a RadASM project is to use the File Browser to find a ".rap" file in one of your project directories and double-click on the project file's icon (the ".rap" file) that appears in the project browser. Any one of these schemes will open the project file you've specified.
RadASM only allows one open project at a time. If you have a currently open project and you open a second project, RadASM will first close the original project. You can also explicitly close a project, without concurrently opening another project, by selecting the "File>Close Project" menu item.
Once you've opened a RadASM project, RadASM's "Project" menu becomes a lot more interesting. When you create a project, RadASM gives you the option of adding certain "stock" files to the project (either empty files, or files with data if you select a template when creating the project). All of the files that RadASM creates bear the project's name (with differing suffixes). As a result, you can only create one ".hla" file (and likewise, only one ".hhf" file, only one ".rc" file, etc.). For smaller assembly projects, this is all you'll probably need. However, as you begin writing more complex applications, you'll probably want additional assembly source files (".hla" files), additional header files (".hhf"), and so on. RadASM's Project menu is where you'll handle these tasks (and many others). See The RadASM Project Menu. shows the entries that are present in the Project menu.
The RadASM Project Menu
To add new, empty, files to a RadASM project, you use the "Project > Add New" menu item. This opens up a new submenu that lets you select an assembly file (".hla" file), an include file (".hhf"), a resource compiler file (".rc"), a text file, and so on. Selecting one of these submenu items opens up an "Add New File" dialog box that lets you specify the filename for the file. Enter the filename and RadASM will create an empty text file with the name you've specified. Later on, you can edit this source file with RadASM and add whatever text is necessary to that file. Note that RadASM will automatically add that file to the appropriate group based on the file's type (i.e., it's suffix).
The "Project > Add Existing" sub-menu lets you add a pre-existing file to a project. This is a useful option for creating a RadASM project out of an existing HLA (non-RadASM) project or adding files from some other project (e.g., library routines) into the current project. Note that this option does not create a copy of the files you specify, it simply notes (in the ".rad" file) that the current project includes that file. To avoid problems, you should make a copy of the actual source file to the current project's folder before adding it to the project; then add the version you've just copied to your project. It's generally unwise to add the same source file to several different projects. If you change that source file in one project, the changes are automatically reflected in every other project that links this file in. Sometimes this is desirable, but most of the time programmers expect changes to a source file to be localized to the current project. That's why it's always best to make a copy of a source file when adding that file to a new project. In those cases where you do want the changes reflect to every application that includes the file, it's better to build a library module project and link the resulting ".lib" file with your project rather than recompile the source file in.
The "Project > Project options" menu item opens up a "Project Options" dialog box that lets you modify certain project options (see See "Project > Project Options" Dialog Box.). This dialog box lets you change certain options that were set up when you first created the project using the "File > New Project" Project Wizard dialogs. Most of the items in this dialog box should have been described earlier, but a few of the items do need a short explanation.
"Project > Project Options" Dialog Box
The Project Options dialog box provides two radio buttons that let you select whether RadASM will do a "debug build" or a "release build." Be sure that the "Release" radio button is selected. The Debug option instructs HLA to insert certain debugging information into your executable file (e.g., for use by OllyDbg). We will not consider that option in this document.
Build Options with RadASM/HLA
Before discussing how to actually edit and compile programs using RadASM, we need to stop for a moment and discuss the internal operation of RadASM and how it controls programs like HLA. RadASM was created to be a very flexible system supporting multiple assemblers and different ways of building applications. In one respect, this flexibility is very good - it is exactly this flexibility that allows RadASM to work with HLA (rather than just with Microsoft's assembler, for which RadASM was initially created). On the other hand, there is a down side to this flexibility - creating HLA projects is a little bit more involved than it has to be had RadASM been written specifically for HLA. In this section we'll discuss the extra work involved with creating and maintaining RadASM projects.
Take another look at See "Project > Project Options" Dialog Box.. Beside the labels "Compile RC", "Assemble", "Link", etc., you'll find some editable strings. These strings are special RadASM commands that tell RadASM what to do whenever you select an item from RadASM's "Make" menu. Originally, the labels next to each of these text edit boxes corresponded to menu items in the RadASM "Make" menu; HLA, however, has renamed the menu items in the "Make" menu, so they no longer correspond to the labels appearing in the "Project Options" dialog box (See "Project > Project Options" Dialog Box.). See Correspondence Between Project Options and Make Menu. shows the relationship between the labels in the Project Options dialog box and the Make menu.
Correspondence Between Project Options and Make Menu
The text appearing in the corresponding text edit box in the Project Options dialog box is a command that RadASM executes whenever you select the corresponding item from the Make menu. Here's the syntax for each of these entries:
DEL, OUT, CMD, FILE {,FILE,...}
DEL is a numeric entry that specfies which files to delete prior to executing the command. Normally, this should be zero (which means "don't delete any files.").
OUT is either "O", "OT", or "C" meaning that the command's output goes to the RadASM output windows ("OT"), the command produces no output (and any output is ignored, "O"), or RadASM opens up a console (command-line) window and sends all output to that window ("C"). For most commands except "RUN", you'll probably want the command's output to go to the RadASM output window; when running the program you'll probably want the output to go to a console window (at least, if you're writing a console application).
CMD is the command (command-line prompt command) to execute in response to this Make menu selection. This includes the program's name and any command line parameters (though you don't usually specify the filenames to process here).
FILE is a special numeric designation (internal to RadASM) that specifies the file that the CMD is to process. We'll normally leave this blank, see the discussion on RadASM customization later in this document for more details on this entry.
There are three common ways people use to have RadASM run HLA to compile an HLA project: direct command execution, batch file execution, and make file execution. Each of these execution modes have their own set of advantages and disadvantages.
Direction command execution is the default mode for RadASM/HLA "out of the box." This mode has the advantage of being the easiest to use. For the most part, it doesn't require the creation of any special files in order to build a given project (though the "run" command works best if you create a batch file for it). There are several disadvantages to this approach. First, it doesn't work with HLA on all versions of Windows. Another disadvantage to this approach is that it's mainly useful for single-file projects (unless you're willing to delve deep into RadASM and learn all about customizing it for your own purposes). Yet another disadvantage is that you have to manually build eachcomponent of the project when using the direct command execution. In general, the disadvantages would outweigh the advantages of this execution mode were it not for the fact that the direct command approach works best for simple projects as it doesn't require the creation of any batch or makefiles. However, once you've created a few HLA projects and get comfortable with RadASM, you'll probably want to shift to one of the other RadASM operation modes. Note that running in this mode is equivalent to creating a project with one of the *App.tpl templates (also note that template settings always override the default settings).
Batch file execution is the second mode of operation that RadASM/HLA supports. In this mode of operation each of the RadASM commands in the Project Options dialog box executes a batch file and that batch file handles whatever set of tasks is necessary for the specified Make menu option. See RadASM in Batch Execution Mode (Project Options). shows the Project Options dialog box with the commands to execute when operating in batch mode. Note that each of the commands simply execute a batch file (build.bat, compilerc.bat, syntax.bat, and run.bat).
RadASM in Batch Execution Mode (Project Options)
The batch files specified in the Project Options dialog box must appear in the same directory as the other files for project (e.g., along with the source files). These batch files contain a list of command-prompt commands to execute whenever you select one of the menu items from the Make menu. Here are the contents for each of the generic batch files supplied with RadASM/HLA:
echo "No Resource Files to Compile!"
The advantage of the batch file execution scheme over the direct execution scheme is that you can execute several commands within a batch file (unlike the direct command execution scheme). This lets you compile multi-file projects and execute other command-line actions within the batch file. Also, the batch file scheme works with all versions of Windows. Furthermore, the batch file scheme doesn't require any additional utility programs to achieve this flexibility. Batch files have two main disadvantages. First, you have to write a set of batch files for every project you create (though for single-file projects, the generic batch files work fine; editing the batch files is only necessary for more sophisticated projects). The second problem with batch files is they force a rebuild of every file in a multi-file project, even if such work is unnecessary.
The makefile execution scheme is the most flexible of the three. Like the batch file scheme, you can execute multiple commands and this scheme works with all versions of Windows. A big advantage of makefiles over batch files is that you can easily handle large multi-file projects using makefiles and you can build the projects only recompiling the files that are necessary. Like batch files, one disadvantage to using makefiles is that you have to maintain a separate "makefile" the directs the compilation. Another disadvantage to the makefile scheme is that you have to have a separate "make" utility installed on your system (if you don't already have a copy of make, you can obtain one for free from Borland; see the section on "Make" for more details). See Makefile Execution Scheme (Project Options). show the command set for RadASM when using the makefile execution scheme with Borland's "make.exe" program (note: to use Microsoft's "nmake.exe" program, simply change each occurrence of "make" to "nmake" in the dialog box).
Makefile Execution Scheme (Project Options)
The version of RadASM that ships with HLA includes several versions of the "hla.ini" initialization file that RadASM uses. These files are the following:
- hla.ini - this is the actual file that RadASM uses. As shipped, this is the same as hla_2000.ini (the direct execution mode file).
- hla_2000.ini - this is the version of the hla.ini file that supports direct command execution. If you ever change hla.ini and you want to restore the direct execution form, simply make a copy of this file and rename it to hla.ini.
- hla_bat.ini - this is the version of the hla.ini file that supports batch mode execution. If you want to use batch mode execution, make a copy of this file and rename the copy to "hla.ini".
- hla_make.ini - this is the version of the hla.ini file that supports Borland's make.exe application for the makefile execution mode (actually, this .ini file supports makefile execution using any make program named "make.exe"). If you want to use makefile mode execution, make a copy of this file and rename the copy to "hla.ini".
hla_nmake.ini - this is the version of the hla.ini file that supports Microsoft's nmake.exe application for the makefile execution mode. If you want to use makefile mode execution, make a copy of this file and rename the copy to "hla.ini".
Note that the execution mode specified by the "hla.ini" files is only available when you create a new project without using a template (template files override the settings in the hla.ini file). Each RadASM project file you create (the ".rap" file) maintains the execution mode as part of that project. Should you change the execution mode by copying some new file over the top of hla.ini, you do not change the execution modes for any pre-existing projects. If you want to change the execution mode of an existing project, you will have to select the "Project>Project Options" menu item and edit the entries in the project option dialog box.
The remainder of this document will assume that you're using the flexible "makefile" execution mode and that you're creating makefiles for each of your projects. Therefore, to follow along with the examples that appear in the remainder of this document, you should make a copy of the hla_make.ini (or hla_nmake.ini) file and rename it to hla.ini. Another alternative is to always use one of the *AppMake.tpl or *AppNMake.tpl templates when creating new projects.
Editing HLA Source Files Within RadASM
The RadASM text editor is quite similar to most Windows based text editors you've used in the past (i.e., RadASM generally adheres to the Microsoft Common User Access (CUA) conventions. So the cursor keys, the mouse, and various control-key combinations (e.g., ctrl-Z, ctrl-X, and ctrl-C) behave exactly as you would expect in a Windows application. Because this is an advanced programming book, this chapter will assume that you've used a CUA-compliant editor (e.g., Visual Studio) in the past and we'll not waste time discussing mundane things like how to select text, cutting and pasting, and other stuff like that. Instead, this section will concentrate on the novel features you'll find in the RadASM editor.
Of course, the first file navigation aid to consider is the Project Browser pane. We've already discussed this RadASM feature in earlier sections of this document, but it's worth repeating that the Project Browser pane lets you quickly switch between the files you're editing in a RadASM project. Just double-click on the icon of the file you want to edit and that file will appear in the RadASM editor window pane.
Immediately below the Project Browser pane is the "Properties" pane (if this pane is not present, you can bring it up by selecting "View > Properties" from the RadASM View menu). This pane contains two main components: a pull down-down menu item that lets you select the information that RadASM displays in the lower half of this window. If not already selected, you should select the ".code" item from this list. The ".code" item tells RadASM to list all the sections of code that it recognizes as procedures (or the main program) in an HLA source file (see See The HLA Properties Window Pane.).
The HLA Properties Window Pane
One very useful RadASM feature is that you can quickly jump to the start of a procedure's body (at the begin statement) by simply double-clicking on that procedure's name in the Properties Window pane. In the example appearing in See The HLA Properties Window Pane. (this is the "Dialog" project supplied with RadASM for HLA), double-clicking on the "Dialog;" and "DialogProc;" lines in this list box automatically navigates to the start of the code for the selected procedure.
The pull-down menu in the Properties window lets you select the type of objects the assembler provides. For example, by selecting ".const" you can take a look at constant declarations in HLA. The "macro" selection lets you view the macro definitions that appear in the source file. As this chapter was first being written, the other property items weren't 100% functional; hopefully by the time you read this RadASM will have additional support for other types of HLA declarations.
Another neat feature that RadASM provides is an "outline" view of the source file. Looking back at See The HLA Properties Window Pane. you'll notice that " begin DialogProc; " statement has a rectangle with a minus sign in it just to the left of the source code line. Clicking on this box closes up all the code between the begin and the corresponding end in the source file. See RadASM Outline View (with Collapsed Procedures). shows what the source file looks like when the Dialog and DialogProc procedures are collapsed in outline mode. The neat thing about outline mode is that it lets you view the "big picture" without out the mind-numbing details of the source code for each procedure in the program. In outline view, you can quickly skim through the source file looking for important code and "drill down" to a greater level of detail by opening up the code for a procedure you're interested in looking at. You can also rapidly collapse or expand all procedure levels by pressing the "expand" or "collapse" buttons appearing on the lower left hand corner of the text editor window (see See RadASM Outline View (with Collapsed Procedures).).
RadASM Outline View (with Collapsed Procedures)
Another useful feature RadASM provides is the ability to display line numbers with each line of source code. Pressing on the line number icon in the lower-left hand corner of the text editor window (the icon with the "123" in it) toggles the display of line numbers in the editor's window. See See Displaying Line Numbers in RadASM's Editor. to see what the source file looks like with line numbers displayed. The line number display mode is quite useful when searching for a line containing a syntax error (as reported by HLA). Note that you can also navigate to a given line number by pressing ctrl-G and entering the line number (you can also select "Edit > Goto line" from the "Edit" menu).
Displaying Line Numbers in RadASM's Editor
Another useful navigation feature in RadASM is support for bookmarks. A bookmark is just a point in the source file that you can mark. You can create a bookmark by selecting a line of text (by clicking the mouse on the gray bar next to the line) and selecting "Edit > Toggle BookMark" or by pressing shift-F8. You can navigate between the bookmarks by pressing F8 or ctrl-F8 (these move to the next or previous bookmarks in the source file). RadASM (by default) provides several icons on it's toolbar to toggle bookmarks, navigate to the previous or next bookmark, or clear all the bookmarks. Which method (edit menu, function keys, or toolbar) is most convenient simply depends on where your hands and the mouse cursor currently sits.
The RadASM "Format" menu also provides some useful features for editing HLA programs. The "Format > Indent" and "Format > Outdent" items (also accessible by pressing F9 and ctrl-F9) move a selected block of text in or out four spaces (so you can indent text between an if and endif , for example). You can also convert tabs in a document to spaces (or vice versa) from the "Format > Convert > Spaces To Tab" and "Format > Convert > Tab To Spaces" menu selections.
You'll notice that RadASM provides syntax coloring in the editor window (that is, it sets the text color for various classes of reserved words and symbols to different colors, making them easy to identify with a quick glance in the editor window). The hla.ini file accompanying the RadASM/HLA release contains a set of reasonable color definitions for HLA's different reserved word types. However, if you don't particularly agree with this color scheme, it's really easy to change the colors that RadASM uses for syntax highlighting. Just select the "Options > Colors & Keywords" menu item and select an item from the Syntax/Group list box (See Option>Colors & Keywords Dialog Box with Group#00 Selected. shows what this dialog box looks like with the Group #00 item selected). By double-clicking on an item within the Group list box, you can change the color for all the items in that particular group (e.g., see See Color Selection Dialog Box.). RadASM automatically updates the hla.ini file to remember your choice of colors the next time you run RadASM.
Managing Complex Projects with RadASM
One of the main reasons for using a project-oriented integrated development environment like RadASM is to streamline the development of complex projects. For the sake of argument, we'll define a "simple" project as any HLA project consisting of a single ".hla" source file and, possibly, a header file. A complex project will be any application that requires multiple source files, object modules, library modules, and resource files that must be separately compiled and linked together to form a single exectuable file. Though an IDE such as RadASM is helpful when working on simple projects, a development environment is most effective when working on larger, complex projects.
Although it is possible to maintain certain complex projects using RadASM's native capabilities, by far the best solution for complex projects is to use a make utility or (if you don't have access to a make utility) batch files to control the compilation process. Though it requires a little additional labor to set up a set of batch files or a make file, the flexibility you gain by using this approach is well worth the small amount of additional effort (effort that will be repaid many times over during the project's development).
Before describing how to write batch files and makefiles to take over control of the compilation process from RadASM, perhaps it would be wise to offer a small justification for this approach. After all, RadASM has some very sophisiticated schemes for building projects, why not stick with RadASM's native approach? Well, there are several reasons. First, although RadASM's general nature is a wonderful attribute of the system (e.g., it allows HLA to work with RadASM even though it was originally designed for MASM), sometimes a specific solution is more efficient or more powerful than a general solution. Second, although RadASM is a great development environment, sometimes it's just easier or more convenient to compile a project from the command line prompt; by using batch or make files in your RadASM projects, you can easily work from the command line or from within RadASM and know that you're building your project exactly the same way in both cases. Also, tools like the make utility have been around for quite some time and contain lots of features that you won't find in a less mature system like RadASM. Fortunately, RadASM is flexible enough to allow the use of batch and make files when working on a project, so you get the best of both worlds - the convenience of an integrated development environment, and the power and flexibility of make files.
Project Maintenance with Batch Files
The batch file approach is usable by those who do not have access to a make utility (or those who want to distribute RadASM projects to others who might not have a make utility available). Although batch files are more flexible than native RadASM builds, you should really attempt to use the make file approach unless there are some extenuating reasons why you would rather go with the batch file approach (e.g., the need to distribute RadASM/HLA projects to people who might not have a make utility).
A batch file is simple an ASCII text file that contains a sequence of command-line commands. The Windows command-line interpreter executes each line of text in a batch file just as though you'd typed those commands directly into a command window. By placing multiple commands in a batch file, you can execute as many commands as necessary to build your project. For example, suppose you have a little utility that increments a version number embedded in an HLA header file. You could execute a batch file that bumps up the version number and builds the HLA application using the following sequence of commands:
hla FileThatIncludesVersionFile.hla
Batch files also let you specify command-line parameters, e.g.,
You may refer to these command-line parameters within the batch file using %1, %2, %3, etc. For example, the default build.bat file that RadASM will create for you if you specify the use of one of the *AppBatch.tpl template files is
RadASM (by default) invokes this build.bat file using a command line like the following:
The batch file processor substitutes "filename.hla" for the "%1" within the batch file.
The big problem with RadASM's native compilation facilities is that it doesn't particularly know what files you want to compile. It will supply the main project name (or, with appropriate customization, all the files in a given project), but it won't let you easily pick and choose which files you want to process. That's where batch files (and makefiles) are useful. In a project-specific batch file, you can easily specify any or all files that you want to compile and link together into a single executable. For example, if you have a project that combines two HLA files, a resource (.rc) file, and a specialized library, you could handle this compilation with the following command in a batch file:
hla myProj.hla subroutines.hla resources.rc speciallib.lib
Such a command line could not be built (automatically) from within RadASM. This is particularly true if some of the files are not present in the project's directory (e.g., common object and library files present in a separate subdirectory).
If you create a project with one of the *AppBatch.tpl templates, or create a generic project using the hla_batch.ini file as your hla.ini file, then RadASM will, by default, connect the following Make menu items to the following batch files.
RadASM/HLA Make Menu/Batch File Correspondence
Note that the Build and Build All menu items both invoke the same batch file. The Build menu item's intent is to build the application by compiling only those files that absolutely need to be compiled. This feature is generally available only if you're using make files. Therefore, if you choose the Build menu item when using batch files, it will generally recompile all files in the application. The Compile Resource and Syntax Check menu items in the Make menu will invoke their corresponding batch files that will contain commands to compile a resource file (if any) or run the HLA compiler in a "compile to assembly" mode (no object or executable output, i.e., a syntax check of the file).
The run.bat file is somewhat special. The default run.bat file takes the following form:
RadASM will pass a command line parameter of the form "projectname.exe" to the run.bat file. Assuming that your project has compiled the files to produce the executable "projectname.exe", this batch file will execute your application and then wait until you hit the enter key before it closes up the console window that executes the batch file (this gives you the opportunity to review any output produced by console applications).
If you would prefer to execute different batch commands when selecting items from RadASM's Make menu, you can specify the commands to execute by selecting the "Project>Project Options" menu item. This opens up a dialog box that let's you specify the command line parameters for each of the menu items. See the discussion elsewhere in this document for more details.
In general, batch files are not the most appropriate way to deal with complex projects. Make files are a much better solution. Therefore, unless you absolutely have to, you should avoid using the RadASM/HLA batch file compilation scheme.
Project Maintenance with Make Files
Makefiles provide the best way to build complex projects when using RadASM/HLA. They are more efficient, they are safer, and they give you more control over the compilation process than you will get with RadASM's native mode or when using batch files. For most projects, the make file build scheme is, by far, the best. There are, of course, a couple of disadvantages to using make files. Specifically, you need to have a make utility in order to use makefiles and you need to learn the "make language" in order to use make files. Fortunately, a decent version of make is available for free from Borland and learning make is not that difficult (see the discussion of make earlier in this document). However, the advantages of make files far outweigh the disadvantages, so you should give make files serious consideration if you're not sure which RadASM/HLA compilation scheme to use.
Here are the commands that RadASM executes whenever you select an item from RadASM's make menu when using make files to build your application:
Build All menu item: make buildall
Syntax Check menu item: make syntax
Compile Resource menu item: make compilerc
These commands all assume that there is a single file, "makefile" present in the project directory. These commands will execute the build, buildall, syntax, compilerc, or run dependencies in the makefile, respectively. Here's what the default makefile (supplied with RadASM/HLA) looks like:
buildall: clean $(hlafile).exe
echo No Resource Files to Process!
$(hlafile).exe: $(hlafile).hla
hla $(DEBUG) -p:tmp $(hlafile)
For simple projects (i.e., projects consisting of a single HLA source file), you'll be able to use the makefile as-is. RadASM automatically supplies the project's name as the "hlafile" variable to build your project whenever you select an item from the RadASM "Make" menu. For more complex projects, you're going to want to edit this makefile extensively to add additional dependencies and commands.
The build dependency in this make file executes whenever someone selects the "Make>Build" menu item in RadASM. The intent of this command is to build the application with as little processing as possible. That is, if several of the files needed to build the final executable have already been compiled into object files, this command should not recompile those files, it should use the up-to-date objects as-is and only recompile those files whose source files are newer than the object files.
The buildall dependency in the makefile executes whenever someone selects the "Make>Build All" menu item in RadASM. The intent of this command is to do a complete build of the system, ignoring any object files that are already up to date. The typical execution of this command involves deleting all temporary files (e.g., object files) by executing the "clean" operation, and then doing a build.
The compilerc dependency executes whenever you select the RadASM "Make>Compile Resource" menu item. In the default make file provided with RadASM/HLA, this command simply displays a brief diagnostic message. If your project has some resource files that you need to compile with Microsoft's resource compiler, then you would normally specify the dependencies and commands needed to process those resource files after the compilerc dependency. For example, if your project includes a resource file named "myProject.rc", you'd typically edit the makefile to add/modify the following:
build: $(hlafile).exe $(hlafile).res
buildall: clean $(hlafile).exe $(hlafile).res
Of course, once you start making major modifications to the makefile, you can probably drop the use of the $(hlafile) variable and use the direct filenames (variables are great for generic makefiles; however, they tend to obscure makefiles created for a specific project). That is, for a project like "myProject" with a "myProject.hla" file and a "myProject.rc" file you'd probably just create a makefile like the following: