<?xml version="1.0" ?>
<notes>
A workspace definition provides <em>CScout</em> with instructions for parsing 
a set of C files;
the task that is typically accomplished when compiling programs 
through the use of makefiles.
<em>CScout</em> must always process all its source files in a single batch,
so running it for each file from a makefile is not possible.
Workspace definition files provide facilities for 
specifying linkage units (typically executable files - 
<em>projects</em> in the workspace definition file parlance)
grouping together similar files and specifying include paths,
read-only paths, and macros.
<p>
Workspace definition files are line-oriented and organized around C-like blocks.
Comments are introduced using the # character.
Consider the following simple example:
<pre>
workspace echo {
	project echo {
		cd "/usr/src/bin/echo"
		file echo.c
	}
}
</pre>
The above workspace definition consists of a single program (echo),
which in turn consists of a single source file (echo.c).
<p>
See how we could expand this for two more programs, all residing in 
our system's <code>/usr/src/bin</code> directory:
<pre>
workspace bin {
	cd "/usr/src/bin"
	ro_prefix "/usr/include"
	project cp {
		cd "cp"
		file cp.c utils.c
	}
	project echo {
		cd "echo"
		file echo.c
	}
	project date {
		cd "date"
		file date.c
	}
}
</pre>
In the new <code>bin</code> workspace we have factored out the common
source directory at the workspace level
(<code>cd "/usr/src/bin"</code>), so that each project only
specifies its directory relatively to the workspace directory
(e.g. <code>cd "date"</code>).
In addition, we have specified that files residing in the
directory <code>/usr/include</code> are to be considered read-only
(<code>ro_prefix "/usr/include"</code>).
This is typically needed when the user running <em>CScout</em>
has permission to modify the system's include files.
Specifying one or more read-only prefixes allows <em>CScout</em> to
distinguish between application identifiers and files, which you can
modify, and system identifiers and files, which should not be changed.
<p>
The <em>CScout</em> workspace compiler <em>cswc</em> will read from its standard input,
or from the file(s) specified on its command line,
a workspace definition and produce on its standard
output a processing script:
a C-like file that <em>CScout</em> can process.
You will have to redirect the <em>cswc</em> output to a file that
will then get passed as an argument to <em>CScout</em>.
</notes>
