z2-Environment

h1. How to create your own system

This Wiki is on the - inherently - not quite trivial task of creating a complete system of yours.

Fortunately, the actual things to do a are few and simple - getting an initial understanding of why and what may not necessarily be simple.

From a Z2 Core perspective it all starts with the local repository that is part of the core. In there, we define at least the Base Repository. The Base Repository typically points to some remote Git or Subversion based repository. Once Z2 has registered that repository, other repository may have appeared that will be registered as well which may lead to the appearance of more repositories and so on. Hence, in effect, we have a chain or tree of repositories with the local repository on its root as far as repositories contain declarations of repositories. 

On the other hand, repositories have a priority (more on that below) that determines what repository has the right to say what a module contains. 

Based on that mechanism you can construct a system definitions that consist of as few as one repository (if we do not count the core) or many repositories of which some are even shared between systems.

Before moving forward on that, let's have a look at the add-ons. 

h2. Add-ons

Add-ons (see [[Add-ons]]) add more functionality to Z2. Generally speaking, an add-on is a regular Git or Subversion  repository that holds one or more modules and is incorporated into a z2-Environment defined system via a component repository declaration (see Components and Component Repositories).

In other words, technically there is nothing particular about add-ons. It is the way they are used that is noteworthy. The idea is that you can pick the add-ons you need and add them on top of z2-base. Previously Z2 was available in distributions. Now you take z2-base and add what you need on top. 

Add-ons provided on z2-environment.net are versioned just like z2-base, so that there is no complicated version vector.  Also add-ons have some documentation in the z2-Environment Wiki and come with some samples.

h2. Building a system on z2-base and add-ons

It is a best practice to encapsulate all system-specifc configuration in a module called *environment*. Also the repository "z2-base.base":http://redmine.z2-environment.net/projects/z2-base/repository/base contains an environment module (exactly "here":http://redmine.z2-environment.net/projects/z2-base/repository/base/show/environment?rev=master). 

The environment module is one of the preferred places to add a repository definition. Although, in your case, in a _scenario repository_. 

Another useful place is the Local Repository.

We recommend a setup where the z2-base repositories hosted z2-environment.net can be incorporated as-is, modulo copying or cloning, that has zero or more add-ons from z2-environment.net or from you and that has one scenario repository that assembles everything.

Such a setup consists of a *z2-base.core* (or a clone or a copy – in all cases from here on) and a *z2-base.base* plus zero or more add-ons, and one of possibly many scenario repositories.

The Local Repository, in the core, has the Base Repository pointing to *z2-base.base* and an Scenario Repository, next to the Base Repository (*z2-base.core* contains a template for that) that points to the Scenario Repository. 

The Scenario Repository has an *environment* module that has definitions for all other add-ons used in the scenario. 

And finally, the scenario component repository has a higher priority that the base component repository. 

Here is a schematic overview:

!extensions.png!