Copyright (c) 2005 Salvador E. Tropea <salvador en inti gov ar>
Copyright (c) 2005 Instituto Nacional de Tecnologa Industrial

 This program is free software; you can redistribute it and/or modify
 it under the terms of the GNU General Public License as published by
 the Free Software Foundation; version 2.

 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


Introduction:
-------------

That's a extremely stupid (baka) VHDL lint script.
The basic idea is that you specify a VHDL source and the program must verify
if it complies with some coding rules.
This implementation does *NOT* pretends to:

1) Be exact. It uses an heuristic parser and hence can fail.
2) Be configurable. It just verifies the fpgalibre guidelines. We whish to
make it configurable, but this is much more complicated.
3) Verify advanced stuff.
4) Verify the correctness of the code. Bakalint assumes the code is valid
VHDL.

This version should be able to verify at least the following rules:

* Signals, variables, ports, types, subtypes, etc. must be lowercase.
* Constants and generics must be uppercase.
* Entities, architectures and packages must be "mixedcase" (may be 100%
uppercase, but not 100% lowercase).
* Ports must be suffixed using _i, _o or _io denoting its kind.
* Labels must be placed in a separated line. Exception: component
instantiation.
* End statements must be documented indicating what are finishing.
* Buffer ports are forbidden.
* VHDL constructions of the "entity xxxx is" and similars must be in one
line. You can't put "entity xxxxx" in one line and "is" in another.
* No more than one VHDL construction is allowed in one line of code.

Additionally invokes the check_vhdl_head.pl tool to verify the following
header details:

* Dependencies.
* Synthesis tools version (uses a custom path, can be disabled).

For more information read the fpgalibre's guidelines.


Usage:
------

You must specify the file to verify. This is done using the --input command
line option or its abbreviation -i. Example:

$ bakalint.pl -i test.vhdl

The progam will inform about warnings and errors using the GNU tools
standard:

file:line:description

The description always begins with "warning - ", "error - " or
"information - " indicating its severity.
Bakalint will offer a fixed version of the VHDL source code when that's
possible. The name of the fixed code will be the same of the specified source
but appending ".lint.vhdl".

When bakalint substitutes the name of a signal, entity, etc. a new file with
the same name and ".lint.txt" appended will be created containing the
performed substitutions.
You must understand that bakalint can fail when applying substitutions if
more than one VHDL element shares the same name. Example: an entity called
test and a signal also called test.

Note: We recommend to run bakalint only after succesfully compilation of the
source code.


Command line options:
---------------------

All command line options can be abbreviated. The abbreviation must avoid
confusion with other option. In most cases the first character is enough.

--help               Shows a text describing the available command line
                     options.

--depends=file       This option is used when invoking bakalint from a
                     makefile. When the source fails the test bakalint will
                     remove the specified file forcing a new test in the next
                     pass. That's usually used to remove the compiled code.

--head-out=file      Configures the output file name for the
                     check_vhdl_head.pl tool.

--keep-output        When specified bakalint doesn't remove the output files.
                     Even when they aren't considered useful by bakalint.
                     It can be used when we know the code will pass the test
                     but we just want to fix the indentation.

--max-sig-len=n      Sets the maximum length for signal names. The default
                     length is 15.

--no-header          Don't use check_vhdl_head.pl

--no-indent          Don't fix the indentation.

--no-warn-case       Don't inform about reserved words with wrong case. It
                     doesn't mean bakalint will ignore them. The warnings
                     won't be reported to avoid huge warning lists.

--no-xilinx          Don't check the synthesis tools version when invoking
                     check_vhdl_head.pl

--output=file        Sets the name of the fixed output.

--over-head          Makes check_vhdl_head.pl to overwrite the original file.

--replace=file       Sets the name of the file containing the substitutions.
                     That's useful when we want to apply the same
                     substitutions to more than one source. If we use the
                     same substitution file for various sources the
                     substitutions will get propagated.

--stack-debug        Used to debug bakalint. Prints information about the
                     internal stack.

--wishbone           Used when we have Wishbone signals in our project and
                     we whish to apply subtitutions on them.


Contact:
--------

If you have doubts, bug reports, comments, suggestions, enhancements, etc.
please contact the FPGA libre project:

http://fpgalibre.sf.net/
http://sf.net/projects/fpgalibre

