Contents of TSE's compile.hlp file
Add Compiler->Command
Compiler to execute when this extension is selected.
The command field is used to specify the action to take when this
compiler is selected. The command usually specifies a compiler to
execute as well as any arguments which need to be passed to the
compiler. The command can actually be one of three types:
1. Single DOS command
2. Sequence of DOS commands
3. TSE macro
And within each of these command types, substitution variables may
be specified (discussed below).
Types of commands
To specify a Single DOS command, simply specify the command to
execute and any parameters it takes (see the "Variable" text
information below)
For example, to invoke the Turbo C compiler use a command such as:
tcc -c &fn& > &output&
To specify a Sequence of DOS commands, separate each of the commands
and their arguments with the ';' symbol. This will cause a temporary
batch file "$$tmp$$.bat" to be created and executed. To specify a
literal ';' specify '\;'.
For example, use the following to invoke the commands 'pre.exe'
and 'post.exe commands':
echo off;pre &fn& > &name&.err;post &name&.err > &output
To specify a TSE macro to execute, the first character of the
command must be the '@' symbol.
For example, to invoke a macro 'compare' specify:
@compare
Variable substitution
Within the command line, the user can specify "variable" text which
depends on the current file, global variables, or the DOS environment.
"Variable" information is specified by using the '&' or '%' symbols:
& The '&' symbol is used to replace text with either a pre-defined
compiler variable or a TSE global variable.
To specify a global variable set by the SetGlobalStr() or
SetGlobalInt() command, enclose the variable name within '&'
symbols, such as &what_to_do&.
The following keywords have special meaning:
KeyWord Replaced with:
-------- -------------------------------------------------------
&Fn& The full filename (including drive, path and
extension) of the current file
&Drive& The drive of the current file (excluding the colon)
&Path& The path of the current file (excluding the drive,
filename, and extension). Also, the trailing
backslash is not included.
&Name& The name of the current file (excluding the drive,
path, and extension).
&Ext& The extension of the current file (excluding the '.')
&Output& The name of the file in which the errors will
appear.
% The '%' symbol is used to replace text based on environment
variables.
For example, to call SC and specify an output directory given by
a TSE_MACRO_DIR environment variable:
sc &fn& %TSE_MACRO_DIR% > &output&;
Note: The '%' symbol is actually processed by DOS requires the
creation of a temporary batch file by using the ';' symbol.
(see example above). In order for a single command to utilize
environment variables, a trailing ';' must be given.
For both the Single DOS command and the Sequence of DOS commands formats,
the Output type has additional meaning.
Add Compiler->Description
Your personal description for identification from
within the List of Compilers.
Add Compiler->Extension
Extension of file to compile
Add Compiler->Output
When the compiler is invoked, the screen updating is affected
by this option.
The five possible settings are:
Clear screen and prompt after shell
--- compiler output is not redirected
--- prompt after running compiler
Clear screen but don't prompt after shell
--- compiler output is not redirected
--- do not prompt after running compiler
Don't clear screen or prompt after shell
--- compiler output is redirected
--- do not prompt after running compiler
*Tee output and don't prompt after shell
--- compiler output is redirected and appears on the
screen as the compiler is running.
--- do not prompt after running compiler
Tee Output, Run Hidden and Don't Prompt After Shell
--- compiler output is redirected and DOES NOT appear
on the screen as the compiler is running.
--- do not prompt after running compiler
*This option is the most commonly used and is the most beneficial
for debugging new compiler setups.
Add Compiler->Rules
The error output format is unique for each compiler. The Rules menu
allows these unique formats to be deciphered as long as the formats
are regular.
See the Rules Overview section for more details.
AdvancedSetupMenu->Merge Data File
This facility is useful when upgrading from a previous version of TSE in
which the user added additional compilers to their compiler setup list.
By selecting this option, the previous compiler setup information will
be copied into the current compiler setup file. Any duplicate entries
will be ignored.
AdvancedSetupMenu->TSE Debugger Extension
By default, The SemWare Editor uses the setup for the ".s" extension for
compiling macros with debug information. If more than one ".s"
extension is necessary, the user can copy the ".s" setup to a unique
extension such as ".!!!" and then specify a "TSE Debugger Extension" of
".!!!" for purposes of compiling macros with debug information.
Compile from list
Lists the compilers for the current extension and allows the user to
add, edit, copy, delete, or execute the desired compiler. If no
compilers exist for the current extension, all compilers are listed.
Within the list several keys have special meaning:
<Enter> Execute compiler *
<Escape> Close compiler list
<Ctrl Enter> Toggle full/short list of compilers
<Ins> Add new compiler
<Del> Delete compiler
<Alt C> Copy compiler setup
<Alt E> Edit compiler setup
* Note: Executing a compiler from the list makes it the primary
compiler for that extension.
Compile Menu->Advanced Setup
The advanced setup menu is used to customize the compiler setup. These
features are only necessary for users who customize or add additional
compilers.
Compile Menu->Close error window
Closes the error window and places the cursor back in the source
window. If the "Previous Error" key <Alt F7> or "Next Error" key
<Alt F8> are pressed, the error window is reopened.
Compile Menu->Compile current file
Compiles the current file by using its extension to determine the
primary compiler to invoke. To change the compiler for this
extension, select the Compile from list menu option.
If no compiler is found for the current extension, the list of
compilers is displayed.
Compile Menu->Compile from list
Lists the compilers for the current extension and allows the user to
add, edit, copy, delete, or execute the desired compiler. If no
compilers exist for the current extension, all compilers are listed.
Within the list several keys have special meaning:
<Ins> Add new compiler
<Del> Delete compiler
<Alt C> Copy compiler setup
<Alt E> Edit compiler setup
<Enter> Execute compiler
<Escape> Close compiler list
Note: Executing a compiler from the list makes it the primary
compiler for that extension.
Compile Menu->Debug Compiler Setup
Runs the selected compiler and displays information as it
locates errors in the file being compiled.
This feature is useful when setting up a new compiler or
when determining why a setup is not responding as expected.
Compile Menu->Help on keys
Displays key assignments for the compile macro.
Compile Menu->Next error
Places the cursor on the next error (if any) and displays the error
message on the status line.
This key is available from both the source or error window.
Compile Menu->Previous error
Places the cursor on the previous error (if any) and displays the
error message on the status line.
This key is available from both the source or error window.
Compile Menu->Switch window
Toggles the active display from the current editing window to the
error window and vice-versa.
Compiler Key Assignments
Key Assignments within the 'Errors' window:
Help <F1>
Previous Error <CursorUp> or <Alt F7>
Next Error <CursorDown> or <Alt F8>
First Error <Home> or <Ctrl PgUp>
Last Error <End> or <Ctrl PgDn>
Next Page <PgUp>
Previous Page <PgDn>
Go to Error <Enter> or <Escape>
Load Macro File <Ctrl Enter>
Key Assignments within the 'source' file:
Previous Error <Alt F7>
Next Error <Alt F8>
Switch Window <Undefined>
Compile Menu <Shift F9>
Compile File <Ctrl F9>
CompilerSetupMenu->Command
Compiler to execute when this extension is selected.
The command field is used to specify the action to take when this
compiler is selected. The command usually specifies a compiler to
execute as well as any arguments which need to be passed to the
compiler. The command can actually be one of three types:
1. Single DOS command
2. Sequence of DOS commands
3. TSE macro
And within each of these command types, substitution variables may
be specified (discussed below).
Types of commands
To specify a Single DOS command, simply specify the command to
execute and any parameters it takes (see the "Variable" text
information below)
For example, to invoke the Turbo C compiler use a command such as:
tcc -c &fn& > &output&
To specify a Sequence of DOS commands, separate each of the commands
and their arguments with the ';' symbol. This will cause a temporary
batch file "$$tmp$$.bat" to be created and executed. To specify a
literal ';' specify '\;'.
For example, use the following to invoke the commands 'pre.exe'
and 'post.exe commands':
echo off;pre &fn& > &name&.err;post &name&.err > &output
To specify a TSE macro to execute, the first character of the
command must be the '@' symbol.
For example, to invoke a macro 'compare' specify:
@compare
Variable substitution
Within the command line, the user can specify "variable" text which
depends on the current file, global variables, or the DOS environment.
"Variable" information is specified by using the '&' or '%' symbols:
& The '&' symbol is used to replace text with either a pre-defined
compiler variable or a TSE global variable.
To specify a global variable set by the SetGlobalStr() or
SetGlobalInt() command, enclose the variable name within '&'
symbols, such as &what_to_do&.
The following keywords have special meaning:
KeyWord Replaced with:
-------- -------------------------------------------------------
&Fn& The full filename (including drive, path and
extension) of the current file
&Drive& The drive of the current file (excluding the colon)
&Path& The path of the current file (excluding the drive,
filename, and extension). Also, the trailing
backslash is not included.
&Name& The name of the current file (excluding the drive,
path, and extension).
&Ext& The extension of the current file (excluding the '.')
&Output& The name of the file in which the errors will
appear.
% The '%' symbol is used to replace text based on environment
variables.
For example, to call SC and specify an output directory given by
a TSE_MACRO_DIR environment variable:
sc &fn& %TSE_MACRO_DIR% > &output&;
Note: The '%' symbol is actually processed by DOS requires the
creation of a temporary batch file by using the ';' symbol.
(see example above). In order for a single command to utilize
environment variables, a trailing ';' must be given.
For both the Single DOS command and the Sequence of DOS commands formats,
the Output type has additional meaning.
CompilerSetupMenu->Description
Your personal description for identification from
within the List of Compilers.
CompilerSetupMenu->Extension
Extension of file to compile
CompilerSetupMenu->Output
When the compiler is invoked, the screen updating is affected
by this option.
The five possible settings are:
Clear screen and prompt after shell
--- compiler output is not redirected
--- prompt after running compiler
Clear screen but don't prompt after shell
--- compiler output is not redirected
--- do not prompt after running compiler
Don't clear screen or prompt after shell
--- compiler output is redirected
--- do not prompt after running compiler
*Tee output and don't prompt after shell
--- compiler output is redirected and appears on the
screen as the compiler is running.
--- do not prompt after running compiler
Tee Output, Run Hidden and Don't Prompt After Shell
--- compiler output is redirected and DOES NOT appear
on the screen as the compiler is running.
--- do not prompt after running compiler
*This option is the most commonly used and is the most beneficial
for debugging new compiler setups.
CompilerSetupMenu->Rules
The error output format is unique for each compiler. The Rules menu
allows these unique formats to be deciphered as long as the formats
are regular.
See the Rules Overview section for more details.
Output File
The output file defaults to '$$err$$.err'. It is placed in the
same directory as the compile macro. The output file can be changed
by editing the compile macro, changing the "output_fn[]" variable,
and recompiling the compile macro. If no path is specified for the
output file, it is placed in the same directory as the compile
macro. Otherwise, the path is honored.
Output type
When the compiler is invoked, the screen updating is affected
by this option.
The five possible settings are:
Clear screen and prompt after shell
--- compiler output is not redirected
--- prompt after running compiler
Clear screen but don't prompt after shell
--- compiler output is not redirected
--- do not prompt after running compiler
Don't clear screen or prompt after shell
--- compiler output is redirected
--- do not prompt after running compiler
*Tee output and don't prompt after shell
--- compiler output is redirected and appears on the
screen as the compiler is running.
--- do not prompt after running compiler
Tee Output, Run Hidden and Don't Prompt After Shell
--- compiler output is redirected and DOES NOT appear
on the screen as the compiler is running.
--- do not prompt after running compiler
*This option is the most commonly used and is the most beneficial
for debugging new compiler setups.
OutputMenu->Clear Screen and Prompt After Shell
When the compiler is invoked, the screen updating is affected
by this option.
The five possible settings are:
Clear screen and prompt after shell
--- compiler output is not redirected
--- prompt after running compiler
Clear screen but don't prompt after shell
--- compiler output is not redirected
--- do not prompt after running compiler
Don't clear screen or prompt after shell
--- compiler output is redirected
--- do not prompt after running compiler
*Tee output and don't prompt after shell
--- compiler output is redirected and appears on the
screen as the compiler is running.
--- do not prompt after running compiler
Tee Output, Run Hidden and Don't Prompt After Shell
--- compiler output is redirected and DOES NOT appear
on the screen as the compiler is running.
--- do not prompt after running compiler
*This option is the most commonly used and is the most beneficial
for debugging new compiler setups.
OutputMenu->Clear Screen but Don't Prompt After Shell
When the compiler is invoked, the screen updating is affected
by this option.
The five possible settings are:
Clear screen and prompt after shell
--- compiler output is not redirected
--- prompt after running compiler
Clear screen but don't prompt after shell
--- compiler output is not redirected
--- do not prompt after running compiler
Don't clear screen or prompt after shell
--- compiler output is redirected
--- do not prompt after running compiler
*Tee output and don't prompt after shell
--- compiler output is redirected and appears on the
screen as the compiler is running.
--- do not prompt after running compiler
Tee Output, Run Hidden and Don't Prompt After Shell
--- compiler output is redirected and DOES NOT appear
on the screen as the compiler is running.
--- do not prompt after running compiler
*This option is the most commonly used and is the most beneficial
for debugging new compiler setups.
OutputMenu->Don't Clear Screen or Prompt After Shell
When the compiler is invoked, the screen updating is affected
by this option.
The five possible settings are:
Clear screen and prompt after shell
--- compiler output is not redirected
--- prompt after running compiler
Clear screen but don't prompt after shell
--- compiler output is not redirected
--- do not prompt after running compiler
Don't clear screen or prompt after shell
--- compiler output is redirected
--- do not prompt after running compiler
*Tee output and don't prompt after shell
--- compiler output is redirected and appears on the
screen as the compiler is running.
--- do not prompt after running compiler
Tee Output, Run Hidden and Don't Prompt After Shell
--- compiler output is redirected and DOES NOT appear
on the screen as the compiler is running.
--- do not prompt after running compiler
*This option is the most commonly used and is the most beneficial
for debugging new compiler setups.
OutputMenu->Tee Output and Don't Prompt After Shell
When the compiler is invoked, the screen updating is affected
by this option.
The five possible settings are:
Clear screen and prompt after shell
--- compiler output is not redirected
--- prompt after running compiler
Clear screen but don't prompt after shell
--- compiler output is not redirected
--- do not prompt after running compiler
Don't clear screen or prompt after shell
--- compiler output is redirected
--- do not prompt after running compiler
*Tee output and don't prompt after shell
--- compiler output is redirected and appears on the
screen as the compiler is running.
--- do not prompt after running compiler
Tee Output, Run Hidden and Don't Prompt After Shell
--- compiler output is redirected and DOES NOT appear
on the screen as the compiler is running.
--- do not prompt after running compiler
*This option is the most commonly used and is the most beneficial
for debugging new compiler setups.
OutputMenu->Tee Output, Run Hidden and Don't Prompt After Shell
When the compiler is invoked, the screen updating is affected
by this option.
The five possible settings are:
Clear screen and prompt after shell
--- compiler output is not redirected
--- prompt after running compiler
Clear screen but don't prompt after shell
--- compiler output is not redirected
--- do not prompt after running compiler
Don't clear screen or prompt after shell
--- compiler output is redirected
--- do not prompt after running compiler
*Tee output and don't prompt after shell
--- compiler output is redirected and appears on the
screen as the compiler is running.
--- do not prompt after running compiler
Tee Output, Run Hidden and Don't Prompt After Shell
--- compiler output is redirected and DOES NOT appear
on the screen as the compiler is running.
--- do not prompt after running compiler
*This option is the most commonly used and is the most beneficial
for debugging new compiler setups.
Rules Overview
The error output format is unique for each compiler. The Rules menu
allows these unique formats to be deciphered as long as the formats
are regular.
The error marks themselves are usually redirected to the
output file. But in rare cases, the error marks themselves are
placed in the source file. In errors are placed in the source
file itself, clear the Filename tag field.
For each compiler, a set of rules must be specified on how to locate
each error. Generally regular expressions are used for this task.
(A discussion on regular expressions may be found in the Users
manual or in the online help system while in editing mode)
The order in which the information is retrieved is a set pattern
which is reflected in the Rules Menu itself as follows:
Error --- identifies an error mark
Filename --- filename in which error occurred
Line --- line on which error exists
Column --- column in which error exists
Message --- descriptive message of error
To retrieve this information, each field (above) is populated
based on marking found text (tags). The order of identification
begins with the error mark itself and finishes with the message.
First errors are identified by finding the error search string.
The cursor is positioned at the beginning of the found text or
optionally at the location specified via '\c' option within the
regular expression.
Once the error is found, the filename in which the error occurred
must be retrieved. The filename can either be a tagged expression
from the previous find, or a tagged expression of a newly tagged
search string.
Next the line and column fields are determined respectively
utilizing a tagged expression. The line field is usually specified
since without this information marking errors is essentially useless.
But columns are not always specified. In this case simply leave
all fields for column identification blank.
Finally, the descriptive error message itself is found. The users
can optionally display the entire error message or simply a part of
the message.
Consider the following example:
The output file looks like the following:
File: c:\compiler\foobar.err
Error 121 at 10,2 Unknown command
Error 109 at 133,20 Invalid use of operator
Warning 32 at 89,10 Variable 'm' is not used
First, to identify the error mark we must look for either the word
"Error" or "Warning" in the first column. Therefore we set the
error search string to "^{Error}|{Warning}", and the options to
"x".
Next, to identify the filename in which the error occurred we want
to find a line which says "File:" somewhere before the current error
line. To find this we set the filename search string to
"^File: {.*}$" and the options to "x". This finds a line which
begins with "File: ". All text which follows this is the filename
in which the error exists. The "{.*}$" part of the search string
identifies all text until the end of line as the filename. By
utilizing the '{' and '}' operators, we identify that this part of
the search string is identified by tag #1. Therefore, we specify the
"tag" as "1" for the filename.
Next, we need to determine the line number on which the error
occurred. Since the last "search" invoked was only for the
filename, there are no expressions we can simply tag. But we can use
one expression to find the line, column, and message all at once.
Then we simply need to tag the appropriate expressions.
Set the Line search string to "at {[0-9]#},{[0-9]#} +{.*}$" and
the options to "x". (Note that this find begins from the location
of the found Error search string.) The first tagged item
"{[0-9]#}" identifies the line number and is tag #1. We set the
line tag number to 1.
The second tagged item "{[0-9]#}" identifies the column and is tag
#2. Since there are no intermediate searches there is no need to
specify a search string or options for the column. We simply set
the column tag to 2.
The third tagged expression "{.*}" includes all characters to
the end of the line and is the error message itself. This is the
error message itself. Since the previous search uniquely identifies
this information, we simply set the message tag to 3.
The menu now looks like the following:
+---------------------------- Search strings -----------------------------+
| Error [^{Error}|{Warning} ] |
| Options [x ] |
| Filename [^File: {.*}$ ] |
| Options [x ] |
| Tag [ 1] |
| Line [at {[0-9]#},{[0-9]#} +{.*}$ ] |
| Options [x ] |
| Tag [ 1] |
| Column [ ] |
| Options [ ] |
| Tag [ 2] |
| Message [ ] |
| Options [ ] |
| Tag [ 3] |
+-------------------------------------------------------------------------+
RulesMenu-> Options
The search options for the specified search string (if any).
The regular expressions option is always assumed.
See the Rules Overview section for more details.
RulesMenu-> Tag
The tag number to mark to populate the specified field.
Special notes:
Clear the Filename tag to indicate errors in source.
Set the Column tag to -1 to indicate that the column search string
has located the cursor in the desired column
Set the Line tag to -1 to indicate that the line search string
has located the cursor on the desired line
See the Rules Overview section for more details.
RulesMenu->Column
This search string is used to identify the column in which the
errors exist. For many compilers this information is not available.
If the errors are in the source, this field, as well as its option
and tag field should be left blank.
See the Rules Overview section for more details.
RulesMenu->Error
This search string is used to identify the error mark itself.
See the Rules Overview section for more details.
RulesMenu->Filename
This search string is used to identify the file in which the errors
exist. If the errors are in the source, this field, as well as its
option and tag field should be left blank. If the errors are not in
the source, the tag field must be populated with an appropriate
value.
See the Rules Overview section for more details.
RulesMenu->Line
This search string is used to identify the line on which the errors
exist. If the errors are in the source, this field, as well as its
option and tag field should be left blank. If the errors are not in
the source, the tag field should be populated with an appropriate
value. Without specifying the line number, error marking is not
possible.
See the Rules Overview section for more details.
RulesMenu->Message
This search string is used to identify the error message to be
displayed for the associated error mark. This field is optional,
but without it, there is no error message to display.
See the Rules Overview section for more details.
RulesMenu->Options
The search options for the specified search string (if any).
The regular expressions option is always assumed.
See the Rules Overview section for more details.
RulesMenu->Tag
The tag number to mark to populate the specified field.
Special notes:
Clear the Filename tag to indicate errors in source.
Set the Column tag to -1 to indicate that the column search string
has located the cursor in the desired column
Set the Line tag to -1 to indicate that the line search string
has located the cursor on the desired line
See the Rules Overview section for more details.