SysFSTools: copy over scan_usb from PVE::Storage
[pve-common.git] / README.dev
index bc6cfbe..0b12123 100644 (file)
-====================================
-Setup PVE Development Environment
-====================================
-
-1.  Install Debian 'jessie'
-2.  Install prerequisites for development environment:
-
-# new jessie depends
-apt-get -y install build-essential git-core debhelper autotools-dev \
-doxygen check pkg-config groff quilt dpatch automake autoconf libtool  \
-lintian libdevel-cycle-perl libjson-perl libcommon-sense-perl    \
-liblinux-inotify2-perl libio-stringy-perl libstring-shellquote-perl  \
-dh-systemd rpm2cpio libsqlite3-dev sqlite3 libglib2.0-dev librrd-dev \
-librrds-perl rrdcached libdigest-hmac-perl libxml-parser-perl \
-gdb libcrypt-openssl-random-perl libcrypt-openssl-rsa-perl \
-libnet-ldap-perl libauthen-pam-perl libjson-xs-perl libterm-readline-gnu-perl oathtool libmime-base32-perl liboath0 libpci-dev texi2html libsdl1.2-dev \
-libgnutls28-dev libspice-protocol-dev xfslibs-dev libnuma-dev libaio-dev \
-libspice-server-dev libusbredirparser-dev glusterfs-common libusb-1.0-0-dev \
-librbd-dev libpopt-dev iproute bridge-utils numactl glusterfs-common \
-ceph-common python-ceph libgoogle-perftools4 libfile-chdir-perl lvm2 \
-glusterfs-client liblockfile-simple-perl libsystemd-daemon-dev \
-libreadline-gplv2-dev libio-multiplex-perl libnetfilter-log-dev \
-libipset3 ipset socat libsasl2-dev
-
-# old wheezy depends
-apt-get -y install build-essential git-core debhelper autotools-dev \
-doxygen check pkg-config libnss3-dev groff quilt dpatch libxml2-dev \
-libncurses5-dev libslang2-dev libldap2-dev xsltproc python-pexpect \
-python-pycurl libdbus-1-dev openipmi sg3-utils libnet-snmp-perl \
-libnet-telnet-perl snmp python-openssl libxml2-utils automake autoconf \
-libsqlite3-dev sqlite3 libfuse-dev libglib2.0-dev librrd-dev \
-librrds-perl rrdcached lintian libdevel-cycle-perl libjson-perl \
-liblinux-inotify2-perl libio-stringy-perl unzip fuse-utils \
-libcrypt-openssl-random-perl libcrypt-openssl-rsa-perl \
-libauthen-pam-perl libterm-readline-gnu-perl libssl-dev open-iscsi \
-libapache2-mod-perl2 libfilesys-df-perl libfile-readbackwards-perl \
-libpci-dev texi2html libgnutls-dev libsdl1.2-dev bridge-utils \
-libvncserver0 rpm2cpio  apache2-mpm-prefork libintl-perl \
-libapache2-request-perl libnet-dns-perl vlan libio-socket-ssl-perl \
-libfile-sync-perl ifenslave-2.6 libnet-ldap-perl console-data \
-libtool dietlibc-dev liblocale-po-perl libstring-shellquote-perl \
-libio-multiplex-perl liblockfile-simple-perl
-
-3.  Download and install the following git modules in order from top to bottom:
-
-# git clone git://git.proxmox.com/git/<PACKAGE.git>
-
-You currently need the following packages:
-
-libqb.git
-corosync-pve.git
-openais-pve.git
-pve-common.git
-pve-cluster.git
-redhat-cluster-pve.git
-lvm.git
-pve-access-control.git
-pve-storage.git
-pve-qemu-kvm.git
-qemu-server.git
-vncterm.git
-vzquota.git
-vzctl.git
-fence-agents-pve.git
-resource-agents-pve.git
-pve-manager.git
-pve-kernel-2.6.32.git
-libiscsi.git
-gfs2-utils.git
-ksm-control-daemon.git
-
-Most packages can be installed with 'make dinstall' command.
-
-4.  Reboot the system.
-5.  Learn to use the quilt patch scripts.
-6.  Happy coding.
-
-There is an experimental package containing the API documentation
-as ExtJS application:
-
-pve2-api-doc.git
-
-You can view the source code at:
-
-https://git.proxmox.com
-
-
-REST vs. SOAP
-=============
+= Setup PVE Development Environment =
+
+0.  Read https://pve.proxmox.com/wiki/Developer_Documentation
+1.  Install Debian 9 'stretch' (you can also start from a PVE installation and
+    skip step 2 - 5, 7 - 11)
+2.  Configure the network interface(s)
+3.  Change the IP address of your hostname for proper name resolution
+    in /etc/hosts
+    Using 127.0.1.1 will not work, so change it to an IP address from your
+    local network!
+
+4:  Check that the Debian repositories are set properly.
+    See https://wiki.debian.org/SourcesList for more information.
+
+5.  Optional: Install openssh-server and connect via ssh to the host.
+
+    run: apt-get update && apt-get install openssh-server
+    Connect via ssh to host and switch user to root
+
+6.  Configure 'pvetest' repository in /etc/apt/sources.list.d/:
+
+    run: echo "deb http://download.proxmox.com/debian stretch pvetest" > /etc/apt/sources.list.d/pve-development.list
+
+7.  Add the repository key:
+
+    run: wget -O- "http://download.proxmox.com/debian/proxmox-ve-release-5.x.gpg" | apt-key add -
+
+8.  run: apt-get update && apt-get dist-upgrade
+9.  run: apt-get install proxmox-ve
+10. run: mv /etc/apt/sources.list.d/pve-enterprise.list /etc/apt/sources.list.d/pve-enterprise.list.bak
+
+11. You should now have a working Proxmox VE installation.
+    Open a browser: https://<host_IP_address>:8006 e.g. https://10.0.0.90:8006
+
+
+= Install build prerequisites for development environment =
+
+NOTE: this is a huge list intended to be able to build (almost) all packages,
+from the UI/API components to backend components to our Linux Kernel.
+If you only want to hack on specific topics you won't need most of those.
+We try to have a complete list of build dependencies in each source
+repositories 'debian/control' file. If you run `make deb` dpkg-buildpackage will
+stop and tell you if you miss some required packages.
+
+12. For installing the most important, always needed, ones run:
+
+apt-get install build-essential git git-email debhelper pve-doc-generator
+
+Additionally, for quickly installing (almost) all build dependencies run:
+
+apt-get install autotools-dev autogen dh-autoreconf dkms doxygen check pkg-config \
+groff quilt dpatch automake autoconf libtool lintian libdevel-cycle-perl \
+libjson-perl libcommon-sense-perl liblinux-inotify2-perl libio-stringy-perl \
+libstring-shellquote-perl dh-systemd rpm2cpio libsqlite3-dev sqlite3 \
+libglib2.0-dev librrd-dev librrds-perl rrdcached libdigest-hmac-perl \
+libxml-parser-perl gdb libcrypt-openssl-random-perl \
+libcrypt-openssl-rsa-perl libnet-ldap-perl libauthen-pam-perl \
+libjson-xs-perl libterm-readline-gnu-perl oathtool libmime-base32-perl \
+liboath0 libpci-dev texi2html libsdl1.2-dev libgnutls28-dev \
+libspice-protocol-dev xfslibs-dev libnuma-dev libaio-dev \
+pve-libspice-server-dev libusbredirparser-dev glusterfs-common \
+libusb-1.0-0-dev librbd-dev libpopt-dev iproute bridge-utils numactl \
+glusterfs-common ceph-common python-ceph libgoogle-perftools4 \
+libfile-chdir-perl lvm2 glusterfs-client liblockfile-simple-perl \
+libsystemd-dev libreadline-gplv2-dev libio-multiplex-perl \
+libnetfilter-log-dev libipset3 ipset socat libsasl2-dev libogg-dev \
+python-pyparsing libfilesys-df-perl libcrypt-ssleay-perl \
+libfile-readbackwards-perl libanyevent-perl libanyevent-http-perl \
+unzip liblocale-po-perl libfile-sync-perl cstream \
+lzop dtach apt-transport-https hdparm gdisk parted ttf-dejavu-core \
+liblzma-dev dosfstools mtools libxen-dev libfuse-dev corosync-dev \
+libcpg-dev libquorum-dev libcmap-dev libuuid-perl \
+libqb-dev libapparmor-dev docbook2x libcap-dev dh-apparmor \
+graphviz libseccomp-dev libglib-perl libgtk3-perl libnss3-dev libdlm-dev \
+libudev-dev asciidoc-dblatex source-highlight libiscsi-dev libiscsi7 \
+librsvg2-bin
+
+
+= Compile PVE packages from Source =
+
+13: Download and install git repositories as Proxmox modules:
+
+    run: mkdir /root/proxmox && cd /root/proxmox
+
+    run: git clone git://git.proxmox.com/git/pve-common.git
+
+    'pve-common.git' is some kind of starting repository and needed for some
+    other repositories as dependency.
+    Install this to get an idea of how the installation process is working.
+
+    See https://git.proxmox.com/ for all available repositories.
+
+14: Most packages can be installed with 'make dinstall' command.
+    run: cd pve-common && make dinstall
+
+15: Reboot the system.
+16. Learn to use the quilt patch scripts.
+17. Happy coding!
+
+
+= REST vs. SOAP =
 
 We decided to change our SOAP API (1.X) and use a REST like API. The
 concept is described in [1] (Resource Oriented Architecture
@@ -101,8 +113,7 @@ That framework, like any other AJAX toolkit, can talk directly to the
 REST API using JSON. So we were able to remove the server side
 template toolkit completely.
 
-JSON and JSON Schema
-====================
+= JSON and JSON Schema =
 
 We use JSON as data format, because it is simple and parse-able by any
 web browser.
@@ -127,8 +138,7 @@ So here is a summary of the advantage:
    - automatic generation of API documentation
    - easy way to create command line tools (using same API).
 
-API Implementation (PVE::RESTHandler)
-=====================================
+= API Implementation (PVE::RESTHandler) =
 
 All classes exposing methods on the API use PVE::RESTHandler as base class.
 
@@ -159,7 +169,7 @@ __PACKAGE__->register_method ({
        type => 'string',
     },
     code => sub {
-       my ($conn, $resp, $param) = @_;
+       my ($param) = @_;
 
        return $param->{text};
     }
@@ -217,8 +227,8 @@ C1->find_handler('GET', "/sub2/index") => C2::list2
 The HTTP server use the URL (a path) to find the corresponding method. 
 
 
-References
-==========
+= References =
+
 [1] RESTful Web Services
 Web services for the real world