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?
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.
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.
lb-rules-int-scala, the rule interpreter. View on GitHub.
lb-rules-parse-ruby, the rule parser. View on Github.
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.
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
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
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.
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:
If no falures occur, use the test-run shell script. This will determine if the project can build and run.
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
./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:
To run a rule, only the followng command is needed:
sbt "runMan org.xalgorithms.rules.Runner test-runs/map/"
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.jsonncludes data that will, as the system matures, be included when a document is submitted for processing.
example.expected.jsonncludes the correct final output for the rule, to ensure the rule is written and running correctly.
example.rules the rule file itself. Currently it must be compiled to
example.rule.jsonbefore interpretation (
./test-run.shdoes 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 .
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,