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