The home task is responsible for the initialization of the magic environment. This includes:
- loading of ${basedir}/user.properties
- loading of ${basedir}/build.properties
- loading of ${project.system}/index.properties
- setup of an artifact repository
- setup of an doc repository
- initialization of the project model
The following example demonstrates the initialization of a home using a default ${project.home}/index.xml.
<property name="project.home" value=".."/> <x:home/>
[x:home] Building system definition.
The creation of a home automatically establishes the following set of immutable project properrties. These properties can be referenced anywhere in an ant script following the home declaration.
| Property | Description |
|---|---|
| ${project.key} | The unique project key. |
| ${project.name} | The project name. |
| ${project.group} | The name of the group that the project is a part of. |
| ${project.version} | The project version. |
| ${project.type} | The project artifact type. |
| ${project.basedir} | The project basedir. |
| ${project.uri} | The full artifact uri. |
| ${project.path} | A relative file path that can be used to a locate the artifact produced by the project relative to a repository root. |
| ${project.spec} | Short form of uri. The spec value is equivalent to the uri with the "artifact:" protocol identifier. |
| filename | The filename of the final artifact that the resource represents. |
| short-filename | The filename without the file type suffix. |
The home task will automatically load properties into the current project.
- loading of ${basedir}/user.properties
- loading of ${basedir}/build.properties
If a home has not been loaded then home initialization will occur relative to ${project.system}. The default value of ${project.system} is ${project.home}. The ${project.system} defines the location of system level properties controlling cache and proxy setup. System properties are defined under the property file ${project.system}/index.properties.
Repositories for build deliverables and documentation are establish. The default location for the build deliverable repository is defined by the property ${project.main.cache}. If the value of this property is a relative path it will be resolved relative to ${project.system). If undefined, the initialization procedure will attempt to locate the environment variable AVALON_HOME and if defined, the AVALON_HOME/repository path will be used. If AVALON_HOME is undefined, ${project.system}/.cache will be used.
The documentation repository currently defaults to ${project.system}/.docs.
The home task loads an index file if not already loaded. If not declared explicity, the index file is located using ${project.home}/index.xml. A static immutable datastructure will be created and made available to magic aware tasks.
A project build.xml identifies itself to magic using the property ${project.name}. The value of ${project.name} is the name of a project within the model. If no ${project.name} property is defined, the name of the project (build file name) will be used as the key. Subsequent version, project group, dependency and plugin requirements will be resolved relative to the project defintion identified by the key.
The following example demonstrates the initialization of a home using an explicit index file.
<x:home index="../../released-packages.xml"/>
The following example demonstrates the initialization of a home using a default ${project.home}/index.xml.
<property name="project.home" value=".."/> <x:home/>
A recommended approach is to define ${project.system} and ${project.name} under a build.properties file and use a template build file that includes home establishment and magic related targets as shown below.
<project name="avalon-tutorial-hello"
default="install" basedir="."
xmlns:x="antlib:org.apache.avalon.tools">
<property file="build.properties"/>
<import file="${project.system}/build/standard.xml"/>
</project>
If ${project.system} is unresolvable a build failure will occur.
IMPORTANT NOTE : once initialized, a home may not be redefined. Subsequent home references within composite build files will not change an existing home definition.
