lgo Binder Go Report Card

Go (golang) Jupyter Notebook kernel and an interactive REPL

Disclaimer

Since go1.10, this Go kernel has performance issue due to a performance regression in Go tool chain.

Also, this Go kernel can not be built with go1.12 due to another regression in Go tool chain.

Now, the compiler options this kernel relies on are completely broken and I’m not sure when they will fix the regressions. Unfortunately, they don’t plan to fix this in go1.13 as of July 8th 2019. If you are interested in using this kernel, please upvote the bugs. For a while, please use other Go kernels if you want to use the later version of Go with Jupyter notebook.

Medium Post

Features

  • Write and execute Go (golang) interactively like Python.
  • Jupyter Notebook integration
  • Full Go (golang) language spec support. 100% gc (go compiler) compatible.
  • Code completion and inspection in Jupyter Notebooks
  • Display images, HTML, JavaScript, SVG, etc…
  • Currently, lgo is only supported on Linux. But you can use lgo on Mac and Windows with virtual machines or Docker.

Jupyter notebook examples

You can view example notebooks of lgo from Example notebooks on Jupyter nbviewer

If you want to execute these notebooks, you can try these notebooks on your browser without installation from Binder

Try lgo from your browser without installation

Binder

Thanks to binder (mybinder.org), you can try lgo on your browsers with temporary docker containers on binder. Open your temporary Jupyter Notebook from the button above and enjoy lgo.

Quick Start with Docker

  1. Install Docker and Docker Compose.
  2. Clone the respository and run the docker container with docker-compose.
git clone https://github.com/yunabe/lgo.git
> cd lgo/docker/jupyter
> docker-compose up -d
“>

> git clone https://github.com/yunabe/lgo.git
> cd lgo/docker/jupyter
> docker-compose up -d

If you want to use a port other than 8888 on host, update ports config in lgo/docker/jupyter/docker-compose.yaml before running docker-compose up.

  1. Get the URL to open the Jupyter Notebook
docker-compose exec jupyter jupyter notebook list
Currently running servers:
http://0.0.0.0:8888/?token=50dfee7e328bf86e70c234a2f06021e1df63a19641c86676 :: /examples
“>

> docker-compose exec jupyter jupyter notebook list
Currently running servers:
http://0.0.0.0:8888/?token=50dfee7e328bf86e70c234a2f06021e1df63a19641c86676 :: /examples
  1. Open the Jupyter Notebook server with the authentication token above.

Linux/Mac OS

If you are using Linux or Mac OS, you can use start/stop scripts instead. Web browser will open the URL automatically.

./up.sh
# stop server
> ./down.sh
“>

# start server
> ./up.sh
# stop server
> ./down.sh

Install

Prerequisites

Install

  • go get github.com/yunabe/lgo/cmd/lgo && go get -d github.com/yunabe/lgo/cmd/lgo-internal
    • This installs lgo command into your $(go env GOPATH)/bin
  • Set LGOPATH environment variable
    • lgo install will install binaries into the directory specified with LGOPATH.
    • You can use any empty directory with write permission as LGOPATH.
  • Run lgo install
    • This installs std libraries and the internal lgo tool into LGOPATH with specific compiler flags.
    • If lgo install fails, please check install log stored in $LGOPATH/install.log
  • (Optional) Run lgo installpkg [packages] to install third-party packages to LGOPATH
    • You can preinstall third-party packages into LGOPATH.
    • This step is optional. If packages are not preinstalled, lgo installs the packages on the fly.
    • But, installing packages is a heavy and slow process. I recommend you to preinstall packages which you will use in the future with high probability.
    • If lgo installpkg fails, please check the log stored in $LGOPATH/installpkg.log.
    • See go’s manual about the format of [packages] args.
  • Install the kernel configuration to Jupyter Notebook
    • python $(go env GOPATH)/src/github.com/yunabe/lgo/bin/install_kernel
    • Make sure to use the same version of python as you used to install jupyter. For example, use python3 instead of python if you install jupyter with pip3.
  • (Optional) If you want to use lgo with JupyterLab, install a jupyterlab extension for lgo
    • jupyter labextension install @yunabe/lgo_extension
    • This extension adds “Go Format” button to the toolbar in JupyterLab.

