Etch Installation and Build Guide

Hardware Requirements
Software Requirements
Building Etch
Installing Etch
Environment Variables used by Etch and Etch Tools

Hardware Requirements

Etch requires an x86 compatible processor, at least 32MB of RAM, a swap file of 200MB, and disk space for the project directories. Users tend to be happiest when running on machines with at least 64MB of RAM and ample disk space. The disk space required by the project depends on the objects being etched and the tool used to etch. For example, a project directory that contains Microsoft Word 95 and all of the DLLs it uses, etched with the unaligned access counter tool, takes approximately 72MB.

Etch and Visual Etch have been tested to run on Windows NT V4.0. Etch also runs under Windows 95, but not all functionality is available and it has received much less testing on Windows 95; therefore, we currently recommend that Etch be used with Windows NT V4.0.

Software Requirements

A binary distribution of Etch consists of a number of directories containing all of the Etch executables and DLLs, perl scripts, instrumentation and optimization tools, and databases. Typically, users of Etch will not need an understanding of these files and directories. However, a detailed description of the structure of those directories can be found in the Guide to the Etch Source Tree document.

In addition to the Etch system and its associated files, use of Etch requires a number of other software systems to be installed for various phases of its execution or installation.

Installing and building Etch requires the following:

Etch currently requires Microsoft Visual C++ V4.0 or greater for building tools (either creating new ones, or modifying the sample tools). Although it should be straightforward to use a different C compiler for compiling Etch tools, our testing has been restricted to MSVC.
Installation of Etch and running Visual Etch require Perl version 5. We include perl v5.001m for Win 32 build 109 (see http://www.perl.hip.com/) in the auxbin directory.
Microsoft Access is required to edit Visual Etch database files. Visual Etch uses these files to control Etch configuration parameters.

Running Etch requires the following software:

The source code browser for the Cgprof call-graph profiling tool requires that GNU Emacs be installed; however, the basic Cgprof profiler can still be used without GNU Emacs.

Building Etch

Use the following steps to build Etch from source.

Open a MS-DOS shell window.
Change to the top-level directory where the etch distribution lives.
Depending on how you installed Microsoft Visual C++, you may have to invoke the vcvars32 environment setup script.
Make sure that Visual Basic 5.0 (vb5.exe) is in the path.
Invoke the script genall.bat (just type "genall") to start the build process. This script compiles the entire etch tree, and then it invokes the bin/run-setup.bat script after the tree is built.
Type "vetch" at the MS-DOS shell prompt to start Visual Etch.

More information about genall

The genall script can also be used to rebuild any portion of the Etch tree when something changes. For example, if an Etch developer sends you a patch to one of the source files, you can apply that patch, and then invoke genall to rebuild your distribution. Also, there is a perl script called clean.pl that lives in the top-level Etch directory, this script can be invoked by the command "perl clean.pl" to delete all of the object files and executables from the source tree.

Creating a binary distribution

After using genall to build the distribution, you can generate a compressed tar file binary distribution with the command "nmake release". This creates a file called "etchrel.tar.gz" in the top-level etch directory. You must have the free software utilities "tar" and "gzip" installed on your machine for this to work.

Installing Etch

Installing a Full distribution (i.e. one that comes with the source code).

Check the software requirements.
Follow the build instructions.
Once genall completes (see above), you can run Visual Etch, and you can use Etch from the command line within the MS-DOS window that you did the build in.
If you create any new MS-DOS windows, you must use the "run-setup" script (just type "run-setup" from the bin directory) in each of them to set the appropriate environment variables for using etch from the command line. If all you want to do is use Visual Etch, then you don't need to use "run-setup" except for the first time you install Etch.

Installing a Binary-only distribution.
1. Open a MS-DOS shell window.
2. Change to the directory for vetch_install, type "setup" to run the program that will install the DLLs and OCXs that Visual Etch requires.
3. Change to the top-level directory where the Etch distribution lives, and then change to the bin subdirectory.
4. Invoke the script run-setup.bat (just type "run-setup").
5. You can now run Visual Etch, and use Etch from the command line within the MS-DOS window that you ran "run-setup" in.
6. If you create any new MS-DOS windows, you must use the "run-setup" script in each of them to set the appropriate environment variables for using Etch from the command line. If all you want to do is use Visual Etch, then you don't need to use "run-setup" except for the first time you install Etch.

Environment Variables used by Etch and Etch Tools

If you want to change the location where Visual Etch creates the default project, you should use the NT control panel. In the control panel, there is an icon called System. This icon has a tab labelled Environment, and this tab lets you set environment variables that are then inherited by all MS-DOS command shells that you create. If you set the TMP environment variables to the desired value, then Visual Etch will create the default project in the directory that you specify.

The following is a list of all the environment variables used by Etch and Visual Etch.

Used by Etch and Visual Etch, set by the run-setup batch script:

ETCHROOT - path to the etch distribution.
ETCHTOOLS - path to the directory containing the tool DLLs.
ETCHBIN - path to the directory containing the Etch and Visual Etch executables
TMP - path to a scratch area
PERLDIR - path to the perl binary
PERLLIB - path that perl uses to find perl source files

Used by Visual Etch:

USERNAME - name of the current user. Used by Visual Etch to create TEMPDIR.
COMPUTERNAME - name of the computer. Used for logging which machine performed the transformation of a binary.
TMP - system temporary directory.

Used by tool scripts, set by Visual Etch:

PROJECTDIR - top level project directory that for the selected project. Used to store files that should not be deleted when the user asks to "clear cache".
CACHEDIR - project cache directory. Used to place non-tool specific files.
WORKINGDIR - the experiment folder.
TEMPDIR - a sub-directory under the system temp directory (%TMP%) where tool scripts can put temporary files. This directory is set by Visual Etch to %USERNAME%.temp under the system temp directory.

Used by Etch, set by Visual Etch or the tool scripts:

ETCHERRORLOG - name of the file to log Etch error messages
ETCHWARNINGLOG - name of the file to log Etch warning messages

Used by tool run-times, set by tool scripts or Visual Etch:

ETCH_UNIQUE_OUTPUT - indicates to the tool runtime DLL that it should create a special output file per process as the application may consist of multiple processes (e.g. direct draw applications).
ETCH_TOOL_ENV - environment variables many tools use for tool scripts to send tool specific options to the tool runtime DLL.