Provided by: freehdl_0.0.7-1_i386 bug

NAME

       v2cc.libs    -    VHDL   library   mapping   file   for   the   FreeHDL
       compiler/simulator.

DESCRIPTION

       FreeHDL is a compiler/simulator  suite  for  the  hardware  description
       language VHDL.  VHDL’93 as well as VHDL’87 standards are supported.

       FreeHDL  translates  the original VHDL source FILEs into C++. Then, the
       C++ source can be compiled and  linked  to  the  kernel  to  build  the
       simulation program. Starting the generated executable will simulate the
       corresponding VHDL model. The actual  build  process  to  generate  the
       simulator from the VHDL source is a complex process which is handled by
       the gvhdl script.

       FreeHDL does not have a opaque notion of design libraries.  VHDL  files
       are  not  pre-analyzed  and  checked  into some library data base as in
       other VHDL compiler/simulator systems.  Instead, whenever  a  reference
       to a design unit needs to be made, FreeHDL parses the VHDL code of that
       design unit from fresh.  Therefore, it needs to be  able  to  find  the
       source file of a design unit given the VHDL name of that unit.

       Thus,  as  far  as  FreeHDL is concerned, a design library is a mapping
       from VHDL identifiers to file names.   There  is  also  a  mapping  for
       getting library names from mapping files.

       Such  a  mapping is specified via a "mapping file".  It contains a list
       of pattern rules that each transform a  certain  class  of  identifiers
       into file names.

       The syntax of a mapping file is:

         Lexical:

            litchar:  ’a’..’z’  |  ’A’..’Z’ | ’0’..’9’ | ’_’ | ’/’ | ’-’ | ’.’
       escchar

            escchar: ’\’ char

            whitespace: ’ ’ | ’\n’ | ’\v’ | ’\t’ | comment

            comment: ’#’ any_character* ’\n’

            opchar: ’:’ | ’,’ | ’(’ | ’)’

            specchar: every printable  char  except  litchar,  whitespace  and
       opchar

            symchar: litchar | specchar

            symbol: symchar+

         Grammar:

            mapping: version patternrule*

            version: "v2cc_mapfile" "0"

            patternrule: symbol [ ’:’ symbol ]

       Comments are ignored.

       A   mapping   files  specifies  a  sequence  of  pattern  rules.   When
       transforming an identifier, each rule is tried in turn  and  the  first
       one that matches is chosen.

       A rule looks like

         pattern: filename

       When  the  ":  filename"  part  is omitted, it defaults to "patternEXT"
       where "EXT" is determined by the user of the mapping file.

       The "pattern" can contain the special character "<" which introduces  a
       ‘wildcard’.   The  "<"  must  be  followed  by  a  ">",  with arbitrary
       characters inbetween.  These characters form the name of the  wildcard.
       A wildcard matches any sequence of characters.  There can be any number
       of wildcards in the pattern, but each must have a unique name.

       The "filename" can also contain the character "<", followed by a  name,
       followed  by  ">".  There, it introduces a ‘wildcard substitution’.  It
       will be replaced with the characters that matched the wildcard with the
       same  name  in  "pattern".  When there is no wildcard in "pattern" with
       the right name, it will be replaced with  nothing.   While  doing  this
       replacement,  the characters "#" and "/" are replaced as "##", and "#-"
       respectively.  No other character translations are done, so if you have
       funny  characters  in  your  VHDL  identifiers,  you  will  have  funny
       characters in your filenames.

       Before doing the comparison with the patterns, the VHDL  identifier  is
       brought  into  a canonical form: when it is not an abstract identifier,
       all its characters are down-cased.

       When the resulting filename is relative (does not begin with  "/"),  it
       is prefixed with the directory of the mapping file.

       A non-existent mapping file is equivalent to the single rule

         <>

       An empty mapping file is just that: an empty mapping.

       The  mapping  does  not  need to be reversible.  It is OK when multiple
       identifiers map to a single filename.

       No special character besides "<" and  ">"  is  valid  in  "pattern"  or
       "filename".  They are reserved for future extensions.

       The  mapping  files  for  going from design unit names to filenames are
       found by looking into directories specified by the ‘v2cc library path’.
       You can use the environment variable V2CC_LIBRARY_PATH and command line
       options to define the path.  When the environment variable is not  set,
       it defaults to a value that makes the standard libraries available that
       are distributed and installed with v2cc itself.  When  it  is  set,  it
       completely overwrites this default value.

       The  variable  V2CC_LIBRARY_PATH  consists  of ":" separated filenames.
       The filename "*" is replaced with the default value mentioned above.

       In addition to the environment variable, you can use  the  "-L  libdir"
       command line option with v2cc.  The directories specified with "-L" are
       added in front of the ones  specified  by  V2CC_LIBRARY_PATH.   In  the
       final  library  path,  they  appear in the same order as on the command
       line.

       Looking for a design unit named UNIT in a library  named  LIB  is  done
       like this:

            for each component of the library path, L
              if L is a regular file
                set LMAP to L
              else if L is a directory
                set LMAP to L/v2cc.libs
              else
                continue with next component
              translate LIB into FLIB using LMAP with EXT=""
              if FLIB.vhdl exists
                terminate with FLIB.vhdl as the result
              if FLIB.v2cc exists
                set UMAP to FLIB.v2cc
              else if FLIB is a directory
                set UMAP to FLIB/v2cc.units
              else
                continue with next component
              translate UNIT into FUNIT using UMAP with EXT=".vhdl"
              terminate with FUNIT as the result
            terminate unsuccessfully

       This  mechanism  is  used for all design units that are referenced from
       within VHDL code (or via other means).  There is  a  complication  with
       architectures and package bodies, though, because they are not uniquely
       identified by a single identifier.  For them, a  artificial  identifier
       is constructed.  Architectures get names of the form

           <entity>(<architecture>)

       while package bodies become

           <package>(body)

       For   example,   "architecture   struct   of   model"  is  turned  into
       "model(struct)" and "package body misc" is turned into "misc(body)".

       When a design file contains multiple design units, they are all parsed,
       checked  for  correctness and remembered, but only the needed unit will
       be used for code generation.  That is, when a design file contains both
       a  package  header  and  a  package  body  and  the  package  header is
       referenced from another design unit, no code will be generated for  the
       package  body.   When one of the ignored units will be referenced later
       in the same invocation of v2cc, the design file will not be read  again
       because all design units are retained in core.

