Sections of the QEF Reference Card
For PDF, PostScript, HTML, and text versions see
../../html/docs/refcard1.pdf (PDF),
../../html/docs/refcard1.ps (PostScript),
../../html/quickref.html (HTML),
or <qtree>/lib/refcard1.{pdf,ps}}.
The QEF Quick Reference Card
User Setup
+ Set $QTREE to Q-Tree directory tree to be used:
export QTREE=qtree-root (possibly `lclqtree`)
+ Add $QTREE/bin to your $PATH
export PATH=$QTREE/bin:$PATH
+ Define qd used to chdir using qds:
eval `qfunc qd` # add -c if using csh
+ A useful function to edit a file from the source path:
eds() { $EDITOR $(sls $*) ; }
+ To set up 
/.qtree directory:
dirsetup -d $HOME dotqtree
+ To set up /.qtree directory with alternative name:
dirsetup -d $HOME -m .qtree=name dotqtree
export HOME_QTREE=$HOME/name
Documentation
+ Manual pages are in $QTREE/man
+ qefgui can be used to view man pages and x_db databases
+ Every Q-Tree program has an -x flag that outputs synopsis,
one line description, summary of flags and options.
+ quete or xdbs can be used to list or query x_db databases
xdbs will list available x-* databases
+ http://qef.gts.org/guide/pages/contents.html contains The Guide and other documentation
Documentation Conventions
+ topic(x-dbnm) refers to entry called topic in the x_db
database dbnm. To access this topic use: x-dbnm topic
+ @Variable refers to a qvrs variable. For documentation on
such a variable use: x-qvrs Variable
Navigating the Forest
Fields of a qdsrv path records:
Index Project Revision TreeType User Host Config Pathdirs ...
qds selection flags (i.e., a path-spec):
-p project *; -r revision *; -t treetype **;
-u user *; -h host *; -c config
-num 
explicit path number
* use `.' for current value; automatically applied, if
necessary, unless the -a flag is specified.
** -o == -tobject, -b == -tbaseline, -w == -tworking
qds -b -pproj # Find the baseline for project proj
qds -u. -a # Find all your paths
qds -R # Find the path of the current tree
qdid -s123 # Bind user's qdid to a specific path (e.g., 123)
qdid -s # Bind user's qdid to the current tree
qd -i # chdir to current path bound to user's qdid identifier
qd -I path-spec # chdir to selected path and
simultaneously bind user's qdid to it
qd -n # chdir to next (i.e., parent) tree in current @RootPath
qd path-spec subdir # chdir to subdir of selected path;
use /subdir to choose directory relative to root
qdmgt list -P # list current projects in the database
qdmgt -X # list messages supported by qdsrv
qdchk # check user's paths on current host
qhost host # check access to host and retrieve qtree and home
Setting Up Working and Object Trees
qd -pproject -b # chdir to project's baseline tree
mkqtree -w working-dir [sub-dirs ...] # create working
tree; use argument `.' to suppress creation of sub-dirs
qd -pathnum # chdir to new working tree
mkqtree -o object-directory # create an object tree
treedirs [sub-dirs ...] # create a tree's sub-directories
defaults to all sub-trees. If in object tree, defaults
to those sub-trees in the working directory.
Examining Your Current Configuration
qvrs # list current qvrs variables
qvrs -f # list current qvrs files
qvrs -Pr # output root.vrs
qvrs -Pc # output conf.vrs
confvrs # output settings by conf.vrs
confvrs -d # compare conf.vrs to default
qvrs @Variable ... # retrieve value of a qvrs variable
qvrs -W Var ... # list where qvrs variables set
qvrs -l # list library mapping controls
qvrs -XI # list cc -I flags
qvrs -VD # output value of @_DestDir_
qvrs -V? # output list of -V and -X short-cuts
Configuring Tree's root.vrs & conf.vrs
rootvrs -d dir # set _DestDir_
rootvrs -A dir # set RootAlias
rootvrs -c conf # set ConfigName
rootvrs -B host # set BuildHost use . for current host
rootvrs -h sys # name type of build system
rootvrs -H # equivalent to -h `system`
rootvrs -u # update current root.vrs from parent's root.vrs
Note: Can use +Variable=value to set variable
Note: Some settings may result in creation of new qdsrv path.
Use `qdmgt delete -number' to delete obsolete entry.
qconfset -v V=Val # add/change variable to conf.vrs
qconfset -o Opt # turn on option Opt
qconfset -n Opt # turn off option Opt
Reduced Qef -x
qef [-x2cFkMntvX] [-A...] [-d dir] [-[DUGL]...] [-P process] [-f file]
[-T {012}] [-m <num>] [args ...]
-x display this explanation
-c suppress the @ForbidQef check use at own risk
-t suppress the time check use at own risk
-n suppress execution by backend
-F force execution by backend
-v report all subcommands
-D mac=value set macro to value see qefdirs
-L var=value define qvrs value (e.g., -LDEBUGGING)
-P process apply special process see below
-d dir chdir to dir
-m <num> set maximum parallel processes to <num>
args ... arguments to backend assigned to @QefArgs
defaults to @_DefaultArgs_
Commonly Used -P Processes
halt halt qefs started from directory (chmod -w %qef*.hlt)
ppscript output macro processed script
script output script but don't process it
targets list target descriptions for directory
treewalk walk tree, but do nothing
inclswalk walk tree refresning running incls
Detaching Long Running Processes, etc.
go cmmd # detaches command merged outputs to ,.g
go -d cmmd # detaches command merged output to
/.qtree/goes/<host>/<pid><key>,g
g # view newest go file add -d to see go -d output
g -o # view second newest go file
g -num # view numth newest go file
g -O # view oldest go file
g -l # list go files
g -h # output head of selected go file
g -t # output tail of selected go file
g -q # show current qefs for all gofiles
g -Q # show qef termination lines for all gofiles
g -f # tail -f ,.g
g -R # remove go file and show next
goes # show go audit trail for current host
goes -hhost # show go audit trail for specified host
goes -h # show audit trails for all hosts
goes -p # purge completed jobs from current host go audit
gomonitor # monitors go messages
Running a Remote Command
qremote cmmd # run command on appropriate @BuildHost
qremote -<num> cmmd # run command in path number <num>
qremote -g ... # go -d the command on the selected host
qremote -v ... # verbosely report the full command
qremote -Sservice ... # run on one @_Servers_[service] hosts
Sls, Libs, Incls, Qhy, Qsg, Qefdirs ...
sls # list the files in the source path
sls -c # do it in columns
sls fname # find and list 1st file called fname in path
sls -a fname # find and list all files called fname in path
sls -S suffix # find all *.suffix files in source path
sls -g t_\* # find files that match t_* in path
sls -n fname # find and list file fname but not in cwd
libs file # list libraries for `sls file`
libs -a file # list libraries all forms
incls file # list includes for `sls file`
qhy module # output why and how module was last built
qhy -r module # qhy for module and each of its prereqs
qsg -M # most common script generator qsg the qeffile
using srclist._ as arguments usually generated by sls -Ls
qsg -c command ... # run qsg command
qsgdump -S hanoi # view source for qsg hanoi script
x-qsg -L \*scripts # list qsg scripts
qefdirs -L # show levels for current directory
use qef -DIto=4 to suppress Installs up to level 4
use qef -DDoto=8 to suppress builds after level 8
qefdirs -ldir # show dir's level
cush -d dir -E eset -sVar=Val cmmd ... # run cmmd
in directory dir, using envset set eset,
setting environment variable $Var to Val
Special @ Sequences in Qvrs
@@ A literal @
@<newline> Replaced by a space used to split up long lines
@. Null used to terminate variable name
@# A literal #
@NotSet Replaced by @NotSet
@var * Replaced by value of variable var
@var[index] * index evaluated before lookup done
@(func ...) * Call to function func see functions(x-qvrs)
@char Replaced by char
* may be followed by operators see tildeops(x-qsg)
See also: syntax(x-qvrs) expansion(x-qvrs) keywords(x-qvrs)
Special @ Sequences in Qsg
@<newline> Replaced by space used to split up long lines
@<space> A literal space
@<tab> A literal tab
@@ A literal @
@#... Ignore balance of the line or function arguments
@var * A value of variable var
@(name ...) * Call to function name
@[Var List ...] * Value of List assigned to Var
@[/List ...] Global variable named by first element set to
balance of list and list returned
@{Var} * Replaced by qvrs variable Var
@<script ...> * Invokes named script
* may be followed by operators see tildeops(x-qsg)
See also: qsg-input(x-qsg) qsg-syntax(x-qsg) functions(x-qsg) faq2 faq3
