![]() |
![]() |
![]() |
![]() |
15 Customizing HLA
Through the use of environment variables and program names, you can create a customized version of HLA that suits your particular needs. The following subsections describe different ways you can optimize HLA for your personal use.
15.1 Changing the Location of HLA
To simplify installation and reduce installation problems, this manual suggests that you install HLA under Windows in the C:\hla subdirectory and install HLA under Linux in the /usr/hla subdirectory. If you would prefer to put the HLA system somewhere else, it's easy to do as long as you tell the system what you're doing. This is typically accomplished by setting up a couple of environment variables.
First and foremost, to be able to run the HLA compiler and associated tools, the hla.exe/hla, hlaparse.exe/hlaparse, back-end assembler (if applicable), and linker all have to be in directories in the execution path. You may either move the HLA executables to some existing directory in the OS' execution path, or you can tell the OS to include the directory containing these files in the execution path (the standard HLA installation instructions, for example, opt for this latter case).
Under Linux, for example, it's not uncommon for someone to put executables in the /usr/bin or /usr/local/bin directories. These directories are always in the execution path, so placing all the HLA executables in one of these directories under Linux would spare you having to add the /usr/hla subdirectory to your execution path.
Under Windows, there is no special directory where everyone dumps their little executable files (like /usr/local/bin under Linux). You could find an existing directory that's in the execution path and dump the HLA executables in there, however it's almost always a better idea to simply change the path environment variable so that it includes the HLA directory that contains the executables. If you've install HLA via the HLA installation program, the install program automatically sets this up for you. However, if you want to move HLA to a different directory in the future, you will need to remove the old path to HLA from your PATH environment variable and add the path to the new HLA executables to the PATH.
Changing the execution path isn't your only concern if you decide to move HLA around. The HLA compiler will also need to know where it can find the HLA include files and the hlalib.lib standard library files. Under Windows, the linker might also want to know where the hlalib.lib file can be found. If you haven't told it otherwise, HLA under Linux assumes that the include subdirectory and the hlalib subdirectory can be found in the /usr/hla subdirectory. Under Windows, HLA will first look in the same directory containing the HLA executables and, failing to find the include and hlalib directories there, it will then look in the C:\HLA subdirectory. If you've moved the HLA include and hlalib directories somewhere else, then you will need to set up environment variables to tell HLA where it can find these directories (technically, you could specify the paths to these directories on the HLA command-line, but that's so painful that you would never consider it for anything other than a temporary solution). The "hlainc" and "hlalib" environment variables serve this purpose.
Windows: set hlainc=path_to_include_directory Linux: set hlainc=path_to_include_directory export hlaincUnder Windows or Linux you can use the set command to set the hlainc environment variable to the path where HLA can find the HLA include subdirectory. For example, if you're using Windows and you've moved the HLA include files to the C:\tools\hla\hlainc subdirectory, you could use the following command to tell HLA where it can find the include file:
set hlainc=c:\tools\hla\hlaincThe hlalib environment variable specifies the complete path to the hlalib.lib file. Unlike the hlainc environment variable, this is not the path to the directory containing the library file, but the full path to the file itself. The reason this is a path to the library file rather than a path to the subdirectory containing the file is very simple: it's possible to have two or more library modules (in the same directory) and you might want to choose the most appropriate one for the job at hand. For example, you might have a debugging version of the library, an OMF version of the library, and a standard version of the library all in one directory. In any case, suppose the hlalib.a file (archive file) under Linux is located at /usr/home/rhyde/hla/hlalib/hlalib.a; you could tell Linux about this using a command like the following:
set hlalib=/usr/home/rhyde/hla/hlalib/hlalib.a export hlalib(export is a bash command that tells it to make the environment variable available to the invoking shell.)
15.2 Setting Auxiliary Paths
When assembling HLA source files using a back-end assembler such as MASM, FASM (external to HLA), Gas, or TASM, it emits a couple intermediate files for use by these back-end assemblers and the linkers. Specifically, the compilation process produces a ".asm" file for the assembler and a ".link" file for the linker. Some HLA users feel that these auxiliary files clutter up their project directory and would prefer not to see them. Fortunately, there are a couple of different ways to tell HLA to put these files in some other location besides the current project directory.
The first way to do this (which isn't really the subject of this section) is to use the "-p:<path>" command-line option to provide a temporary path for HLA to use. The advantage to using this command-line parameter is that you can set a different temporary path for each compilation. The disadvantage to this approach is that it can be a real pain to constantly set the path (if you're typing command lines manually).
A more comprehensive solution is to define the hlatmp environment variable. When HLA runs, it checks this environment variable and, if defined, uses its value to determine the path the the directory where HLA will store all temporary files. This spares you from having to place an explicit path on each command line. For example, the following command line will tell HLA to use the C:\temp (under Windows) subdirectory to hold all temporary files:
set hlatmp=c:\tempDo take care when using the hlatmp environment variable. If you compile multiple source files with the same name (presumably from different directories), then the intermediate files they produce may create conflicts. In other words, don't use the hlatmp environment variable to specify a temporary path when doing several compilations in a batch operation. Use an explicit "-p:<path>" command-line option in those cases.
15.3 Setting the Default Back-End Assembler
By default, the "HLA.EXE" (Windows) or "hla" (Linux) programs use an internal version of FASM to directly produce an object file from the translation of the input HLA source file. For reasons explained earlier, you might want to override this default selection and use one of the back-end assemblers that HLA supports (MASM, TASM, or FASM under Windows, or FASM or GAS under Linux). There are three ways to do this: via command-line parameters, by changing the name of the HLA.EXE (Windows) or hla (Linux) programs, or by the "hla" environment variable.
As described earlier, the -co, -cf, -cm, -ct, and -cg let you specify which assembly language syntax and back-end assembler HLA will use to produce an object code file. The default is "-co" which uses the internal version of FASM to directly produce an object code file without using an intermediate assembly language file. The other options all produce an intermediate assembly language source file and use the associated assembler (if possible under the current operating system) to translate that assembly language source file into an object code file.
If you would like to change the default so you don't have to specify a "-cX" command-line option all the time, you can rename the "HLA.EXE" (Windows) or "hla" (Linux) program name to one of the following:
If you commonly switch between the different assembly language source formats for some reason, you can make copies of the "HLA.EXE" (Windows) or "hla" (Linux) program files so you don't have to constantly rename them. Note that the language level options also allow you to change HLA's behavior by renaming the HLA executable file. However, you may only use this technique to choose the language level or choose the back-end assembler, not both. The language level option is really for beginning students in a formal assembly language programming class; and those students would almost never care about what back-end assembler HLA is using. Conversely, choosing a back-end assembler via the program name is something that an advanced HLA user would do and such users would rarely operating HLA at any language level other than "high". Therefore, there really isn't the need to make it possible to support both sets of options via a program name change. If you really need to operate at a different language level and exercise control over the back-end assembler on the same project, use command-line options or environment variables.
A third option you can use to control HLA's back-end assembler is to use the "hla" environment variable. When you run one of the programs listed in the previous, the program first detemines whether it's name is "HLA.EXE" (Windows) or "hla" (Linux); if so, then the program checks for the "hla" environment variable to determine how the program should behave. The possible environment variable settings are given in the following table:
15.4 Setting the Default Linker
The HLA system currently employs one of three different linkers to combine the output object and library files into an executable:
Microsoft's linker (link.exe) - The default when compiling HLA code to MASM or TASM source under Windows.
The Pelles C linker (polink.exe) - The default when compiling HLA code to .obj files under Windows using the internal or external versions of FASM.
The FSF/GNU ld linker - This is the default, under non-Windows operating systems, when compiling HLA code to .o files using FASM (internal or external) or when compiling HLA code to Gas-syntax .asm files.
Note that polink and Microsoft's linker are usable only under Windows and the FSF/GNU ld linker is usable only under non-Windows operating systems. The following table more clearly shows the default and optional linker possibilities:
Assembler Default linker under Windows Linker choices under Windows Linker for Linux, FreeBSD, MacOS, etc. MASM link.exe1 link.exepolink.exe n/a TASM link.exe link.exepolink.exe FASM (internal version) polink.exe link.exepolink.exe ld FASM(external version) polink.exe link.exepolink.exe ld Gas n/a n/a ld
Under non-Windows operating systems (e.g., Linux) the only choice is the GNU/FSF ld linker. If you attempt to force the use of one of these other linkers, HLA will issue a warning and use ld instead. Under Windows, the HLA system (directly) supports either the Microsoft linker or the Pelles C linker. HLA defaults to polink for FASM because the HLA/FASM/POLINK combination consists of freely distributable software and many HLA users prefer to use free software. For MASM and TASM, HLA defaults to using the Microsoft linker as it is a bit more complementary to these tools.
Note that HLA does not provide direct support for the Borland TLINK program, but there is nothing stopping you from using TLINK to process OMF files produced by running HLA output through either MASM or TASM (HLA does not support OMF output via FASM, sorry). This is quite useful, for example, when combing HLA-produced output with other Borland tools that depend on the use of TLINK (e.g., Borland C++ or Delphi). However, as HLA does not directly support TLINK, this document will not discuss that option further.
Because Windows supports two different linkers (each as the default for certain assemblers), the natural questions arise: "How do I change the linker choice from the default?" and "How do I change the default linker choice?" As usual for HLA, there are a couple ways to achieve this goal.
The first way to change the default linker choice is via a command-line parameter. Specifically, under Windows you can use either the "-mslink" or "-polink" command-line parameter to force the use of that linker for the current compilation operation. This will not affect the linker choice for future compilations.
Of course, selecting a different assembler on the command-line also selects the default linker for that assembler. Because there is a potential conflict when specifying both types of command-line parameters, plus the fact that HLA gives precedence to the last command-line parameter when there is any ambiguity, if you specify both an assembler and a linker on the command line, you should always specify the linker option last, e.g.,
hla -xm -polink t.hla // Compile using MASM and polink hla -xf -mslink u.hla // Compile using (external) FASM and Microsoft's linkerThe last way to specify the default linker to use, which operates in a global fashion, is via the 'hlalink' environment variable. You can set the hlalink environment variable to one of the following three values: mslink, polink, or ld, e.g.,
set hlalink=mslinkNote that "mslink" and "polink" are valid only under Windows and "ld" is only valid under non-Windows operating systems (which makes setting the hlalink environment variable under Linux rather pointless, to be honest). If you have defined the hlalink environment variable to some reasonable value for the operating system you're using, then this overrides all the default cases and only a command-line parameter to specify a different linker will take precedence. That is, if you use one of the auxiliary HLA names such as MHLA, FHLA, or THLA, HLA will continue to use the linker you've specified by the hlalink environment variable. Likewise, even if you temporarily choose a different assembler with a "-xm", "-xf", "-xt", or "-xo" command-line parameter, HLA will still continue to use the default linker you've specified by the hlalink environment variable. The only way to override this is to delete the environment variable (i.e., by the command-line "set hlalink=") or by using one of the "-mslink", "-polink", or "-ld" command-line parameters.
Why would someone want to change the default linker? Well, defects in the linkers themselves could be an issue. For example, a known issue in POLINK is that it emits a (harmless) warning whenever linking HLA-compiled programs. If this warning message annoys you (and it does annoy some people), you can switch the default linker to Microsoft and avoid this message. For some other reason, you might want to set the default linker to POLINK, even when using TASM or MASM as the HLA back-end assembler. Whatever the reason, it's nice to have the choice and be able to configure the system however you please.
![]() |
![]() |
![]() |
![]() |
![]() |