Function: `vhdl-mode`

vhdl-mode is an autoloaded, interactive and byte-compiled function defined in vhdl-mode.el.gz.

Signature

(vhdl-mode)

Documentation

Major mode for editing VHDL code.

Usage:
------

  TEMPLATE INSERTION (electrification):
    After typing a VHDL keyword and entering SPC, you are prompted for
    arguments while a template is generated for that VHDL construct. Typing
    RET or C-g at the first (mandatory) prompt aborts the current
    template generation. Optional arguments are indicated by square
    brackets and removed if the queried string is left empty. Prompts for
    mandatory arguments remain in the code if the queried string is left
    empty. They can be queried again by C-c C-t C-q. Enabled
    electrification is indicated by /e in the mode line.

      Typing M-SPC after a keyword inserts a space without calling the
    template generator. Automatic template generation (i.e.
    electrification) can be disabled (enabled) by typing C-c C-m C-e or by
    setting option vhdl-electric-mode(var)/vhdl-electric-mode(fun) (see OPTIONS).

      Template generators can be invoked from the VHDL menu, by key
    bindings, by typing C-c C-i C-c and choosing a construct, or by typing
    the keyword (i.e. first word of menu entry not in parenthesis) and
    SPC. The following abbreviations can also be used: arch, attr, cond,
    conf, comp, cons, func, inst, pack, sig, var.

