runtest.pl: use lib '.' - because newer perl does not have that by default
[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
48e957b9 177. run: apt-get install proxmox-ve
e143e9d8 18
a4a9a328
DM
19You should now have a working Proxmox VE installation.
20
21= Install build prerequisites for development environment =
47e4eb11 22
48e957b9
MR
23apt-get -y install build-essential git-core git-email debhelper \
24autotools-dev autogen dh-autoreconf dkms doxygen check pkg-config \
25groff quilt dpatch automake autoconf libtool lintian libdevel-cycle-perl \
26libjson-perl libcommon-sense-perl liblinux-inotify2-perl libio-stringy-perl \
8bc53243
DM
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 44liblzma-dev dosfstools mtools libxen-dev libfuse-dev libcorosync-pve-dev \
fe949d0e
WL
45libqb-dev libapparmor-dev docbook2x libcap-dev dh-apparmor libcgmanager-dev \
46graphviz libseccomp-dev libglib-perl libgtk3-perl libnss3-dev libdlm-dev \
47libudev-dev
e143e9d8 48
a4a9a328
DM
49= Compile PVE packages from Source =
50
51Download and install the following git modules in order from top to bottom:
e143e9d8 52
7da024b1 53# git clone git://git.proxmox.com/git/<PACKAGE.git>
e143e9d8 54
7da024b1
DM
55You currently need the following packages:
56
47e4eb11 57libqb.git
7da024b1 58corosync-pve.git
7da024b1 59pve-common.git
f77a3f79 60pve-docs.git
7da024b1 61pve-cluster.git
56d42b76 62lvm.git
7da024b1
DM
63pve-access-control.git
64pve-storage.git
65pve-qemu-kvm.git
66qemu-server.git
67vncterm.git
8bc53243
DM
68spiceterm.git
69#vzquota.git
70#vzctl.git
71#fence-agents-pve.git
72#resource-agents-pve.git
7da024b1 73pve-manager.git
fe949d0e 74#pve-kernel-3.10.0.git
60f4e8c7 75libiscsi.git
8bc53243 76#gfs2-utils.git
60f4e8c7 77ksm-control-daemon.git
fe949d0e
WL
78pve-container.git
79pve-firewall.git
80pve-kernel.git
e143e9d8 81
60f4e8c7 82Most packages can be installed with 'make dinstall' command.
e143e9d8
DM
83
844. Reboot the system.
855. Learn to use the quilt patch scripts.
866. Happy coding.
87
88There is an experimental package containing the API documentation
89as ExtJS application:
90
7da024b1
DM
91pve2-api-doc.git
92
93You can view the source code at:
94
95https://git.proxmox.com
e143e9d8
DM
96
97
a4a9a328 98= REST vs. SOAP =
e143e9d8
DM
99
100We decided to change our SOAP API (1.X) and use a REST like API. The
101concept is described in [1] (Resource Oriented Architecture
102(ROA)). The main advantage is that we are able to remove a lot of code
103(the whole SOAP stack) to reduce software complexity.
104
105We also moved away from server side content generation. Instead we use
106the ExtJS Rich Internet Application Framework
107(http://www.sencha.com).
108
109That framework, like any other AJAX toolkit, can talk directly to the
110REST API using JSON. So we were able to remove the server side
111template toolkit completely.
112
a4a9a328 113= JSON and JSON Schema =
e143e9d8
DM
114
115We use JSON as data format, because it is simple and parse-able by any
116web browser.
117
118Additionally, we use JSON Schema [2] to formally describe our API. So
119we can automatically generate the whole API Documentation, and we can
120verify all parameters and return values.
121
60f4e8c7 122A great side effect was that we are able to use JSON Schema to
e143e9d8
DM
123produce command line argument parsers automatically. In fact, the REST
124API and the command line tools use the same code.
125
126Object linkage is done using the JSON Hyper Schema (links property).
127
128A small utility called 'pvesh' exposes the whole REST API on the command
129line.
130
131So here is a summary of the advantage:
132
133 - easy, human readable data format (native web browser format)
134 - automatic parameter verification (we can also verify return values)
135 - automatic generation of API documentation
136 - easy way to create command line tools (using same API).
137
a4a9a328 138= API Implementation (PVE::RESTHandler) =
e143e9d8
DM
139
140All classes exposing methods on the API use PVE::RESTHandler as base class.
141
142 use base qw(PVE::RESTHandler);
143
144To expose methods, one needs to call register_method():
145
146 __PACKAGE__->register_method ($schema);
147
148Where $schema is a PVE method schema as described in
149PVE::JSONSchema. It includes a description of parameters and return
150values, and a reference to the actual code
151
152__PACKAGE__->register_method ({
153 name => 'echo',
154 path => 'echo',
155 method => 'GET',
156 description => "simple return value of parameter 'text'",
157 parameters => {
158 additionalProperties => 0,
159 properties => {
160 text => {
161 type => 'string',
162 }
163 },
164 },
165 returns => {
166 type => 'string',
167 },
168 code => sub {
169 my ($conn, $resp, $param) = @_;
170
171 return $param->{text};
172 }
173});
174
175The 'name' property is only used if you want to call the method
176directly from Perl. You can do that using:
177
178 print __PACKAGE__->echo({ text => "a test" });
179
180We use Perl's AUTOLOAD feature to implement this. Note: You need to
181pass parameters a HASH reference.
182
183There is a special helper method called cli_handler(). This is used by
184the CLIHandler Class for command line tools, where you want to pass
185arguments as array of strings. This uses Getopt::Long to parse parameters.
186
187There is a second way to map names to methods - using the 'path'
188property. And you can register subclasses. That way you can set up a
189filesystem like hierarchy to access methods.
190
191Here is an example:
192----------------------------
193package C1;
194
195__PACKAGE__->register_method ({
196 subclass => "C2",
197 path => 'sub2',
198});
199
200
201__PACKAGE__->register_method ({
202 name => 'list1',
203 path => 'index',
204 method => 'GET',
205 ...
206});
207
208package C2;
209
210__PACKAGE__->register_method ({
211 name => 'list2',
212 path => 'index',
213 method => 'GET',
214 ...
215});
216-------------------------------
217
218The utily method find_handler (in PVE::RESTHandler) can be use to do
219'path' related method lookups.
220
221C1->find_handler('GET', "/index") => C1::list1
222C1->find_handler('GET', "/sub2/index") => C2::list2
223
224The HTTP server use the URL (a path) to find the corresponding method.
225
226
a4a9a328
DM
227= References =
228
e143e9d8
DM
229[1] RESTful Web Services
230Web services for the real world
231
232By
233 Leonard Richardson, Sam Ruby
234Publisher:
235 O'Reilly Media
236Released:
237 May 2007
238
239[2] JSON Schema links: http://json-schema.org/