thekid/rfc — Issue #178: RFC 0178: XP installations
Author: thekid
Created: 2011-10-09 15:37:02+00:00
State: open

Scope of Change
====
The XP runner infrastructure created in xp-framework/rfc #166 will be extended to be
able to be installed system-wide and have user-specific overrides.

Rationale
====
* Always have XP runners available on a system.
* Allow for user-specific overrides, though!

Functionality
====
The XP runners are version-unspecific and can run XP5 upwards. Thus these
programs don't need to be versioned and can always reside in the same
directory. The configuration file `xp.ini` points the runners to
the directory the XP framework resides in (e.g. the SVN checkout or more
commonly, the released versions). Users may be happy with this but may
choose to override this and use a different version instead.

The XP runners compile the `include_path` setting passed to PHP
by looking at every element in the `use_xp` setting (can be
determined by either `USE_XP` environment variable or the key
`use=` configuration key), searching for `*.pth` files in
these directories and concatenating the paths found inside.

When one of the XP runners start up, the following sources are examined
in the order listed:
* Examine the environment variable (E)
* Look at the per-directory configuration (P)
* Look at the user configuration (U)
* Look at the XP installation (I)
The first source to supply a `use_xp` setting prevails.

Examples
----

Example #1: Given these settings, use_xp would be set to the value from
the environment.

```
Source Value
------ -------------------------------------------------------------
S /usr/local/lib/xp/5.7.7/
U ~/devel/xp.public/trunk
P ~/devel/xp.public/branches/xp5_8
E ~/devel/xp.forge/trunk/experiments/arena/namespaces/six

```

Example #2: In this case, the SVN checkout of the 5_8 branch in the
~/devel directory would be used.

```
Source Value
------ -------------------------------------------------------------
S /usr/local/lib/xp/5.7.7/
U ~/devel/xp.public/trunk
P ~/devel/xp.public/branches/xp5_8
E (empty / not set)

```

Example #3: In this case, the SVN trunk checkout in the ~/devel
directory would be used.

```
Source Value
------ -------------------------------------------------------------
S /usr/local/lib/xp/5.7.7/
U ~/devel/xp.public/trunk
P (no config file in per-directory configuration)
E (empty / not set)

```

Example #4: Here, the system XP, a 5.7.7-RELEASE, is used:

```
Source Value
------ -------------------------------------------------------------
S /usr/local/lib/xp/5.7.7/
U (no config file in user configuration)
P (no config file in per-directory configuration)
E (empty / not set)

```

Windows
----
We suggest to follow the conventions as follows:

I) System-wide installation

```
# Runners { xp xar xpcli unittest doclet cgen } and { xp.ini }
${System.Environment.SpecialFolder.ProgramFiles}\Xp\

# XARS { xp-rt-5.7.7.xar }, Path { boot.pth }
${System.Environment.SpecialFolder.ProgramFiles}\Xp\5.7.7\

# Shortcut to the former
${System.Environment.SpecialFolder.ProgramFiles}\Xp\5.7-latest.lnk

```

I) User installation

```
# Runners { xp xar xpcli unittest doclet cgen } and { xp.ini }
${USERPROFILE}\Xp\

# XARS { xp-rt-5.7.7.xar }, Path { boot.pth }
${USERPROFILE}\Xp\5.7.7\

# Shortcut to the former
${USERPROFILE}\Xp\5.7-latest.lnk

```

P) Per-directory configuration

```
# Dir config { xp.ini }
.\xp.ini

```

U) User configuration

```
# User config { xp.ini }
${System.Environment.SpecialFolder.LocalApplicationData}\Xp\xp.ini

```

E) Environment

```
# Environment variable
USE_XP=...

```

Cygwin
----
Differing from the Windows defaults, the user configuration will also
searched for in `~/.xp`.

Un*x
----
We suggest to follow the conventions as follows:

I) System-wide installation (PREFIX=`/usr/local` or `/opt` for example):

```
# Runners { xp xar xpcli unittest doclet cgen } and { xp.ini }
${PREFIX}/bin/

# XARS { xp-rt-5.7.7.xar }, Path { boot.pth }
${PREFIX}/lib/xp/5.7.7/

# Symlink to the former
${PREFIX}/lib/xp/5.7-latest

```

I) User installation (where `~` represents the user's home dir):

```
# Runners { xp xar xpcli unittest doclet cgen } and { xp.ini }
~/bin/

# XARS { xp-rt-5.7.7.xar }, Path { boot.pth }
~/xp/5.7.7/

# Symlink to the former
~/xp/5.7-latest

```

P) Per-directory configuration

```
# Dir config { xp.ini }
./xp.ini

```

U) User configuration

```
# User config { xp.ini }
~/.xp/xp.ini

```

E) Environment

```
# Environment variable
USE_XP=...

```

Security considerations
====
None.

Speed impact
====
None.

Dependencies
====
None.

Related documents
====
* xp-framework/rfc #166 - XP Runners
* http://news.xp-framework.net/article/285/2009/01/09/ - XP Runners installation
* http://news.xp-framework.net/article/294/0009/04/23/ - New features in XP runners
* http://news.xp-framework.net/article/349/2010/03/12/ - Update script included with runner distributions

Comments
====
None.