Skip to main content

tools for working with chiklisp language; compiler, repl, python and wasm bindings

Project description

klvm_tools_rs

Theory of operation of the modern compiler: ./HOW_CHIKLISP_IS_COMPILED.md

This repo can be installed via cargo

cargo install klvm_tools_rs

or via pip

pip install klvm_tools_rs@git+https://github.com/Chik-Network/klvm_tools_rs.git@e17412032aa7d3b8b1d1f931893fb5802eee626a

Note: pip installs a subset of the tools installed by cargo, including brun, run, opc and opd.

The most current version of the language is in the nightly branch:

[nightly](https://github.com/Chik-Network/klvm_tools_rs/tree/nightly)

To install from a specific branch:

cargo install --no-default-features --git 'https://github.com/Chik-Network/klvm_tools_rs' --branch nightly

To install a git checkout into your current python environment (must be in some kind of venv or conda environment):

git clone https://github.com/Chik-Network/klvm_tools_rs
cd klvm_tools_rs
maturin develop

Install from PYPI:

pip install -i https://pypi.chiknetwork.com/nightlies/ klvm_tools_rs

Most people still compile chiklisp via python. One way to set up compilation in that way is like this:

import json
from klvm_tools_rs import compile_klvm

def compile_module_with_symbols(include_paths,source):
    path_obj = Path(source)
    file_path = path_obj.parent
    file_stem = path_obj.stem
    target_file = file_path / (file_stem + ".klvm.hex")
    sym_file = file_path / (file_stem + ".sym")
    compile_result = compile_klvm(source, str(target_file.absolute()), include_paths, True)
    symbols = compile_result['symbols']
    if len(symbols) != 0:
        with open(str(sym_file.absolute()),'w') as symfile:
            symfile.write(json.dumps(symbols))

The command line tools provided:

- run -- Compiles KLVM code from chiklisp

Most commonly, you'll compile chiklisp like this:

  ./target/debug/run -O -i include_dir chiklisp.clsp

'run' outputs the code resulting from compiling the program, or an error.

- repl -- Accepts chiklisp forms and expressions and produces results
          interactively.
          
Run like:

  ./target/debug/repl
  
Example session:

>>> (defmacro assert items
   (if (r items)
       (list if (f items) (c assert (r items)) (q . (x)))
     (f items)
     )
   )
(q)
>>> (assert 1 1 "hello")
(q . hello)
>>> (assert 1 0 "bye")
failed: CompileErr(Srcloc { file: "*macros*", line: 2, col: 26, until: Some(Until { line: 2, col: 82 }) }, "klvm raise in (8) (())")
>>> 

- cldb -- Stepwise run chiklisp programs with program readable yaml output.

  ./target/debug/cldb '(mod (X) (x X))' '(4)'
  ---
  - Arguments: (() (4))
    Operator: "4"
    Operator-Location: "*command*(1):11"
    Result-Location: "*command*(1):11"
    Row: "0"
    Value: (() 4)
  - Env: "4"
    Env-Args: ()
    Operator: "2"
    Operator-Location: "*command*(1):11"
    Result-Location: "*command*(1):13"
    Row: "1"
    Value: "4"
  - Arguments: (4)
    Failure: klvm raise in (8 5) (() 4)
    Failure-Location: "*command*(1):11"
    Operator: "8"
    Operator-Location: "*command*(1):13"

- brun -- Runs a "binary" program.  Instead of serving as a chiklisp
  compiler, instead runs klvm programs.

As 'brun' from the python code:

$ ./target/debug/run '(mod (X) (defun fact (N X) (if (> 2 X) N (fact (* X N) (- X 1)))) (fact 1 X))'
(a (q 2 2 (c 2 (c (q . 1) (c 5 ())))) (c (q 2 (i (> (q . 2) 11) (q . 5) (q 2 2 (c 2 (c (* 11 5) (c (- 11 (q . 1)) ()))))) 1) 1))
$ ./target/debug/brun '(a (q 2 2 (c 2 (c (q . 1) (c 5 ())))) (c (q 2 (i (> (q . 2) 11) (q . 5) (q 2 2 (c 2 (c (* 11 5) (c (- 11 (q . 1)) ()))))) 1) 1))' '(5)'
120

- opc -- crush klvm s-expression form to hex.

As 'opc' from the python code.

opc '(a (q 2 2 (c 2 (c (q . 1) (c 5 ())))) (c (q 2 (i (> (q . 2) 11) (q . 5) (q 2 2 (c 2 (c (* 11 5) (c (- 11 (q . 1)) ()))))) 1) 1))'
ff02ffff01ff02ff02ffff04ff02ffff04ffff0101ffff04ff05ff8080808080ffff04ffff01ff02ffff03ffff15ffff0102ff0b80ffff0105ffff01ff02ff02ffff04ff02ffff04ffff12ff0bff0580ffff04ffff11ff0bffff010180ff808080808080ff0180ff018080

- opd -- disassemble hex to s-expression form.

As 'opd' from the python code.

opd 'ff02ffff01ff02ff02ffff04ff02ffff04ffff0101ffff04ff05ff8080808080ffff04ffff01ff02ffff03ffff15ffff0102ff0b80ffff0105ffff01ff02ff02ffff04ff02ffff04ffff12ff0bff0580ffff04ffff11ff0bffff010180ff808080808080ff0180ff018080'
(a (q 2 2 (c 2 (c (q . 1) (c 5 ())))) (c (q 2 (i (> (q . 2) 11) (q . 5) (q 2 2 (c 2 (c (* 11 5) (c (- 11 (q . 1)) ()))))) 1) 1))

History

This is a second-hand port of chik's klvm tools to rust via the work of ChikMineJP porting to typescript. This would have been a lot harder to get to where it is without prior work mapping out the types of various semi-dynamic things (thanks, ChikMineJP).

Some reasons for doing this are:

  • Chik switched the klvm implementation to rust: klvm_rs, and this code may both pick up speed and track klvm better being in the same language.

  • I wrote a new compiler with a simpler, less intricate structure that should be easier to improve and verify in the future in ocaml: ochiklisp.

  • Also it's faster even in this unoptimized form.

All acceptance tests i've brought over so far work, and more are being added. As of now, I'm not aware of anything that shouldn't be authentic when running these command line tools from klvm_tools in their equivalents in this repository

  • opc

  • opd

  • run

  • brun

  • repl

argparse was ported to javascript and I believe I have faithfully reproduced it as it is used in cmds, so command line parsing should work similarly in all three versions.

The directory structure is expected to be:

src/classic  <-- any ported code with heritage pointing back to
                 the original chik repo.
                
src/compiler <-- a newer compiler (ochiklisp) with a simpler
                 structure.  Select new style compilation by
                 including a `(include *standard-cl-21*)`
                 form in your toplevel `mod` form.

Mac M1

Use cargo build --no-default-features due to differences in how mac m1 and other platforms handle python extensions.

Use with chik-blockchain

# Activate your venv, then
$ maturin develop --release

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distributions

klvm_tools_rs-0.1.44-cp38-abi3-win_amd64.whl (1.3 MB view details)

Uploaded CPython 3.8+ Windows x86-64

klvm_tools_rs-0.1.44-cp38-abi3-musllinux_1_1_x86_64.whl (1.6 MB view details)

Uploaded CPython 3.8+ musllinux: musl 1.1+ x86-64

klvm_tools_rs-0.1.44-cp38-abi3-manylinux_2_28_x86_64.whl (1.4 MB view details)

Uploaded CPython 3.8+ manylinux: glibc 2.28+ x86-64

klvm_tools_rs-0.1.44-cp38-abi3-manylinux_2_28_aarch64.whl (1.5 MB view details)

Uploaded CPython 3.8+ manylinux: glibc 2.28+ ARM64

klvm_tools_rs-0.1.44-cp38-abi3-macosx_11_0_x86_64.whl (1.3 MB view details)

Uploaded CPython 3.8+ macOS 11.0+ x86-64

klvm_tools_rs-0.1.44-cp38-abi3-macosx_11_0_arm64.whl (1.2 MB view details)

Uploaded CPython 3.8+ macOS 11.0+ ARM64

File details

Details for the file klvm_tools_rs-0.1.44-cp38-abi3-win_amd64.whl.

File metadata

File hashes

Hashes for klvm_tools_rs-0.1.44-cp38-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 9ac97fd5de93bd46f1e9c1fde8037c12d83b843e81c463510c86a0a37a6f8f25
MD5 cec343e5b4c24de76eafea3588012795
BLAKE2b-256 b999f431e337d4f3eaa898ccc3e04cf4e112c20809ca9321c5a8462133e79fa8

See more details on using hashes here.

File details

Details for the file klvm_tools_rs-0.1.44-cp38-abi3-musllinux_1_1_x86_64.whl.

File metadata

File hashes

Hashes for klvm_tools_rs-0.1.44-cp38-abi3-musllinux_1_1_x86_64.whl
Algorithm Hash digest
SHA256 add9af1ab3923f976a0590ff3c8ce19b299594cd1e88d323d4c0c0f023b89439
MD5 1b947a189e69155334b56506a962cef2
BLAKE2b-256 f4dc514d7e68f7470dd2641d9016725007ff1b97183880109ab04d50cfcef367

See more details on using hashes here.

File details

Details for the file klvm_tools_rs-0.1.44-cp38-abi3-manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for klvm_tools_rs-0.1.44-cp38-abi3-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 e847a27831f7f9b962f789c88f6b2d0eeecb32f83fa412014930a2fe3ee67f29
MD5 c468feeffe29358d4a343cd1e70908de
BLAKE2b-256 fec5101a2842ff4dce63edf2480e7f6f538cd3fc276e7eead46298dba9597ab0

See more details on using hashes here.

File details

Details for the file klvm_tools_rs-0.1.44-cp38-abi3-manylinux_2_28_aarch64.whl.

File metadata

File hashes

Hashes for klvm_tools_rs-0.1.44-cp38-abi3-manylinux_2_28_aarch64.whl
Algorithm Hash digest
SHA256 3e32e244bf8d96cf0b4156f5258662ec055029eb2e885b03d18d4efbad7f6f10
MD5 3f8a20f7e0d42c5a6e4a748f3f842c47
BLAKE2b-256 f2b5250b462cbbe2d05744f1362515fbd911f71ed14e30846157af18ff7cb914

See more details on using hashes here.

File details

Details for the file klvm_tools_rs-0.1.44-cp38-abi3-macosx_11_0_x86_64.whl.

File metadata

File hashes

Hashes for klvm_tools_rs-0.1.44-cp38-abi3-macosx_11_0_x86_64.whl
Algorithm Hash digest
SHA256 03acb65d4eb6ac6743b007fe54f7fa4a2add140eee448f0e9001788c51d88a3a
MD5 3dde02dd85d8fdd71db25164b6176efa
BLAKE2b-256 f8f38fd2085809044110484a2493d419a36a79311c345bb2102661b8e98134cb

See more details on using hashes here.

File details

Details for the file klvm_tools_rs-0.1.44-cp38-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for klvm_tools_rs-0.1.44-cp38-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 433d56b6208585632391b99d967c6335f101281589d2ae2bef682d3999dfe7ea
MD5 74e7f00929891ad23b09f80ab1618a09
BLAKE2b-256 84d85d89feba5132cba474355a1196c84cf80dcbe1466acaaba90ba173c5291d

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page