doc/dejagnu.1

   1 .\" Copyright (C) 2018  Free Software Foundation, Inc.
   2 .\" You may distribute this file under the terms of the GNU Free
   3 .\" Documentation License.
   4 .Dd December 17, 2018
   5 .Os GNU
   6 .Dt DEJAGNU 1 URM
   7 .Sh NAME
   8 .Nm dejagnu
   9 .Nd DejaGnu auxiliary command launcher
  10 .Sh SYNOPSIS
  11 .Nm dejagnu
  12 .Ao Ar command Ac
  13 .Op Fl -help \*(Ba Ar options...
  14 .Nm
  15 .Fl -help
  16 .Nm
  17 .Fl -version
  18 .Sh DESCRIPTION
  19 The
  20 .Nm
  21 command finds a script that implements the requested
  22 .Ar command ,
  23 selects from multiple implementations if available
  24 according to a fixed internal list, and executes the command.
  25 .Sh OPTIONS
  26 .Bl -tag -width ".Fl -version"
  27 .It Fl -help
  28 Print a help message instead of running a command.
  29 If no command is given, prints brief usage for
  30 .Nm
  31 itself.
  32 .It Fl V , -version
  33 Print a version banner for the launcher itself including the version of DejaGnu.
  34 Any command given is ignored.
  35 .It Fl v , -verbose
  36 Emit additional output describing the operation of the
  37 .Nm
  38 launcher itself.
  39 This option is also passed on to the invoked command.
  40 .El
  41 .Pp
  42 All arguments after the command name are passed to the invoked command.
  43 .Sh ENVIRONMENT
  44 .Bl -tag -width ".Ev DEJAGNULIBS"
  45 .It Ev DEJAGNULIBS
  46 If set, the location of DejaGnu's library in the filesystem.
  47 The search described in
  48 .Sx FILES
  49 does not happen if
  50 .Ev DEJAGNULIBS
  51 is set.
  52 .It Ev AWK
  53 Full file name for an Awk interpreter that may or may not actually be GNU Awk.
  54 If not set,
  55 .Ev PATH
  56 will be searched for an
  57 .Nm awk
  58 program.
  59 If the Awk interpreter is actually GNU Awk, the
  60 .Fl -posix
  61 option will be given if an Awk implementation is used.
  62 .It Ev GAWK
  63 Full file name for GNU Awk.  If not set,
  64 .Ev PATH
  65 will be searched for a
  66 .Nm gawk
  67 program.
  68 .It Ev BASH
  69 Full file name for GNU Bash.  If not set,
  70 .Ev PATH
  71 will be searched for a
  72 .Nm bash
  73 program.
  74 Note that Bash itself sets this variable, even when run as
  75 .Nm sh ,
  76 even when running a script.
  77 .It Ev EXPECT
  78 Full file name for Expect, which is a Tcl interpreter with the Expect
  79 extension already loaded.  If not set,
  80 .Ev PATH
  81 will be searched for an
  82 .Nm expect
  83 program.  Note that the DejaGnu core is written in Expect, so this
  84 interpreter should always be available.
  85 .It Ev TCLSH
  86 Full file name for a Tcl interpreter.  If not set,
  87 .Ev PATH
  88 will be searched for a
  89 .Nm tclsh
  90 program.
  91 .El
  92 .Pp
  93 Note that GNU Awk is considered a superset of Awk and that Expect is
  94 considered a superset of Tcl, allowing the former to be used to run scripts
  95 written for the latter.
  96 This means that, while Awk programs will generally be run with GNU
  97 extensions disabled using the
  98 .Fl -posix
  99 option to GNU Awk, Tcl programs may be run with either
 100 .Nm tclsh
 101 or
 102 .Nm expect
 103 and should be written accordingly.
 104 .Sh FILES
 105 .Bl -tag -width ".Pa $DEJAGNULIBS/commands"
 106 .It Pa $DEJAGNULIBS/commands
 107 If
 108 .Ev DEJAGNULIBS
 109 is set, all command scripts are expected to be in this directory.
 110 .El
 111 Otherwise, the first directory that actually exists in the following list
 112 is used, where
 113 .Pa @bindir@
 114 represents the directory containing
 115 .Nm
 116 itself.
 117 .Bl -item -offset indent
 118 .It
 119 .Pa @bindir@/../share/dejagnu/commands
 120 .It
 121 .Pa @bindir@/../../share/dejagnu/commands
 122 .It
 123 .Pa /usr/share/dejagnu/commands
 124 .It
 125 .Pa /usr/local/share/dejagnu/commands
 126 .El
 127 .\" .Sh EXAMPLES
 128 .Sh SEE ALSO
 129 The full documentation for DejaGnu is maintained as a Texinfo manual.
 130 If the
 131 .Nm info
 132 program is properly installed at your site, the command
 133 .Li info dejagnu
 134 should give you access to the complete manual.
 135 .Sh AUTHORS
 136 .An "Jacob Bachmeyer"
 137 .Sh BUGS
 138 The command name must precede all other arguments due to limitations of the
 139 shell.
 140 .\"  LocalWords:  Dt URM Nm DejaGnu Ao DEJAGNULIBS DejaGnu's Sx awk posix tclsh
 141 .\"  LocalWords:  tcl superset bindir usr Texinfo