5) A Cook's tour of QEF

5. Tree Set Up and the ROOT.VRS File

In this page, we setup our working and object tree and introduce qvrs and its all important files root.vrs and conf.vrs.

For the sake of this tour we're going to pretend that the path #46 and its associated object and working trees do not exist so that we can create them to illustrate creating a development environment.

First chdir to the appropriate baseline:

% qd -pcook -b The following multiple directories matched: 26 cook 3.4 baseline dt gobo - /p/cook/s3.4 50 cook 2.2 baseline dt gobo - /p/cook/s2.2 qds: Use the index in the first column to resolve ambiguity % qd -26 # we want release 3.4 Using 26 cook 3.4 baseline dt gobo - /p/cook/s3.4

Creating a working tree
Now we will create a working directory for ctoe:
% mkqtree -w ~/cook/work ctoe # eliminated some of the output qdupd: Added: 27 cook 3.4 working dt gobo - /g/dt/cook/work /p/cook/s3.4 % qd -w # chdir to the newly created working directory Using 27 cook 3.4 working dt gobo - /g/dt/cook/work /p/cook/s3.4 % ls -RF # List the contents of the work tree ctoe/ root.vrs ctoe:

So far the tree is empty with the exception of the root.vrs file, which is a file that we'll find at the root of nearly every tree as one of its purposes is to define the root. The root.vrs file serves a number of other purposes, one of which is to specify the RootPath, but we'll get back to that later.

Creating a object tree
Now we'll create the object tree and chdir to it.
% mkqtree -D -o ../obj # D for default dest and config # eliminated some of the output qdupd: Added: 46 cook 3.4 object dt gobo linux2_0i /g/dt/cook/obj /g/dt/cook/work /p/cook/s3.4 % qd -o # chdir to the newly created object tree Using 46 cook 3.4 object dt gobo linux2_0i /g/dt/cook/obj /g/dt/cook/work /p/cook/s3.4 % ls -RF # list the contents of the object tree conf.vrs ctoe/ root.vrs ctoe:

The conf.vrs file was created by mkqtree o by copying the project's default configuration file. This file is provided to facilitate setting user options such as the versions of third party software to be used or client options.
The conf.vrs and root.vrs files are part of the qvrs system, which is the QEF parameterization package which will be explained in more detail later.

The root.vrs file
As was stated above, a root.vrs file is contained in every tree's root. In fact its location defines the root. Its purpose is to name the RootPath, specify the tree's type, configuration controls, release, project name, and a variety of other variables. Our current root.vrs file looks like the following, with additional comments in italics:
addpath RootPath /g/dt/cook/work /p/cook/s3.4 # other roots cset RootAlias @NotSet # optional alias for current root cset Project cook cset Revision 3.4 cset TreeType object # the type of the current tree cset TreeType[/g/dt/cook/work] working # other roots' types cset TreeType[/p/cook/s3.4] baseline cset BuildHost @NotSet # the host on which to run the build cset BuildSys Linux-2.0.34-i686 # this tree's configuration cset QremoteEnv @NotSet # explained later cset _DestDir_ @(resolve @RootDir/../dest) # the product dir cset ConfigName linux2_0i # abbreviated configuration name cset ConfVrs @NotSet # name of qvrs conf file cset SysVrs @NotSet # name of qvrs system config file cset TreedirsList @NotSet # name of directory list cset VCSys rcs # name of version system cset VCRoot @NotSet # location of VCSys tree cset VCBranch @NotSet # to circumvent CVS stupidity

rootvrs
The list of settings in root.vrs files is virtually the same for every root.vrs file as it is most often created or changed by the program rootvrs.
A couple of further explanations are in order. "cset" is a qvrs keyword to set a variable, but only if it is not set already.
The value @NotSet is a magic value which when assigned to a variable undefines that variable. When combined with cset, as in:
cset RootAlias @NotSet
the combination is effectively a no-op, as the variable is not set if already set, but if not set, it is assigned @NotSet which unsets it (which it is already). This provides a convenient mechanism for annotated place holders in a configuration file.
Given the standard nature of the root.vrs file, a program rootvrs is provided to set the standard variables. At this time we will set the BuildHost variable to the current host, as the remote building mechanism is to be demonstrated later.
% rootvrs -B. # reduced display of the new root.vrs cset BuildHost gobo qdupd: Unchanged: 46 cook 3.4 object dt gobo linux2_0i /g/dt/cook/obj /g/dt/cook/work /p/cook/s3.4

Summary
The following summarizes the commands illustrated above:
% qd -pcook -b # chdir to cook's baseline % qd -26 # must use explicit index as above is ambiguous % mkqtree -w ~/cook/work ctoe # create working tree % qd -w # and chdir to it % mkqtree -D -o ../obj # create object tree % qd -o # and chdir to it % rootvrs -B. # set root.vrs BuildHost to current host

