.\" Copyright (C) 2018  Free Software Foundation, Inc.
.\" You may distribute this file under the terms of the GNU Free
.\" Documentation License.
.Dd December 17, 2018
.Os GNU
.Dt DEJAGNU 1 URM
.Sh NAME
.Nm dejagnu
.Nd DejaGnu auxiliary command launcher
.Sh SYNOPSIS
.Nm dejagnu
.Ao Ar command Ac
.Op Fl -help \*(Ba Ar options...
.Nm
.Fl -help
.Nm
.Fl -version
.Sh DESCRIPTION
The
.Nm
command finds a script that implements the requested
.Ar command ,
selects from multiple implementations if available
according to a fixed internal list, and executes the command.
.Sh OPTIONS
.Bl -tag -width ".Fl -version"
.It Fl -help
Print a help message instead of running a command.
If no command is given, prints brief usage for
.Nm
itself.
.It Fl V , -version
Print a version banner for the launcher itself including the version of DejaGnu.
Any command given is ignored.
.It Fl v , -verbose
Emit additional output describing the operation of the
.Nm
launcher itself.
This option is also passed on to the invoked command.
.El
.Pp
All arguments after the command name are passed to the invoked command.
.Sh ENVIRONMENT
.Bl -tag -width ".Ev DEJAGNULIBS"
.It Ev DEJAGNULIBS
If set, the location of DejaGnu's library in the filesystem.
The search described in
.Sx FILES
does not happen if
.Ev DEJAGNULIBS
is set.
.It Ev AWK
Full file name for an Awk interpreter that may or may not actually be GNU Awk.
If not set,
.Ev PATH
will be searched for an
.Nm awk
program.
If the Awk interpreter is actually GNU Awk, the
.Fl -posix
option will be given if an Awk implementation is used.
.It Ev GAWK
Full file name for GNU Awk.  If not set,
.Ev PATH
will be searched for a
.Nm gawk
program.
.It Ev BASH
Full file name for GNU Bash.  If not set,
.Ev PATH
will be searched for a
.Nm bash
program.
Note that Bash itself sets this variable, even when run as
.Nm sh ,
even when running a script.
.It Ev EXPECT
Full file name for Expect, which is a Tcl interpreter with the Expect
extension already loaded.  If not set,
.Ev PATH
will be searched for an
.Nm expect
program.  Note that the DejaGnu core is written in Expect, so this
interpreter should always be available.
.It Ev TCLSH
Full file name for a Tcl interpreter.  If not set,
.Ev PATH
will be searched for a
.Nm tclsh
program.
.El
.Pp
Note that GNU Awk is considered a superset of Awk and that Expect is
considered a superset of Tcl, allowing the former to be used to run scripts
written for the latter.
This means that, while Awk programs will generally be run with GNU
extensions disabled using the
.Fl -posix
option to GNU Awk, Tcl programs may be run with either
.Nm tclsh
or
.Nm expect
and should be written accordingly.
.Sh FILES
.Bl -tag -width ".Pa $DEJAGNULIBS/commands"
.It Pa $DEJAGNULIBS/commands
If
.Ev DEJAGNULIBS
is set, all command scripts are expected to be in this directory.
.El
Otherwise, the first directory that actually exists in the following list
is used, where
.Pa @bindir@
represents the directory containing
.Nm
itself.
.Bl -item -offset indent
.It
.Pa @bindir@/../share/dejagnu/commands
.It
.Pa @bindir@/../../share/dejagnu/commands
.It
.Pa /usr/share/dejagnu/commands
.It
.Pa /usr/local/share/dejagnu/commands
.El
.\" .Sh EXAMPLES
.Sh SEE ALSO
The full documentation for DejaGnu is maintained as a Texinfo manual.
If the
.Nm info
program is properly installed at your site, the command
.Li info dejagnu
should give you access to the complete manual.
.Sh AUTHORS
.An "Jacob Bachmeyer"
.Sh BUGS
The command name must precede all other arguments due to limitations of the
shell.
.\"  LocalWords:  Dt URM Nm DejaGnu Ao DEJAGNULIBS DejaGnu's Sx awk posix tclsh
.\"  LocalWords:  tcl superset bindir usr Texinfo