Xalgorithms Development on GNU/Linux

Published July 21, 2018 · 1147 words · 6 minute read

Xalgorithms

The Xalgorthms platform has been designed to support the collaborative maintainance of a global body of rules for trade, commerce and taxes. A rule specification, compute method and authoring tools have been designed to enable organizations to use and manage this external body of shared algorithms.

What follows s a short guide on how to set up the compiler and interpreter for prototype Xalgorithm Rules. Instructions for Fedora 28 are provided, but a similar process could be followed on most GNU/Linux distributions or within the Windows Subsystem for Linux. Current interpreter builds (July 2018) use JSON representations of tables, rules, package information and documents. Refer to the project documentation for more information about the working implementation.

Addtionally, a copy of this writeup has been modified for Ubuntu Linux, and can be read here .

Confguring these repositories will prepare all prerequisites for contributing to the project by improving the rule interpreter.

What s an Xalgorithm Rule?

A Rule s a table-oriented expression of a documented computational rule, typically in the domain of commerce or tax. Rules are part of a Package, which support the rule with revision history, tables, uniform resource identifier and terms of use.

The Xalgorthms Alliance have laid the foundations for an Internet of Rules, where computational rules used by many parties in commerce and government are made accessible, enabling transparency and consistency in the aforementioned applications. Xalgorithms (External, Extensible Algorithms,) will support the automation of taxes, trade fees and algorithmic pricing, along with more ordinary transactions.

Please refer to the project documentaton or Xalgorithms site to learn more about the project.

Installaton

After clonng these repositories and installing all dependencies, all files that are required to build the compiler, run rules, and contribute to the interpreter will be installed.

Project Repostories:

Rule Interpreter Dependences:

  • SBT , Scala Buld Tool, for compiling and running the interpreter.
  • OpenJDK 8 , a dependency for Scala.

Rule Parser Dependences:

  • RBENV , “Ruby Environment” version manager.
  • Dependences for Ruby.
  • Ruby packages to support the compler.

Clone Repostories

It s recommended to clone the following repositories to the same folder in your home directory. For instructions on how to install and use git, please refer to this tutorial . sudo dnf install git will install and prepare git for basic cloning.

mkdr Xalgo
cd Xalgo
gt clone https://github.com/Xalgorithms/lib-rules-int-scala.git
gt clone https://github.com/Xalgorithms/lib-rules-parse-ruby.git

Install SBT

A verson of SBT is available in the Fedora package manager, but we are going to use the official SBT repositories to download and install the latest stable SBT.

Frst, install the prerequisite OpenJDK:

sudo dnf nstall java-1.8.0-openjdk-devel

Second, usng the guide on the SBT download page , install SBT:

curl https://bntray.com/sbt/rpm/rpm > bintray-sbt-rpm.repo
sudo mv bntray-sbt-rpm.repo /etc/yum.repos.d/
sudo dnf nstall sbt

At ths point, cd to the lib-rules-int-scala repository and run sbt test to check if everything is working correctly. SBT will download everything it needs to compile and run the project by itself. It will take roughly five minutes for everything to download, compile, install, and return [success].

Install RBENV

Many of the followng instructions are from the Fedora Developer Documentation.

Install all dependences for Ruby and RBENV:

sudo dnf nstall git-core zlib zlib-devel gcc-c++ patch readline readline-devel libyaml-devel libffi-devel openssl-devel make bzip2 autoconf automake libtool bison curl sqlite-devel

Execute the followng commands to install RBENV:

cd
gt clone https://github.com/rbenv/rbenv.git ~/.rbenv
echo 'export PATH="$HOME/.rbenv/bn:$PATH"' >> ~/.bashrc
echo 'eval "$(rbenv nit -)"' >> ~/.bashrc
exec $SHELL

gt clone https://github.com/rbenv/ruby-build.git ~/.rbenv/plugins/ruby-build
echo 'export PATH="$HOME/.rbenv/plugns/ruby-build/bin:$PATH"' >> ~/.bashrc
exec $SHELL