Now, given we have our trees and configuration set up, let's do a build.

cook15.qh - 1.17 - 03/10/24


	% qd -pcook -b The following multiple directories matched: 26 cook 3.4 baseline dt gobo - /p/cook/s3.4 50 cook 2.2 baseline dt gobo - /p/cook/s2.2 qds: Use the index in the first column to resolve ambiguity % qd -26 # we want release 3.4 Using 26 cook 3.4 baseline dt gobo - /p/cook/s3.4
Creating a working tree	Now we will create a working directory for ctoe: % mkqtree -w ~/cook/work ctoe # eliminated some of the output qdupd: Added: 27 cook 3.4 working dt gobo - /g/dt/cook/work /p/cook/s3.4 % qd -w # chdir to the newly created working directory Using 27 cook 3.4 working dt gobo - /g/dt/cook/work /p/cook/s3.4 % ls -RF # List the contents of the work tree ctoe/ root.vrs ctoe: So far the tree is empty with the exception of the root.vrs file, which is a file that we'll find at the root of nearly every tree as one of its purposes is to define the root. The root.vrs file serves a number of other purposes, one of which is to specify the RootPath, but we'll get back to that later.
Creating a object tree	Now we'll create the object tree and chdir to it. % mkqtree -D -o ../obj # D for default dest and config # eliminated some of the output qdupd: Added: 46 cook 3.4 object dt gobo linux2_0i /g/dt/cook/obj /g/dt/cook/work /p/cook/s3.4 % qd -o # chdir to the newly created object tree Using 46 cook 3.4 object dt gobo linux2_0i /g/dt/cook/obj /g/dt/cook/work /p/cook/s3.4 % ls -RF # list the contents of the object tree conf.vrs ctoe/ root.vrs ctoe: The conf.vrs file was created by mkqtree o by copying the project's default configuration file. This file is provided to facilitate setting user options such as the versions of third party software to be used or client options. The conf.vrs and root.vrs files are part of the qvrs system, which is the *QEF* parameterization package which will be explained in more detail later.
The root.vrs file	As was stated above, a root.vrs file is contained in every tree's root. In fact its location defines the root. Its purpose is to name the RootPath, specify the tree's type, configuration controls, release, project name, and a variety of other variables. Our current root.vrs file looks like the following, with additional comments in italics: addpath RootPath /g/dt/cook/work /p/cook/s3.4 # other roots cset RootAlias @NotSet # optional alias for current root cset Project cook cset Revision 3.4 cset TreeType object # the type of the current tree cset TreeType[/g/dt/cook/work] working # other roots' types cset TreeType[/p/cook/s3.4] baseline cset BuildHost @NotSet # the host on which to run the build cset BuildSys Linux-2.0.34-i686 # this tree's configuration cset QremoteEnv @NotSet # explained later cset _DestDir_ @(resolve @RootDir/../dest) # the product dir cset ConfigName linux2_0i # abbreviated configuration name cset ConfVrs @NotSet # name of qvrs conf file cset SysVrs @NotSet # name of qvrs system config file cset TreedirsList @NotSet # name of directory list cset VCSys rcs # name of version system cset VCRoot @NotSet # location of VCSys tree cset VCBranch @NotSet # to circumvent CVS stupidity
rootvrs	The list of settings in root.vrs files is virtually the same for every root.vrs file as it is most often created or changed by the program rootvrs. A couple of further explanations are in order. "`cset`" is a qvrs keyword to set a variable, but only if it is not set already. The value `@NotSet` is a magic value which when assigned to a variable undefines that variable. When combined with `cset`, as in: cset RootAlias @NotSet the combination is effectively a no-op, as the variable is not set if already set, but if not set, it is assigned @NotSet which unsets it (which it is already). This provides a convenient mechanism for annotated place holders in a configuration file. Given the standard nature of the root.vrs file, a program rootvrs is provided to set the standard variables. At this time we will set the BuildHost variable to the current host, as the remote building mechanism is to be demonstrated later. % rootvrs -B. # reduced display of the new root.vrs cset BuildHost gobo qdupd: Unchanged: 46 cook 3.4 object dt gobo linux2_0i /g/dt/cook/obj /g/dt/cook/work /p/cook/s3.4
Summary	The following summarizes the commands illustrated above: % qd -pcook -b # chdir to cook's baseline % qd -26 # must use explicit index as above is ambiguous % mkqtree -w ~/cook/work ctoe # create working tree % qd -w # and chdir to it % mkqtree -D -o ../obj # create object tree % qd -o # and chdir to it % rootvrs -B. # set root.vrs BuildHost to current host Now, given we have our trees and configuration set up, let's do a build.