EXAMPLES

       The  simplest  situation  is  when you have no mapping files at all.  A
       design library is then a directory on your library path.  The  name  of
       that  directory  is  that  of  the  library in VHDL.  Each file in that
       directory with a ".vhdl" extension is used for a design unit  with  the
       same name as the file without the extension.

       Say you have this directory structure

           somedir/
             std/
               standard.vhdl
               textio.vhdl
             ieee/
               numeric_bit.vhdl
               std_logic_1164.vhdl

       When  you  put "somedir" into your library path, you have access to the
       design units

              STD.STANDARD
              STD.TEXTIO
              IEEE.NUMERIC_BIT
              IEEE.STD_LOGIC_1164

       In this situation, you have one file per design unit.   When  you  have
       one file per design library, it would look like this

           somedir/
             fmf.vhdl

       All  references  to  design  units  in  the FMF design library would be
       routed to "fmf.vhdl".

       As another example assume that  all  VHDL  libraries  are  mapped  into
       subdirs starting from root directory "/foo". Further, assume that there
       are VHDL libraries named "lib1" and "lib2". They  shall  be  mapped  to
       subdir  "/foo/lib1_dir"  and "/foo/lib2_dir". Hence, the file/directory
       structure is as follows:

       /foo                <-  library root directory  /foo/v2cc.libs       <-
       mapping  control  file   /foo/lib1_dir       <-   library  dir for VHDL
       library lib1 /foo/lib1_dir/comp1.vhdl <- file that contains VHDL  model
       comp1   /foo/lib2_dir       <-   library  dir  for  VHDL  library  lib2
       /foo/lib2_dir/comp2.vhdl <- file that contains VHDL model comp2

       Then, file "/foo/v2cc.libs" should contain:

       v2cc_mapfile 0 lib1 : lib1_dir lib2 : lib2_dir

       In order to compile a design named comp1 (stored  in  file  comp1.vhdl)
       into VHDL library lib1 goto subdir "/foo/lib1_dir" and execute:

           gvhdl -c -L .. -l lib1 comp1.vhdl

       Note  that  option "-l lib1" forces the compiler to associate the model
       stored in "comp1.vhdl" with VHDL library lib1.  Note further, that  the
       compiler  switch  "-L  .."  specifies  the  path to the directory where
       "v2cc.libs" is stored. You may also specify an absolute path:

           gvhdl -c -L /foo -l lib1 comp1.vhdl

       Note that comp1 should reside in a file named "comp1.vhdl".

       If lib2 contains a design comp2 that makes use of comp1 from lib1  then
       goto  "/foo/lib2_dir"  and  run  the  following  command  to  create an
       executable for model comp2:

           gvhdl -L .. -l lib2 comp2.vhdl ../lib1_dir/comp1.o

SEE ALSO

       gvhdl(1), freehdl-v2cc(1), freehdl-config(1)

AVAILABILITY

       The  latest  version  of  FreeHDL   can   always   be   obtained   from
       www.freehdl.seul.org

REPORTING BUGS

       Known  bugs  are  documented  within  the  BUGS  file.   If your report
       addresses  a  parser  related  topic  then   contact   Marius   Vollmer
       <mvo@zagadka.ping.de>.   If  it  is  related  to  the code generator or
       compiler then send an email to Edwin  Naroska  <edwin@ds.e-technik.uni-
       dortmund.de>.   If  your  are  not sure send it to Edwin.  He will take
       care of forwarding your report to the appropriate recipient.

COPYRIGHT

       Edwin Naroska © 1999, 2000, 2001, 2002, 2003, 2004,  2005  <edwin@ds.e-
       technik.uni-dortmund.de>

       This is free software; see the source for copying conditions.  There is
       NO warranty; not even for MERCHANTABILITY or FITNESS FOR  A  PARTICULAR
       PURPOSE.

AUTHORS

       Written  by  Marius  Vollmer  <mvo@zagadka.ping.de>  and  Edwin Naroska
       <edwin@ds.e-technik.uni-dortmund.de>.