Orient(able)

(↻Observe-Orient-Decide-Act↩)

Orient began life as a proof-of-concept reference implementation intended as a lightweight way to explore and clarify the (now somewhat outdated) Orientable specification.

The underlying framework has been developed alongside the Filecoin Übercalc. Eventually the repositories for these two projects will be split. In the meantime, for ease of development and deployment, they are colocated here.

For a brief introduction to Orient, see the tutorial.

Installation

sbcl

Code is in Common Lisp, developed and (to the extent it is) tested with SBCL.

> brew install sbcl

> apt-get install sbcl

QuickLisp & ASDF

Install QuickLisp:

Download the file for installation. (https://beta.quicklisp.org/quicklisp.lisp)
Then run sbcl with that file loaded by this command.

sbcl --load path/of/quicklisp.lisp

After sbcl launched, type in the command below.

(quicklisp-quickstart:install)

Now Quicklisp has been installed. To ensure Quicklisp is loaded every time you start Lisp, type in the command below.

(ql:add-to-init-file)

Optional for Emacs Users

NOTE: If you intend to develop on or with Orient (as opposed to just use CLI or web interfaces), then use of Emacs + Slime is strongly recommended.

Type in the command which will create a file you can load in Emacs to configure the right load-path for loading Quicklisp's installation of SLIME.

(ql:quickload "quicklisp-slime-helper")

Then configure Emacs to use Slime. Here is a simple but helpful configuration to place in you .emacs file:

(use-package slime
  :init
  (global-set-key (kbd "C-c z") 'slime-repl)
  (load (expand-file-name "~/quicklisp/slime-helper.el"))
  (setq inferior-lisp-program "/usr/local/bin/sbcl")
  (add-to-list 'slime-contribs 'slime-repl))

Ensure the path to your sbcl installation is correct.

You may also need to first install use-package by carefully following the linked instructions. This is strongly recommended.

Integrate the project with quicklisp

QuickLisp needs to find the project, so add a symlink:

> cd ~/quicklisp/local-projects
> ln -s ~/<installdir>/orient/orient.asd orient.asd

Test the Setup

When configured correctly, this should work and show no failures:

> sbcl
This is SBCL 1.4.14, an implementation of ANSI Common Lisp.
More information about SBCL is available at <http://www.sbcl.org/>.

SBCL is free software, provided as is, with absolutely no warranty.
It is mostly in the public domain; some portions are provided under
BSD-style licenses.  See the CREDITS and COPYING files in the
distribution for more information.
* (ql:quickload :orient)
To load "orient":
  Load 1 ASDF system:
    orient
; Loading "orient"
.....................................
(:ORIENT)
* (asdf:test-system :orient)

Running test suite ORIENT-SUITE
 Running test RENAME-ATTRIBUTES ..
 Running test RESTRICT .
 Running test PROJECT-TUPLE .
 Running test PROJECT-RELATION .
 Running test MULTIPLICATION-CONSTRAINT .......
 Running test DIVISION-CONSTRAINT ....
 Running test ADDITION-CONSTRAINT .......
 Running test SUBTRACTION-CONSTRAINT ...
 Running test LOG-CONSTRAINT ....
 Running test INTEGER-CONSTRAINT .......
 Running test EQUALITY-CONSTRAINT ...
 Running test LESS-THAN-CONSTRAINT ..
 Running test LESS-THAN-OR-EQUAL-CONSTRAINT ...
 Running test GREATER-THAN-CONSTRAINT ..
 Running test GREATER-THAN-OR-EQUAL-CONSTRAINT ...
 Running test AND-CONSTRAINT .............
 Running test CONSTRAINT-CONSTANTS ..
 Running test ORIENT-TESTS ............
 Running test JOIN ....
 Running test RENAME-TUPLE .
 Running test RENAME-RELATION .
 Running test SIMPLE-BIDIRECTIONAL ..
 Running test PLANNING-TERMINATES .
 Did 86 checks.
    Pass: 86 (100%)
    Skip: 0 ( 0%)
    Fail: 0 ( 0%)

Running test suite INTERFACE-SUITE
 Running test ROUNDTRIP-TRANSFORMATION .
 Running test ROUNDTRIP-SIGNATURE .
 Running test ROUNDTRIP-TUPLE .
 Running test ROUNDTRIP-SCHEMA .
 Running test ROUNDTRIP-PARAMETER .
 Running test ROUNDTRIP-COMPONENT .
 Running test ROUNDTRIP-SYSTEM .
 Did 7 checks.
    Pass: 7 (100%)
    Skip: 0 ( 0%)
    Fail: 0 ( 0%)

Running test suite FILECOIN-SUITE
 Running test PERFORMANCE-TEST .
 Running test MERKLE-TREE-CONSTRAINT-SYSTEM ...
 Running test SELECT-MERKLE-HASH-FUNCTION .
 Running test SELECT-KDF-HASH-FUNCTION .
 Running test MULTIPLE-HASH-FUNCTION-SELECTORS .
 Running test ZIGZAG-SYSTEM .
 Running test FILECOIN-DEFAULTS .
 Did 9 checks.
    Pass: 9 (100%)
    Skip: 0 ( 0%)
    Fail: 0 ( 0%)

Running test suite WEB-SUITE
 Running test TEST-ECONOMIC-PERFORMANCE .
 Running test TEST-ZIGZAG .
 Running test TEST-FILECOIN-SECURITY .
 Running test TEST-FILECOIN .
 Did 4 checks.
    Pass: 4 (100%)
    Skip: 0 ( 0%)
    Fail: 0 ( 0%)

T
*

You should get similar output from the shell:

>  make test

To start a web server, from REPL:

(orient.web:start-web)

Then navigate to http://localhost:8888.

To generate graphs, you will need Graphviz.

To generate and view graphs, graphviz must be installed locally, and dot must be in the path.

CLI

There are severals ways to run the CLI.

Development Mode

Install cl-launch, so /usr/local/bin/cl

For example, you may need to create a symlink:

> ln -s /<installdir>cl-launch.sh /usr/local/bin/cl
>  cl
cl-launch.sh 4.1.5

For help, invoke script with help argument:
        /usr/local/bin/cl -h

Now you can run the CLI and source changes will be immediately reflected, but startup is a bit slow.

> ./bin/orient ... <args>

Executable Image

If you just want to use the CLI, first dump an image:

> make image

Now startup should be very fast:

> ./bin/orient ... <args>

Docker

If you're having a hard time setting up a development environment, Docker might be easiest, but startup is a bit slow.

> make docker
> ./bin/dcalc ... <args>

Tests from shell

> make test

Tutorial