bump version to 4.0-16
[pve-common.git] / README.dev
CommitLineData
a4a9a328 1= Setup PVE Development Environment =
e143e9d8 2
8bc53243
DM
31. Install Debian 'jessie'
42. Configure pvetest repository in apt sources.list
a4a9a328
DM
5
6 deb http://download.proxmox.com/debian jessie pvetest
7
83. Add our repository key with apt-key:
9
10 wget -O- "http://download.proxmox.com/debian/key.asc" | apt-key add -
11
124. make sure you have a read IP address for your hostname in /etc/hosts
8bc53243 13 (using 127.0.1.1 will not work)
8bc53243 14
a4a9a328
DM
155. run: apt-get update
166. run: apt-get dist-upgrade
177. run: apt-get install proxmox-ve-3.10.0
e143e9d8 18
a4a9a328
DM
19You should now have a working Proxmox VE installation.
20
21= Install build prerequisites for development environment =
47e4eb11 22
7da024b1 23apt-get -y install build-essential git-core debhelper autotools-dev \
8bc53243
DM
24autogen dh-autoreconf dkms doxygen check pkg-config groff quilt dpatch \
25automake autoconf libtool lintian libdevel-cycle-perl libjson-perl \
26libcommon-sense-perl liblinux-inotify2-perl libio-stringy-perl \
27libstring-shellquote-perl dh-systemd rpm2cpio libsqlite3-dev sqlite3 \
28libglib2.0-dev librrd-dev librrds-perl rrdcached libdigest-hmac-perl \
29libxml-parser-perl gdb libcrypt-openssl-random-perl \
30libcrypt-openssl-rsa-perl libnet-ldap-perl libauthen-pam-perl \
31libjson-xs-perl libterm-readline-gnu-perl oathtool libmime-base32-perl \
32liboath0 libpci-dev texi2html libsdl1.2-dev libgnutls28-dev \
33libspice-protocol-dev xfslibs-dev libnuma-dev libaio-dev \
1cfd43f6 34pve-libspice-server-dev libusbredirparser-dev glusterfs-common \
8bc53243
DM
35libusb-1.0-0-dev librbd-dev libpopt-dev iproute bridge-utils numactl \
36glusterfs-common ceph-common python-ceph libgoogle-perftools4 \
37libfile-chdir-perl lvm2 glusterfs-client liblockfile-simple-perl \
38libsystemd-daemon-dev libreadline-gplv2-dev libio-multiplex-perl \
39libnetfilter-log-dev libipset3 ipset socat libsasl2-dev libogg-dev \
40python-pyparsing libfilesys-df-perl libcrypt-ssleay-perl \
41libfile-readbackwards-perl libanyevent-perl libanyevent-http-perl \
42unzip liblocale-po-perl vlan ifenslave-2.6 libfile-sync-perl cstream \
43lzop dtach apt-transport-https hdparm gdisk parted ttf-dejavu-core \
8998d715
TL
44liblzma-dev dosfstools mtools libxen-dev libfuse-dev libcorosync-pve-dev \
45libqb-dev
e143e9d8 46
a4a9a328
DM
47= Compile PVE packages from Source =
48
49Download and install the following git modules in order from top to bottom:
e143e9d8 50
7da024b1 51# git clone git://git.proxmox.com/git/<PACKAGE.git>
e143e9d8 52
7da024b1
DM
53You currently need the following packages:
54
47e4eb11 55libqb.git
7da024b1 56corosync-pve.git
7da024b1
DM
57pve-common.git
58pve-cluster.git
56d42b76 59lvm.git
7da024b1
DM
60pve-access-control.git
61pve-storage.git
62pve-qemu-kvm.git
63qemu-server.git
64vncterm.git
8bc53243
DM
65spiceterm.git
66#vzquota.git
67#vzctl.git
68#fence-agents-pve.git
69#resource-agents-pve.git
7da024b1 70pve-manager.git
8bc53243 71pve-kernel-3.10.0.git
60f4e8c7 72libiscsi.git
8bc53243 73#gfs2-utils.git
60f4e8c7 74ksm-control-daemon.git
e143e9d8 75
60f4e8c7 76Most packages can be installed with 'make dinstall' command.
e143e9d8
DM
77
784. Reboot the system.
795. Learn to use the quilt patch scripts.
806. Happy coding.
81
82There is an experimental package containing the API documentation
83as ExtJS application:
84
7da024b1
DM
85pve2-api-doc.git
86
87You can view the source code at:
88
89https://git.proxmox.com
e143e9d8
DM
90
91
a4a9a328 92= REST vs. SOAP =
e143e9d8
DM
93
94We decided to change our SOAP API (1.X) and use a REST like API. The
95concept is described in [1] (Resource Oriented Architecture
96(ROA)). The main advantage is that we are able to remove a lot of code
97(the whole SOAP stack) to reduce software complexity.
98
99We also moved away from server side content generation. Instead we use
100the ExtJS Rich Internet Application Framework
101(http://www.sencha.com).
102
103That framework, like any other AJAX toolkit, can talk directly to the
104REST API using JSON. So we were able to remove the server side
105template toolkit completely.
106
a4a9a328 107= JSON and JSON Schema =
e143e9d8
DM
108
109We use JSON as data format, because it is simple and parse-able by any
110web browser.
111
112Additionally, we use JSON Schema [2] to formally describe our API. So
113we can automatically generate the whole API Documentation, and we can
114verify all parameters and return values.
115
60f4e8c7 116A great side effect was that we are able to use JSON Schema to
e143e9d8
DM
117produce command line argument parsers automatically. In fact, the REST
118API and the command line tools use the same code.
119
120Object linkage is done using the JSON Hyper Schema (links property).
121
122A small utility called 'pvesh' exposes the whole REST API on the command
123line.
124
125So here is a summary of the advantage:
126
127 - easy, human readable data format (native web browser format)
128 - automatic parameter verification (we can also verify return values)
129 - automatic generation of API documentation
130 - easy way to create command line tools (using same API).
131
a4a9a328 132= API Implementation (PVE::RESTHandler) =
e143e9d8
DM
133
134All classes exposing methods on the API use PVE::RESTHandler as base class.
135
136 use base qw(PVE::RESTHandler);
137
138To expose methods, one needs to call register_method():
139
140 __PACKAGE__->register_method ($schema);
141
142Where $schema is a PVE method schema as described in
143PVE::JSONSchema. It includes a description of parameters and return
144values, and a reference to the actual code
145
146__PACKAGE__->register_method ({
147 name => 'echo',
148 path => 'echo',
149 method => 'GET',
150 description => "simple return value of parameter 'text'",
151 parameters => {
152 additionalProperties => 0,
153 properties => {
154 text => {
155 type => 'string',
156 }
157 },
158 },
159 returns => {
160 type => 'string',
161 },
162 code => sub {
163 my ($conn, $resp, $param) = @_;
164
165 return $param->{text};
166 }
167});
168
169The 'name' property is only used if you want to call the method
170directly from Perl. You can do that using:
171
172 print __PACKAGE__->echo({ text => "a test" });
173
174We use Perl's AUTOLOAD feature to implement this. Note: You need to
175pass parameters a HASH reference.
176
177There is a special helper method called cli_handler(). This is used by
178the CLIHandler Class for command line tools, where you want to pass
179arguments as array of strings. This uses Getopt::Long to parse parameters.
180
181There is a second way to map names to methods - using the 'path'
182property. And you can register subclasses. That way you can set up a
183filesystem like hierarchy to access methods.
184
185Here is an example:
186----------------------------
187package C1;
188
189__PACKAGE__->register_method ({
190 subclass => "C2",
191 path => 'sub2',
192});
193
194
195__PACKAGE__->register_method ({
196 name => 'list1',
197 path => 'index',
198 method => 'GET',
199 ...
200});
201
202package C2;
203
204__PACKAGE__->register_method ({
205 name => 'list2',
206 path => 'index',
207 method => 'GET',
208 ...
209});
210-------------------------------
211
212The utily method find_handler (in PVE::RESTHandler) can be use to do
213'path' related method lookups.
214
215C1->find_handler('GET', "/index") => C1::list1
216C1->find_handler('GET', "/sub2/index") => C2::list2
217
218The HTTP server use the URL (a path) to find the corresponding method.
219
220
a4a9a328
DM
221= References =
222
e143e9d8
DM
223[1] RESTful Web Services
224Web services for the real world
225
226By
227 Leonard Richardson, Sam Ruby
228Publisher:
229 O'Reilly Media
230Released:
231 May 2007
232
233[2] JSON Schema links: http://json-schema.org/