How to use native libraries in Splay
N.B For security reasons, this feature will not be available through our public SPLAY demo.
Once your controller is properly installed, you need to enable the support for native libraries. To proceed, you first need to make sure that your controller and all the splayds are not running.A. Splayd
To make sure your splayd is ready to accept jobs that require a native library, you need to ensure that the following line in the settings.lua file is uncommented:
splayd.settings.protocol = "grid"
B. Controller
To enable your SPLAY users to submit their libraries and to submit jobs requiring them, uncomment the following line in the file lib/config.rb:AllowNativeLibs = true
C. Submitting a native library to the controller
Currently, every user can submit a library to the controller. To do that, a single call to a script is sufficient:
./splay-submit-lib.lua -l hello.so -lv 1.0 -a i386 -o LinuxThe scripts requires four mandatory parameters: -l for the name of the library, -lv as the version number, -a as the architecture and -o as the OS the library has been compiled for. If everything works, the following output corresponds to a successful insertion executed with the previous command:
LIB_NAME= hello.so OS= Linux ARCH= x86_64 version= 1.0 SHA1= 632861aa6e8d1337e5f4126139396c1f43e8cf7e NEW NATIVE LIBRARY INSTALLED
Note: There is no validation that takes place with regard to the information provided by the user. It is her responsibility to ensure its validity.
D. Submitting a jobs with a native library
Once a library is available on the controller, we are ready to use it with a job (provided that there are splayds that match its platform).
./splay-submit-job.lua -l hello.so -lv 1.0 sample.lua
As shown in the example, both -l and -lv need to be specified. If there are enough splayds, the job will be deployed.
E. Updating a lib
Sometimes it is required to update a library (to correct bugs or for improvements) after its successful deployment. It is possible to use same script as in A) to do that. We have the following policy: we allow only one version of a lib per platform (architecture + os). It implies that if a library A is available for platforms X an Y at version 1.0, updating A to vresion 2.0 for platform X will leave the one available for platform Y at 1.0. Also note that the library version numbers are a matter of convention: therefore, the system won't check for increasing versions (infact, It is perfectly possible to replace a library from version 2.0 to version 1.1).
./splay-submit-lib.lua -l hello.so -lv 2.0 -a i386 -o Linux
The following output shows the message a user receives when successfully updating a library.
LIB_NAME= hello.so OS= Linux ARCH= x86_64 version= 2.0 SHA1= 3de50b680d5e2d5b8ad3903c6ddc89ffe25d015d EXISTING NATIVE LIBRARY UPDATED
F. Other administration tasks
For administrative purposes we provide two more scripts to list the available libraries and remove the deprecated ones.
Listing libraries is done with splay-list-libs.lua. It supports only one option -l LIB_NAME to filter the libraries you want to list to a given name.
./splay-list-libs.lua -l hello.soThat will give the following output provided that we only have the libraries uploaded in the previous examples.
N.B for the sake of this example, we added a second library by repeating the submission process at A.
SESSION_ID = 13586bc3a682749aa623f81b3f82f338b78901c9 CLI SERVER URL = http://127.0.0.1:2222/splay-ctrl-api LIB NAME = Sending command to http://127.0.0.1:2222/splay-ctrl-api... Libs list : number of items 2 Lib name =hello.so Version=1.0 Arch=x86_64 OS=Linux SHA1=632861aa6e8d1337e5f4126139396c1f43e8cf7e Lib name =hello.so Version=1.0 Arch=i386 OS=Linux SHA1=7cda17cbb957de2219f98e64ad5194187c3b8beb
Removing libraries is also important in order to clean the controller without having an access to the controller database.
Its only mandatory parameter is the name of the library to remove, specified by the -l parameter. It supports several (but optional) parameters: -lv will remove all instances of a given version, -o will remove all instances for a given operating system and -a will remove all instances for the given architecture. All the optional parameters can be combined to narrow down the number of libraries to remove../splay-remove-lib.lua -l hello.soAs a result we obtain this output:
SESSION_ID = e85eb3ae5d82db0289db3137687f99bf5f06959f CLI SERVER URL = http://127.0.0.1:2222/splay-ctrl-api LIB NAME = hello.so Sending command to http://127.0.0.1:2222/splay-ctrl-api... Controller : Lib deletedAnd by listing again all the libraries, we can see that the controller is empty.
./splay-list-libs.lua -l hello.so
SESSION_ID = e85eb3ae5d82db0289db3137687f99bf5f06959f CLI SERVER URL = http://127.0.0.1:2222/splay-ctrl-api LIB NAME = hello.so Sending command to http://127.0.0.1:2222/splay-ctrl-api... Libs list : number of items 0