f-cpu/vhdl/tools.desc/README.txt
created Fri Jun 21 18:35:46 CEST 2002 by whygee@f-cpu.org
updated Sun Jun 23 01:56:45 CEST 2002
updated Sun Jun 23 23:15:55 CEST 2002 : file formats are changed

About this package :
--------------------

This directory (f-cpu/vhdl/tools.desc) contains a script
that can call several other VHDL tools in with abstracted
interface. It is sourced by other compilation scripts and
can be configured by environment variables. It is used
to reduce scripting efforts and remove dependencies on
ools (and their possible "evolutions"). Reuse of the
script is subject to the terms of the GPL. Read LICENSE.txt
for a bit more informations. It is developped in the F-CPU
project because nothing similar already exists. A little
hack like this is rather easy to implement but it can be
useful outside the F-CPU project and we'd rather foster
efforts rather than keep it for ourselves.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The goal of this package is to be useful and so simple
it can be hacked with a simple text editor. It needs no
specific software and removes the need for (almost)
any tool-specific script, leaving only generic, portable
and compact results. Finally, it must allow portable
VHDL sources to be compiled and simulated anywhere by
anybody (with a Un*x box), whatever described tool is
available. When several tools are available, they are
used together to perform portability or regression tests.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

In the pure F-CPU tradition, this software is not
intrusive : you don't need to be root or to modify
your environment, but read and write permissions are
still necessary to store some configuration results.
The tools must also be accessible from your usual $PATH.


Some technical details :
------------------------

This package contains the following files (at least) :
   README.txt    (this file)
   INSTALL.txt   (how to get started)
   LICENSE.txt   (just in case)
   vhdl_tools.sh (the abstraction script)


The script contains several bash functions that can
be called directly or indirectly. The main function
is called "all_tools" and it is the low-level part
which calls all the other VHDL tools and detects them.

Detection is performed whenever the tool list is
not available from the variable environment "$VHDL_TOOLNAMES"
or from the file ".vhdl_tools". The detection function
will call "all_tools" for all known tools and generate
"$VHDL_TOOLNAMES" and ".vhdl_tools". They can be edited
to modify the behaviour of the script.

The internal "tool database" in "all_tools" is accessed
with the name of the desired tool and the operation to
perform.

 - The provided tool name is the generic name of the
   tool it describes, but it is not a requirement :
   several versions of the same tool's decriptions
   can have different names ("tool-1", "tool-2.5"...)
   as long as the corresponding bash code is provided.

 - The allowed operations depend on the desired tool
   and they can be empty. They are :
       "detect" - how to call it for asking a version
           and what signature the output must contain
      "prepare" - how to prepare the compilation
      "compile" - how to compile a single file
    "elaborate" - how to elaborate the design
     "simulate" - how to simulate the design
   Other operation keywords are not allowed yet but
   could be added if a new tool requires it.

Depending on the operation, other variables are required :
 - $FILENAMELIST is the list of files to compile.
 - $ENTITY is the name of the entity to elaborate and/or
    simulate.
 - $ARCHITECTURE is the optional name of the simulated
    architecture.
This list could also grow as needed.


Adding a tool to the database :
-------------------------------

The first thing to do is to copy the "template" in
"all_tools" and populate it with the necessary commands.
The new tool must be given a name that can be recognised
easily (a single word). Add this name to the variable
"$VHDL_TOOLNAMES" that is defined before the "all_tools"
function. Then run tests locally on existing tools,
noone knows ;-)

I believe that the system is simple enough and not too
cryptic. It uses some "nice" (?) features of bash and
doesn't need any extra tool or modifications to your
environment. And if you read this file, you should be
able to fine-tune it, or even add new tool descriptions.
Avoid any bloatware and keep the features as generic
as possible (nobody cares if you can detect version 1.3.5
of a tool as long as it works everywhere without hacking).


Contacts : you can contact me (whygee@f-cpu.org)
at this moment. You can also find this package in
the F-CPU source tree or as a separate file at
http://f-cpu.seul.org/new
