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.

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.

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 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: