implement AbstractMigrate.pm
[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 \
67799787 22libfile-sync-perl ifenslave-2.6 libnet-ldap-perl console-data \
a0f855e6 23libtool dietlibc-dev liblocale-po-perl
e143e9d8 24
7da024b1 253. Download and install the following git modules in order from top to bottom:
e143e9d8 26
7da024b1 27# git clone git://git.proxmox.com/git/<PACKAGE.git>
e143e9d8 28
7da024b1
DM
29You currently need the following packages:
30
31libqb.git
32corosync-pve.git
33openais-pve.git
34pve-common.git
35pve-cluster.git
36redhat-cluster-pve.git
56d42b76 37lvm.git
7da024b1
DM
38pve-access-control.git
39pve-storage.git
40pve-qemu-kvm.git
41qemu-server.git
42vncterm.git
b2b9ba38 43vzctl.git
7da024b1
DM
44pve-manager.git
45pve-kernel-2.6.32.git
d232e4b6 46fence-agents-pve.git
e143e9d8
DM
47
48Most source can be installed with 'make dinstall' command.
49
504. Reboot the system.
515. Learn to use the quilt patch scripts.
526. Happy coding.
53
54There is an experimental package containing the API documentation
55as ExtJS application:
56
7da024b1
DM
57pve2-api-doc.git
58
59You can view the source code at:
60
61https://git.proxmox.com
e143e9d8
DM
62
63
64REST vs. SOAP
65=============
66
67We decided to change our SOAP API (1.X) and use a REST like API. The
68concept is described in [1] (Resource Oriented Architecture
69(ROA)). The main advantage is that we are able to remove a lot of code
70(the whole SOAP stack) to reduce software complexity.
71
72We also moved away from server side content generation. Instead we use
73the ExtJS Rich Internet Application Framework
74(http://www.sencha.com).
75
76That framework, like any other AJAX toolkit, can talk directly to the
77REST API using JSON. So we were able to remove the server side
78template toolkit completely.
79
80JSON and JSON Schema
81====================
82
83We use JSON as data format, because it is simple and parse-able by any
84web browser.
85
86Additionally, we use JSON Schema [2] to formally describe our API. So
87we can automatically generate the whole API Documentation, and we can
88verify all parameters and return values.
89
90An great side effect was that we are able to use JSON Schema to
91produce command line argument parsers automatically. In fact, the REST
92API and the command line tools use the same code.
93
94Object linkage is done using the JSON Hyper Schema (links property).
95
96A small utility called 'pvesh' exposes the whole REST API on the command
97line.
98
99So here is a summary of the advantage:
100
101 - easy, human readable data format (native web browser format)
102 - automatic parameter verification (we can also verify return values)
103 - automatic generation of API documentation
104 - easy way to create command line tools (using same API).
105
106API Implementation (PVE::RESTHandler)
107=====================================
108
109All classes exposing methods on the API use PVE::RESTHandler as base class.
110
111 use base qw(PVE::RESTHandler);
112
113To expose methods, one needs to call register_method():
114
115 __PACKAGE__->register_method ($schema);
116
117Where $schema is a PVE method schema as described in
118PVE::JSONSchema. It includes a description of parameters and return
119values, and a reference to the actual code
120
121__PACKAGE__->register_method ({
122 name => 'echo',
123 path => 'echo',
124 method => 'GET',
125 description => "simple return value of parameter 'text'",
126 parameters => {
127 additionalProperties => 0,
128 properties => {
129 text => {
130 type => 'string',
131 }
132 },
133 },
134 returns => {
135 type => 'string',
136 },
137 code => sub {
138 my ($conn, $resp, $param) = @_;
139
140 return $param->{text};
141 }
142});
143
144The 'name' property is only used if you want to call the method
145directly from Perl. You can do that using:
146
147 print __PACKAGE__->echo({ text => "a test" });
148
149We use Perl's AUTOLOAD feature to implement this. Note: You need to
150pass parameters a HASH reference.
151
152There is a special helper method called cli_handler(). This is used by
153the CLIHandler Class for command line tools, where you want to pass
154arguments as array of strings. This uses Getopt::Long to parse parameters.
155
156There is a second way to map names to methods - using the 'path'
157property. And you can register subclasses. That way you can set up a
158filesystem like hierarchy to access methods.
159
160Here is an example:
161----------------------------
162package C1;
163
164__PACKAGE__->register_method ({
165 subclass => "C2",
166 path => 'sub2',
167});
168
169
170__PACKAGE__->register_method ({
171 name => 'list1',
172 path => 'index',
173 method => 'GET',
174 ...
175});
176
177package C2;
178
179__PACKAGE__->register_method ({
180 name => 'list2',
181 path => 'index',
182 method => 'GET',
183 ...
184});
185-------------------------------
186
187The utily method find_handler (in PVE::RESTHandler) can be use to do
188'path' related method lookups.
189
190C1->find_handler('GET', "/index") => C1::list1
191C1->find_handler('GET', "/sub2/index") => C2::list2
192
193The HTTP server use the URL (a path) to find the corresponding method.
194
195
196References
197==========
198[1] RESTful Web Services
199Web services for the real world
200
201By
202 Leonard Richardson, Sam Ruby
203Publisher:
204 O'Reilly Media
205Released:
206 May 2007
207
208[2] JSON Schema links: http://json-schema.org/