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