Appendix A: QEF Installation Instructions

Installing the QEF System on UNIX and Windows.

If you are using qef on a single system, the conventional locations to install the Q-Tree are /usr/qtree or /usr/local/qtree. If you expect to be using more than one version of the Q-Tree use a name that incorporates the Q-Tree release number as in /usr/local/qtree/9.1.

If you are planning to install the Q-Tree for multiple platforms then the installation directory name should include both the release number and the type of system, as in /usr/local/qtree/linux2_0i/9.1. The Q-Tree includes a program sysnm that prints out a canonical version of the system name that you can use in your $PATH settings. For example, you could use the shell expression:

    /usr/local/qtree/`sysnm`/9.1

sysnm outputs the type of the system by mapping the output of uname into a standard form.

This naming scheme is recommended, but it does require that you can find sysnm before you know the location of the Q-Tree, which may raise problems if users have login scripts that are shared by all platforms. A possible solution is offered below in the Creating Lclqtree section.

The value of sysnm for the current distribution can be determined by looking at the relinfo file in the distribution directory. The first line will look something like:

    Qtree(full) 9.1.6(567) - Linux-2.0.34-i686(linux2_0i)
		- 2000/04/14

In the documentation that follows the location of the Q-Tree is referred to as <newqtree>.

If updating an existing Q-Tree, one should take measures to ensure that any modifications that have been made to the existing installation are preserved.

The Q-Tree is designed to store all volatile files in its data/ directory and the installation process will not over-write any existing files in that directory. However, there are a few files that are not in data/ that might be modified locally to facilitate use, such as:

• the dirsetup database "dotqtree" (used to set up a user's $HOME.qtree directory) might be modified to set up site specific settings and controls, as described in Post Installation Processing.
• the lib/sysvrs/*.vrs file might be modified to correct site specific settings.
• the lib/qsg/*.qsl libraries might have been modified.

The following is a possible way of protecting such files:

    % cd $QTREE # chdir to the root of the Q-Tree
    % rls -sf -yrelinfo | ct # find files younger than the
		# relinfo file and save list in a cut file
    % pa -n # note the cut file index for future use
    % vi `pa -n` # edit cut file to examine its contents and to
		# to remove any files that need not be protected
    /.qtree/ctdir/,04
    % upd -ic `pa` # make +1 copies of files to be protected
    - cp bin/Dirsetup.dir/dotqtree bin/Dirsetup.dir/dotqtree+1
    ...
    # If qsg libraries were changed, special processing
    # may be required as described below.

If qsg libraries were changed, the current sources for those files should be extracted before the installation is done. The format of the qsg binaries may have changed thus the new qsgdump will not be able to read the old binaries.

To extract the source for a qsg library X, and save in directory dir, run:

    % qsgdump -Edir -l-N -lX

If the version of qsgdump predates 2003/10/18 (i.e., does not provide the E flag), use:

    % mkdir dir # create a temporary directory for the source
    % cd dir
    % qsgdump -L -l-N -lX -L | sed 's/X.//' | ct # get list of modules
	# The sed is used to remove the leading "X>"
    % pa | lash -lo 'qsgdump -S -l-N -lX -o %1.qsg %1'
	# for each module Z, extract its source and save in Z.qsg

Once the new libraries are installed, you can compare their sources to the ones saved and then incorporate your changes as necessary.

Alternatively, you're installing the cygwin version of Q-Tree, you'll have to acquire and install cygwin yourself.

If you want to use the qefgui you'll have to acquire and install an appropriate X-server for Windows (e.g., hummingbird).

This text appears in the Readme.txt file of a distribution, the x_db database x-qmisc, and this appendix.

The normal distribution mechanism is a single compressed tar file, which itself contains other tar files. This file should be untarred in a temporary directory. If the tar you are using does not support compressed input files, then use gunzip first and then untar the resulting file.

When the tar file is uncompressed and untarred, it creates a directory called Qtree.install that contains the following files:

Install	The program used to install the other files.
AppndixA.ps	This section in PostScript.
Readme.txt	A file that contains this text.
bin.tar	A tar file of the basic system -- the entire system minus the man and data directories.
data.ds	A dirsetup archive of the data directory.
man.tar	A tar file of the manual sections.
relinfo	The release information.

To run Install, you will have to provide the following information:

• the directory into which the system will be installed, henceforth referred to as <newqtree>.
• the symbolic link for the man directory, if any, to allow multiple installations to share a single copy of the man directory, henceforth referred to as <manlink>.
• the symbolic link for the data directory, if any, to allow multiple installations to share a single copy of the data directory, henceforth referred to as <datalink>.
• the hostname on which the qdsrv is to run and the port number to be used by client programs to connect to that server, henceforth referred to as QDSRV_settings.

Install will prompt the user for the above settings when required. Alternatively they can be specified via flags. Information and advice on the settings of the above is given below.

The Install program is usually started in the Qtree.install directory. It may be invoked from a remote directory by providing the name of the distribution directory using the D flag.

Install should be run by the user who is to own the Q-Tree files. This CANNOT be root. In fact, Install will abort if run as root. This is because if Install is run as root, the owners and groups of the untarred files will be set to the values in the tar file (i.e., the uid/gid of the builder on his/her build host). This will cause the three setuid programs -- see Special Modes -- to fail as they will not be able to write in the Q-Tree directories which will be owned by root.

You might need root privileges to create <newqtree>, but it be chowned and chgrped to a suitable uid/gid pair. Our recommendation is that a new owner be created to own the Q-Tree, or you use bin.

Install's basic processing consists of:

1. creating <newqtree> (if necessary) and untarring bin.tar
2. creating the man symbolic link (if specified) or the directory <newqtree>/man and untarring man.tar into the specified location.
3. creating the data symbolic link (if specified) or the directory <newqtree>/data and running <newqtree>/bin/dirsetup data.ds in the specified location to create those files that do not already exist. The specified QDSRV_settings will be inserted into the created <newqtree>/data/traits.ext file.
4. running <newqtree>/bin/mktraits u to create the host's binary traits database <newqtree>/data/traits/host.tab.

The command:

    % ./Install x

will list and explain Install's options and flags. A response of '?' to any prompt will explain the prompt and the possible or required responses to the prompt. You will be asked if a step is to be skipped if a file that would be created already exists. If the file does not exist, the step will be performed unconditionally.

% ./Install # install the product
Note:   A response of `?' to any prompt will explain that
        prompt and any valid or required responses.
        A response of EOF (i.e., usually ^D) will cause
        the program to exit.

Enter name of destination directory: <newqtree><Enter>
+ tar -xf dir/Qtree.install/bin.tar [1]

Name directory to be symlinked to man: <Enter>
+ tar -xf dir/Qtree.install/man.tar [2]

Name directory to be symlinked to data: <Enter>

Enter qdsrv host/port setting: gobo/6631
+ <newqtree>/bin/dirsetup -shgobo -sp6631
		dir/Qtree.install/data.ds [3]
- mkdir data; mode = 0755
...
+ <newqtree>/bin/mktraits -u

[1]

If the file relinfo exists in the target directory, the user will be prompted to confirm that the tar is to be run.

[2]

If the man directory exists, user will not be prompted for <manlink> option. If the file man/whatis exists, the user will be prompted as to whether or not the tar should be done.

[3]

If the data directory exists, user will not be prompted for the datalink option. If the file data/traits.ext exists, the user will be prompted as to whether or not the data.ds should be processed. The dirsetup program will not overwrite existing files.

    % export QTREE=<newqtree>
    % export PATH=<newqtree>:$PATH
    # equivalent csh commands left as exercise for the reader

    # Add following to appropriate boot script
    <newqtree>/bin/qdsrv -Q

The Q flag specifies that the path of the invoked program up to but not including /bin is taken to be the setting of $QTREE, a step that is required as it may not have been previously set.

To halt the server when shutting down or rebooting the system, add the command:

    <newqtree>/bin/qdmgt -Q quit

On systems that use a SysV init scheme, the command:

    % x-qefeg -M rc.d/qdsrv
    #!/bin/sh
    #
    # description: Starts and stops the qdsrv
    # processname: qdsrv
    #
    ...

    % qdsrv

    % qdmgt vset host.qtree <newqtree>

    % qvrs -Ps # name and display the sysvrs file
    <newqtree>/lib/sysvrs/linux2.vrs:
    #       SID     @(#)linux2.vrs  7.4 - 00/02/18
    ...

    % upd -ic <newqtree>/lib/sysvrs/linux2.vrs
    - cp <newqtree>/lib/sysvrs/linux2.vrs
	<newqtree>/lib/sysvrs/linux2.vrs+1

    # make backup copy of the current version
    % upd -ic `pathto qt/lib/envset.cf`
    % ed `pathto qt/lib/envset.cf` # edit as required

The installed Q-Tree will contain three setuid files. The owner of these files should be the owner of the data directory and its files. The setuid programs are:

qdsrv	so that it can be started by any user
mkquete	so that any user can update the quete database
mktraits	so that any user can update/create a data/traits/host.tab file

One possible mechanism to avoid the problem is to create symbolic links with a universally used name such as /usr/local/qtree to the appropriate directory on each system or host that needs it, however, that approach obscures important information that might be needed in the build record.

As discussed in Section 1, sysnm may be required to name the $QTREE to be used on a system. However, sysnm itself and the database it uses have to be located.

In the following solutions, a new file will be created for each and every platform that will be using the Q-Tree. This file must have the same basename on all platforms. Furthermore it must be either rooted or always in the default $PATH for each platform (e.g., could be /bin on one system or /usr/bin on another).

There are two possible schemes for resolving the problem of determining the appropriate value of $QTREE at login or in an rsh command:

1. Create a system specific shell script that simply outputs the appropriate setting for $QTREE. See Lclqtree Sh Script. This is the recommended option for initial installations.
2. Create a system specific utility that invokes sysnm to output the type of the system and let the user's login script convert this to $QTREE. There are two ways this can be done:
   1. Creating a shell script that sets $QTREE explicitly and then invokes sysnm. See Lclsysnm Sh Script.
   2. Patching the database pathname into a local copy of sysnm. See Lclsysnm Binary.

Option 2a provides a sh script that can be used to map other products or systems and allows the user more control on the Q-Tree release to be used.

Both the option 1 and 2a scripts can be implemented to be system independent, so that the same script can be used on all platforms.

Option 2b has the same advantages as 2a, other than system independence. It has the advantage that the database can be changed without the needing to modify Lclsysnm itself, whereas options 1 and 2a will require fixing the shell scripts if the database changes.

    % x-qefeg -M Lclqtree > Lclqtree
    % chmod +x Lclqtree # make it executable

If this option is employed, the users add:

    export QTREE=`Lclqtree`
    export PATH=$QTREE/bin:$PATH

    % x-qefeg -M Lclsysnm > Lclsysnm
    % chmod +x Lclsysnm # make it executable

If this option is employed, the users add:

    SYSNM=`Lclsysnm`
    export QTREE=/p/opt/qtree/$SYSNM/9.1
    export PATH=$QTREE/bin:$PATH

The basename of the copy must end with "sysnm" (e.g., Lclsysnm) as the last five letters are checked to determine the default flag. sysnm is a link to system which implies the n flag.

system uses a database called $QTREE/data/sysnames.tab to map the host platform's uname srm fields to names for the system. See the comments at the beginning of that file for a description of the mapping and the various names.

Given that sysnm needs to locate this database before $QTREE is set, the default pathname for the database is embedded in the program itself starting at the ninth character of a 100 character array. The first eight characters of the array are "@HERE@:=". To embed the name of the database in the system binary, use the following command:

    % setbytes -i `fnd sysnm` -o lclsysnm \
	8+`fndstr @HERE@:= sysnm` \
	"<newqtree>/data/sysnames.tab\0"
    % chmod +x lclsysnm
    % ./lclsysnm -x # check patch - -f description name DB
    % ./lclsysnm # check program can read database