Skip to content

Latest commit

 

History

History
135 lines (86 loc) · 4.75 KB

readme.md

File metadata and controls

135 lines (86 loc) · 4.75 KB
Raw

Nim-Julia bridge

workflow

Prerequisite

  • Install Julia version 1.5.3 or above. Version 1.6.6 or above is recommended.
  • julia executable must be in your path.
    • By-default, nimjl will use Julia's Sys.BINDIR parent directory as the installation folder of Julia.
    • If you want nimjl to use a specific Julia installation, set the environment variable JULIA_PATH to the root of the installation folder.
  • Run nimble install or nimble develop

After this steps, $JULIA_PATH/include should points to Julia header and $JULIA_PATH/lib should point to libjulia.so

You can also install Julia locally by running nimble install julia, in that case it will install Julia in the third_party folder

Ressources

How to embed Julia w/ C :

Next steps

Julia is mostly oriented towards numerical computing so Arrays are THE most important data structure to support

In-progress

Mostly quality-of-life improvements, especially when handling arrays.

  • Improve Julia Arrays interop. from Nim.
    • Supports complex Arrays
    • map / apply / reduce /fold

Backlog

  • Support Julia chaining syntax
  • Add support for Enum types

Limitations

  • Avoid using global scope for Julia function call. Always have everything inse proc / func. It's good practice anyway

  • Value conversion Nim -> Julia are done by copy.

    • Arrays are an exception to this rule and can be created from buffer / are accessible using a buffer.

  • Value conversion Julia -> Nim s always done by copy

    • When using Arrays you can access the buffer as ptr UncheckedArray of the Julia Arrays with rawData().
    • Using to(seq[T]) or to(Tensor[T]) perform a copyMem of jlArray.rawData() in your seq/Tensor

  • Julia allocated arrays only goes up to 3 dimensions (but Arrays can be allocated in Nim)

  • Linux / WSL supports only

    • Windows dynamic library linking is different than Linux.
    • If you need Windows support, consider opening an issue or a PR :).
    • Otherwise, just use WSL

Examples & tips

Examples

Here is the basic example:

import nimjl
proc main() =
 Julia.init() # Initialize Julia VM. Subsequent call will be ignored
 
 var myval = 4.0'f64
 # Call Julia function "sqrt" and convert the result to a float
 var res = Julia.sqrt(myval).to(float64)
 echo res # 2.0

when isMainModule:
  main()

JlVmExit() seems optionnal. It's present in the C API but not calling it doesn't seem to cause any problem.

Nonetheless, if you use OS resources from Julia it is probably better to call Julia.exit() / JlVmExit() for a clean exit.

Setting up Julia dependency

  • It is now possible to embed Julia files inside a Nim compiled binary to easily distribute Julia code. To make distribution possible, an API to call Pkg.add("...") has also been added with version number easy to specify.
import nimjl

Julia.init:
  Pkg:
    add(name="Polynomials", version="3.0.0")
    add(name="LinearAlgebra")
    add("DSP")
    add(name="Wavelets", version="0.9.4")

  Embed:
    # embed all files with '*.jl' extension in folder ``JuliaToolBox/``
    dir("JuliaToolBox/")
    # embed all files with '*.jl' extension in the folder of he source file (at compilation) i.e. ``getProjectPath()`` 
    thisDir()
    # embed specific file; path should be relative to ``getProjectPath()``
    file("localfile.jl")

Note that the order of the file matters. See examples/ex09_embed_file.nim for a concrete example.

Take a look at tests/ or examples/ folder for typical examples.

  • You can use Pkg: activate() to setup a virtual env
    • Alternatively, you can embed a Julia file that setup your environment and dependencies and embed it first.
    • Because files are evaluated in the order they are embedded, it will deterine the env for all the other files.

Debugging

  • Most error will come from incorrect type passed between Julia and Nim. Check function interface and return type first.

  • If you have random segfault that are non-reproductible, that may be a cause of the Julia GC cleaning memory that Nim uses. Consider using jlGcRoot.

  • If you do not work with fixed version package for Julia, you are at risk of code breaking when packages are updated / upgraded.

License

This project is released under MIT License.