Project

General

Profile

How to run a sample » History » Version 37

Udo Offermann, 21.05.2014 13:59

1 19 Henning Blohm
h1. How to run a sample
2 1 Henning Blohm
3
Various z2-based sample system configurations have been prepared as Git repositories. 
4
5 23 Henning Blohm
Assuming you know the repository URL these three steps (with or without Eclipse) are all there is to do.
6 14 Henning Blohm
7 25 Henning Blohm
While these instructions are for Git users, they can be applied to the Subversion case quite similarly as described below.
8
9 27 Henning Blohm
*Note:* If you experience problems reaching out to the internet, you may need to configure some proxy settings. Please see [[How_to_proxy_settings]] for how that is done.
10
11 31 Udo Offermann
h1. Eclipse users
12 14 Henning Blohm
13 20 Henning Blohm
Most likely you will want to look at code or configuration files of a sample. That is why we recommend to start from within the Eclipse IDE. If you prefer the command line or another IDE, please proceed to [[How to Run a Sample#From the command line|From the command line]].
14 14 Henning Blohm
15 17 Henning Blohm
Open Eclipse with a new workspace in a new folder, say *sample*. Note: We will clone repositories as siblings to your workspace. So let's assume your workspace is *sample/workspace*.
16 1 Henning Blohm
17 19 Henning Blohm
h2. 1. Prepare a z2-base installation
18 1 Henning Blohm
19 17 Henning Blohm
As the location where repositories are cloned to matters, it is simplest you open the Git tab in the Eclipse preferences and enter "${workspace_loc}/.." as default repository location.
20 1 Henning Blohm
21 18 Henning Blohm
Open the Git Perspective and clone the "z2-base.core":http://redmine.z2-environment.net/projects/z2-base/repository/core repository from this URL *http://git.z2-environment.net/z2-base.core*. For convenience choose to import all projects into the workspace or do so after cloning has completed. You should end up having a project *core* in your workspace. That project is the z2 core that will fetch dependency resources as needed later on.
22 1 Henning Blohm
23 19 Henning Blohm
h2. 2. Clone the sample repository
24 17 Henning Blohm
25
Now repeat the same with the repository for the specific sample. It is important that the repository is cloned as a sibling to the core, So that the core can pick up modules defined in the sample.
26
27 22 Henning Blohm
h2. 3. Start and introspect
28 1 Henning Blohm
29
You can launch Z2 from Eclipse by the _launcher_ file in the root of the *core* project (or by navigating to *Run* / *External Tools* / *External Tools Configurations...* and pick the launcher). A GUI wrapping the console should open up and you are ready to go.
30 21 Henning Blohm
31 1 Henning Blohm
Once it is running, import the projects from the sample repository into your workspace, so that you can have a look at them. If you have previously installed the Eclipsoid plugin (see [[Step_3_-_First_steps_with_Z2_on_Git#Installation-of-the-Eclipsoid-plug-in]]) you can conveniently resolve all compilation dependencies with one click from within Eclipse.
32 31 Udo Offermann
33
h1. Using IntelliJ
34
35
[[IntelliJ z2 plugin]] shows how to install the z2 plugin and its basic features.
36 32 Udo Offermann
You can checkout the z2 repositories using VCS -> Checkout from Version Control... but make sure that you don't create a new project when IntelliJ asks you if "would you like to create a new IDEA project for ..."!
37
38
Furthermore make sure that the repository folders are located directly beneath the project folder:
39
<pre>
40
.../my-project
41 34 Udo Offermann
     /.idea
42 32 Udo Offermann
     /z2-base-core
43
     /z2-samples.xyz
44
</pre>
45
46 36 Udo Offermann
Once z2-base.core is checked out navigate to Preferences -> Project Settings -> z2-Environment and click "Search z2-Home" which should find the z2-base-core folder inside your project; press ok.
47
Still in the preference pane select Project Settings -> File Colors and add a new label to the local colors. As scope select "Armed z2-Modules" and choose a color you like and press ok and close the
48
Settings pane with ok. Now armed z2-modules will be displayed with the selected color.
49 1 Henning Blohm
50
Now launch the z2-environment from Tools -> Launch z2-environment...
51
52 36 Udo Offermann
Once it is running, import the projects from the sample repository into your workspace, by selecting the menu "Manage z2-modules" !z2_module.png! inside the toolbar. This opens a popup window showing 
53
the checked out repositories as root folders and their modules as children. Choose the modules belonging to the samples repository or simply select the sample repository node and press ok. 
54
This will create modules for each selected z2-modules inside your project. Since z2-modules in the samples repository are armed by default the modules should be displayed with the color selected above.
55
56 37 Udo Offermann
Of course the java classes will contain a lot of errors coming from unresolved dependencies. Choose "Resolve z2-classpath" !z_refresh.png! in the toolbar which will download all missing jars and add them
57
to the modules.
58 35 Udo Offermann
59 19 Henning Blohm
h1. From the command line
60 17 Henning Blohm
61
All you need is Java Runtime Environment (JRE) of at least version 6. Other pre-requisites, for example some database setup may be required based on the specific example, i.e. stuff that cannot be covered here.
62 1 Henning Blohm
63 19 Henning Blohm
h2. 1. Prepare a z2-base installation
64 2 Henning Blohm
65
Create a folder to hold the installation. We will assume that folder is called *sample*
66
67
In *sample* execute
68 11 Henning Blohm
69 5 Henning Blohm
<pre>
70 11 Henning Blohm
git clone -b master http://git.z2-environment.net/z2-base.core
71 2 Henning Blohm
</pre>
72
73
Go into *sample/z2-base.core/run/bin* and run 
74
75
<pre>
76
./gui.sh
77
</pre>
78
79
or 
80
81
<pre>
82
gui.bat
83 1 Henning Blohm
</pre>
84 3 Henning Blohm
85 2 Henning Blohm
depending on your operating system. A simple graphical console should open up that displays the console log output of the z2 &lt;home&gt; and worker processes - as explained in http://www.z2-environment.eu/check_it_out.
86
87 18 Henning Blohm
At the first start, the environment will download required resources, which may take a few minutes - depending on your network bandwidth. Subsequent starts will be much quicker. Eventually the server should be up and you can go to the basic admin view at http://localhost:8080/adm (use z* with password z) to verify everything is cool. You do actually not need to start before completing step 3. But checking things are working doesn't hurt either.
88 6 Henning Blohm
89 1 Henning Blohm
Stop the environment again by either pressing Ctrl+C on the console where you started the GUI or by clicking the Exit button on the GUI.
90 3 Henning Blohm
91 1 Henning Blohm
h2. 2. Clone the specific sample repository
92 3 Henning Blohm
93 1 Henning Blohm
Given the sample repository is called *z2-samples.sampleX*, go into *sample* once more and run 
94 3 Henning Blohm
95 1 Henning Blohm
<pre>
96
git clone -b master http://git.z2-environment.net/z2-samples.sampleX
97 5 Henning Blohm
</pre>
98 3 Henning Blohm
99 18 Henning Blohm
h2. 3. Start 
100
101
Now start the environment again as described above. The environment will now run with the sample configuration and all required dependencies.
102 4 Henning Blohm
103
In other words: That's it.
104 3 Henning Blohm
105 19 Henning Blohm
h2. Why does that actually work?
106 3 Henning Blohm
107
If you care, here is how everything falls into place:
108 13 Henning Blohm
109 3 Henning Blohm
The z2-base.core repository contains a z2 core installation that is bound to a remote "system repository" at "http://git.z2-environment.net/z2-base.base":http://redmine.z2-environment.net/projects/z2-base/repository/base?rev=master. As it is by now best practice with z2, that repository contains an *environment* module that describes system specific settings such as other repositories.
110
111
By cloning the sample repository you put an override of *environment* module into view of the _dev repository_. That is, the local server will take your local definitions with preference over the remote definitions. These may include other remote component repositories such as *z2-addons.spring*.
112
113
In addition the sample repository contains all the modules holding code and other resources that implement the actual sample.
114
115
If you already understand how the _dev repository_ works, you will not be surprised to find files called LOCAL in the module folders of cloned repository's workspace.
116
117 24 Henning Blohm
h2. Subversion support
118
119 26 Henning Blohm
Please see [[Repositories]] for the mapping of Git repositories to Subversion repositories. Samples are generally provided just the same - but throughout configured for Subversion - in the respective Subversion repositories. 
120 1 Henning Blohm
121 26 Henning Blohm
When you are using Eclipse, instead of cloning the whole repository to get the modules of the sample however, you do instead check out all modules in the repository to your workspace or in some folder. All the rest is just the same. 
122
123
So, for example, given the z2-samples.spring-basic sample, from the command line run
124
125
<pre><code class="ruby">
126
mkdir sample
127
cd sample
128 28 Udo Offermann
svn co --username=z2-envionment --password=z2-environment http://z2-environment.net/svn/z2-environment/trunk/z2-base.core
129 29 Udo Offermann
svn co --username=z2-envionment --password=z2-environment http://z2-environment.net/svn/z2-environment/trunk/z2-samples.spring-basic
130 26 Henning Blohm
cd z2-base.core/run/bin
131
./gui.sh
132
</code></pre>
133
134
135
Similarly, in Eclipse, in some workspace, first check out http://z2-environment.net/svn/trunk/z2-base.core (should get your a project named "core") and then check out all projects underneath http://z2-environment.net/svn/trunk/z2-base.spring-basic. Use the z2 start launcher to start Z2.
136 24 Henning Blohm
137
138 3 Henning Blohm
h2. References
139
140 1 Henning Blohm
* Dev Repository: http://www.z2-environment.eu/v20doc#Workspace%20Development%20Using%20the%20Dev%20Repository