= oVirt Ruby SDK

image:https://copr.fedorainfracloud.org/coprs/ovirt/ovirt-master-snapshot/package/rubygem-ovirt-engine-sdk4/status_image/last_build.png[https://copr.fedorainfracloud.org/coprs/ovirt/ovirt-master-snapshot/package/rubygem-ovirt-engine-sdk4/]

== Introduction

The oVirt Ruby SDK is a Ruby gem that simplyfies access to the oVirt Engine API.

IMPORTANT: This document describes how to generate, build and test the SDK. If you are interested in how to use it read the README.adoc file in the sdk directory instead.

== Building

The SDK uses http://www.xmlsoft.org[libxml2] for parsing and rendering XML documents and https://curl.haxx.se/libcurl[libcurl] for HTTP communication. The part of the SDK that interacts with these libraries is written in C. This means that before building you must make sure you have the C compiler and the required header and libraries files installed in your system. For example to install with the yum or dnf package manager in distributions like Fedora, CentOS or RHEL you will need to do the following:

dnf -y install \

gcc
libcurl-devel
libxml2-devel
redhat-rpm-config
ruby
ruby-devel
rubygems
rubygems-devel

NOTE: The installation of the ruby, ruby-devel, rubygems and rubygems-devel packages is necessary if you are going to use the Ruby version included in your distribution. If you are using tools like rbenv or rvm then this is not necessary.

If you are using the apt-get tool, in distributions like Debian, or Ubuntu:

apt-get --assume-yes install \

gcc
libcurl4-openssl-dev
libxml2-dev
ruby
ruby-dev

NOTE: The installation of the ruby, and ruby-dev packages is necessary if you are going to use the Ruby version included in your distribution. If you are using tools like rbenv or rvm then this is not necessary.

Some Linux distributions, like Debian and Ubuntu, provide multiple versions of libcurl, compiled with support for different TLS libraries: OpenSSL, NSS and GnuTLS. Currently the SDK only supports OpenSSL, so make sure that you have that version of libcurl installed. For example, in Ubuntu 16.04 if you have the NSS version installed, you will have to remove it and then install the OpenSSL version:

apt-get --assume-yes remove libcurl4-nss-dev

apt-get --assume-yes install libcurl4-openssl-dev

To manage the Ruby gems required for the build the project uses http://bundler.io[bundler], so you need to install this as well:

gem install bundler

Most of the source code of the Ruby SDK is automatically generated from the API model.

The code generator is a Java program that resides in the generator directory. This Java program will get the API model and the metamodel artifacts from the available Maven repositories. To build and run it use the you will need to have https://maven.apache.org[Maven] installed. For example, in Fedora, CentOS or RHEL:

dnf -y install maven

And in Debian or Ubuntu:

apt-get --assume-yes install maven

Once all the requirements are installed the SDK can be built as follows:

$ git clone git://gerrit.ovirt.org/ovirt-engine-sdk-ruby $ cd ovirt-engine-sdk-ruby $ mvn package

This will build the code generator, run it to generate the SDK for the version of the API that corresponds to the branch of the SDK that you are using, run the tests, and build the .gem file.

If you need to generate the SDK for a different version of the API then you can use the model.version property. For example, if you need to generate the SDK for version 4.1.0 of the SDK you can use this command:

$ mvn package -Dmodel.version=4.1.0

The generated .gem file will be located in the sdk directory:

$ ls sdk/*.gem sdk/ovirt-engine-sdk-4.0.0.alpha0.gem

== Testing

The test suite of the project is inside the sdk/spec directory. To run the tests change into the sdk directory and execute the bundle exec rake test command:

$ cd sdk $ bundle exec rake test

This will run the http://rspec.info[RSpec] tests. You can also run them directly with the rspec command, if you have it installed:

$ rspec