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