workspace(1)

NAME
workspace - making an Exodus Storage Manager workspace

DESCRIPTION
NB: All the makes here are verbose. If you want to limit the output of make, see Makefile - making an Exodus Storage Manager.

    Your environment variable BASELINE must be the baseline's absolute path.
        	cd baseline
        	setenv BASELINE `pwd`

    Create a directory for your workspace. It can have any name; for this discussion, we call it
        	mkdir WORKSPACE

    Go to the workspace directory and get its make files:
        	cd WORKSPACE
        	co $BASELINE/src/RCS/[Mm]akefile*,v
    This checks out, among other things, Makefile. All Makefiles include a makefile.depend, which should not exist in the RCS directories, so the now you have to do
        	touch makefile.depend
    The makefiles rely on being able to change makefile.depend, so if a makefile.depend was in the RCS directory and got checked out, you must make it writable in your workspace.

    The default Makefile will put everything in your workspace. If that suits you, skip the next step.

    If you want some modules to come from the baseline, do
        	make [-e -s] workspace.1level
        	vi makefile
        	...
    This creates all the first-level subdirectories and makes a writable copy of Makefile in makefile in the top-level and each first-level directory.
        	vi makefile
        	...
    Edit the macros MOD_WORKSPACE and MOD_BASELINE in each makefile, according to your wishes. If you want only part of a module (e.g., client/bf) in your workspace, put the parent of the part that you want (e.g., client) in your workspace. Modules listed in MOD_BASELINE will be taken in their entirety from the baseline.

    Go back to the root of the workspace:
        	cd WORKSPACE
        	make [-s -e] workspace

    If everything is in your workspace, skip this step. If anything comes from the baseline, do
        	cd WORKSPACE
        	make [-s -e] getbaselineparts

    Still in the root of the workspace, make dependencies:
        	make [-s -e] depend

    Still in the root of the workspace, make tags:
        	make [-s -e] tags
    Now you have a pair of links (tags.all, tags.baseline) in each directory. Tags.all points to the tags file for its module (e.g. tags.all in client/* point to client/tags). Tags.baseline points to the baseline's tags file for the module (e.g. tags.baseline in client/* point to $BASELINE/src/client/tags.

    To use the tags files made in the previous step, add to your ~/.exrc the following line:
        	set tags=tags\ tags.all\ tags.baseline

    If you want to eliminate duplicate tags files in the subdirectories, do
        	make [-s -e] tags.clean

Now you have a workspace with the appropriate sources and baseline products. To make a server in the workspace, see Makefile - making an Exodus Storage Manager.

MAKE OPTIONS

Silent Makes:
    You have several ways to limit the output of the makes. You can use the -s option, to prevent Make from printing each command it executes. (See make(1).)

    You can set your environment variable LOCK to "-q" and use the "-e" option with Make, to make the rcs functions like co and ci quiet. (See co(1), ci(1), rcs(1).)

Partial Makes:
    You can work on a portion of the storage manager code without having to make the entire storage manager, or having to copy the source for the entire storage manager. This is useful when you are working on a workstation that has little available disk space, and want to mount most of the source from another machine. It is also useful when several people are working on the code at once. A stable "baseline" copy is kept on a server machine. Each programmer has his own "workspace". The Makefiles have macros that specify which modules of the storage manager are in you workspace, and which are taken from the baseline. Modules taken from the baseline are taken in object or executable form. Thing in your workspace are made from a copy of the source.

Adding a module to the baseline or workspace:
    You can remove modules entirely and remake them. For example,
        	cd WORKSPACE
        	rm -rf client
    Now you can remake the client module, either in the workspace or from the baseline, regardless of where it came from before you removed it. If you want client in the workspace, put it in MOD_WORKSPACE, and do
        	make [-s -e] workspace
    If you want it from the baseline, put it in MOD_BASELINE, and do
        	make getbaselineparts
        		or
        	make [-s -e] client
        	cd client
        	make [-s -e] getbaseline
    The last two examples are equivalent.

CONFIGURATION OPTIONS

Debugging:
    The storage manager can be made with several debugging options, which can be combined.

    If the DEBUG C preprocessor flag is defined (with -DDEBUG), the storage manager includes myriad internal checks. Some of the checks are CPU-intensive.

    The -g compiler flag can be used to generate symbols for use with dbx(1). (See cc(1), dbx(1).)

Optimization:
    The -O compiler flag can be used, in the absence of -g, to generate optimized code. -O cannot be used with -g; -g3 is used with -g to create optimized code with symbols.

Profiling:
    The storage manager can be configured to profile itself by using compiler flags -DPROFIL -p. (See prof(1).) When compiled with -DPROFIL, the storage manager responds to the cl_MonDump() client request by writing its profiling information to a file, and passing along the request to all its disk processes, who do the same. Use the environment variable PROFDIR, so that each process writes its profiling information in a different file.

IPC configuration options:
    The server and disk processes communicate in one of two ways: with Unix-domain sockets (see socket(2)), or with shared-memory queues. When the storage manager is made with -DDISK_QUEUES, the queues are used. When DISK_QUEUES is not defined, the processes use Unix-domain sockets.

RESTRICTIONS

The client and server have some function names in common, such as bf_ReadPage, so it is not possible to have a global tags file for the entire storage manager. Instead, there are separate tags files for client modules and for server modules. The tags files you use depend on your working directory. Since not all of the source is in a workspace, you also need to use tags from the baseline. The unfortunate result is that all the tags in the tags files have absolute path names. This may create problems for people who mount a baseline with NFS.

CAVEATS

Be sure that you don't put a module both in MOD_WORKSPACE and MOD_BASELINE. You will get a message to the effect, "Too many commands", and you will get unpredictable results or errors when you try to make anything.

Some directories get their sources from other directories. If one of these directories is in the workspace, the other must also be. Examples are:

btree
    The code for the btrees is in client/btree. The serverlib/btree gets its source by linking to client/btree.

disk and diskproc
    The disk directory in serverlib uses source from diskproc, and vice versa. If diskproc is in the workspace, so must be serverlib/disk, and vice versa.

When making dependencies or tags, if old makefile.depend or tags files are around, they must be removed or made writable. It is best to remove the tags files.

If you move modules from the baseline to your workspace, you must delete the modules, recreate them, and run "make [-s -e] workspace" in those modules. If you move remove modules from the workspace and get them from the baseline instead, you must delete the modules, recreate them, and run "make getbaselineparts" at the super-directory level, or "make getbaseline" in each of the modules. You also have to re-make tags and dependencies at the super-directory level.

If you add or delete files from a module, you can re-make tags and dependencies at that module level only without affecting tags or dependencies at other levels, but the other levels will not be up-to-date with respect to your new or obsolete files.

SEE ALSO
Makefiles - making an Exodus Storage Manager