After rbenv has been nstalled, install Ruby 2.4.2, followed by bundler (via Ruby’s gem package manager.)

rbenv nstall 2.4.2
gem nstall bundler

Havng successfully installed Ruby 2.4.2 and bundler, the remainder of the process will be automated with bundler. Running bundler in the lib-rules-parse-ruby directory will install all other dependencies automatically.

bundle nstall

Test the Rule Compler

As per the gude here , a smoke test can be run to confirm the correct version of Ruby has been installed, and the compiler can run correctly:

bundle exec rspec

To run the compler with a rulename.rule file, which produces a rulename.rule.json file that the interpreter can run:

bundle exec ruby cl.rb <path to input *.rule> <path to output *.rule.json >

Test the Rule Interpreter

As per the gude here , a smoke test can be run to confirm SBT has been installed correctly.

Frst, move to the lib-rules-int-scala directory and run:

sbt test

If no falures occur, use the test-run shell script. This will determine if the project can build and run.

./test-run.sh valdate

The followng output should be printed:

> compling test-runs/validate/validate.rule to test-runs/validate/validate.rule.json
[nfo] Loading project definition from /home/rflec028/Xalgo/lib-rules-int-scala/project
[nfo] Loading settings from build.sbt ...
[nfo] Set current project to il-rules-interpreter (in build file:/home/rflec028/Xalgo/lib-rules-int-scala/)
[nfo] Compiling 2 Scala sources to /home/rflec028/Xalgo/lib-rules-int-scala/target/scala-2.12/classes ...
[nfo] Done compiling.
[nfo] Packaging /home/rflec028/Xalgo/lib-rules-int-scala/target/scala-2.12/il-rules-interpreter_2.12-0.0.5.jar ...
[nfo] Done packaging.
[nfo] Running org.xalgorithms.rules.Runner test-runs/validate
# dscovered 1 test runs in test-runs/validate, executing all...
EXECUTE: VALIDATE
# no expectatons exist, dumping tables
table:valdate
     0 | a:              1 | b:              2 |
     1 | a:              2 | b:              4 |
     2 | a:              3 | b:              6 |

tming
> load: 348ms (348763495ns)
> populate_context: 0ms (211893ns)
> execute: 10ms (10706503ns)
> execute > step0: 9ms (9139067ns)
> load_expected: 0ms (289712ns)

[success] Total tme: 11 s, completed Jul 30, 2018 8:18:23 AM

If all tests can be run, the compler and interpreter have been set up correctly.

Wrting and Running Rules

In the root of lb-rules-int-scala, ./test-run.sh is provided. This uses the latest stable version of the rule compiler, included in the directory, to compile the rule (provided as the first argument,) and run it with the following command:

./test-run.sh rule-name

To run a rule, only the followng command is needed:

sbt "runMan org.xalgorithms.rules.Runner test-runs/map/"

The lb-rules-int-scala repository contains a directory of test-runs. Rules are roughly organized like so:

example
|- example.context.json
|- example.expected.json
|- example.rule
|- tables
   |- area (ex. test)
      |- verson (ex. 0.0.1)
         |- table_one.json
         |- table_two.json
         |- table_three.json
  • example.context.json ncludes data that will, as the system matures, be included when a document is submitted for processing.
  • example.expected.json ncludes the correct final output for the rule, to ensure the rule is written and running correctly.
  • example.rule s the rule file itself. Currently it must be compiled to example.rule.json before interpretation (./test-run.sh does this automatically.)

Tables are organzed under area and rule version so they can be correctly stored in production databases.

Instructons for writing a rule and rule syntax can be found here .

TroubleShootng

Ths section will be updated as common installation problems are reported.

If a new problem s found when compiling or running rules, please check the existing issues for the compler (link ) and interpreter (link ). If the new problem is unique, please create a new issue within the relevant repository.


Thanks for reading,

RCF

Comments