Command File Format
===================

The basic format of a command file is one source file or compiler argument per
line. Command files may also have comments of various form, and options for
controlling the compiler.

Comments
--------

Lines that start with a "#" character are comments. All text after the "#"
character, is ignored.

The "//" character sequence also starts a comment that continues to the end of
the line.

The "/\*" and "\*/" character sequences surround multi-line comments. All the
text between the comment start and comment end sequences is ignored, even when
that text spans multiple lines. This style of comment does not nest, so a "/\*"
sequence within a multi-line comment is probably an error.

Plus-args
---------

Outside of comments, lines that start with a "+" character are compiler
arguments. These are called plusargs but they are not the same as extended
arguments passed to the "vvp" command. The supported plusargs are definitively
listed in the iverilog manual page.

The plusargs lines are generally "+<name>+..." where the name is the name of
an switch, and the arguments are separated by "+" characters, as in::

  +libext+.v+.V+.ver

With plusargs lines, the "+" character separates tokens, and not white space,
so arguments, which may include file paths, may include spaces. A plusarg line
is terminated by the line end.

The line in the command file may also be a "-y" argument. This works exactly
the same as the::

  -y <path>

argument to the compiler; it declares a library directory. The "-y" syntax is
also a shorthand for the "+libdir" plusarg, which is a more general form::

  +libdir+<path>...

File Names
----------

Any lines that are not comments, compiler arguments or plusargs are taken by
the compiler to be a source file. The path can contain any characters (other
then comment sequences) including blanks, although leading and trailing white
space characters are stripped. The restriction of one file name per line is in
support of operating systems that can name files any which way. It is not
appropriate to expect white spaces to separate file names.

Variable Substitution
---------------------

The syntax "$(name)" is a variable reference, and may be used anywhere within
filenames or directory names. The contents of the variable are read from the
environment and substituted in place of the variable reference. In Windows,
these environment variables are the very same variables that are set through
the Control Panel->System dialog box, and in UNIX these variables are
environment variables as exported by your shell.

Variables are useful for giving command files some installation
independence. For example, one can import a vendor library with the line::

  -y $(VENDOR)/verilog/library

in the command file, and the next programmer will be able to use this command
file without editing it to point to the location of VENDOR on his
machine. Note the use of forward slashes as a directory separator. This works
even under Windows, so always use forward slashes in file paths and Windows
and UNIX users will be able to share command files.

An Example
----------

This sample::

  # This is a comment in a command file.
  # The -y statement declares a library
  # search directory
  -y $(PROJ_LIBRARY)/prims
  #
  # This plusarg tells the compiler that
  # files in libraries may have .v or .vl
  # extensions.
  +libext+.v+.vl
  #
  main.v // This is a source file
  #
  # This is a file name with blanks.
  C:/Project Directory/file name.vl

is a command file that demonstrates the major syntactic elements of command
files. It demonstrates the use of comments, variables, plusargs and file
names. It contains a lot of information about the hypothetical project, and
suggests that command files can be used to describe the project as a whole
fairly concisely.

The syntax of command files is rich enough that they can be used to document
and control the assembly and compilation of large Verilog programs. It is not
unusual to have command files that are hundreds of lines long, although
judicious use of libraries can lead to very short command files even for large
designs. It is also practical to have different command files that pull
together combinations of sources and compiler arguments to make different
designs from the same Verilog source files.

Summary
-------

Given the above description of the command file format, the following is a
list of the special records with their meaning.

* +libdir+*dir-path*

  Specify directories to be searched for library modules. The *dir-path* can
  have multiple directories, separated by "+" characters.

* +libdir-nocase+dir-path
  
  This is the same as "+libdir+", but when searching "nocase" libraries for
  module files, case will not be taken as significant. This is useful when the
  library is on a case insensitive file system.

* +libext+*suffix-string*

  Declare the suffix strings to use when searching library directories for
  Verilog files. The compiler may test a list of suffix strings to support a
  variety of naming conventions.

* -y dir-path
  
  This is like "+libdir+" but each line takes only one path. Like "+libdir+"
  there can be multiple "-y" records to declare multiple library
  directories. This is similar to the "-y" flag on the iverilog command line.

* -v *file-name* or -l *file-name*

  This declares a library file. A library file is just like any other Verilog
  source file, except that modules declared within it are not implicitly
  possible root modules.

  NOTE: The "-l" alias is new as of 2 October 2016. It will become available
  in releases and snapshots made after that date.

* +incdir+*include-dir-path*
  
  Declare a directory or list of directories to search for files included by
  the "include" compiler directive. The directories are searched in
  order. This is similar to the "-I" flag on the iverilog command line.

* +define+*name=value*
  
  Define the preprocessor symbol "name" to have the string value "value". If
  the value (and the "=") are omitted, then it is assumed to be the string
  "1". This is similar to the "-D" on the iverilog command line.

* +timescale+*units/precision*
  
  Define the default timescale. This is the timescale that is used if there is
  no other timescale directive in the Verilog source. The compiler default
  default is "+timescale+1s/1s", which this command file setting can
  change. The format of the units/precision is the same as that for the
  timescale directive in the verilog source.

* +toupper-filename
  
  This token causes file names after this in the command file to be translated
  to uppercase. this helps with situations where a directory has passed
  through a DOS machine (or a FAT file system) and in the process the file
  names become munged. This is not meant to be used in general, but only in
  emergencies.

* +tolower-filename
  
  The is the lowercase version of "+toupper-filename".

* +parameter+*name=value*
  
  This token causes the compiler to override a parameter value for a top-level
  module. For example, if the module main has the parameter WIDTH, set the
  width like this "+parameter+main.WIDTH=5". Note the use of the complete
  hierarchical name. This currently only works for parameters defined in root
  (top level) modules and a defparam may override the command file value.

* +vhdl-work+*path*
  
  When compiling VHDL, this token allows control over the directory to use for
  holding working package declarations. For example, "+vhdl-work+workdir" will
  cause the directory "workdir" to be used as a directory for holding working
  working copies of package headers.