Handling of absolute and relative paths.

* [Introduction](#introduction)
* [Motivation](#motivation)
* [Solution - _relativity roots_](#solution---relativity-roots)
  * [Using _relativity roots_](#using--relativity-roots-)
    * [Default _relativity root_ of instructions](#default--relativity-root--of-instructions)
  * [Summary of _relativity roots_](#summary-of-relativity-roots)
* [Custom _relativity roots_](#custom-relativity-roots)


# Introduction


Exactly tries to be good at testing programs that operate on files and directories -
creates, deletes, modifies or moves files, for example.

One feature designed to accomplish this is executing the [act] phase
(the system under test)
in a temporary sandbox directory, so that it will not pollute existing
files and directories.


# Motivation


For this to work, the [setup] phase must be able to populate the sandbox
with relevant files and directories, and to set the current working directory
to one that is meaningful to the test.

Also, the [assert] phase must be able to look at the files in the sandbox and
compare them with predefined files that represent expected outcome.

To accomplish this, it must be possible to refer to files in different
locations.

It helps a lot if paths used during the execution of a test case are absolute,
since that makes it possible to use a
path no matter what the current directory happens to be.

On the other hand, paths in a test case file must not be absolute!
A test case might be part of a
source tree for the program it tests, and it is impossible to know where on
the computer this source tree has been checked out. Or the source tree might
be checked out in multiple locations,
and of course, the test case
should test the version of the program that is in the same source tree as
the test case file itself.

> (There are tools to help with such situations, like GNU autotools, that
can search-replace path identifiers with absolute paths.
But Exactly tries to avoid to force the use of such a tool, when it comes to
executing Exactly tests.)


# Solution - _relativity roots_


Exactly uses a mechanism called _relativity roots_ to translate
relative paths in the test case, to absolute paths during the
execution of the test case.

One of these relativity roots is the _act home_ root.
This is where the [act]
phase expects to find the program file that is tested.

> Of course, this is relevant only if a program file is tested.
If the test uses an "actor" that tests something else, this is irrelevant.

_act home_ is specified relative to the location of the test case file.
But during execution of the test case it is translated to an absolute path,
so that the [act] phase can find it, no matter where the temporary sandbox
is located.


## Using _relativity roots_


Each relativity root has a corresponding
  * command line option,
  * predefined symbol,
  * predefined environment variable.

The symbol and the environment variable have identical identifiers.

The relativity root can be specified for each instruction argument
that is a path.

The following ways to supple the _act_ relativity root for a file `my-file`
are equivalent
(the _act_ root has, option "-rel-act" and identifier "EXACTLY_ACT"):

`-rel-act my-file`

`-rel EXACTLY_ACT my-file`

`@[EXACTLY_ACT]@/my-file`


Programs run as sub processes from the test case (except for the [act] phase),
have access to the environment variable "EXACTLY_ACT".


### Default _relativity root_ of instructions


Some instructions have a default relativity for some of its PATH arguments.

The reason is of course that the default is what expected to be
the most common relativity,
so that the option can be skipped to make the test case a bit more concise.

Check with each instruction to see if it uses a default relativity.


## Summary of _relativity roots_


There are two "directory structures" that "contains" relativity roots:

* [_home directory_structure_](Home-directories.md#summary-of-directories)
* [_sandbox directory_structure_](Sandbox-directories.md#summary-of-directories)


# Custom _relativity roots_


A symbol defined as a "path" constitutes a kind of custom relativity root.

If the symbol MY_ROOT is defined as a path symbol, it may be used in the same way
as the predefined path symbols:

`-rel MY_ROOT file-in-my-root`

`@[MY_ROOT]@/file-in-my-root`

(both specify the same path).

The custom root may build on an existing relativity root

`def path MY_ROOT = -rel-act my-sub-dir-of-act/my-other-sub-dir`

`def path MY_ROOT = -rel MY_OTHER_ROOT my-sub-dir`

`def path MY_ROOT = @[MY_OTHER_ROOT]@/my-sub-dir`

(the last two ones are equivalent)

or be a hard coded absolute path:

`def path MY_ROOT = /usr/bin`