\begindata{text,538322772}
\textdsversion{12}
\template{help}
\define{global
}


\chapter{Compile: A command execution package with error parsing

}
\section{What compile is

}\leftindent{
The compile package allows you to run commands (usually compilations) and have 
the output collected in a buffer.  After the compilation is done, you can use 
keys to step from one error to the next in your program.

}
\section{Starting compile

}\leftindent{
Before you can use the compile package, you need to add the following lines to 
your .ezinit file:


\example{# Bind up compilation package.

addkey compile-build ^X^E textview

addkey compile-kill-build ^X^K textview

addkey compile-next-error ^X^N textview

addkey compile-previous-error ^X^P textview

}
If you prefer, you may bind these functions to other keys. T he ^X^P binding 
is especially dubious in that it overrides the default binding for the 
"Plainer" function in text.  Note that you need to restart ez before any 
changes to your .ezinit file will manifest themselves.


To start the compilation, press "^X^E".  Any output from the command will be 
put into the buffer "Error-Log."  If you have more than one EZ window up, the 
compile package will use one of them for the Error-Log.  Otherwise, you can 
use ^Xb to change to the Error-Log.


As the compilation progresses, the compile package scans it for errors.  You 
can use ^X^N to go to the next (or first) error.  The compile package will 
select the offending lines in one window and the lines describing the error in 
another.  After fixing the error, you can use ^X^N or ^X^P to go to the next 
or previous error.


If you decide that you need to end the compilation, you can press ^X^K to kill 
the processes behind the compilation.

}
\section{Warnings

}\leftindent{
The compile package is capable of parsing errors while the compilation is 
still taking place. This is very useful, but has one subtle side-effect. 
Compile parses errors when you have requested the next error, but it does not 
have any errors parsed. When it parses errors, it parses to the end of the 
Error-Log. It is possible to catch the compilation process in the middle of a 
file so that the parsing stops part of the way through the errors in a given 
file. Then if you edit the file and type next error again, the line numbers 
from the compiler will be wrong and compile will show you sections of your 
program slightly off from where the error actually occured. This situation is 
extremely rare.

}
\section{Quick reference

}\leftindent{
The default command for compile is "build -k", if you wish to use another 
command (i.e. "make -k"), you can set the ez.CompileComand preference to the 
comand you wish to execute. For example, the following line in your 
preferences file will tell compile to use make instead of build:


\example{ez.CompileCommand: make -k

}
If, while running ez, you want to execute some command other than the default, 
prefix the the ^X^E with a ^U (i.e. ^U^X^E). The compile package will then 
prompt you for the command to execute. The default will then become the last 
command that was executed. This can be useful in conjunction with the "-n" 
flag to egrep.


}\section{Advice

}\leftindent{
The output generated by "egrep -n ..." looks just like errors to compile 
package, so you can use ^X^N and ^X^P to step through each place egrep found 
the string you gave it. For example, to find all of the occurances of 
foo_Bletch in all the C files in the current directory, type ^U^X^E and enter 
the following command at the prompt:


\example{egrep -n foo_Bletch *.c

}
Since the command is processed by /bin/csh before processing, the wildcards 
will be expanded appropriately. Another useful idiom is to prefix the command 
with a cd to execute in another directory:


\example{cd \italic{directory} \typewriter{;} \italic{command}}


Note that the space between the directory and the ';' is required.


If you want to temporally stop the compilation, you can press ^U^X^K. To 
restart the compilation, press ^X^E again. This is just like typing ^Z in the 
typescript window. (^X^K sends a SIGTERM to the process group started by ^X^E. 
^U^X^K sends a SIGSTOP to the same. If there is a stopped compilation, ^X^E 
sends a SIGCONT to its process group.)

}
\section{Program Author}


\leftindent{Zalman Stern}

\leftindent{
}\section{Related tools}  


Select (highlight) one of the italicized names and choose "Show Help on 
Selected Word" from the pop-up menu to see the help document for:


\leftindent{\italic{\helptopic{ez}

\helptopic{ez-buffers}

\helptopic{initfiles}}\italic{

}}

\begindata{bp,537558784}
\enddata{bp,537558784}
\view{bpv,537558784,854,0,0}
Copyright 1992 Carnegie Mellon University and IBM.  All rights reserved.

\smaller{\smaller{$Disclaimer: 

Permission to use, copy, modify, and distribute this software and its 

documentation for any purpose is hereby granted without fee, 

provided that the above copyright notice appear in all copies and that 

both that copyright notice, this permission notice, and the following 

disclaimer appear in supporting documentation, and that the names of 

IBM, Carnegie Mellon University, and other copyright holders, not be 

used in advertising or publicity pertaining to distribution of the software 

without specific, written prior permission.



IBM, CARNEGIE MELLON UNIVERSITY, AND THE OTHER COPYRIGHT HOLDERS 

DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING 

ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS.  IN NO EVENT 

SHALL IBM, CARNEGIE MELLON UNIVERSITY, OR ANY OTHER COPYRIGHT HOLDER 

BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY 

DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, 

WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS 

ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE 

OF THIS SOFTWARE.

 $

}}\enddata{text,538322772}
