6) A Cook's tour of QEF

6. A Simple QEF Build

In this page we use QEF to build etoc and ctoe and explore some of the basic QEF facilities.

Most QEF builds are done in the object directory so first we must chdir to the required location.

% qd -46 ctoe % ls -a # list the contents of the directory . ..

The source ls sls
The ls reveals that the directory is virtually empty. Unlike some other approaches, QEF does not use symbolic links or copy source into the object tree, thus the directory is empty as we have not built anything as yet. However, if we use the QEF tool sls we see there are files associated with this directory via the source path as named by the variable SrcPath which is initially set using the RootPath.
% sls /p/cook/s3.4/ctoe/RCS /p/cook/s3.4/ctoe/ctoe.1 /p/cook/s3.4/ctoe/ctoe.c /p/cook/s3.4/ctoe/ctoe.h /p/cook/s3.4/ctoe/ctoel.l /p/cook/s3.4/ctoe/ctoey.y /p/cook/s3.4/ctoe/etoc.1 /p/cook/s3.4/ctoe/etoc.l /p/cook/s3.4/ctoe/qeffile % sls -c # list in columns by directory /p/cook/s3.4/ctoe: RCS ctoe.1 ctoe.c ctoe.h ctoel.l ctoey.y etoc.1 etoc.l qeffile % sls qeffile # sls can also find a file in the source path /p/cook/s3.4/ctoe/qeffile

Let's look at that qeffile.
% cat `sls qeffile`

cats: A Convenient Alias
But wait. The above form is a little awkward and we'll need to do it a lot, so lets make things easier.
% qfunc cats # show function cats cats() { cat $(sls $*) ; } % qfunc -c cats # show csh form of function cats alias cats 'cat `sls \!$`' % eval `qfunc cats` # define cats % qfunc # list other available functions Ev invoke envset for selected set Qf eval qfunc for selected function cats invoke cat on file(s) found using sls eds invoke $EDITOR on file(s) found using sls pdirs pushd and popd implemented with pdirs qd chdir using qds selection qdp pushd using qds selection qdpush pushd using qds selection # user can create their own qfunc entries -- see qfunc(1)

Now back to our regular program:
% cats qeffile set _F_qyacc[ctoey.y] -h -yctoe set _F_qlex[ctoel.l] -yctoe addpath InclPath @SrcPath -s @QTREE/include addpath LibPath -s @QTREE/lib set Suffixes -std 1 # that's a digit one, not an lower case L Begin program ctoe.c ctoey.y ctoel.l commands @argv

The Begin line
The lines in the above file before the Begin lines are actually more qvrs configuration lines. The first two lines are setting flags for the compilation of the ctoe lex and yacc sources. The InclPath and LibPath sets are extending the current search paths for #includes and libraries respectively. The Suffixes line is setting the suffixes that indicate source files. The std1 specifies that the standard suffixes and 1 (for manual sections) are to be used.
The Begin line itself is very significant in that it terminates the qvrs segment of the qeffile, but it also specifies the command to be used to translate the lines that follow. In this case the default value -- usually qsg M -- will be used.
The lines that follow the Begin are usually input to the command specified by the Begin line. In this case the directives are to build a program using the ctoe*.[cyl] sources and to process any other sources selected by the Suffixes as commands (which includes manual sections).

Let's build something
Every directory that has things to be built or processed will have an associated qeffile. So let's see it in action, but to keep it simple we'll just build etoc at this time.
% qef -v etoc # the -v flag causes sub-command echos #{ -v etoc @gobo 2003/07/17 23:15:03 # qvrs -Bp -LQefArgs=etoc -o/tmp/qv_09844a.tmp # QEFHALTFILE: /g/dt/cook/obj/ctoe/%qef09844b.hlt # cwd=/g/dt/cook/obj/ctoe # sls -Ls New: /p/cook/s3.4/ctoe/ctoe.1 New: /p/cook/s3.4/ctoe/ctoe.c New: /p/cook/s3.4/ctoe/ctoel.l New: /p/cook/s3.4/ctoe/ctoey.y New: /p/cook/s3.4/ctoe/etoc.1 New: /p/cook/s3.4/ctoe/etoc.l # qsg -M # incls -MUS # mimk -f /tmp/qefa09844 etoc Warning: "qmkhist._" does not exist -- everything will be redone See warnMimk1(x-qmisc) + qlex /p/cook/s3.4/ctoe/etoc.l + cc -c -I. -I/g/dt/cook/work/ctoe -I/p/cook/s3.4/ctoe \ -I/p/qtree/9.1/linux2_0i/include etoc.c + cc -o etoc etoc.o -L/p/qtree/9.1/linux2_0i/lib -ldt \ /p/qtree/9.1/linux2_0i/lib/libl.a #} E0 gobo@/g/dt/cook/obj/ctoe 2003/07/17 23:15:04(1)

