ivlpp/ivlpp.txt

   1
   2    Copyright (c) 1999 Stephen Williams (steve@icarus.com)
   3
   4       This source code is free software; you can redistribute it
   5       and/or modify it in source code form under the terms of the GNU
   6       General Public License as published by the Free Software
   7       Foundation; either version 2 of the License, or (at your option)
   8       any later version.
   9
  10       This program is distributed in the hope that it will be useful,
  11       but WITHOUT ANY WARRANTY; without even the implied warranty of
  12       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13       GNU General Public License for more details.
  14
  15       You should have received a copy of the GNU General Public License
  16       along with this program; if not, write to the Free Software
  17       Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
  18
  19
  20 THE IVL PREPROCESSOR
  21
  22 The ivlpp command is a Verilog preprocessor that handles file
  23 inclusion and macro substitution. The program runs separate from the
  24 actual compiler so as to ease the task of the compiler proper, and
  25 provides a means of preprocessing files off-line.
  26
  27
  28 USAGE:
  29
  30         ivlpp [options] <file>
  31
  32 The <file> parameter is the name of the file to be read and
  33 preprocessed. The resulting output is sent to standard output. The
  34 valid options include:
  35
  36         -Dname[=value]
  37             Predefine the symbol ``name'' to have the specified
  38             value. If the value is not specified, then ``1'' is
  39             used. This is mostly of use for controlling conditional
  40             compilation.
  41
  42             This option does *not* override existing `define
  43             directives in the source file.
  44
  45         -I <dir>
  46             Add a directory to the include path. Normally, only "." is
  47             in the search path. The -I flag causes other directories
  48             to be searched for a named file. There may be as many -I
  49             flags as needed.
  50
  51         -L
  52             Generate `line directives. The ivl compiler understands
  53             these directives and uses them to keep track of the
  54             current line of the original source file. This makes error
  55             messages more meaningful.
  56
  57         -o <file>
  58             Send the output to the named file, instead of to standard
  59             output.
  60
  61         -v
  62             Print version and copyright information
  63
  64
  65 LOCATING INCLUDED FILES
  66
  67 The ivlpp preprocessor implements the `include directives by
  68 substituting the contents of the included file in place of the line
  69 with the `include directive. The name that the programmer specifies is
  70 a file name. Normally, the preprocessor looks in the current working
  71 directory for the named file. However, the ``-I'' flags can be used to
  72 specify a path of directories to search for named include files. The
  73 current directory will be searched first, followed by all the include
  74 directories in the order that the -I flag appears.
  75
  76 The exception to this process is include files that have a name that
  77 starts with the '/' character. These file names are ``rooted names''
  78 and must be in the rooted location specified.
  79
  80
  81 GENERATED LINE DIRECTIVES
  82
  83 Compilers generally try to print along with their error messages the
  84 file and line number where the error occurred. Icarus Verilog is no
  85 exception. However, if a separate preprocessor is actually selecting
  86 and opening files, then the line numbers counted by the compiler
  87 proper will not reflect the actual line numbers in the source file.
  88
  89 To handle this situation, the preprocessor can generate line
  90 directives. These directives are lines of the form:
  91
  92         `line <num> <name> <level>
  93
  94 where <name> is the file name in double-quotes and <num> is the line
  95 number in the file. The parser changes the filename and line number
  96 counters in such a way that the next line is line number <num> in
  97 the file named <name>. For example:
  98
  99         `line 6 "foo.vl" 0
 100         // I am on line 6 in file foo.vl.
 101
 102 The preprocessor generates a `line directive every time it switches
 103 files. That includes starting an included file (`line 1 "foo.vlh" 1) or
 104 returning to the including file.
 105