Copyright (c) 1999 Stephen Williams (steve@icarus.com)
  
      This source code is free software; you can redistribute it
      and/or modify it in source code form under the terms of the GNU
      General Public License as published by the Free Software
      Foundation; either version 2 of the License, or (at your option)
      any later version.
  
      This program is distributed in the hope that it will be useful,
      but WITHOUT ANY WARRANTY; without even the implied warranty of
      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
      GNU General Public License for more details.
  
      You should have received a copy of the GNU General Public License
      along with this program; if not, write to the Free Software
      Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA


THE IVL PREPROCESSOR

The ivlpp command is a verilog preprocessor that handles file
inclusion and macro substitution. The program runs separate from the
actual compiler so as to ease the task of the compiler proper, and
provides a means of preprocessing files off-line.


USAGE:

	ivlpp [options] <file>

The <file> parameter is the name of the file to be read and
preprocessed. The resulting output is sent to standard output. The
valid options include:

	-Dname[=value]
	    Predefine the symbol ``name'' to have the specified
	    value. If the value is not specified, then ``1'' is
	    used. This is mostly of use for controlling conditional
	    compilaiton.

	    This option does *not* override existing `define
	    directives in the source file.

	-I <dir>
	    Add a directory to the include path. Normally, only "." is
	    in the search path. The -I flag causes other directories
	    to be searched for a named file. There may be as many -I
	    flags as needed.

	-L
	    Generate `line directives. The ivl compiler understands
	    these directives and uses them to keep track of the
	    current line of the original source file. This makes error
	    messages more meaningful.

	-o <file>
	    Send the output to the named file, instead of to standard
	    output.

	-v
	    Print version and copyright information


LOCATING INCLUDED FILES

The ivlpp preprocessor implements the `include directives by
substituting the contents of the included file in place of the line
with the `include directive. The name that the programmer specifies is
a file name. Normally, the preprocessor looks in the current working
directory for the named file. However, the ``-I'' flags can be used to
specify a path of directories to search for named include files. The
current directory will be searched first, followed by all the include
directories in the order that the -I flag appears.

The exception to this process is include files that have a name that
starts with the '/' character. These file names are ``rooted names''
and must be in the rooted location specified.


GENERATED LINE DIRECTIVES

Compilers generally try to print along with their error messages the
file and line number where the error occurred. Icarus Verilog is no
exception. However, if a separate preprocessor is actually selecting
and opening files, then the line numbers counted by the compiler
proper will not reflect the actual line numbers in the source file.

To handle this situation, the preprocessor can generate line
directives. These directives are lines of the form:

	`line <num> <name> <level>

where <name> is the file name in double-quotes and <num> is the line
number in the file. The parser changes the filename and line number
counters in such a way that the next line is line number <num> in
the file named <name>. For example:

	`line 6 "foo.vl" 0
	// I am on line 6 in file foo.vl.

The preprocessor generates a `line directive every time it switches
files. That includes starting an included file (`line 1 "foo.vlh" 1) or
returning to the including file.