Template styles can be customized in customization group
vhdl-template (see OPTIONS).

  HEADER INSERTION:
    A file header can be inserted by C-c C-t C-h. A file footer
    (template at the end of the file) can be inserted by C-c C-t C-f.
    See customization group vhdl-header.

  STUTTERING:
    Double striking of some keys inserts cumbersome VHDL syntax elements.
    Stuttering can be disabled (enabled) by typing C-c C-m C-s or by
    option vhdl-stutter-mode(var)/vhdl-stutter-mode(fun). Enabled stuttering is indicated by /s in
    the mode line. The stuttering keys and their effects are:

      ;; --> " : " [ --> ( -- --> comment
      ;;; --> " := " [[ --> [ --CR --> comment-out code
      .. --> " => " ] --> ) --- --> horizontal line
      ,, --> " <= " ]] --> ] ---- --> display comment
      == --> " == " '' --> \"

  WORD COMPLETION:
    Typing `TAB' after a (not completed) word looks for a VHDL keyword or a
    word in the buffer that starts alike, inserts it and adjusts case.
    Re-typing `TAB' toggles through alternative word completions. This also
    works in the minibuffer (i.e. in template generator prompts).

      Typing `TAB' after `(' looks for and inserts complete parenthesized
    expressions (e.g. for array index ranges). All keywords as well as
    standard types and subprograms of VHDL have predefined abbreviations
    (e.g., type "std" and `TAB' will toggle through all standard types
    beginning with "std").

      Typing `TAB' after a non-word character indents the line if at the
    beginning of a line (i.e. no preceding non-blank characters), and
    inserts a tabulator stop otherwise. `M-TAB' always inserts a tabulator
    stop.

  COMMENTS:
        `--' puts a single comment.
        `---' draws a horizontal line for separating code segments.
        `----' inserts a display comment, i.e. two horizontal lines
                   with a comment in between.
        `--CR' comments out code on that line. Re-hitting CR comments
                   out following lines.
        `C-c C-c' comments out a region if not commented out,
                   uncomments a region if already commented out. Option
                   `comment-style' defines where the comment characters
                   should be placed (beginning of line, indent, etc.).

      You are prompted for comments after object definitions (i.e. signals,
    variables, constants, ports) and after subprogram and process
    specifications if option `vhdl-prompt-for-comments' is non-nil.
    Comments are automatically inserted as additional labels (e.g. after
    begin statements) and as help comments if `vhdl-self-insert-comments' is
    non-nil.

      Inline comments (i.e. comments after a piece of code on the same line)
    are indented at least to `vhdl-inline-comment-column'. Comments go at
    maximum to `vhdl-end-comment-column'. `RET' after a space in a comment
    will open a new comment line. Typing beyond `vhdl-end-comment-column'
    in a comment automatically opens a new comment line. `M-q' re-fills
    multi-line comments.

  INDENTATION:
    `TAB' indents a line if at the beginning of the line. The amount of
    indentation is specified by option `vhdl-basic-offset'. `C-c C-i C-l'
    always indents the current line (is bound to `TAB' if option
    `vhdl-intelligent-tab' is nil). If a region is active, `TAB' indents
    the entire region.

      Indentation can be done for a group of lines (`C-c C-i C-g'), a region
    (`M-C-\\') or the entire buffer (menu). Argument and port lists are
    indented normally (nil) or relative to the opening parenthesis (non-nil)
    according to option `vhdl-argument-list-indent'.

      If option `vhdl-indent-tabs-mode' is nil, spaces are used instead of
    tabs. `\\[tabify]' and `\\[untabify]' allow the conversion of spaces to
    tabs and vice versa.

Syntax-based indentation can be very slow in large files. Option
`vhdl-indent-syntax-based' allows you to use faster but simpler indentation.

      Option `vhdl-indent-comment-like-next-code-line' controls whether
    comment lines are indented like the preceding or like the following code
    line.

  ALIGNMENT:
    The alignment functions align operators, keywords, and inline comments
    to beautify the code. `C-c C-a C-a' aligns a group of consecutive lines
    separated by blank lines, `C-c C-a C-i' a block of lines with same
    indent. `C-c C-a C-l' aligns all lines belonging to a list enclosed by
    a pair of parentheses (e.g. port clause/map, argument list), and `C-c
    C-a C-d' all lines within the declarative part of a design unit. `C-c
    C-a M-a' aligns an entire region. `C-c C-a C-c' aligns inline comments
    for a group of lines, and `C-c C-a M-c' for a region.

      If option `vhdl-align-groups' is non-nil, groups of code lines
    separated by special lines (see option `vhdl-align-group-separate') are
    aligned individually. If option `vhdl-align-same-indent' is non-nil,
    blocks of lines with same indent are aligned separately. Some templates
    are automatically aligned after generation if option `vhdl-auto-align'
    is non-nil.

      Alignment tries to align inline comments at
    `vhdl-inline-comment-column' and tries inline comment not to exceed
    `vhdl-end-comment-column'.

`C-c C-x M-w' fixes up whitespace in a region. That is, operator
symbols are surrounded by one space, and multiple spaces are eliminated.

  CODE FILLING:
    Code filling allows you to condense code (e.g. sensitivity lists or port
    maps) by removing comments and newlines and re-wrapping so that all
    lines are maximally filled (block filling). `C-c C-f C-f' fills a list
    enclosed by parenthesis, `C-c C-f C-g' a group of lines separated by
    blank lines, `C-c C-f C-i' a block of lines with same indent, and
    `C-c C-f M-f' an entire region.

  CODE BEAUTIFICATION:
    `C-c M-b' and `C-c C-b' beautify the code of a region or of the entire
    buffer respectively. This includes indentation, alignment, and case
    fixing. Code beautification can also be run non-interactively using the
    command:

emacs -batch -l ~/.emacs filename.vhd -f vhdl-beautify-buffer

  PORT TRANSLATION:
    Generic and port clauses from entity or component declarations can be
    copied (`C-c C-p C-w') and pasted as entity and component declarations,
    as component instantiations and corresponding internal constants and
    signals, as a generic map with constants as actual generics, and as
    internal signal initializations (menu).

      To include formals in component instantiations, see option
    `vhdl-association-list-with-formals'. To include comments in pasting,
    see options `vhdl-include-...-comments'.

      A clause with several generic/port names on the same line can be
    flattened (`C-c C-p C-f') so that only one name per line exists. The
    direction of ports can be reversed (`C-c C-p C-r'), i.e., inputs become
    outputs and vice versa, which can be useful in testbenches. (This
    reversion is done on the internal data structure and is only reflected
    in subsequent paste operations.)

      Names for actual ports, instances, testbenches, and
    design-under-test instances can be derived from existing names according
    to options `vhdl-...-name'. See customization group `vhdl-port'.

  SUBPROGRAM TRANSLATION:
    Similar functionality exists for copying/pasting the interface of
    subprograms (function/procedure). A subprogram interface can be copied
    and then pasted as a subprogram declaration, body or call (uses
    association list with formals).

  TESTBENCH GENERATION:
    A copied port can also be pasted as a testbench. The generated
    testbench includes an entity, an architecture, and an optional
    configuration. The architecture contains the component declaration and
    instantiation of the DUT as well as internal constant and signal
    declarations. Additional user-defined templates can be inserted. The
    names used for entity/architecture/configuration/DUT as well as the file
    structure to be generated can be customized. See customization group
   `vhdl-testbench'.

KEY BINDINGS:
Key bindings (`C-c ...') exist for most commands (see in menu).

VHDL MENU:
All commands can be found in the VHDL menu including their key bindings.

  FILE BROWSER:
    The speedbar allows browsing of directories and file contents. It can
    be accessed from the VHDL menu and is automatically opened if option
    `vhdl-speedbar-auto-open' is non-nil.

In speedbar, open files and directories with `mouse-2' on the name and
browse/rescan their contents with `mouse-2'/`S-mouse-2' on the `+'.

  DESIGN HIERARCHY BROWSER:
    The speedbar can also be used for browsing the hierarchy of design units
    contained in the source files of the current directory or the specified
    projects (see option `vhdl-project-alist').

      The speedbar can be switched between file, directory hierarchy and
    project hierarchy browsing mode in the speedbar menu or by typing `f',
    `h' or `H' in speedbar.

      In speedbar, open design units with `mouse-2' on the name and browse
    their hierarchy with `mouse-2' on the `+'. Ports can directly be copied
    from entities and components (in packages). Individual design units and
    complete designs can directly be compiled ("Make" menu entry).

      The hierarchy is automatically updated upon saving a modified source
    file when option `vhdl-speedbar-update-on-saving' is non-nil. The
    hierarchy is only updated for projects that have been opened once in the
    speedbar. The hierarchy is cached between Emacs sessions in a file (see
    options in group `vhdl-speedbar').

      Simple design consistency checks are done during scanning, such as
    multiple declarations of the same unit or missing primary units that are
    required by secondary units.

  STRUCTURAL COMPOSITION:
    Enables simple structural composition. `C-c C-m C-n' creates a skeleton
    for a new component. Subcomponents (i.e. component declaration and
    instantiation) can be automatically placed from a previously read port
    (`C-c C-m C-p') or directly from the hierarchy browser (`P'). Finally,
    all subcomponents can be automatically connected using internal signals
    and ports (`C-c C-m C-w') following these rules:
      - subcomponent actual ports with same name are considered to be
        connected by a signal (internal signal or port)
      - signals that are only inputs to subcomponents are considered as
        inputs to this component -> input port created
      - signals that are only outputs from subcomponents are considered as
        outputs from this component -> output port created
      - signals that are inputs to AND outputs from subcomponents are
        considered as internal connections -> internal signal created

      Purpose: With appropriate naming conventions it is possible to
    create higher design levels with only a few mouse clicks or key
    strokes. A new design level can be created by simply generating a new
    component, placing the required subcomponents from the hierarchy
    browser, and wiring everything automatically.

Note: Automatic wiring only works reliably on templates of new
components and component instantiations that were created by VHDL mode.

      Component declarations can be placed in a components package (option
    `vhdl-use-components-package') which can be automatically generated for
    an entire directory or project (`C-c C-m M-p'). The VHDL'93 direct
    component instantiation is also supported (option
    `vhdl-use-direct-instantiation').

      Configuration declarations can automatically be generated either from
    the menu (`C-c C-m C-f') (for the architecture the cursor is in) or from
    the speedbar menu (for the architecture under the cursor). The
    configurations can optionally be hierarchical (i.e. include all
    component levels of a hierarchical design, option
    `vhdl-compose-configuration-hierarchical') or include subconfigurations
    (option `vhdl-compose-configuration-use-subconfiguration'). For
    subcomponents in hierarchical configurations, the most-recently-analyzed
    (mra) architecture is selected. If another architecture is desired, it
    can be marked as most-recently-analyzed (speedbar menu) before
    generating the configuration.

      Note: Configurations of subcomponents (i.e. hierarchical configuration
    declarations) are currently not considered when displaying
    configurations in speedbar.

See the options group `vhdl-compose' for all relevant user options.

  SOURCE FILE COMPILATION:
    The syntax of the current buffer can be analyzed by calling a VHDL
    compiler (menu, `C-c C-k'). The compiler to be used is specified by
    option `vhdl-compiler'. The available compilers are listed in option
    `vhdl-compiler-alist' including all required compilation command,
    command options, compilation directory, and error message syntax
    information. New compilers can be added.

All the source files of an entire design can be compiled by the `make'
command (menu, `C-c M-C-k') if an appropriate Makefile exists.

  MAKEFILE GENERATION:
    Makefiles can be generated automatically by an internal generation
    routine (`C-c M-k'). The library unit dependency information is
    obtained from the hierarchy browser. Makefile generation can be
    customized for each compiler in option `vhdl-compiler-alist'.

Makefile generation can also be run non-interactively using the
command:

        emacs -batch -l ~/.emacs -l vhdl-mode
              [-compiler compilername] [-project projectname]
              -f vhdl-generate-makefile

      The Makefile's default target "all" compiles the entire design, the
    target "clean" removes it and the target "library" creates the
    library directory if not existent. These target names can be customized
    by option `vhdl-makefile-default-targets'. The Makefile also includes a
    target for each primary library unit which allows selective compilation
    of this unit, its secondary units and its subhierarchy (example:
    compilation of a design specified by a configuration). User specific
    parts can be inserted into a Makefile with option
    `vhdl-makefile-generation-hook'.

    Limitations:
      - Only library units and dependencies within the current library are
        considered. Makefiles for designs that span multiple libraries are
        not (yet) supported.
      - Only one-level configurations are supported (also hierarchical),
        but configurations that go down several levels are not.
      - The "others" keyword in configurations is not supported.

  PROJECTS:
    Projects can be defined in option `vhdl-project-alist' and a current
    project be selected using option `vhdl-project' (permanently) or from
    the menu or speedbar (temporarily). For each project, title and
    description strings (for the file headers), source files/directories
    (for the hierarchy browser and Makefile generation), library name, and
    compiler-dependent options, exceptions and compilation directory can be
    specified. Compilation settings overwrite the settings of option
    `vhdl-compiler-alist'.

      Project setups can be exported (i.e. written to a file) and imported.
    Imported setups are not automatically saved in `vhdl-project-alist' but
    can be saved afterwards in its customization buffer. When starting
    Emacs with VHDL Mode (i.e. load a VHDL file or use "emacs -l
    vhdl-mode") in a directory with an existing project setup file, it is
    automatically loaded and its project activated if option
    `vhdl-project-autoload' is non-nil. Names/paths of the project setup
    files can be specified in option `vhdl-project-file-name'. Multiple
    project setups can be automatically loaded from global directories.
    This is an alternative to specifying project setups with option
    `vhdl-project-alist'.

  SPECIAL MENUS:
    As an alternative to the speedbar, an index menu can be added (set
    option `vhdl-index-menu' to non-nil) or made accessible as a mouse menu
    (e.g. add "(global-set-key [S-down-mouse-3] 'imenu)" to your start-up
    file) for browsing the file contents (is not populated if buffer is
    larger than 256000). Also, a source file menu can be
    added (set option `vhdl-source-file-menu' to non-nil) for browsing the
    current directory for VHDL source files.

  VHDL STANDARDS:
    The VHDL standards to be used are specified in option `vhdl-standard'.
    Available standards are: VHDL'87/'93(02)/'08, VHDL-AMS, and Math Packages.

  KEYWORD CASE:
    Lower and upper case for keywords and standardized types, attributes,
    and enumeration values is supported. If the option
    `vhdl-upper-case-keywords' is set to non-nil, keywords can be typed in
    lower case and are converted into upper case automatically (not for
    types, attributes, and enumeration values). The case of keywords,
    types, attributes,and enumeration values can be fixed for an entire
    region (menu) or buffer (`C-c C-x C-c') according to the options
    `vhdl-upper-case-{keywords,types,attributes,enum-values}'.

  HIGHLIGHTING (fontification):
    Keywords and standardized types, attributes, enumeration values, and
    function names (controlled by option `vhdl-highlight-keywords'), as well
    as comments, strings, and template prompts are highlighted using
    different colors. Unit, subprogram, signal, variable, constant,
    parameter and generic/port names in declarations as well as labels are
    highlighted if option `vhdl-highlight-names' is non-nil.

      Additional reserved words or words with a forbidden syntax (e.g. words
    that should be avoided) can be specified in option
    `vhdl-forbidden-words' or `vhdl-forbidden-syntax' and be highlighted in
    a warning color (option `vhdl-highlight-forbidden-words'). Verilog
    keywords are highlighted as forbidden words if option
    `vhdl-highlight-verilog-keywords' is non-nil.

      Words with special syntax can be highlighted by specifying their
    syntax and color in option `vhdl-special-syntax-alist' and by setting
    option `vhdl-highlight-special-words' to non-nil. This allows you to
    establish some naming conventions (e.g. to distinguish different kinds
    of signals or other objects by using name suffices) and to support them
    visually.

      Option `vhdl-highlight-case-sensitive' can be set to non-nil in order
    to support case-sensitive highlighting. However, keywords are then only
    highlighted if written in lower case.

      Code between "translate_off" and "translate_on" pragmas is
    highlighted using a different background color if option
    `vhdl-highlight-translate-off' is non-nil.

      For documentation and customization of the used colors see
    customization group `vhdl-highlight-faces' (`\\[customize-group]'). For
    highlighting of matching parenthesis, see customization group
    `paren-showing'. Automatic buffer highlighting is turned on/off by
    option `global-font-lock-mode' (`font-lock-auto-fontify' in XEmacs).

  USER MODELS:
    VHDL models (templates) can be specified by the user and made accessible
    in the menu, through key bindings (`C-c C-m ...'), or by keyword
    electrification. See option `vhdl-model-alist'.

  HIDE/SHOW:
    The code of blocks, processes, subprograms, component declarations and
    instantiations, generic/port clauses, and configuration declarations can
    be hidden using the `Hide/Show' menu or by pressing `S-mouse-2' within
    the code (see customization group `vhdl-menu'). XEmacs: limited
    functionality due to old `hideshow.el' package.

  CODE UPDATING:
    - Sensitivity List: `C-c C-u C-s' updates the sensitivity list of the
      current process, `C-c C-u M-s' of all processes in the current buffer.
      Limitations:
        - Only declared local signals (ports, signals declared in
          architecture and blocks) are automatically inserted.
        - Global signals declared in packages are not automatically inserted.
          Insert them once manually (will be kept afterwards).
        - Out parameters of procedures are considered to be read.
      Use option `vhdl-entity-file-name' to specify the entity file name
      (used to obtain the port names).
      Use option `vhdl-array-index-record-field-in-sensitivity-list' to
      specify whether to include array indices and record fields in
      sensitivity lists.

  CODE FIXING:
    `C-c C-x C-p' fixes the closing parenthesis of a generic/port clause
    (e.g., if the closing parenthesis is on the wrong line or is missing).

  PRINTING:
    PostScript printing with different faces (an optimized set of faces is
    used if `vhdl-print-customize-faces' is non-nil) or colors (if
    `ps-print-color-p' is non-nil) is possible using the standard Emacs
    PostScript printing commands. Option `vhdl-print-two-column' defines
    appropriate default settings for nice landscape two-column printing.
    The paper format can be set by option `ps-paper-type'. Do not forget to
    switch `ps-print-color-p' to nil for printing on black-and-white
    printers.

  OPTIONS:
    User options allow customization of VHDL Mode. All options are
    accessible from the "Options" menu entry. Simple options (switches
    and choices) can directly be changed, while for complex options a
    customization buffer is opened. Changed options can be saved for future
    sessions using the "Save Options" menu entry.

      Options and their detailed descriptions can also be accessed by using
    the "Customize" menu entry or the command `\\[customize-option]'
    (`\\[customize-group]' for groups). Some customizations only take effect
    after some action (read the NOTE in the option documentation).
    Customization can also be done globally (i.e. site-wide, read the
    INSTALL file).

Not all options are described in this documentation, so go and see
what other useful user options there are (`\\[vhdl-customize]' or menu)!

  FILE EXTENSIONS:
    As default, files with extensions ".vhd" and ".vhdl" are
    automatically recognized as VHDL source files. To add an extension
    ".xxx", add the following line to your Emacs start-up file (`.emacs'):

(push \\='("\\.xxx\\'" . vhdl-mode) auto-mode-alist)

  HINTS:
    - To start Emacs with open VHDL hierarchy browser without having to load
      a VHDL file first, use the command:

emacs -l vhdl-mode -f speedbar-frame-mode

- Type C-g C-g to interrupt long operations or if Emacs hangs.

- Some features only work on properly indented code.

RELEASE NOTES:
See also the release notes (menu) for added features in new releases.

Maintenance:
------------

To submit a bug report, enter M-x vhdl-submit-bug-report (vhdl-submit-bug-report) within VHDL Mode. Add a description of the problem and include a reproducible test case.

Questions and enhancement requests can be sent to <reto@gnu.org>.

The vhdl-mode-announce mailing list informs about new VHDL Mode releases. The vhdl-mode-victims mailing list informs about new VHDL Mode beta releases. You are kindly invited to participate in beta testing. Subscribe to above mailing lists by sending an email to <reto@gnu.org>.

VHDL Mode is officially distributed at https://guest.iis.ee.ethz.ch/~zimmi/emacs/vhdl-mode.html where the latest version can be found.

Known problems:
---------------

- XEmacs: Incorrect start-up when automatically opening speedbar.
- XEmacs: Indentation in XEmacs 21.4 (and higher).
- Indentation incorrect for new postponed VHDL keyword.
- Indentation incorrect for protected body construct.

The VHDL Mode Authors
Reto Zimmermann and Rod Whitby

Key bindings:
-------------

In addition to any hooks its parent mode prog-mode might have run, this mode runs the hook vhdl-mode-hook, as the final or penultimate step during initialization.

Probably introduced at or before Emacs version 20.3.

Key Bindings

Source Code

;; Defined in /usr/src/emacs/lisp/progmodes/vhdl-mode.el.gz
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;; Mode definition
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; performs all buffer local initializations

;;;###autoload
(define-derived-mode vhdl-mode prog-mode
  '("VHDL" (vhdl-electric-mode "/" (vhdl-stutter-mode "/"))
           (vhdl-electric-mode "e")
           (vhdl-stutter-mode "s"))
  "Major mode for editing VHDL code.

Usage:
------

  TEMPLATE INSERTION (electrification):
    After typing a VHDL keyword and entering `SPC', you are prompted for
    arguments while a template is generated for that VHDL construct.  Typing
    `RET' or `C-g' at the first (mandatory) prompt aborts the current
    template generation.  Optional arguments are indicated by square
    brackets and removed if the queried string is left empty.  Prompts for
    mandatory arguments remain in the code if the queried string is left
    empty.  They can be queried again by `C-c C-t C-q'.  Enabled
    electrification is indicated by `/e' in the mode line.

      Typing `M-SPC' after a keyword inserts a space without calling the
    template generator.  Automatic template generation (i.e.
    electrification) can be disabled (enabled) by typing `C-c C-m C-e' or by
    setting option `vhdl-electric-mode' (see OPTIONS).

      Template generators can be invoked from the VHDL menu, by key
    bindings, by typing `C-c C-i C-c' and choosing a construct, or by typing
    the keyword (i.e. first word of menu entry not in parenthesis) and
    `SPC'.  The following abbreviations can also be used: arch, attr, cond,
    conf, comp, cons, func, inst, pack, sig, var.

      Template styles can be customized in customization group
    `vhdl-template' (see OPTIONS).


  HEADER INSERTION:
    A file header can be inserted by `C-c C-t C-h'.  A file footer
    (template at the end of the file) can be inserted by `C-c C-t C-f'.
    See customization group `vhdl-header'.


  STUTTERING:
    Double striking of some keys inserts cumbersome VHDL syntax elements.
    Stuttering can be disabled (enabled) by typing `C-c C-m C-s' or by
    option `vhdl-stutter-mode'.  Enabled stuttering is indicated by `/s' in
    the mode line.  The stuttering keys and their effects are:

      ;;   -->  \" : \"       [   -->  (        --    -->  comment
      ;;;  -->  \" := \"      [[  -->  [        --CR  -->  comment-out code
      ..   -->  \" => \"      ]   -->  )        ---   -->  horizontal line
      ,,   -->  \" <= \"      ]]  -->  ]        ----  -->  display comment
      ==   -->  \" == \"      \\='\\='  -->  \\\"


  WORD COMPLETION:
    Typing `TAB' after a (not completed) word looks for a VHDL keyword or a
    word in the buffer that starts alike, inserts it and adjusts case.
    Re-typing `TAB' toggles through alternative word completions.  This also
    works in the minibuffer (i.e. in template generator prompts).

      Typing `TAB' after `(' looks for and inserts complete parenthesized
    expressions (e.g. for array index ranges).  All keywords as well as
    standard types and subprograms of VHDL have predefined abbreviations
    (e.g., type \"std\" and `TAB' will toggle through all standard types
    beginning with \"std\").

      Typing `TAB' after a non-word character indents the line if at the
    beginning of a line (i.e. no preceding non-blank characters), and
    inserts a tabulator stop otherwise.  `M-TAB' always inserts a tabulator
    stop.


  COMMENTS:
        `--'       puts a single comment.
        `---'      draws a horizontal line for separating code segments.
        `----'     inserts a display comment, i.e. two horizontal lines
                   with a comment in between.
        `--CR'     comments out code on that line.  Re-hitting CR comments
                   out following lines.
        `C-c C-c'  comments out a region if not commented out,
                   uncomments a region if already commented out.  Option
                   `comment-style' defines where the comment characters
                   should be placed (beginning of line, indent, etc.).

      You are prompted for comments after object definitions (i.e. signals,
    variables, constants, ports) and after subprogram and process
    specifications if option `vhdl-prompt-for-comments' is non-nil.
    Comments are automatically inserted as additional labels (e.g. after
    begin statements) and as help comments if `vhdl-self-insert-comments' is
    non-nil.

      Inline comments (i.e. comments after a piece of code on the same line)
    are indented at least to `vhdl-inline-comment-column'.  Comments go at
    maximum to `vhdl-end-comment-column'.  `RET' after a space in a comment
    will open a new comment line.  Typing beyond `vhdl-end-comment-column'
    in a comment automatically opens a new comment line.  `M-q' re-fills
    multi-line comments.


  INDENTATION:
    `TAB' indents a line if at the beginning of the line.  The amount of
    indentation is specified by option `vhdl-basic-offset'.  `C-c C-i C-l'
    always indents the current line (is bound to `TAB' if option
    `vhdl-intelligent-tab' is nil).  If a region is active, `TAB' indents
    the entire region.

      Indentation can be done for a group of lines (`C-c C-i C-g'), a region
    (`M-C-\\') or the entire buffer (menu).  Argument and port lists are
    indented normally (nil) or relative to the opening parenthesis (non-nil)
    according to option `vhdl-argument-list-indent'.

      If option `vhdl-indent-tabs-mode' is nil, spaces are used instead of
    tabs.  `\\[tabify]' and `\\[untabify]' allow the conversion of spaces to
    tabs and vice versa.

      Syntax-based indentation can be very slow in large files.  Option
    `vhdl-indent-syntax-based' allows you to use faster but simpler indentation.

      Option `vhdl-indent-comment-like-next-code-line' controls whether
    comment lines are indented like the preceding or like the following code
    line.


  ALIGNMENT:
    The alignment functions align operators, keywords, and inline comments
    to beautify the code.  `C-c C-a C-a' aligns a group of consecutive lines
    separated by blank lines, `C-c C-a C-i' a block of lines with same
    indent.  `C-c C-a C-l' aligns all lines belonging to a list enclosed by
    a pair of parentheses (e.g. port clause/map, argument list), and `C-c
    C-a C-d' all lines within the declarative part of a design unit.  `C-c
    C-a M-a' aligns an entire region.  `C-c C-a C-c' aligns inline comments
    for a group of lines, and `C-c C-a M-c' for a region.

      If option `vhdl-align-groups' is non-nil, groups of code lines
    separated by special lines (see option `vhdl-align-group-separate') are
    aligned individually.  If option `vhdl-align-same-indent' is non-nil,
    blocks of lines with same indent are aligned separately.  Some templates
    are automatically aligned after generation if option `vhdl-auto-align'
    is non-nil.

      Alignment tries to align inline comments at
    `vhdl-inline-comment-column' and tries inline comment not to exceed
    `vhdl-end-comment-column'.

      `C-c C-x M-w' fixes up whitespace in a region.  That is, operator
    symbols are surrounded by one space, and multiple spaces are eliminated.


  CODE FILLING:
    Code filling allows you to condense code (e.g. sensitivity lists or port
    maps) by removing comments and newlines and re-wrapping so that all
    lines are maximally filled (block filling).  `C-c C-f C-f' fills a list
    enclosed by parenthesis, `C-c C-f C-g' a group of lines separated by
    blank lines, `C-c C-f C-i' a block of lines with same indent, and
    `C-c C-f M-f' an entire region.


  CODE BEAUTIFICATION:
    `C-c M-b' and `C-c C-b' beautify the code of a region or of the entire
    buffer respectively.  This includes indentation, alignment, and case
    fixing.  Code beautification can also be run non-interactively using the
    command:

      emacs -batch -l ~/.emacs filename.vhd -f vhdl-beautify-buffer


  PORT TRANSLATION:
    Generic and port clauses from entity or component declarations can be
    copied (`C-c C-p C-w') and pasted as entity and component declarations,
    as component instantiations and corresponding internal constants and
    signals, as a generic map with constants as actual generics, and as
    internal signal initializations (menu).

      To include formals in component instantiations, see option
    `vhdl-association-list-with-formals'.  To include comments in pasting,
    see options `vhdl-include-...-comments'.

      A clause with several generic/port names on the same line can be
    flattened (`C-c C-p C-f') so that only one name per line exists.  The
    direction of ports can be reversed (`C-c C-p C-r'), i.e., inputs become
    outputs and vice versa, which can be useful in testbenches.  (This
    reversion is done on the internal data structure and is only reflected
    in subsequent paste operations.)

      Names for actual ports, instances, testbenches, and
    design-under-test instances can be derived from existing names according
    to options `vhdl-...-name'.  See customization group `vhdl-port'.


  SUBPROGRAM TRANSLATION:
    Similar functionality exists for copying/pasting the interface of
    subprograms (function/procedure).  A subprogram interface can be copied
    and then pasted as a subprogram declaration, body or call (uses
    association list with formals).


  TESTBENCH GENERATION:
    A copied port can also be pasted as a testbench.  The generated
    testbench includes an entity, an architecture, and an optional
    configuration.  The architecture contains the component declaration and
    instantiation of the DUT as well as internal constant and signal
    declarations.  Additional user-defined templates can be inserted.  The
    names used for entity/architecture/configuration/DUT as well as the file
    structure to be generated can be customized. See customization group
   `vhdl-testbench'.


  KEY BINDINGS:
    Key bindings (`C-c ...') exist for most commands (see in menu).


  VHDL MENU:
    All commands can be found in the VHDL menu including their key bindings.


  FILE BROWSER:
    The speedbar allows browsing of directories and file contents.  It can
    be accessed from the VHDL menu and is automatically opened if option
    `vhdl-speedbar-auto-open' is non-nil.

      In speedbar, open files and directories with `mouse-2' on the name and
    browse/rescan their contents with `mouse-2'/`S-mouse-2' on the `+'.


  DESIGN HIERARCHY BROWSER:
    The speedbar can also be used for browsing the hierarchy of design units
    contained in the source files of the current directory or the specified
    projects (see option `vhdl-project-alist').

      The speedbar can be switched between file, directory hierarchy and
    project hierarchy browsing mode in the speedbar menu or by typing `f',
    `h' or `H' in speedbar.

      In speedbar, open design units with `mouse-2' on the name and browse
    their hierarchy with `mouse-2' on the `+'.  Ports can directly be copied
    from entities and components (in packages).  Individual design units and
    complete designs can directly be compiled (\"Make\" menu entry).

      The hierarchy is automatically updated upon saving a modified source
    file when option `vhdl-speedbar-update-on-saving' is non-nil.  The
    hierarchy is only updated for projects that have been opened once in the
    speedbar.  The hierarchy is cached between Emacs sessions in a file (see
    options in group `vhdl-speedbar').

      Simple design consistency checks are done during scanning, such as
    multiple declarations of the same unit or missing primary units that are
    required by secondary units.


  STRUCTURAL COMPOSITION:
    Enables simple structural composition.  `C-c C-m C-n' creates a skeleton
    for a new component.  Subcomponents (i.e. component declaration and
    instantiation) can be automatically placed from a previously read port
    (`C-c C-m C-p') or directly from the hierarchy browser (`P').  Finally,
    all subcomponents can be automatically connected using internal signals
    and ports (`C-c C-m C-w') following these rules:
      - subcomponent actual ports with same name are considered to be
        connected by a signal (internal signal or port)
      - signals that are only inputs to subcomponents are considered as
        inputs to this component -> input port created
      - signals that are only outputs from subcomponents are considered as
        outputs from this component -> output port created
      - signals that are inputs to AND outputs from subcomponents are
        considered as internal connections -> internal signal created

      Purpose:  With appropriate naming conventions it is possible to
    create higher design levels with only a few mouse clicks or key
    strokes.  A new design level can be created by simply generating a new
    component, placing the required subcomponents from the hierarchy
    browser, and wiring everything automatically.

      Note: Automatic wiring only works reliably on templates of new
    components and component instantiations that were created by VHDL mode.

      Component declarations can be placed in a components package (option
    `vhdl-use-components-package') which can be automatically generated for
    an entire directory or project (`C-c C-m M-p').  The VHDL'93 direct
    component instantiation is also supported (option
    `vhdl-use-direct-instantiation').

      Configuration declarations can automatically be generated either from
    the menu (`C-c C-m C-f') (for the architecture the cursor is in) or from
    the speedbar menu (for the architecture under the cursor).  The
    configurations can optionally be hierarchical (i.e. include all
    component levels of a hierarchical design, option
    `vhdl-compose-configuration-hierarchical') or include subconfigurations
    (option `vhdl-compose-configuration-use-subconfiguration').  For
    subcomponents in hierarchical configurations, the most-recently-analyzed
    (mra) architecture is selected.  If another architecture is desired, it
    can be marked as most-recently-analyzed (speedbar menu) before
    generating the configuration.

      Note: Configurations of subcomponents (i.e. hierarchical configuration
    declarations) are currently not considered when displaying
    configurations in speedbar.

      See the options group `vhdl-compose' for all relevant user options.


  SOURCE FILE COMPILATION:
    The syntax of the current buffer can be analyzed by calling a VHDL
    compiler (menu, `C-c C-k').  The compiler to be used is specified by
    option `vhdl-compiler'.  The available compilers are listed in option
    `vhdl-compiler-alist' including all required compilation command,
    command options, compilation directory, and error message syntax
    information.  New compilers can be added.

      All the source files of an entire design can be compiled by the `make'
    command (menu, `C-c M-C-k') if an appropriate Makefile exists.


  MAKEFILE GENERATION:
    Makefiles can be generated automatically by an internal generation
    routine (`C-c M-k').  The library unit dependency information is
    obtained from the hierarchy browser.  Makefile generation can be
    customized for each compiler in option `vhdl-compiler-alist'.

      Makefile generation can also be run non-interactively using the
    command:

        emacs -batch -l ~/.emacs -l vhdl-mode
              [-compiler compilername] [-project projectname]
              -f vhdl-generate-makefile

      The Makefile's default target \"all\" compiles the entire design, the
    target \"clean\" removes it and the target \"library\" creates the
    library directory if not existent.  These target names can be customized
    by option `vhdl-makefile-default-targets'.  The Makefile also includes a
    target for each primary library unit which allows selective compilation
    of this unit, its secondary units and its subhierarchy (example:
    compilation of a design specified by a configuration).  User specific
    parts can be inserted into a Makefile with option
    `vhdl-makefile-generation-hook'.

    Limitations:
      - Only library units and dependencies within the current library are
        considered.  Makefiles for designs that span multiple libraries are
        not (yet) supported.
      - Only one-level configurations are supported (also hierarchical),
        but configurations that go down several levels are not.
      - The \"others\" keyword in configurations is not supported.


  PROJECTS:
    Projects can be defined in option `vhdl-project-alist' and a current
    project be selected using option `vhdl-project' (permanently) or from
    the menu or speedbar (temporarily).  For each project, title and
    description strings (for the file headers), source files/directories
    (for the hierarchy browser and Makefile generation), library name, and
    compiler-dependent options, exceptions and compilation directory can be
    specified.  Compilation settings overwrite the settings of option
    `vhdl-compiler-alist'.

      Project setups can be exported (i.e. written to a file) and imported.
    Imported setups are not automatically saved in `vhdl-project-alist' but
    can be saved afterwards in its customization buffer.  When starting
    Emacs with VHDL Mode (i.e. load a VHDL file or use \"emacs -l
    vhdl-mode\") in a directory with an existing project setup file, it is
    automatically loaded and its project activated if option
    `vhdl-project-autoload' is non-nil.  Names/paths of the project setup
    files can be specified in option `vhdl-project-file-name'.  Multiple
    project setups can be automatically loaded from global directories.
    This is an alternative to specifying project setups with option
    `vhdl-project-alist'.


  SPECIAL MENUS:
    As an alternative to the speedbar, an index menu can be added (set
    option `vhdl-index-menu' to non-nil) or made accessible as a mouse menu
    (e.g. add \"(global-set-key [S-down-mouse-3] \\='imenu)\" to your start-up
    file) for browsing the file contents (is not populated if buffer is
    larger than 256000).  Also, a source file menu can be
    added (set option `vhdl-source-file-menu' to non-nil) for browsing the
    current directory for VHDL source files.


  VHDL STANDARDS:
    The VHDL standards to be used are specified in option `vhdl-standard'.
    Available standards are: VHDL'87/'93(02)/'08, VHDL-AMS, and Math Packages.


  KEYWORD CASE:
    Lower and upper case for keywords and standardized types, attributes,
    and enumeration values is supported.  If the option
    `vhdl-upper-case-keywords' is set to non-nil, keywords can be typed in
    lower case and are converted into upper case automatically (not for
    types, attributes, and enumeration values).  The case of keywords,
    types, attributes,and enumeration values can be fixed for an entire
    region (menu) or buffer (`C-c C-x C-c') according to the options
    `vhdl-upper-case-{keywords,types,attributes,enum-values}'.


  HIGHLIGHTING (fontification):
    Keywords and standardized types, attributes, enumeration values, and
    function names (controlled by option `vhdl-highlight-keywords'), as well
    as comments, strings, and template prompts are highlighted using
    different colors.  Unit, subprogram, signal, variable, constant,
    parameter and generic/port names in declarations as well as labels are
    highlighted if option `vhdl-highlight-names' is non-nil.

      Additional reserved words or words with a forbidden syntax (e.g. words
    that should be avoided) can be specified in option
    `vhdl-forbidden-words' or `vhdl-forbidden-syntax' and be highlighted in
    a warning color (option `vhdl-highlight-forbidden-words').  Verilog
    keywords are highlighted as forbidden words if option
    `vhdl-highlight-verilog-keywords' is non-nil.

      Words with special syntax can be highlighted by specifying their
    syntax and color in option `vhdl-special-syntax-alist' and by setting
    option `vhdl-highlight-special-words' to non-nil.  This allows you to
    establish some naming conventions (e.g. to distinguish different kinds
    of signals or other objects by using name suffices) and to support them
    visually.

      Option `vhdl-highlight-case-sensitive' can be set to non-nil in order
    to support case-sensitive highlighting.  However, keywords are then only
    highlighted if written in lower case.

      Code between \"translate_off\" and \"translate_on\" pragmas is
    highlighted using a different background color if option
    `vhdl-highlight-translate-off' is non-nil.

      For documentation and customization of the used colors see
    customization group `vhdl-highlight-faces' (`\\[customize-group]').  For
    highlighting of matching parenthesis, see customization group
    `paren-showing'.  Automatic buffer highlighting is turned on/off by
    option `global-font-lock-mode' (`font-lock-auto-fontify' in XEmacs).


  USER MODELS:
    VHDL models (templates) can be specified by the user and made accessible
    in the menu, through key bindings (`C-c C-m ...'), or by keyword
    electrification.  See option `vhdl-model-alist'.


  HIDE/SHOW:
    The code of blocks, processes, subprograms, component declarations and
    instantiations, generic/port clauses, and configuration declarations can
    be hidden using the `Hide/Show' menu or by pressing `S-mouse-2' within
    the code (see customization group `vhdl-menu').  XEmacs: limited
    functionality due to old `hideshow.el' package.


  CODE UPDATING:
    - Sensitivity List: `C-c C-u C-s' updates the sensitivity list of the
      current process, `C-c C-u M-s' of all processes in the current buffer.
      Limitations:
        - Only declared local signals (ports, signals declared in
          architecture and blocks) are automatically inserted.
        - Global signals declared in packages are not automatically inserted.
          Insert them once manually (will be kept afterwards).
        - Out parameters of procedures are considered to be read.
      Use option `vhdl-entity-file-name' to specify the entity file name
      (used to obtain the port names).
      Use option `vhdl-array-index-record-field-in-sensitivity-list' to
      specify whether to include array indices and record fields in
      sensitivity lists.


  CODE FIXING:
    `C-c C-x C-p' fixes the closing parenthesis of a generic/port clause
    (e.g., if the closing parenthesis is on the wrong line or is missing).


  PRINTING:
    PostScript printing with different faces (an optimized set of faces is
    used if `vhdl-print-customize-faces' is non-nil) or colors (if
    `ps-print-color-p' is non-nil) is possible using the standard Emacs
    PostScript printing commands.  Option `vhdl-print-two-column' defines
    appropriate default settings for nice landscape two-column printing.
    The paper format can be set by option `ps-paper-type'.  Do not forget to
    switch `ps-print-color-p' to nil for printing on black-and-white
    printers.


  OPTIONS:
    User options allow customization of VHDL Mode.  All options are
    accessible from the \"Options\" menu entry.  Simple options (switches
    and choices) can directly be changed, while for complex options a
    customization buffer is opened.  Changed options can be saved for future
    sessions using the \"Save Options\" menu entry.

      Options and their detailed descriptions can also be accessed by using
    the \"Customize\" menu entry or the command `\\[customize-option]'
    (`\\[customize-group]' for groups).  Some customizations only take effect
    after some action (read the NOTE in the option documentation).
    Customization can also be done globally (i.e. site-wide, read the
    INSTALL file).

      Not all options are described in this documentation, so go and see
    what other useful user options there are (`\\[vhdl-customize]' or menu)!


  FILE EXTENSIONS:
    As default, files with extensions \".vhd\" and \".vhdl\" are
    automatically recognized as VHDL source files.  To add an extension
    \".xxx\", add the following line to your Emacs start-up file (`.emacs'):

      (push \\='(\"\\\\.xxx\\\\\\='\" . vhdl-mode) auto-mode-alist)


  HINTS:
    - To start Emacs with open VHDL hierarchy browser without having to load
      a VHDL file first, use the command:

        emacs -l vhdl-mode -f speedbar-frame-mode

    - Type `C-g C-g' to interrupt long operations or if Emacs hangs.

    - Some features only work on properly indented code.


  RELEASE NOTES:
    See also the release notes (menu) for added features in new releases.


Maintenance:
------------

To submit a bug report, enter `\\[vhdl-submit-bug-report]' within VHDL Mode.
Add a description of the problem and include a reproducible test case.

Questions and enhancement requests can be sent to <reto@gnu.org>.

The `vhdl-mode-announce' mailing list informs about new VHDL Mode releases.
The `vhdl-mode-victims' mailing list informs about new VHDL Mode beta
releases.  You are kindly invited to participate in beta testing.  Subscribe
to above mailing lists by sending an email to <reto@gnu.org>.

VHDL Mode is officially distributed at
https://guest.iis.ee.ethz.ch/~zimmi/emacs/vhdl-mode.html
where the latest version can be found.


Known problems:
---------------

- XEmacs: Incorrect start-up when automatically opening speedbar.
- XEmacs: Indentation in XEmacs 21.4 (and higher).
- Indentation incorrect for new `postponed' VHDL keyword.
- Indentation incorrect for `protected body' construct.


                                                The VHDL Mode Authors
                                            Reto Zimmermann and Rod Whitby

Key bindings:
-------------

\\{vhdl-mode-map}"
  :abbrev-table vhdl-mode-abbrev-table

  ;; set local variables
  (set (make-local-variable 'paragraph-start)
       "\\s-*\\(--+\\s-*$\\|$\\)")
  (set (make-local-variable 'paragraph-separate) paragraph-start)
  (set (make-local-variable 'paragraph-ignore-fill-prefix) t)
  (set (make-local-variable 'parse-sexp-ignore-comments) t)
  (set (make-local-variable 'indent-line-function) #'vhdl-indent-line)
  (set (make-local-variable 'comment-start) "--")
  (set (make-local-variable 'comment-end) "")
  (set (make-local-variable 'comment-column) vhdl-inline-comment-column)
  (set (make-local-variable 'end-comment-column) vhdl-end-comment-column)
  (set (make-local-variable 'comment-start-skip) "--+\\s-*")
  (set (make-local-variable 'comment-multi-line) nil)
  (set (make-local-variable 'indent-tabs-mode) vhdl-indent-tabs-mode)
  (set (make-local-variable 'hippie-expand-verbose) nil)

  ;; setup the comment indent variable in an Emacs version portable way
  ;; ignore any byte compiler warnings you might get here
  (when (boundp 'comment-indent-function)
    (set (make-local-variable 'comment-indent-function) #'vhdl-comment-indent))

  ;; initialize font locking
  (set (make-local-variable 'font-lock-defaults)
       (list
	'(nil vhdl-font-lock-keywords) nil
	(not vhdl-highlight-case-sensitive) '((?\_ . "w")) #'beginning-of-line))
  (if (eval-when-compile (fboundp 'syntax-propertize-rules))
      (set (make-local-variable 'syntax-propertize-function)
           (syntax-propertize-rules
            ;; Mark single quotes as having string quote syntax in
            ;; 'c' instances.
            ("\\('\\).\\('\\)" (1 "\"'") (2 "\"'"))))
    (set (make-local-variable 'font-lock-syntactic-keywords)
         vhdl-font-lock-syntactic-keywords))
  (when (featurep 'xemacs)
    (set (make-local-variable 'font-lock-support-mode) 'lazy-lock-mode)
    (set (make-local-variable 'lazy-lock-defer-contextually) nil)
    (set (make-local-variable 'lazy-lock-defer-on-the-fly) t)
    (set (make-local-variable 'lazy-lock-defer-on-scrolling) t))

  ;; variables for source file compilation
  (when vhdl-compile-use-local-error-regexp
    (set (make-local-variable 'compilation-error-regexp-alist) nil)
    (set (make-local-variable 'compilation-file-regexp-alist) nil))

  ;; add index menu
  (vhdl-index-menu-init)
  ;; add source file menu
  (if vhdl-source-file-menu (vhdl-add-source-files-menu))
  ;; add VHDL menu
  (when (featurep 'xemacs)
    (easy-menu-add vhdl-mode-menu-list))
  (easy-menu-define vhdl-mode-menu vhdl-mode-map
		    "Menu keymap for VHDL Mode." vhdl-mode-menu-list)
  ;; initialize hideshow and add menu
  (vhdl-hideshow-init)
  (run-hooks 'menu-bar-update-hook)

  ;; miscellaneous
  (vhdl-ps-print-init)
  (vhdl-write-file-hooks-init)
  (message "VHDL Mode %s.%s" vhdl-version
	   (if noninteractive "" "  See menu for documentation and release notes.")))

Function: vhdl-mode

Signature

Documentation

Key Bindings

Source Code

Function: `vhdl-mode`