
   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., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, 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
	    compilation.

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

	-F <path>
	    Read ivlpp options from a FLAGS FILE. This is not the same
	    as a file list. This file contains flags, not source
	    files. There may be multiple flags files.

	-f <path>
	    Read ivlpp input files from a file list. There can be no
	    more than one file list.

	-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 before processing
	    input files.

	-V
	    Print version and copyright information, then exit WITHOUT
	    processing any input files.

FLAGS FILE

A flags file contains flags for use by ivlpp. This is a convenient way
for programs to pass complex sets of flags to the ivlpp program.

Blank lines and lines that start with "#" are ignored. The latter can
be used as comment lines. All other lines are flag lines. Leading and
trailing white space are removed before the lines are interpreted.

Other lines have the simple format:

  <key>:<value>

The colon character separates a key from the value. The supported
keys, with their corresponding values, are:

   D:name=<value>
      This is exactly the same as the "-Dname=<value>" described above.

   I:<dir>
      This is exactly the same as "-I<dir>".

   relative include:<flag>
      The <flag> can be "true" or "false". This enables "relative
      includes" nesting behavior.

   vhdlpp:<path>
      Give the path to the vhdlpp program. This program is used to
      process VHDL input files.

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.

