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