QEF home page

Appendix A: QEF Installation Instructions

The Guide's Table of Contents Previous Chapter Bottom Of Page Next Chapter

Installing the QEF System on UNIX and Windows.


A.1) Choosing the Q-Tree Installation Directory

The Q-Tree can be installed anywhere there is 30 megabytes of disk space available. The actual size of the installation depends on the platform and the version of the product.
Note:The above requirements include the online documentation and data directories. If you are installing the Q-Tree for multiple platforms, these directories can be shared by all installations, reducing the total disk space required. They represent 4-8 Megabytes, depending on the size of the catman directories and the data log files and audit trails.
The $QTREE environment variable must be set to the directory where the Q-Tree is installed. All of the Q-Tree tools use this variable to locate the Q-Tree. On Microsoft Windows platforms, the installation program automatically sets this variable. On other platforms, your login scripts (e.g., .profile) should set $QTREE and add $QTREE/bin to $PATH.

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
to map to the Q-Tree directory.

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
The sysnm value appears after the configuration name in parentheses (e.g., "linux2_0i" in the above example).

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

WARNING With Respect To Re-installation
If you are not updating an existing copy of the Q-Tree, this warning may be ignored until such time as you are.

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.
Measures should be taken to protect these files and restore their modifications after the new copy has been installed.

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.
Now the installation is performed as described below. Once that process has completed, the saved copies (as named in the ct/pa file created above) can be examined to incorporate any required local changes.

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.

A.2) QEF Installation on Windows

The QEF installation on a Windows system requires that the Microsoft Windows Services for UNIX system has been previously installed. See http://www.microsoft.com/windows/sfu/default.asp for purchase at $99 US.

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).

A.3) QEF Installation

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.psThis section in PostScript.
Readme.txtA file that contains this text.
bin.tarA tar file of the basic system -- the entire system minus the man and data directories.
data.dsA dirsetup archive of the data directory.
man.tarA tar file of the manual sections.
relinfoThe 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.

Install processing:

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.

Notes on Install:

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.

Running Install
To install the system, Install is run in the Qtree.install directory. In the following, [#] refers to notes that follow the listing.
% ./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.
prompt for new qtree name
Enter name of destination directory: <newqtree><Enter>
+ tar -xf dir/Qtree.install/bin.tar [1]
prompt for manlink
Name directory to be symlinked to man: <Enter>
+ tar -xf dir/Qtree.install/man.tar [2]
prompt for datalink
Name directory to be symlinked to data: <Enter>
prompt for qd server host/port
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
Notes on above
[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.
Information and Advice on Settings:

<newqtree> See Section 1.
<manlink> This directory will require about 3 Megabytes. If possible it is desirable to have a single man directory shared by all the Q-tree installations. This is done by specifying to Install, via the --m flag or when prompted, the <manlink> directory to be symbolically linked to <newqtree>/man. Typically this would be the man directory of another previously installed Q-Tree.
<datalink> The data directory (see <Q>/data(x-qef)) will initially require less than a Megabyte, but it contains log files and databases that will grow considerably, thus a minimum of 3 Megabytes of available space is recommended. This directory should be shared by as many installations as possible. This is done by specifying via the --d flag or when prompted, the <datalink> directory to be symbolically linked to <newqtree>/data. Typically this would be the data directory for the host that runs qdsrv, as named by QDSRV_HOST and as initialized by the QDSRV_settings>.

QDSRV settings This setting should be `/' separated catenation of the name of the host that runs qdsrv and the port number used by clients to connect to that server, for example `localhost/6631'. If there has been a previously installed Q-Tree, these settings should be the same as those used on that system. Note that all systems on the local network can use the same qdsrv. When doing the first installation, the name of the current host should be used so that qdsrv can be run as soon as the traits file has been installed. The settings can be changed at a later date by editing <newqtree>/data/traits.ext.

A.4) Post Installation Processing

To use the newly installed system:
    % export QTREE=<newqtree>
    % export PATH=<newqtree>:$PATH
    # equivalent csh commands left as exercise for the reader
For more information on starting to use the QEF system, see Chapter 3.
Running qdsrv Once the Q-Tree has been installed, if the current host is the one that will run qdsrv (i.e., QDSRV_HOST) the bootstrap process should be modified to start qdsrv.
    # Add following to appropriate boot script
    <newqtree>/bin/qdsrv -Q
The above command should be added to the appropriate start up scripts, such as /etc/rc.d/rc.local or its equivalent.

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
to the appropriate location on your system.

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
    #
    ...
will output a shell script suitable for inclusion in /etc/rc.d/init.d and the /etc/rc.d/rc[1-5].d directories.
Note: The qdsrv does not need to be started as part of the bootstrap as it can be started by just issuing the command:
    % qdsrv
on the appropriate host. qdsrv will not start if it is not on the host named by the traits variable QDSRV_HOST. Once the Q-Tree system is being used regularly by multiple users qdsrv should be started automatically on boot, but initially one can just start it manually.
qdsrv host.qtree variable The remote execution program qremote needs to know the location of the Q-Tree for its target host. This is done by retrieving the qdsrv variable host.qtree, thus once a Q-Tree is installed, this variable should be set as in:
    % qdmgt vset host.qtree <newqtree>
Other Configurations
Some of the files in <newqtree>/data may need modification. The company.cf file should be edited to make the appropriate settings, but this is optional.
data/traits.ext The <newqtree>/data/traits.ext should be examined particularly with respect to the settings of: LD_LIBRARY_PATH (if required), LM_LICENSE_FILE (if required), STD_PATH, and BuildPath. The latter two are set in <newqtree>/lib/traits.vrs, but may need to be modified in the traits.ext to conform with the local system.
Note:STD_PATH should be limited to the standard directories for the host system that will normally be required to use the system. The X11 bin directory might be included. The BuildPath should be set to the directories absolutely required to use the system (usually just /bin and/or /usr/bin). Tools from other directories are normally mapped using _T_ settings. This is to minimize the dependence on local system variations to increase the likelihood that the software products can be on other systems or in the future.
Ultimately <newqtree>/data/traits.ext may need to be edited to fix tool paths and site or host dependent options, but this is probably not necessary initially.
Note:Anytime traits.ext is modified, the command:
    % mktraits -u # update the traits binary DB
should be run to create or update the binary file.
dirsetup dotqtree To facilitate setting up new QEF users, the dirsetup database dotqtree should be localized. See Appendix C: New User Setup.
lib/sysvrs/*.vrs The qvrs file for the system might need to be modified to reflect local or site dependent settings. The file used for the current system is named and displayed by:
    % qvrs -Ps # name and display the sysvrs file
    <newqtree>/lib/sysvrs/linux2.vrs:
    #       SID     @(#)linux2.vrs  7.4 - 00/02/18
    ...
Before this file is modified it is recommended that a copy be created using:
    % upd -ic <newqtree>/lib/sysvrs/linux2.vrs
    - cp <newqtree>/lib/sysvrs/linux2.vrs
	<newqtree>/lib/sysvrs/linux2.vrs+1
Note that some of the settings (e.g., LibDirs[gcc]) use @(trait Var). The trait function retrieves the setting for Var from the traits database. Any new, possibly site dependent settings should be made in the traits database and incorporated into the sysvrs.vrs file using the trait function.
lib/envset.cf The lib/envset.cf file is used to set the necessary environment variables when qremoteing to the host. As such it may be necessary to modify this file to correct the contained qremote set. This file as distributed has settings for $PATH, $LD_LIBRARY_PATH, and $LM_LICENSE_FILE using values retrieved from the traits database. To change:
    # make backup copy of the current version
    % upd -ic `pathto qt/lib/envset.cf`
    % ed `pathto qt/lib/envset.cf` # edit as required
Special Modes:

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:
qdsrvso that it can be started by any user
mkqueteso that any user can update the quete database
mktraitsso that any user can update/create a data/traits/host.tab file

A.5) Creating Lclqtree

This section addresses the problem of determining the location of the Q-Tree in a system independent way as might be required in a login shell script.

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.
The first option is recommended and is the simplest for the user, but, it cannot be used to map systems other than the Q-Tree, or to select alternative releases of the Q-Tree.

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.

Option 1: Lclqtree Sh Script A shell script that simply outputs an appropriate $QTREE setting for the host is created. The commands:
    % x-qefeg -M Lclqtree > Lclqtree
    % chmod +x Lclqtree # make it executable
will create such a script. The generated script offers alternative implementations that use case statements based on hostname or uname. Use of these alternatives can produce a platform independent script that can be shared by all systems.

If this option is employed, the users add:

    export QTREE=`Lclqtree`
    export PATH=$QTREE/bin:$PATH
or the equivalent csh commands to their .profile or .login file.
Option 2a: Lclsysnm Sh Script A shell script that simply outputs the system type for the host is created. The commands:
    % x-qefeg -M Lclsysnm > Lclsysnm
    % chmod +x Lclsysnm # make it executable
will create such a script. The generated script offers alternative implementations that use case statements based on hostname or uname. Use of these alternatives can produce a platform independent script that can be shared by all systems.

If this option is employed, the users add:

    SYSNM=`Lclsysnm`
    export QTREE=/p/opt/qtree/$SYSNM/9.1
    export PATH=$QTREE/bin:$PATH
or the equivalent csh commands to their .profile or .login file. An alternative name for the shell script may be used, provided it is the same for all platforms.
Option 2b: Lclsysnm Binary If this historic option is chosen, sysnm is copied to the appropriate directory patching in the pathname for the system database.

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
See system(1) for a fuller description of the above.
Note:The Q-Tree copy of bin/system does not need to be modified! If system can be invoked, then its location is known. Therefore $QTREE is either set or the default is sufficient and system can use that setting to locate the database.
The default $QTREE The default $QTREE is set at compile time, but it is done in such a way that it can be changed. The brave installer can change the default $QTREE using a technique similar to the above using the power of the Q-Tree tool set as described in DefaultQtree(x-qmisc).
The relinfo File When the Q-Tree is installed, the relinfo file should have the most recent modification time. This fact is used when doing a re-installation as illustrated by the Warning section in Section 1. If in the course of normal use and/or modification, any file of the Q-Tree (other than in data/) is changed or a new file is created, it should be done in a way that will change its last modification time. touch or untouch may be used to ensure that the file is younger than the relinfo file.
Note:The relinfo file itself contains the date and time of its creation.

x010.qh - 9.4 - 03/10/22 QEF Home The Guide's Table of Contents Previous Chapter Top Of Page Next Chapter