Inotify: delete vlan-id for "iface.X" vlan iface.
[pve-common.git] / README.dev
CommitLineData
a4a9a328 1= Setup PVE Development Environment =
e143e9d8 2
bb9d3865 30. Read https://pve.proxmox.com/wiki/Developer_Documentation
2c2b3b55
TL
41. Install Debian 9 'stretch' (you can also start from a PVE installation and
5 skip step 2 - 5, 7 - 11)
bb9d3865
MB
62. Configure the network interface(s)
73. Change the IP address of your hostname for proper name resolution
8 in /etc/hosts
9 Using 127.0.1.1 will not work, so change it to an IP address from your
10 local network!
a4a9a328 11
bb9d3865
MB
124: Check that the Debian repositories are set properly.
13 See https://wiki.debian.org/SourcesList for more information.
a4a9a328 14
bb9d3865 155. Optional: Install openssh-server and connect via ssh to the host.
a4a9a328 16
bb9d3865
MB
17 run: apt-get update && apt-get install openssh-server
18 Connect via ssh to host and switch user to root
a4a9a328 19
bb9d3865 206. Configure 'pvetest' repository in /etc/apt/sources.list.d/:
8bc53243 21
bb9d3865
MB
22 run: echo "deb http://download.proxmox.com/debian stretch pvetest" > /etc/apt/sources.list.d/pve-development.list
23
247. Add the repository key:
25
26 run: wget -O- "http://download.proxmox.com/debian/proxmox-ve-release-5.x.gpg" | apt-key add -
27
288. run: apt-get update && apt-get dist-upgrade
299. run: apt-get install proxmox-ve
3010. run: mv /etc/apt/sources.list.d/pve-enterprise.list /etc/apt/sources.list.d/pve-enterprise.list.bak
31
3211. You should now have a working Proxmox VE installation.
33 Open a browser: https://<host_IP_address>:8006 e.g. https://10.0.0.90:8006
e143e9d8 34
a4a9a328
DM
35
36= Install build prerequisites for development environment =
47e4eb11 37
69e15ccb
TL
38NOTE: this is a huge and probably outdated list intended to be able to build
39(almost) all packages, from the UI/API components to backend components to our
40Linux Kernel. If you only want to hack on specific topics you won't need most
41of those.
42Instead we try to have a complete list of build dependencies in each source
43repositories 'debian/control' file. If you run `make deb` dpkg-buildpackage
44will stop and tell you if you miss some required packages.
bb9d3865 45
fb6134fe
TL
4612. For installing the most important, always needed, ones run:
47
48apt-get install build-essential git git-email debhelper pve-doc-generator
49
50Additionally, for quickly installing (almost) all build dependencies run:
51
69e15ccb
TL
52WARNING: this list is almost for sure outdated! Use the build-deps definitions
53defined in each package! You could install `devscripts` (huge package, but nice
54helpers) and use:
55# mk-build-deps --install
56in the top-level directory of a git repository.
57
fb6134fe 58apt-get install autotools-dev autogen dh-autoreconf dkms doxygen check pkg-config \
48e957b9
MR
59groff quilt dpatch automake autoconf libtool lintian libdevel-cycle-perl \
60libjson-perl libcommon-sense-perl liblinux-inotify2-perl libio-stringy-perl \
8bc53243
DM
61libstring-shellquote-perl dh-systemd rpm2cpio libsqlite3-dev sqlite3 \
62libglib2.0-dev librrd-dev librrds-perl rrdcached libdigest-hmac-perl \
63libxml-parser-perl gdb libcrypt-openssl-random-perl \
64libcrypt-openssl-rsa-perl libnet-ldap-perl libauthen-pam-perl \
65libjson-xs-perl libterm-readline-gnu-perl oathtool libmime-base32-perl \
66liboath0 libpci-dev texi2html libsdl1.2-dev libgnutls28-dev \
67libspice-protocol-dev xfslibs-dev libnuma-dev libaio-dev \
1cfd43f6 68pve-libspice-server-dev libusbredirparser-dev glusterfs-common \
8bc53243
DM
69libusb-1.0-0-dev librbd-dev libpopt-dev iproute bridge-utils numactl \
70glusterfs-common ceph-common python-ceph libgoogle-perftools4 \
71libfile-chdir-perl lvm2 glusterfs-client liblockfile-simple-perl \
37640d62 72libsystemd-dev libreadline-gplv2-dev libio-multiplex-perl \
8bc53243
DM
73libnetfilter-log-dev libipset3 ipset socat libsasl2-dev libogg-dev \
74python-pyparsing libfilesys-df-perl libcrypt-ssleay-perl \
75libfile-readbackwards-perl libanyevent-perl libanyevent-http-perl \
692160c1 76unzip liblocale-po-perl libfile-sync-perl cstream \
0da8dc9d 77lzop dtach hdparm gdisk parted ttf-dejavu-core \
77624d02
TL
78liblzma-dev dosfstools mtools libxen-dev libfuse-dev libcpg-dev libquorum-dev \
79libcmap-dev libuuid-perl libqb-dev libapparmor-dev docbook2x libcap-dev \
80dh-apparmor graphviz libseccomp-dev libglib-perl libgtk3-perl libnss3-dev \
81libdlm-dev libudev-dev asciidoc-dblatex source-highlight libiscsi-dev \
82libiscsi7 librsvg2-bin libarchive-dev libgpgme-dev libcurl4-gnutls-dev \
cc74c62d 83libtest-mockmodule-perl libjemalloc-dev libjpeg-dev
bb9d3865 84
e143e9d8 85
a4a9a328
DM
86= Compile PVE packages from Source =
87
bb9d3865
MB
8813: Download and install git repositories as Proxmox modules:
89
90 run: mkdir /root/proxmox && cd /root/proxmox
91
92 run: git clone git://git.proxmox.com/git/pve-common.git
93
94 'pve-common.git' is some kind of starting repository and needed for some
95 other repositories as dependency.
96 Install this to get an idea of how the installation process is working.
97
98 See https://git.proxmox.com/ for all available repositories.
99
10014: Most packages can be installed with 'make dinstall' command.
101 run: cd pve-common && make dinstall
102
10315: Reboot the system.
10416. Learn to use the quilt patch scripts.
10517. Happy coding!
e143e9d8
DM
106
107
a4a9a328 108= REST vs. SOAP =
e143e9d8
DM
109
110We decided to change our SOAP API (1.X) and use a REST like API. The
111concept is described in [1] (Resource Oriented Architecture
112(ROA)). The main advantage is that we are able to remove a lot of code
113(the whole SOAP stack) to reduce software complexity.
114
115We also moved away from server side content generation. Instead we use
116the ExtJS Rich Internet Application Framework
117(http://www.sencha.com).
118
119That framework, like any other AJAX toolkit, can talk directly to the
120REST API using JSON. So we were able to remove the server side
121template toolkit completely.
122
a4a9a328 123= JSON and JSON Schema =
e143e9d8
DM
124
125We use JSON as data format, because it is simple and parse-able by any
126web browser.
127
128Additionally, we use JSON Schema [2] to formally describe our API. So
129we can automatically generate the whole API Documentation, and we can
130verify all parameters and return values.
131
60f4e8c7 132A great side effect was that we are able to use JSON Schema to
e143e9d8
DM
133produce command line argument parsers automatically. In fact, the REST
134API and the command line tools use the same code.
135
136Object linkage is done using the JSON Hyper Schema (links property).
137
138A small utility called 'pvesh' exposes the whole REST API on the command
139line.
140
141So here is a summary of the advantage:
142
143 - easy, human readable data format (native web browser format)
144 - automatic parameter verification (we can also verify return values)
145 - automatic generation of API documentation
146 - easy way to create command line tools (using same API).
147
a4a9a328 148= API Implementation (PVE::RESTHandler) =
e143e9d8
DM
149
150All classes exposing methods on the API use PVE::RESTHandler as base class.
151
152 use base qw(PVE::RESTHandler);
153
154To expose methods, one needs to call register_method():
155
156 __PACKAGE__->register_method ($schema);
157
158Where $schema is a PVE method schema as described in
159PVE::JSONSchema. It includes a description of parameters and return
160values, and a reference to the actual code
161
162__PACKAGE__->register_method ({
163 name => 'echo',
164 path => 'echo',
165 method => 'GET',
166 description => "simple return value of parameter 'text'",
167 parameters => {
168 additionalProperties => 0,
169 properties => {
170 text => {
171 type => 'string',
172 }
173 },
174 },
175 returns => {
176 type => 'string',
177 },
178 code => sub {
ef73f03b 179 my ($param) = @_;
e143e9d8
DM
180
181 return $param->{text};
182 }
183});
184
185The 'name' property is only used if you want to call the method
186directly from Perl. You can do that using:
187
188 print __PACKAGE__->echo({ text => "a test" });
189
190We use Perl's AUTOLOAD feature to implement this. Note: You need to
191pass parameters a HASH reference.
192
193There is a special helper method called cli_handler(). This is used by
194the CLIHandler Class for command line tools, where you want to pass
195arguments as array of strings. This uses Getopt::Long to parse parameters.
196
197There is a second way to map names to methods - using the 'path'
198property. And you can register subclasses. That way you can set up a
199filesystem like hierarchy to access methods.
200
201Here is an example:
202----------------------------
203package C1;
204
205__PACKAGE__->register_method ({
206 subclass => "C2",
207 path => 'sub2',
208});
209
210
211__PACKAGE__->register_method ({
212 name => 'list1',
213 path => 'index',
214 method => 'GET',
215 ...
216});
217
218package C2;
219
220__PACKAGE__->register_method ({
221 name => 'list2',
222 path => 'index',
223 method => 'GET',
224 ...
225});
226-------------------------------
227
228The utily method find_handler (in PVE::RESTHandler) can be use to do
229'path' related method lookups.
230
231C1->find_handler('GET', "/index") => C1::list1
232C1->find_handler('GET', "/sub2/index") => C2::list2
233
234The HTTP server use the URL (a path) to find the corresponding method.
235
236
a4a9a328
DM
237= References =
238
e143e9d8
DM
239[1] RESTful Web Services
240Web services for the real world
241
242By
243 Leonard Richardson, Sam Ruby
244Publisher:
245 O'Reilly Media
246Released:
247 May 2007
248
249[2] JSON Schema links: http://json-schema.org/