How to create your own system » History » Version 3

Henning Blohm, 14.09.2012 17:28

1 2 Henning Blohm
h1. How to create your own system
2 1 Henning Blohm
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.
7 3 Henning Blohm
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. 
11 1 Henning Blohm
12 3 Henning Blohm
h2. Add-ons
13 1 Henning Blohm
14 3 Henning Blohm
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).
15 1 Henning Blohm
16 3 Henning Blohm
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. 
17 1 Henning Blohm
18 3 Henning Blohm
Add-ons provided on 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.
19 1 Henning Blohm
20 3 Henning Blohm
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": contains an environment module (exactly "here": 
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 can be incorporated as-is, modulo copying or cloning, that has zero or more add-ons from 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: