add hint to lvm.git
[pve-common.git] / README.dev
CommitLineData
e143e9d8
DM
1====================================
2Setup PVE v2 Development Environment
3====================================
4
51. Install Debian 'squeeze'
62. Install prerequisites for development environment:
7
7da024b1 8apt-get -y install build-essential git-core debhelper autotools-dev \
e143e9d8
DM
9doxygen check pkg-config libnss3-dev groff quilt dpatch libxml2-dev \
10libncurses5-dev libslang2-dev libldap2-dev xsltproc python-pexpect \
11python-pycurl libdbus-1-dev openipmi sg3-utils libnet-snmp-perl \
12libnet-telnet-perl snmp python-openssl libxml2-utils automake autoconf \
13libsqlite3-dev sqlite3 libfuse-dev libglib2.0-dev librrd-dev \
14librrds-perl rrdcached lintian libdevel-cycle-perl libjson-perl \
15liblinux-inotify2-perl libio-stringy-perl unzip fuse-utils \
16libcrypt-openssl-random-perl libcrypt-openssl-rsa-perl \
17libauthen-pam-perl libterm-readline-gnu-perl libssl-dev open-iscsi \
18libapache2-mod-perl2 libfilesys-df-perl libfile-readbackwards-perl \
19libpci-dev texi2html libgnutls-dev libsdl1.2-dev bridge-utils \
20libvncserver0 rpm2cpio apache2-mpm-prefork libintl-perl \
21libapache2-request-perl libnet-dns-perl vlan libio-socket-ssl-perl \
22libfile-sync-perl ifenslave-2.6 libnet-ldap-perl console-data
23
7da024b1 243. Download and install the following git modules in order from top to bottom:
e143e9d8 25
7da024b1 26# git clone git://git.proxmox.com/git/<PACKAGE.git>
e143e9d8 27
7da024b1
DM
28You currently need the following packages:
29
30libqb.git
31corosync-pve.git
32openais-pve.git
33pve-common.git
34pve-cluster.git
35redhat-cluster-pve.git
56d42b76 36lvm.git
7da024b1
DM
37pve-access-control.git
38pve-storage.git
39pve-qemu-kvm.git
40qemu-server.git
41vncterm.git
42pve-manager.git
43pve-kernel-2.6.32.git
d232e4b6 44fence-agents-pve.git
e143e9d8
DM
45
46Most source can be installed with 'make dinstall' command.
47
484. Reboot the system.
495. Learn to use the quilt patch scripts.
506. Happy coding.
51
52There is an experimental package containing the API documentation
53as ExtJS application:
54
7da024b1
DM
55pve2-api-doc.git
56
57You can view the source code at:
58
59https://git.proxmox.com
e143e9d8
DM
60
61
62REST vs. SOAP
63=============
64
65We decided to change our SOAP API (1.X) and use a REST like API. The
66concept is described in [1] (Resource Oriented Architecture
67(ROA)). The main advantage is that we are able to remove a lot of code
68(the whole SOAP stack) to reduce software complexity.
69
70We also moved away from server side content generation. Instead we use
71the ExtJS Rich Internet Application Framework
72(http://www.sencha.com).
73
74That framework, like any other AJAX toolkit, can talk directly to the
75REST API using JSON. So we were able to remove the server side
76template toolkit completely.
77
78JSON and JSON Schema
79====================
80
81We use JSON as data format, because it is simple and parse-able by any
82web browser.
83
84Additionally, we use JSON Schema [2] to formally describe our API. So
85we can automatically generate the whole API Documentation, and we can
86verify all parameters and return values.
87
88An great side effect was that we are able to use JSON Schema to
89produce command line argument parsers automatically. In fact, the REST
90API and the command line tools use the same code.
91
92Object linkage is done using the JSON Hyper Schema (links property).
93
94A small utility called 'pvesh' exposes the whole REST API on the command
95line.
96
97So here is a summary of the advantage:
98
99 - easy, human readable data format (native web browser format)
100 - automatic parameter verification (we can also verify return values)
101 - automatic generation of API documentation
102 - easy way to create command line tools (using same API).
103
104API Implementation (PVE::RESTHandler)
105=====================================
106
107All classes exposing methods on the API use PVE::RESTHandler as base class.
108
109 use base qw(PVE::RESTHandler);
110
111To expose methods, one needs to call register_method():
112
113 __PACKAGE__->register_method ($schema);
114
115Where $schema is a PVE method schema as described in
116PVE::JSONSchema. It includes a description of parameters and return
117values, and a reference to the actual code
118
119__PACKAGE__->register_method ({
120 name => 'echo',
121 path => 'echo',
122 method => 'GET',
123 description => "simple return value of parameter 'text'",
124 parameters => {
125 additionalProperties => 0,
126 properties => {
127 text => {
128 type => 'string',
129 }
130 },
131 },
132 returns => {
133 type => 'string',
134 },
135 code => sub {
136 my ($conn, $resp, $param) = @_;
137
138 return $param->{text};
139 }
140});
141
142The 'name' property is only used if you want to call the method
143directly from Perl. You can do that using:
144
145 print __PACKAGE__->echo({ text => "a test" });
146
147We use Perl's AUTOLOAD feature to implement this. Note: You need to
148pass parameters a HASH reference.
149
150There is a special helper method called cli_handler(). This is used by
151the CLIHandler Class for command line tools, where you want to pass
152arguments as array of strings. This uses Getopt::Long to parse parameters.
153
154There is a second way to map names to methods - using the 'path'
155property. And you can register subclasses. That way you can set up a
156filesystem like hierarchy to access methods.
157
158Here is an example:
159----------------------------
160package C1;
161
162__PACKAGE__->register_method ({
163 subclass => "C2",
164 path => 'sub2',
165});
166
167
168__PACKAGE__->register_method ({
169 name => 'list1',
170 path => 'index',
171 method => 'GET',
172 ...
173});
174
175package C2;
176
177__PACKAGE__->register_method ({
178 name => 'list2',
179 path => 'index',
180 method => 'GET',
181 ...
182});
183-------------------------------
184
185The utily method find_handler (in PVE::RESTHandler) can be use to do
186'path' related method lookups.
187
188C1->find_handler('GET', "/index") => C1::list1
189C1->find_handler('GET', "/sub2/index") => C2::list2
190
191The HTTP server use the URL (a path) to find the corresponding method.
192
193
194References
195==========
196[1] RESTful Web Services
197Web services for the real world
198
199By
200 Leonard Richardson, Sam Ruby
201Publisher:
202 O'Reilly Media
203Released:
204 May 2007
205
206[2] JSON Schema links: http://json-schema.org/