Commit 4f7417b9 authored by Ludovic Courtès's avatar Ludovic Courtès
Browse files

Update README.

* Update.
parent 07724eab
......@@ -10,77 +10,128 @@ Version =0.0.1=
#+html: <img src="" />
#+html: <img src="" />
** Project goal
*** Jupyter
With classic way, /Jupyter/ use the system software environment to get
kernel, this is a problem when we try to reproduce experimentation for
specific software version. This is the same issue when we share
notebook, it's difficult to recreate the same software environment.
** Motivation
Some people use /Docker/ for share notebook, but /guix-kernel/ try
another way.
[[][Jupyter Notebook]] provides a way for scientists and engineers to share
code along with a narrative providing context and explanations. It is
no wonder that Jupyter Notebook is now regarded as a tool of choice for
scientists concerned with /reproducible science/ who wish to share their
*** Another way
The guix-kernel use /GNU Guix/ and containers to set multi software
environment in same /Jupyter/ notebook, and it's able to use other
Jupyter kernel to eval code in different language.
Unfortunately a notebook is a program, and Jupyter leaves it up to you
to set up the right execution environment for the program. The notebook
itself does not say what its dependencies are. I wrote my notebook with
Python 3 and SciPy; if you run it on Python 2 or SciPy is missing on
your system, it won’t run; if you have different a different version of
SciPy than the one I have, perhaps it will run, but provide different
#+html: <img src="doc/images/graph.png" />
Guix-Jupyter aims to address this by supporting:
The first container are create at kernel startup with name "default"
and the user software environment, it's possible to create others
container with magic cells.
1. Self-contained notebooks that describe their execution environment;
2. Automatic and reproducible deployment of that environment through
[[][GNU Guix]];
3. Execution of the code in a isolated environment, a “container”.
** How to use it
Guix-kernel use magic cells format like:
#+BEGIN_SRC scheme
;;guix <command> <args>
** Usage
A notebook file demo are available in source directory
Guix-Jupyter is implemented as a /Jupyter kernel/. Thus, when running
`jupyter notebook`, you will select the “Guix” kernel instead of
selecting, say, the “Python 3” kernel. This kernel delegates deployment
to Guix itself, so Guix must be installed on your machine and its build
daemon must up and running. Currently support for Linux unprivileged
user namespaces is also required (see below).
*** Environment
The =environment= command must be use to create new container with
specific software environment.
*** Environments
From there on, annotations, aka. /magics/, allow you to create and use
environments. The general syntax is:
#+BEGIN_SRC scheme
;;guix environment <env-name> <- <packages ...>
;;guix environment <env-name> <- <package> …
/This command can take few minutes./
So to create an environment call `python` containing the IPython kernel,
Matplotlib, and NumPy, you would write this in a cell:
ENV-NAME is the container id. PACKAGES is list of guix packages to put
in software environment.
#+begin_src scheme
;;guix environment my-python <- python-ipykernel python-matplotlib python-numpy
#+BEGIN_SRC scheme
;;guix environment my-env <- guile@2.2.2 jupyter-guile-kernel guile-commonmark
(Tab completion on package names is supported.) By default, subsequent
cells will be executed by the IPython kernel in this environment.
*** Run
Run command must be use to eval /Guile sexp/ in existing container.
You can create as many environments as you like in a notebook. You can
then switch to a specific environment in a cell by starting it with a
line like this:
#+BEGIN_SRC scheme
;;guix run <env>
#+begin_src scheme
;;guix environment <env-name>
*** Kernel
Kernel command must be use to eval code in an other Jupyter kernel.
*** Built-in Guile kernel
#+BEGIN_SRC scheme
;;guix kernel <env-name> <kernel-name>
Guix-Jupyter has a built-in kernel for [[][GNU Guile]] programming. To use
it, simply create an environment that contains the =guile= executable:
#+begin_src scheme
;;guix environment my-guile-env <- guile@2.2 guile-picture-language guile-minikanren
*** Isolation
The kernels select through =;;guix environment= annotations are spawned
/in a container/, isolated from other processes on the machine and from
the network (thus support for Linux /unprivileged user namespaces/ is
required). This ensures that the notebook results do not depend on
anything but the environments it specifies and the code it contains.
It’s also nice from a security standpoint.
*** Downloads
Since kernels run without access to the network, we have an obvious
problem: how to we populate the environment with things that are not
software packages, such as data files?
*/!\* /This feature have been tested only with guile-kernel and
To address that, Guix-Jupyter provides a =download= magic that can be
used like this:
#+begin_src scheme
;;guix download e831b3a86091496cdba720411f9748de81507798f6130adeaef872d206e1b057
Here we specify the URL of a file and its expected SHA256 hash. The
file is downloaded, unless it has already been downloaded before, and is
made available in the current environment.
The download mechanism ensures that the hash matches, again for the sake
of reproducibility.
*** Pinning
It is usually desirable to /pin/ Guix to a specific revision to ensure
that the notebook will keep behaving the same at any point in time,
regardless of changes to the Guix package collection.
To do that, run this magic in a cell:
#+begin_src scheme
;;guix pin COMMIT
… where /COMMIT/ is the commit ID (hexadecimal string) of the Guix
commit you want to use.
If you’re unsure what commit to use, run =guix describe= on your machine
or navigate the [[][Guix Data Service]] to find out which Guix revisions
contains the package versions you need.
** Installation
*** Guix
Build package.
This is how you’d build Guix-Jupyter with Guix:
#+BEGIN_SRC shell
# Clone repo
$ git clone
......@@ -90,23 +141,26 @@ $ cd guix-kernel
$ guix build -f environment.scm
Install on current environment.
You can install it with:
#+BEGIN_SRC shell
$ guix package -f environment.scm
Create environment with /Jupyter/.
To start Jupyter in an environment that contains Guix-Jupyter, run:
#+BEGIN_SRC shell
$ guix environment --ad-hoc jupyter -l environment.scm
guix environment --ad-hoc jupyter -l environment.scm guile-git guile \
-- jupyter notebook
** Contributing
*** Devel environment
*** Development environment
#+BEGIN_SRC shell
$ guix environment -l environement.scm
*** Developer
*** Developers
Made with *λ* by the *GNU Guix community*.
Based on *[[][Guile-kernel]]*.
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment