Chapter 1: Welcome to QEF

What QEF is, why it was created, and the principles underlying its design.

With the QEF toolkit, you can build all your software in a consistent way. No matter what the project, development language, platform, release or developer, a single set of commands builds the product.

At first, you might find it useful to think of QEF as super-make, though it is more than an extended or enhanced make. QEF is a toolkit. The QEF tools combine in various ways to control your software constructions. Most of the QEF tools are command-line utilities that can be invoked directly from the shell. Although you can run any of the QEF tools directly, you as a developer normally deal with one of the two interface or driver programs: qef, the command-line interface, and qefgui, the GUI interface.

These two driver programs allow you to invoke arbitrarily complex construction processes with simple mouse clicks or commands. This is perhaps the greatest strength of QEF. As one developer has said, "All you ever say is `qef'."

The most common tool for software construction is make or one of its derivatives. When the original make was developed in the mid-seventies, it was a major step forward. In the decades since, software has grown much more complex. The standard make and its descendants fall short of what you need as a software developer. At the very least, you need a system that:

• employs a simple, standard set of commands to build the product(s);

• expresses the goals of the construction process at a higher level and does not require that all intermediate constructions be explicitly described;

• describes the construction environment exactly -- there are no volatile components (e.g., environment variables) which might be forgotten;

• recognizes and facilitates the standard constructions (e.g., library, program, debugging versions, instrumented versions, man pages, etc.);

• makes no unconfigurable assumptions about development style, platform, language, compiler, etc.; a tool that works with whatever software a given project requires;

• provides an audit trail of each construction, enabling you to know precisely what went into a construction and why each generated file was generated;

• allows precise configuration, by sub-tree, directory, or individual file;

• enables remote and multi-platform constructions from a single source;

• supports nested constructions, with parallel constructions and the ability to synchronize parallel builds, pausing one build until another is complete;

• provides a useful interface for learning what projects are available and where they are.

QEF was designed to give you confidence in your software constructions. In practice, this involves several sub-goals:

1. You can work on any portion of any release of any product on any machine at any time.
2. You can copy files to your workspace and include them in the next build without changing anything else. Once the files are verified, you should be able to update the baseline source directory, delete the local copies, and build the product without changing anything else.
3. You have access to your colleagues' changes as soon as they are ready for developer use.
4. You can build any part of any product with any set of flags, while the rest of the product is built in the standard way (e.g., compile only this part with the debug flag).

qef is a driver program that controls your builds, calling QEF tools and other programs as needed to perform the builds. A qef run passes through three phases:

To better understand how QEF works, you should be familiar with some terms used throughout the QEF documentation.

Other terms may be retrieved from the on-line glossary by typing

    % x-qmisc glossary

Because QEF is flexible, it can be adapted to a number of development models. Here is one that is strongly supported by QEF. It is suitable for large projects. Preferably there is a code librarian, who is responsible for all code in the project and for building all of the versions of the product. The code librarian may be the project manager or part of the quality assurance staff, or simply a senior developer.

The source code that is used to build the product is kept in the baseline tree, which should be under the control of the code librarian, and under version control.

Each developer has a working tree for this project, and one or more object trees. Typically there is an object tree for each configuration supported.

When developers need to make changes to a file or set of files, they use the version control interface (vci) to retrieve the file(s) from the baseline source into their working tree. After making modifications to the working tree source, they build in their object trees.

This is shown here. The two production trees are both object trees representing different configurations. Both are built from the baseline source. The developer has a working tree that is a subset of the baseline tree. Each object tree is built from the source in the working tree, with any files not there taken from the baseline source. If any additional files (e.g., headers, tools, or libraries) that are not built in the developer's tree are required, they are usually accessed directly from the production version.

When the developer is satisfied with the changes, he or she uses the version control interface to submit them to the version system. The changes will then be incorporated into the baseline and used to build the production versions.

This scheme has a number of interesting advantages.

• the developers need build only a subset of the product
• the developer's system is kept in sync with the production baseline source tree
• the files that are being modified are conspicuous in the working tree
• both people and products are insulated from the effects of changes that are not (currently) of relevance

Some of the more important tools in the QEF toolset are:

There are many other tools besides these, but for the most part they are called automatically by these principal tools. Some of the other important or really useful tools are described in Chapter 11. A complete list of the QEF tool set is given in Appendix D.

1. A universal interface for developers, quality assurance staff, and management to build software.
2. A hierarchical configuration tool, qvrs, which provides a system-wide project database housing data about projects, tools, file locations and construction recipes. All developers reference a single database, and can use a symbolic language for describing the information.
3. Generation of scripts at run-time using arbitrary shell commands. Simple statements of intent are translated into scripts that reflect the current state of the system and the user's current intent.
4. Dynamic and complete dependency generation done at run-time.
5. An efficient and comprehensive tool, mimk, for providing products that are consistent with the source.
6. Support for portable construction recipes.

This means:

• The QEF script generators prepare all your construction scripts, freeing you from maintenance and reducing errors, omissions and constraints.
• The seamless interface to the version-control system lets you build any release of any product at any time. You can build any portion of any product at any time.
• With the audit trail, you can know precisely what went into any build.
• Finally, the abstraction of the software construction process allows you to work at a higher level -- across products, releases, platforms and modes.

The result is confidence in your work.