org-nix-shell

org-nix-shell copied to clipboard

#+html:

#+html:

org-nix-shell

#+html:

Buffer-local nix-shell environments in org-mode.

#+html: #+html:

Use nix shells directly in org-mode source blocks. =org-nix-shell= works by seamlessly inheriting a nix shell environment using [[https://direnv.net/][direnv]] before executing org-babel source blocks.

• Quickstart

#+begin_src org ,#+name: my-shell ,#+begin_src nix { pkgs ? import {} }: pkgs.mkShell { buildInputs = [ pkgs.hello ]; } ,#+end_src

,#+begin_src sh :nix-shell "my-shell" hello # use 'hello' from 'my-shell' ,#+end_src #+end_src

Enable =org-nix-shell-mode= and evaluate or export the buffer. See [[file:demo.org][demo.org]] with examples for Python and C.

• Usage

First create a nix shell in a named source block.

#+begin_src org ,#+name: ,#+begin_src nix { pkgs ? import {} }: pkgs.mkShell { buildInputs = with pkgs; [ python3 ]; } ,#+end_src #+end_src

Source blocks with a =:nix-shell = header argument will use the nix shell environment specified by ==; where == is the corresponding named source block in the same buffer. Other source blocks should be unaffected and you can explicitly set =:nix-shell 'nil= to not depend on any nix shell.

To use the nix shell above we can do:

#+begin_src org ,#+begin_src python :nix-shell print("hello from python") ,#+end_src #+end_src

There are three ways to configure the =:nix-shell= header property; also see [[https://orgmode.org/manual/Using-Header-Arguments.html][Using Header Arguments (The Org Manual)]]. In increasing order of priority they are:

** Buffer Scope

#+begin_src org ,#+property: header-args: :nix-shell #+end_src

** Subtree Scope

#+begin_src org ,* sample header :PROPERTIES: :header-args: :nix-shell :END: #+end_src

** Source Block Scope

#+begin_src org ,#+begin_src python :nix-shell print("hello from python") ,#+end_src #+end_src

• Installation

Make sure [[https://nixos.org/manual/nix/stable/command-ref/nix-shell][nix-shell]] and [[https://direnv.net/][direnv]] is installed on your system ([[https://github.com/nix-community/nix-direnv#installation][nix-community/nix-direnv#Installation]]).

** Manual

First, put [[file:org-nix-shell.el][org-nix-shell.el]] in your load path.

#+begin_src emacs-lisp (require 'org-nix-shell) (add-hook 'org-mode-hook 'org-nix-shell-mode) #+end_src

** Melpa

#+begin_src emacs-lisp (use-package org-nix-shell :hook (org-mode . org-nix-shell-mode)) #+end_src

** Straight

#+begin_src elisp (use-package org-nix-shell :straight '(org-nix-shell :type git :host github :repo "AntonHakansson/org-nix-shell") :hook (org-mode . org-nix-shell-mode)) #+end_src

• Customization

=M-x customize-group org-nix-shell= to see available customizable variables.