Some things to note in the above
Each QEF invocation, included the nested ones, generate header ("#{") and trailer ("#}") lines that include the start and stop times, the arguments, host, current directory, and the exit status. Nested invocations show the level of nesting with minus signs as in "#--{ ... #--}".
The second line ("# qvrs ...") invokes qvrs to build a binary version of the qvrs database that can be loaded directly by programs within this directory.
The third line ("# QEFHALTFILE: ...") names the halt file. This file is created by the top level QEF invocation and contains a trail of the qef commands. It also serves as a mechanism to halt the QEF session as suggested by the name. If this file is removed or write protected, associated QEF, mimk and qsh (our normal back ends) will gently come to a halt (i.e., not start any new processes).
The # sls, qsg, incls, mimk lines indicate the QEF sub-commands. These lines are not output unless the v flag is specified.
This QEF session is typical of about fifty percent of QEF managed directories, but there are many other variations as specified by the qvrs settings. See The QEF Architecture section.
The sls Ls command searches the source path for files that match the Suffixes variable, suppressing generated files (e.g., etoc.c which is created from etoc.l), and files that are hidden by files of the same name that occur earlier in the source path. The L flag specifies that the list of files is to be stored in the file srclist._ and to report any changes to an existing srclist._ such as the New: lines shown above.

qsg: The Primary Script Generator
qsg is the most commonly used script generator in that it is used in about seventy five percent of directories. Two thirds of those directories use the M flag which specifies that srclist._ is to be processed as the qsg argument list. qsg's purpose in this instance is to translate the lines of the qeffile after the Begin line into input for mimk.

incls: The Dependency Generator
The incls command generates the dependencies, such as those implied by "#include" lines. This is a very fast dependency analyser (ten times faster than makedepend) that maintains a cache of previous scans to make it even faster (a hundred times faster). This efficiency means that it can be run everytime, thereby assuring the accuracy of the source implied dependencies. It also handles a variety of other languages such as TeX, bcpl, and f77.

mimk: The Primary Back End
mimk is QEF's analogue of make, however, given the use of script generator and qvrs, mimk does not need suffix rules and variables. Instead it provides a history mechanism, parallel execution, virtual dependencies, transitive dependencies, and a number of other important features.
But the preceding is just the build. The next page describes a variety of other QEF facilities.

cook16.qh - 1.25 - 03/10/24


	% qd -46 ctoe % ls -a # list the contents of the directory . ..
