Merge pull request #50 from SciNim/devel

Devel

Author: Clonkk

nimjl.nimble

@@ -1,6 +1,6 @@
 # Nimjl
 # Licensed and distributed under MIT license (license terms in the root directory or at http://opensource.org/licenses/MIT).
-version       = "0.8.0"
+version       = "0.8.2"
 author        = "Regis Caillaud"
 description   = "Nim Julia bridge"
 license       = "MIT"

readme.md

@@ -49,6 +49,8 @@ Mostly quality-of-life improvements, especially when handling arrays.
 
 ## 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.
 
@@ -63,24 +65,33 @@ Mostly quality-of-life improvements, especially when handling arrays.
   * If you need Windows support, consider opening an issue or a PR :).
   * Otherwise, just use WSL
 
-# Examples
+# Examples & tips
+
+## Examples
 
 Here is the basic example:
 ```nim
 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
 
-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**.
+* 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**.
 
 ```nim
 import nimjl
@@ -100,10 +111,25 @@ Julia.init:
     # embed specific file; path should be relative to ``getProjectPath()``
     file("localfile.jl")
 ```
-See examples/ex09_embed_file.nim for a concrete example 
+
+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.