Usage: Jupyter Notebook

  • Run jupyter notebook command to start Juyputer Notebook and select “Go (lgo)” from New Notebook menu.
  • To show documents of packages, functions and variables in your code, move the cursor to the identifier you want to inspect and press Shift-Tab.
  • Press Tab to complete code
  • Click Format Go button in the toolbar to format code.
  • lgo works with JupyterLab. To use lgo from JupyterLab, install JupyterLab and run jupyter lab.

Usage: REPL console

You can use lgo from command line with Jupyter Console or build-in REPL mode of lgo

Jupyter Console (Recommended)

Run jupyter console --kernel lgo

In [1]: a, b := 3, 4

In [2]: func sum(x, y int) int {
      :     return x + y
      :     }

In [3]: import "fmt"

In [4]: fmt.Sprintf("sum(%d, %d) = %d", a, b, sum(a, b))
sum(3, 4) = 7

built-in REPL mode

Run lgo run

>> a, b := 3, 4
>>> func sum(x, y int) int {
… return x + y
… }
>>> import ” fmt”>>> fmt.Sprintf(“sum(%d, %d) = %d”, a, b, sum(a, b))
sum(3, 4) = 7
“>

$ lgo run
>>> a, b := 3, 4
>>> func sum(x, y int) int {
...     return x + y
...     }
>>> import "fmt"
>>> fmt.Sprintf("sum(%d, %d) = %d", a, b, sum(a, b))
sum(3, 4) = 7

Tips

go get and lgo

The packages you want to use in lgo must be prebuilt and installed into $LGOPATH by lgo install command. Please make sure to run lgo install after you fetch a new package with go get command.

Update go version

Please run lgo install --clean after you update go version.

lgo install installs prebuilt packages into $LGOPATH. When you update go version, you need to reinstall these prebuilt packages with the newer go because binary formats of prebuilt packages may change in the newer version of go.

Display HTML and images

To display HTML and images in lgo, use _ctx.Display. See the example of _ctx.Display in an example notebook

Cancellation

In lgo, you can interrupt execution by pressing “Stop” button (or pressing I, I) in Jupyter Notebook and pressing Ctrl-C in the interactive shell.

However, as you may know, Go does not allow you to cancel running goroutines with Ctrl-C. Go does not provide any API to cancel specific goroutines. The standard way to handle cancellation in Go today is to use context.Context (Read Go Concurrency Patterns: Context if you are not familiar with context.Context in Go).

lgo creates a special context _ctx on every execution and _ctx is cancelled when the execution is cancelled. Please pass _ctx as a context.Context param of Go libraries you want to cancel. Here is an example notebook of cancellation in lgo.

Memory Management

In lgo, memory is managed by the garbage collector of Go. Memory not referenced from any variables or goroutines is collected and released automatically.

One caveat of memory management in lgo is that memory referenced from global variables are not released automatically when the global variables are shadowed by other global variables with the same names. For example, if you run the following code blocks, the 32MB RAM reserved in [1] is not released after executing [2] and [3] because

  • [2] does not reset the value of b in [1]. It just defines another global variable b with the same name and shadows the reference to the first b.
  • [3] resets b defined in [2]. The memory reserved in [2] will be released after [3]. But the memory reserved in [1] will not be released.

<div class="snippet-clipboard-content position-relative" data-snippet-clipboard-copy-content="[1]
// Assign 32MB ram to b.
b := make([]byte, 1 << 25)
[2]
// This shadows the first b.
b := make([]byte, 1 <

[1]
// Assign 32MB ram to b.
b := make([]byte, 1 << 25)
[2]
// This shadows the first b.
b := make([]byte, 1 << 24)
[3]
// This sets nil to the second b.
b = nil