The source ls sls	The ls reveals that the directory is virtually empty. Unlike some other approaches, *QEF* does not use symbolic links or copy source into the object tree, thus the directory is empty as we have not built anything as yet. However, if we use the *QEF* tool sls we see there are files associated with this directory via the source path as named by the variable SrcPath which is initially set using the RootPath. % sls /p/cook/s3.4/ctoe/RCS /p/cook/s3.4/ctoe/ctoe.1 /p/cook/s3.4/ctoe/ctoe.c /p/cook/s3.4/ctoe/ctoe.h /p/cook/s3.4/ctoe/ctoel.l /p/cook/s3.4/ctoe/ctoey.y /p/cook/s3.4/ctoe/etoc.1 /p/cook/s3.4/ctoe/etoc.l /p/cook/s3.4/ctoe/qeffile % sls -c # list in columns by directory /p/cook/s3.4/ctoe: RCS ctoe.1 ctoe.c ctoe.h ctoel.l ctoey.y etoc.1 etoc.l qeffile % sls qeffile # sls can also find a file in the source path /p/cook/s3.4/ctoe/qeffile Let's look at that qeffile. % cat `sls qeffile`
cats: A Convenient Alias	But wait. The above form is a little awkward and we'll need to do it a lot, so lets make things easier. % qfunc cats # show function cats cats() { cat $(sls $) ; } % qfunc -c cats* # show csh form of function cats alias cats 'cat `sls \!$`' % eval `qfunc cats` # define cats % qfunc # list other available functions Ev invoke envset for selected set Qf eval qfunc for selected function cats invoke cat on file(s) found using sls eds invoke $EDITOR on file(s) found using sls pdirs pushd and popd implemented with pdirs qd chdir using qds selection qdp pushd using qds selection qdpush pushd using qds selection # user can create their own qfunc entries -- see qfunc(1) Now back to our regular program: % cats qeffile set _F_qyacc[ctoey.y] -h -yctoe set _F_qlex[ctoel.l] -yctoe addpath InclPath @SrcPath -s @QTREE/include addpath LibPath -s @QTREE/lib set Suffixes -std 1 # that's a digit one, not an lower case L Begin program ctoe.c ctoey.y ctoel.l commands @argv
The Begin line	The lines in the above file before the Begin lines are actually more qvrs configuration lines. The first two lines are setting flags for the compilation of the ctoe lex and yacc sources. The InclPath and LibPath sets are extending the current search paths for #includes and libraries respectively. The Suffixes line is setting the suffixes that indicate source files. The std1 specifies that the standard suffixes and 1 (for manual sections) are to be used. The Begin line itself is very significant in that it terminates the qvrs segment of the qeffile, but it also specifies the command to be used to translate the lines that follow. In this case the default value -- usually qsg M -- will be used. The lines that follow the Begin are usually input to the command specified by the Begin line. In this case the directives are to build a program using the *ctoe.[cyl] sources and to process any other sources selected by the Suffixes** as commands (which includes manual sections).
Let's build something	Every directory that has things to be built or processed will have an associated qeffile. So let's see it in action, but to keep it simple we'll just build etoc at this time. % qef -v etoc # the -v flag causes sub-command echos #{ -v etoc @gobo 2003/07/17 23:15:03 # qvrs -Bp -LQefArgs=etoc -o/tmp/qv_09844a.tmp # QEFHALTFILE: /g/dt/cook/obj/ctoe/%qef09844b.hlt # cwd=/g/dt/cook/obj/ctoe # sls -Ls New: /p/cook/s3.4/ctoe/ctoe.1 New: /p/cook/s3.4/ctoe/ctoe.c New: /p/cook/s3.4/ctoe/ctoel.l New: /p/cook/s3.4/ctoe/ctoey.y New: /p/cook/s3.4/ctoe/etoc.1 New: /p/cook/s3.4/ctoe/etoc.l # qsg -M # incls -MUS # mimk -f /tmp/qefa09844 etoc Warning: "qmkhist._" does not exist -- everything will be redone See warnMimk1(x-qmisc) + qlex /p/cook/s3.4/ctoe/etoc.l + cc -c -I. -I/g/dt/cook/work/ctoe -I/p/cook/s3.4/ctoe \ -I/p/qtree/9.1/linux2_0i/include etoc.c + cc -o etoc etoc.o -L/p/qtree/9.1/linux2_0i/lib -ldt \ /p/qtree/9.1/linux2_0i/lib/libl.a #} E0 gobo@/g/dt/cook/obj/ctoe 2003/07/17 23:15:04(1)
Some things to note in the above	Each *QEF* invocation, included the nested ones, generate header ("`#{`") and trailer ("`#}`") lines that include the start and stop times, the arguments, host, current directory, and the exit status. Nested invocations show the level of nesting with minus signs as in "`#--{` ... `#--}`". The second line ("# qvrs ...") invokes qvrs to build a binary version of the qvrs database that can be loaded directly by programs within this directory. The third line ("# QEFHALTFILE: ...") names the halt file. This file is created by the top level *QEF* invocation and contains a trail of the qef commands. It also serves as a mechanism to halt the *QEF* session as suggested by the name. If this file is removed or write protected, associated *QEF, mimk and qsh (our normal back ends) will gently come to a halt (i.e., not start any new processes). The # sls, qsg, incls, mimk* lines indicate the *QEF* sub-commands. These lines are not output unless the v flag is specified. This *QEF* session is typical of about fifty percent of *QEF* managed directories, but there are many other variations as specified by the qvrs settings. See The QEF Architecture section. The sls Ls command searches the source path for files that match the Suffixes variable, suppressing generated files (e.g., etoc.c which is created from etoc.l), and files that are hidden by files of the same name that occur earlier in the source path. The L flag specifies that the list of files is to be stored in the file srclist._ and to report any changes to an existing srclist._ such as the New: lines shown above.
qsg: The Primary Script Generator	qsg is the most commonly used script generator in that it is used in about seventy five percent of directories. Two thirds of those directories use the M flag which specifies that srclist._ is to be processed as the qsg argument list. qsg's purpose in this instance is to translate the lines of the qeffile after the Begin line into input for mimk.
incls: The Dependency Generator	The incls command generates the dependencies, such as those implied by "#include" lines. This is a very fast dependency analyser (ten times faster than makedepend) that maintains a cache of previous scans to make it even faster (a hundred times faster). This efficiency means that it can be run everytime, thereby assuring the accuracy of the source implied dependencies. It also handles a variety of other languages such as TeX, bcpl, and f77.
mimk: The Primary Back End	mimk is *QEF's analogue of make, however, given the use of script generator and qvrs, mimk does not need suffix rules and variables. Instead it provides a history mechanism, parallel execution, virtual dependencies, transitive dependencies, and a number of other important features. But the preceding is just the build. The next page describes a variety of other QEF* facilities.