How to create your own system » History » Version 5

Henning Blohm, 08.04.2013 15:43

1 2 Henning Blohm
h1. How to create your own system
2 1 Henning Blohm
3 5 Henning Blohm
This Wiki is on the task of creating a complete system of yours. I.e. to set up a development of your own solution based on the z2-base system.
4 1 Henning Blohm
5 5 Henning Blohm
*Note:* This is not needed to run the samples or to check things out. This is only useful, if you wish to start 
Fortunately, the actual things to do a are few and simple.
8 1 Henning Blohm
9 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. 
10 4 Henning Blohm
11 3 Henning Blohm
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. 
12 4 Henning Blohm
13 3 Henning Blohm
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.
14 4 Henning Blohm
15 3 Henning Blohm
Before moving forward on that, let's have a look at the add-ons. 
16 1 Henning Blohm
17 3 Henning Blohm
h2. Add-ons
18 1 Henning Blohm
19 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).
20 1 Henning Blohm
21 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. 
22 1 Henning Blohm
23 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.
24 1 Henning Blohm
25 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:
46 4 Henning Blohm
Sounds complicated. But in reality, it's really just filling the scenario component repository definition. The samples in work almost exactly the same way. The difference is that we do not use the extension component repository but rather the Development Repository.
The effects of this setup are:
*The z2-base.core always stays connected with z2-base.base*
This is somewhat crucial. There is no meaningful way of using Z2 without a base repository like z2-base.base.
*You can run many scenarios with shared add-ons*
By only changing the scenario repository definition you can control a complete application system definition that is implemented on a Z2 Home - while still sharing all Add-on and base repositories. 
The *environment* module in the scenario repository defines what is part of the scenario.
*You can leave repositories from untouched*
As you only re-use, typically you will not need to modify repository content unless you apply bug fixes and the like. That separates cleanly what is yours, what is from others.