TOC PREV NEXT INDEX

Put your logo here!


13 Using the HLA Command-Line Compiler


This section assumes that you are running the standard version of HLA. If you want to run "freeHLA" rather than the standard version under Windows, then simply substitute the command "fhla" for "hla" throughout this documentation.

Once you've installed HLA and verified that it is operational, you can run the HLA compiler. The HLA compiler consists of two executables: hla(.exe)1, which is a shell that processes command line arguments, compiles ".hla" files to ".asm" files, assembles the ".asm" files by calling an assembler, and links the resulting files together using a linker program; the second executable is hlaparse(.exe) which compiles a single ".hla" file to an assembly language file. Generally, you would only run hla(.exe). The hla(.exe) program automatically runs the hlaparse(.exe) and assembler/linker programs. The hla(.exe) command uses the following syntax:

hla  optional_command_line_parameters  Filename_list
 

The filenames list consists of one or more unambiguous filenames having the extension: ".hla", ".asm" or ".obj"/".o"2. HLA will first run the hlaparse(.exe) program on all files with the HLA extension (producing files with the same basename and an ASM extension). Then HLA runs the assembler on all files with the ".asm" extension (including the files produced by hlaparse). Finally, HLA runs the linker to combine all the object files together (including the ".obj"/".o" files the assembler produces). The ultimate result, assuming there were no errors along the way, is an executable file (with an EXE extension under Windows, with no extension under Linux).

HLA supports the following command line parameters:

  
 
 options:
 
  -@        Do not generate linker response file.
 
  -@@       Always generate a linker response file.
 
  -axxxxx   Pass xxxxx as command line parameter to assembler.
 
  -dxx      Define VAL symbol xx to have type BOOLEAN and value TRUE.
 
  -dxx=yy   Define VAL symbol xx to have type STRING and value "yy".
 
  -e:name   Executable output filename.
 
  -i:path   Specifies path to HLA include file directory.
 
  -lib:path Specifies path to the HLALIB.LIB file.
 
  -license  Displays copyright and license info for the HLA system.
 
  -lxxxxx   Pass xxxxx as command line parameter to linker.
 
            (note: use -lLIBPATH=<path> to specify path to HLALIB.LIB)
 
  -m        Create a map file during link
 
  -p:path   Specifies path to hold temporary working files.
 
  -r:name   <name> is a text file containing cmd line options.
 
  -obj:path Specifies path to place object files.
 
  -o:omf    Produce OMF files (default - tasm).
 
  -o:coff   Produce win32 COFF files.
 
  -o:elf    Produce Linux ELF files.
 
  -s        Compile to .ASM files only.
 
  -sf       Compile to FASM files only.
 
  -sg       Compile to Gas files only.
 
  -sm       Compile to MASM files only (default for -s).
 
  -st       Compile to TASM files only.
 
  -c        Compile and assemble to object files only.
 
  -co       Compile and assemble to object file using internal version of FASM
 
  -cf       Compile and assemble to object file using FASM
 
  -cm       Compile and assemble to object file using MASM
 
  -ct       Compile and assemble to object file using TASM
 
  -cg       Compile and assemble to object file using GAS
 
  -xo       Compile/assemble/link to executable using internal version of FASM
 
  -xf       Compile/assemble/link to executable using FASM
 
  -xm       Compile/assemble/link to executable using MASM
 
  -xt       Compile/assemble/link to executable using TASM
 
  -xg       Compile/assemble/link to executable using GAS
 
  -sym      Dump symbol table after compile.
 
  -test     Send diagnostic info to stdout rather than stderr (This
 
             option is intended for HLA test/debug purposes).
 
  -v        Verbose compile.
 
  -level=h  High-level assembly language
 
  -level=m  Medium-level assembly language
 
  -level=l  Low-level assembly language
 
  -level=v  Machine-level assembly language (very low level).
 
  -w        Compile as windows app (default is console app).
 
  -?        Display this help message.
 

 

Note that HLA ignores case when processing command line parameters (unlike typical Linux programs). Hence, "-s" is equivalent to "-S" (for example) when specifying a command line parameter.

-@
-@@

Under Windows, HLA will produce a "linker response file" that it supplies to the Microsoft LINK.EXE (or POLINK.EXE) program during the link phase. This linker response file contains necessary segment declarations and other vital linker information. By default, HLA uses any existing ".LINK" file whenever you run the compiler; it will create a new "xxx.link" file only if one does not already exist. The "-@" option tells HLA not to create a new ".LINK" file, even if one does not already exist. The "-@@" option tells HLA to always create a ".link" file, even if one already exists.

If you specify multiple ".HLA" filenames on the command line, HLA only generates a single ".LINK" file using the name of the first ".HLA" file it encounters. Linux's ld program does not require this linker response file, so the Linux version of HLA does not produce this file.

-r:filename

The "-r:filename" option lets you specify a response file containing a sequence of HLA command-line parameters. The file specified after this option must contain a seqeuence of HLA command-line parameters, one per line, which HLA executes exactly as though they were specified on the command line. E.g.,


 
sampleFile.resp:
 

 
-cf
 
sampleFile.hla
 

 
The following command treats each of the above lines as separate HLA command-line parameters:
 

 
hla -r:sampleFile.resp
 

 

 

-aXXXXX

The -aXXXXX option lets you pass assembler-specific command line options to the assembler during the assembler phase. This option is ignored if you use one of the -s options. One common form of this command often used with the MASM assembler is "-aFi -aFz" that tells MASM to generate debugging information in the object file (for use with the OllyDbg debugger program).

-c

The -c option tells HLA to run the hlaparse compiler and the (default) assembler, producing ".obj"/".o" files. HLA will process all filenames on the command line that have ".hla" or ".asm" extension, but it will ignore any filenames with ".obj" extensions. If you compile an HLA unit without compiling an HLA program at the same time, you will need to use this option or the linker will complain about not finding the main program. You may specify the ".obj"/".o" file format using the COFF or OMF command line options (MASM only, TASM always produces OMF files, Gas always produces ELF files, and FASM always produces COFF files).

One common use of this option is to compile HLA units to OBJ files. Since HLA units do not contain a main program, you cannot compile an HLA unit directly to an executable. To compile an HLA unit separately (i.e., without compiling an HLA main program during the same HLA.EXE invocation) you must specify the "-c" option or the compilation will generate an error when it attempts to link the program.

A second reason for using the "-c" option is because you want to explicitly run the linker yourself and supply linker command line options that are different than those that HLA automatically provides.

-co

Compiles an HLA source file directly to an object file using the internal version of FASM (overriding the default assembler). Otherwise, the actions are identical to -c.

-cf

Compiles an HLA source file to a FASM source file and then compile this source file to an object file using an external version of FASM (overriding the default assembler). Otherwise, the actions are identical to -c.

-cm

Compiles an HLA source file to a MASM source file and then compile this source file to an object file using MASM (overriding the default assembler). Otherwise, the actions are identical to -c. Note that this option is available only under Windows.

-ct

Compiles an HLA source file to a TASM source file and then compile this source file to an object file using TASM (overriding the default assembler). Otherwise, the actions are identical to -c. Note that this option is available only under Windows.

-cg

Compiles an HLA source file to a Gas source file and then compile this source file to an object file using Gas (overriding the default assembler). Otherwise, the actions are identical to -c. Note that this option is available only under non-Windows operating systems.

-xo

Compiles an HLA source file directly to an object file using the internal version of FASM (overriding the default assembler). Links the result to produce an exectuable file. Under Windows, this option uses POLINK as the default linker unless overriden. Under Linux, this command option uses the GNU LD linker.

-xf

Compiles an HLA source file to a FASM source file and then compile this source file to an object file using an external version of FASM (overriding the default assembler). Then links the result to produce an executable file. Under Windows, this option uses POLINK as the default linker unless overriden. Under Linux, this command option uses the GNU LD linker.

-xm

Compiles an HLA source file to a MASM source file and then compile this source file to an object file using MASM (overriding the default assembler). Links the resulting object file to produce an executable (Microsoft's linker is the default linker). Note that this option is available only under Windows. Under Linux, this command-line option is identical to "-sf".

-xt

Compiles an HLA source file to a TASM source file and then compile this source file to an object file using TASM (overriding the default assembler). Then links the result to produce an executable (Microsoft's linker is the default linker it uses). Under Linux, this option only produces a source file; it will not run TASM or the linker to produce an executable (that is, this command is equal to "-st" under Linux).

-cg

Compiles an HLA source file to a Gas source file and then compile this source file to an object file using Gas (overriding the default assembler). Runs GNU's LD linker to produce an executable (under Linux). If you use this option under Windows, it will not assemble and link the result (that is, this option is equal to "-sg" under Windows).

-d:XXXXX{=YYYYY}

The -dXXXXX option tells HLA to define the symbol XXXXX as a boolean VAL constant and initialize it with the value TRUE. Generally you use such symbols to control the emission of code during assembly using statements like "#if( @defined( XXXXX )) ..."

The -dXXXX=YYYY option tells HLA to define the symbol XXXX as a string VAL constant and give it the initial value "YYYY".

-e:name

By default, HLA creates an executable filename using the extension ".exe" (Windows) or without an extension (Linux) and the basename of the first filename on the command line. You can use the -e name option to specify a different executable file name.

-lXXXXX

The -lXXXXX option passes the text XXXXX on to the linker as a command line option. One common command to pass to the Microsoft linker is "-lDEBUG -lDEBUGTYPE:COFF" that tells the linker to generate debugging information in the object file (for use with the OllyDbg debugger program).

-m

The -m option tells the Microsoft linker or POLINK to produce a map file during the link phase. This is equivalent to the "-lmap" option. The Linux version of HLA ignores this option.

-o:omf

The -o:omf option tells the underlying assembler (MASM or TASM) to produce an Object Module Format (OMF) OBJ file. This option is generally applicable only to MASM since TASM always produces OMF files. This option is not legal when using the Gas or FASM assemblers.

-o:coff

The -o:coff option instructs the assembler to generate a COFF OBJ file. This option is the default for MASM/FASM and may not be available for other assemblers. This option is only available under Windows.

-s

The -s option tells the HLA/FHLA program to run only the hlaparse compiler to produce an assembly language source file; HLA will not run an assembler or linker. As a result, HLA ignores any ".asm" or ".obj" filenames you supply on the command line. This option is useful if you wish to view the output of an HLA compilation without producing any actual object code. If you specify this option with a version of HLA that would normally produce an object file output, HLA will emit a FASM-compatible source file instead.

-st

The -st option tells HLA to produce TASM-compatible assembly and stop after compilation. Note that the source file you produce will contain Windows-specific code, even if you produce the TASM-compatible source file under Linux.

-sm

The -sm option tells HLA to produce MASM-compatible assembly and stop after compilation. Note that the source file you produce will contain Windows-specific code, even if you produce the MASM-compatible source file under Linux.

-sg

The -sg option tells HLA to produce Gas-compatible assembly and stop after compilation. Note that the source file will contain Linux-specific code even if you produce the source file under Linux.

-sf

The -sf option tells HLA to produce FASM-compatible assembly and stop after compilation. Unlike the other source output forms, FASM output is specific to the underlying OS on which you ran HLA. That is, using the -sf option under Windows produces Windows-specific output, using the -sf option under Linux produces a Linux-compatible file.

-sym

The -sym option dumps the symbol table after compiling each file with an HLA extension. This option is primarily intended for testing and debugging the HLA compiler; however, this information can be useful to the HLA programmer on occasion.

-test

The -test option is intended for hlaparse testing and debugging purposes only. It causes the compiler to send all error messages to the standard output device rather than the standard error device. This allows the test code to redirect all errors to a text file for comparison against other files.

-v

The -v option (verbose) causes HLA to print additional information during compile to show the progress of the compilation. Due to a bug in MASM, if you do not specify the -v option the compilation isn't completely quiet. MASM will still output data to the standard error device even in quiet (non-verbose) mode.

-w

The -w option informs HLA that you are compiling a standard Windows (GUI) application rather than a console application. By default, HLA assumes that you are compiling a executable that will run from the command window. If you want to write a full Windows application, you will need to supply this option to tell HLA not to link the code for console operation. Obviously, this option doesn't apply to Linux systems.

The "-w" option tells HLA to invoke the linker using the command line option

-subsystem:windows

rather than the default

-subsystem:console

This provides a convenient mechanism for those who wish to create win32 GUI applications. Most likely, however, if you wish to create GUI applications, you will run the linker explicitly yourself (as this document will explain), so you'll probably not use the "-w" option very frequently. It's great for some short GUI demos, but larger GUI programs will probably not use this option. This option is only active if HLA compiles the program to an executable. If you compile the program to an OBJ or ASM file, HLA ignores this option.

If you want to develop Win32 GUI apps, take a look at Randy Hyde's book "Windows Programming in Assembly". This book provides the linker commands and makefiles for generation such applications (as well as describing how you actually write such code).

-p:path

During compilation, HLA produces several temporary files (that it doesn't delete, because they may be of interest to the HLA user). These files have a habit of cluttering up the current work directory. If you prefer, you can tell HLA to place these files in a temporary directory so they don't clutter up your working directory. One way to accomplish this is by using the "-p:dirpath" command line option. For example, the option "-p:c:\hla\tmp" tells HLA to put all temporary files (for the current assembly) into the "c:\hla\tmp" subdirectory (which must exist). Note that you can set also set the temporary directory using the hla "hlatemp" environment variable. The "-p:dirpath" option will override the environment variable (if it exists). See the description of the hlatemp environment variable for more details. Warning: as of FASM v1.51, the use of this option with FHLA is not recommend because of the way FASM handles include files. FASM's author is aware of this issue and will probably do something about it at some point. Until then, you should always CD into the directory where your HLA projects lie and leave all the temporary files in that same folder when running FHLA.EXE. This restriction will be relaxed in a future version of FHLA/FASM.

-obj:path

During compilation, HLA normally writes all object files to the current working directory. Some programmers have requested a way to specify a different directory for the .OBJ (.o under Linux) files that HLA produces. This is now accomplished using the "-obj:dirpath" command line option. The dirpath item has to be the path to a valid directory. HLA places all object files produced by the compiler and/or resource editor in this directory. Note that, unlike the -p option, there is no environment variable that lets you permanently set this path. You must specify the path on a compilation by compilation basis (use a makefile if you get tired of typing the path in on each compilation).

-level=h

-level=m

-level=l

-level=v

The -level options enable or disable certain HLA language features. These command-line options are intended for use in programming courses where the instructor needs to batch compile dozens or even hundreds of student projects at one time and the instructor would like a convenient way to ensure that the students aren't using high-level control constructs that are inappropriate for that point in the course (e.g., towards the end of a course, most instructors don't allow the use of various high-level control constructs; some instructors may never allow them). The "-level" command-line options will "turn off" various statements in the HLA language so that the HLA compiler will report an error if the student attempts to use them in a source file.

The default, "-level=h" (high) enables the entire HLA language.

The "-level=m" (medium level) disables high-level language control constructs, such as "if", "while", and "for" but still allows the use of high-level-like procedure calls in the HLA language. Medium-level assembly language also allows the use of exceptions using HLA's try..except..endtry and raise statements.

The "-level=l" (low-level assembly) disables all high-level control constructs other than the exception-handling statements and disables high-level-like procedure calls in HLA. This option also disables automatic stack frame generation and clean up in HLA procedures (that is, the programmer will be responsible for writing that code themselves).

The "-level=v" (very low-level assembly) option disables all high-level control constructs including exception handling. Only machine instructions (and user written macros) are legal in the source file. No high-level control constructs or high-level procedure calls are allowed.

-?

The -? option cause HLA to dump the list of command line options and immediately quit without further work.

Note that the command line options this document describes are for HLA v1.87 and later only. Earlier versions of HLA used a different command line set. See the documentation for the specific version you're using if you have questions.

-license

This command displays license information for the entire HLA system. Although the HLA source code written by Randall Hyde is all public domain, certain components of the HLA system, including the back-end assembler, the linker, and the resource editor, come from other sources. The "-license" command-line parameter lists license information about these other products.

1The ".exe" suffix appears only in the Windows' version.
2Windows object files use the ".obj" suffix while Linux object files have the ".o" suffix. Although Linux users who write assembly code with Gas typically use a ".s" or ".S" suffix, HLA still uses ".asm" since Gas happily accepts this.


TOC PREV NEXT INDEX