README.dev

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