diff --git a/.bazelignore b/.bazelignore
new file mode 100644
index 000000000..1e107f52e
--- /dev/null
+++ b/.bazelignore
@@ -0,0 +1 @@
+examples
diff --git a/.github/workflows/workflow.yaml b/.github/workflows/workflow.yaml
index bf18c2c22..bc021dd69 100644
--- a/.github/workflows/workflow.yaml
+++ b/.github/workflows/workflow.yaml
@@ -6,11 +6,11 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        os: [ubuntu-latest, macos-10.15]
+        os: [ubuntu-latest, macos-10.15] # TODO: this job does not yet work on more recent macOS (macos-11)
     runs-on: ${{ matrix.os }}
     steps:
-      - uses: actions/checkout@v2
-      - uses: cachix/install-nix-action@v14.1
+      - uses: actions/checkout@v2.4.0
+      - uses: cachix/install-nix-action@v16
         with:
           nix_path: nixpkgs=./nixpkgs.nix
       - name: Configure
@@ -27,3 +27,41 @@ jobs:
             set -euo pipefail
             bazel test //...
           '
+  test-examples:
+    name: Build & Test - Examples
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest] # TODO: this job does not yet work on any version of macOS
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v2.4.0
+      - uses: cachix/install-nix-action@v16
+        with:
+          nix_path: nixpkgs=./nixpkgs.nix
+      - name: Configure
+        env:
+          BUILDBUDDY_API_KEY: ${{ secrets.BUILDBUDDY_API_KEY }}
+        run: |
+          cat >.bazelrc.local <<EOF
+          common --config=ci
+          build --remote_header=x-buildbuddy-api-key="$BUILDBUDDY_API_KEY"
+          EOF
+      - name: Build & test
+        run: |
+          cd examples/toolchains
+          for dir in *; do
+              cd "$dir"
+              echo
+              echo Running $(head -n1 README.md) with Nix
+              nix-shell --command 'bazel run --config=nix :hello'
+              # TODO: all toolchains should run without Nixpkgs
+              cd ..
+          done
+          for dir in cc go; do
+              cd "$dir"
+              echo
+              echo Running $(head -n1 README.md) without Nix
+              bazel run :hello
+              cd ..
+          done
diff --git a/examples/.gitignore b/examples/.gitignore
new file mode 100644
index 000000000..ac51a054d
--- /dev/null
+++ b/examples/.gitignore
@@ -0,0 +1 @@
+bazel-*
diff --git a/examples/toolchains/cc/.bazelrc b/examples/toolchains/cc/.bazelrc
new file mode 100644
index 000000000..ada692625
--- /dev/null
+++ b/examples/toolchains/cc/.bazelrc
@@ -0,0 +1 @@
+build:nix --host_platform=@io_tweag_rules_nixpkgs//nixpkgs/platforms:host
diff --git a/examples/toolchains/cc/BUILD b/examples/toolchains/cc/BUILD
new file mode 100644
index 000000000..c263a2a1b
--- /dev/null
+++ b/examples/toolchains/cc/BUILD
@@ -0,0 +1,6 @@
+load("@rules_cc//cc:defs.bzl", "cc_binary")
+
+cc_binary(
+    name = "hello",
+    srcs = ["hello.cc"],
+)
diff --git a/examples/toolchains/cc/README.md b/examples/toolchains/cc/README.md
new file mode 100644
index 000000000..ec8191ad1
--- /dev/null
+++ b/examples/toolchains/cc/README.md
@@ -0,0 +1,19 @@
+C++ Toolchain Example
+=====================
+
+This is an example C++ project that uses `rules_cc`.
+
+If the Nix package manager is present in the build environment, this example will use Nix to provide the C++ toolchain. Otherwise, it will use the toolchain provided by `rules_cc` and not rely on Nix at all.
+
+# Usage
+
+To run the example with Nix, issue the following command:
+```
+nix-shell --command 'bazel run --config=nix :hello'
+```
+
+To run the example without Nix, make sure you have Bazel installed, and issue the following command:
+```
+bazel run :hello
+```
+This non-Nix example will look for the C++ toolchain on the PATH.
diff --git a/examples/toolchains/cc/WORKSPACE b/examples/toolchains/cc/WORKSPACE
new file mode 100644
index 000000000..94f13d159
--- /dev/null
+++ b/examples/toolchains/cc/WORKSPACE
@@ -0,0 +1,43 @@
+# Replace with http_archive: https://github.com/tweag/rules_nixpkgs/#setup
+local_repository(
+    name = "io_tweag_rules_nixpkgs",
+    path = "../../../",
+)
+
+load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
+
+http_archive(
+    name = "rules_cc",
+    sha256 = "4dccbfd22c0def164c8f47458bd50e0c7148f3d92002cdb459c2a96a68498241",
+    urls = [
+        "https://github.com/bazelbuild/rules_cc/releases/download/0.0.1/rules_cc-0.0.1.tar.gz",
+    ],
+)
+
+load("@io_tweag_rules_nixpkgs//nixpkgs:repositories.bzl", "rules_nixpkgs_dependencies")
+
+rules_nixpkgs_dependencies()
+
+load(
+    "@io_tweag_rules_nixpkgs//nixpkgs:nixpkgs.bzl",
+    "nixpkgs_cc_configure",
+    "nixpkgs_git_repository",
+)
+
+nixpkgs_git_repository(
+    name = "nixpkgs",
+    revision = "21.11",
+    sha256 = "c77bb41cf5dd82f4718fa789d49363f512bb6fa6bc25f8d60902fe2d698ed7cc",
+)
+
+nixpkgs_cc_configure(
+    name = "nixpkgs_config_cc",
+    fail_not_supported = False,
+    repository = "@nixpkgs",
+)
+
+load("@rules_cc//cc:repositories.bzl", "rules_cc_dependencies", "rules_cc_toolchains")
+
+rules_cc_dependencies()
+
+rules_cc_toolchains()
diff --git a/examples/toolchains/cc/hello.cc b/examples/toolchains/cc/hello.cc
new file mode 100644
index 000000000..93c672643
--- /dev/null
+++ b/examples/toolchains/cc/hello.cc
@@ -0,0 +1,6 @@
+#include <iostream>
+
+int main()
+{
+	std::cout << "Hello world!\n";
+}
diff --git a/examples/toolchains/cc/shell.nix b/examples/toolchains/cc/shell.nix
new file mode 100644
index 000000000..8443bdce4
--- /dev/null
+++ b/examples/toolchains/cc/shell.nix
@@ -0,0 +1,6 @@
+{ pkgs ? import (builtins.fetchTarball {
+  url = "https://github.com/NixOS/nixpkgs/archive/21.11.tar.gz";
+  sha256 = "162dywda2dvfj1248afxc45kcrg83appjd0nmdb541hl7rnncf02";
+}) { } }:
+
+pkgs.mkShell { nativeBuildInputs = [ pkgs.bazel_4 ]; }
diff --git a/examples/toolchains/cc_with_deps/.bazelrc b/examples/toolchains/cc_with_deps/.bazelrc
new file mode 100644
index 000000000..ada692625
--- /dev/null
+++ b/examples/toolchains/cc_with_deps/.bazelrc
@@ -0,0 +1 @@
+build:nix --host_platform=@io_tweag_rules_nixpkgs//nixpkgs/platforms:host
diff --git a/examples/toolchains/cc_with_deps/BUILD b/examples/toolchains/cc_with_deps/BUILD
new file mode 100644
index 000000000..ddce225d4
--- /dev/null
+++ b/examples/toolchains/cc_with_deps/BUILD
@@ -0,0 +1,10 @@
+load("@rules_cc//cc:defs.bzl", "cc_binary")
+
+cc_binary(
+    name = "hello",
+    srcs = ["hello.cc"],
+    deps = [
+        "@boost.dev//:boost",
+        "@zlib.dev//:zlib",
+    ],
+)
diff --git a/examples/toolchains/cc_with_deps/README.md b/examples/toolchains/cc_with_deps/README.md
new file mode 100644
index 000000000..56bf07ccc
--- /dev/null
+++ b/examples/toolchains/cc_with_deps/README.md
@@ -0,0 +1,13 @@
+C++ With Dependencies Toolchain Example
+=======================================
+
+This is an example C++ project with dependencies that uses `rules_cc`.
+
+This example uses the Nix package manager to provide C++ dependencies, and as such only works with Nix installed. Demonstrating other methods of providing C++ dependencies is out of scope of this example.
+
+# Usage
+
+To run the example with Nix, issue the following command:
+```
+nix-shell --command 'bazel run --config=nix :hello'
+```
diff --git a/examples/toolchains/cc_with_deps/WORKSPACE b/examples/toolchains/cc_with_deps/WORKSPACE
new file mode 100644
index 000000000..890956363
--- /dev/null
+++ b/examples/toolchains/cc_with_deps/WORKSPACE
@@ -0,0 +1,81 @@
+# Replace with http_archive: https://github.com/tweag/rules_nixpkgs/#setup
+local_repository(
+    name = "io_tweag_rules_nixpkgs",
+    path = "../../../",
+)
+
+load("@io_tweag_rules_nixpkgs//nixpkgs:repositories.bzl", "rules_nixpkgs_dependencies")
+
+rules_nixpkgs_dependencies()
+
+load(
+    "@io_tweag_rules_nixpkgs//nixpkgs:nixpkgs.bzl",
+    "nixpkgs_cc_configure",
+    "nixpkgs_git_repository",
+)
+
+nixpkgs_git_repository(
+    name = "nixpkgs",
+    revision = "21.11",
+    sha256 = "c77bb41cf5dd82f4718fa789d49363f512bb6fa6bc25f8d60902fe2d698ed7cc",
+)
+
+nixpkgs_cc_configure(
+    name = "nixpkgs_config_cc",
+    fail_not_supported = False,
+    repository = "@nixpkgs",
+)
+
+load("@io_tweag_rules_nixpkgs//nixpkgs:nixpkgs.bzl", "nixpkgs_package")
+
+nixpkgs_package(
+    name = "boost",
+    attribute_path = "boost175",
+    repository = "@nixpkgs",
+)
+
+nixpkgs_package(
+    name = "boost.dev",
+    attribute_path = "boost175.dev",
+    build_file_content = """\
+load("@rules_cc//cc:defs.bzl", "cc_library")
+filegroup(
+    name = "include",
+    srcs = glob(["include/**/*.h", "include/**/*.hpp"]),
+    visibility = ["//visibility:public"],
+)
+cc_library(
+    name = "boost",
+    srcs = ["@boost//:lib"],
+    hdrs = [":include"],
+    strip_include_prefix = "include",
+    visibility = ["//visibility:public"],
+)
+""",
+    repository = "@nixpkgs",
+)
+
+nixpkgs_package(
+    name = "zlib",
+    repository = "@nixpkgs",
+)
+
+nixpkgs_package(
+    name = "zlib.dev",
+    build_file_content = """\
+load("@rules_cc//cc:defs.bzl", "cc_library")
+filegroup(
+    name = "include",
+    srcs = glob(["include/**/*.h"]),
+    visibility = ["//visibility:public"],
+)
+cc_library(
+    name = "zlib",
+    srcs = ["@zlib//:lib"],
+    hdrs = [":include"],
+    strip_include_prefix = "include",
+    visibility = ["//visibility:public"],
+)
+""",
+    repository = "@nixpkgs",
+)
diff --git a/examples/toolchains/cc_with_deps/hello.cc b/examples/toolchains/cc_with_deps/hello.cc
new file mode 100644
index 000000000..cdb8fc0da
--- /dev/null
+++ b/examples/toolchains/cc_with_deps/hello.cc
@@ -0,0 +1,8 @@
+#include <iostream>
+#include <boost/filesystem/operations.hpp>
+#include <zlib.h>
+
+int main()
+{
+	std::cout << "Hello world!\n";
+}
diff --git a/examples/toolchains/cc_with_deps/shell.nix b/examples/toolchains/cc_with_deps/shell.nix
new file mode 100644
index 000000000..8443bdce4
--- /dev/null
+++ b/examples/toolchains/cc_with_deps/shell.nix
@@ -0,0 +1,6 @@
+{ pkgs ? import (builtins.fetchTarball {
+  url = "https://github.com/NixOS/nixpkgs/archive/21.11.tar.gz";
+  sha256 = "162dywda2dvfj1248afxc45kcrg83appjd0nmdb541hl7rnncf02";
+}) { } }:
+
+pkgs.mkShell { nativeBuildInputs = [ pkgs.bazel_4 ]; }
diff --git a/examples/toolchains/go/.bazelrc b/examples/toolchains/go/.bazelrc
new file mode 100644
index 000000000..ada692625
--- /dev/null
+++ b/examples/toolchains/go/.bazelrc
@@ -0,0 +1 @@
+build:nix --host_platform=@io_tweag_rules_nixpkgs//nixpkgs/platforms:host
diff --git a/examples/toolchains/go/BUILD b/examples/toolchains/go/BUILD
new file mode 100644
index 000000000..ec0d61796
--- /dev/null
+++ b/examples/toolchains/go/BUILD
@@ -0,0 +1,6 @@
+load("@io_bazel_rules_go//go:def.bzl", "go_binary")
+
+go_binary(
+    name = "hello",
+    srcs = ["hello.go"],
+)
diff --git a/examples/toolchains/go/README.md b/examples/toolchains/go/README.md
new file mode 100644
index 000000000..58f25e71e
--- /dev/null
+++ b/examples/toolchains/go/README.md
@@ -0,0 +1,18 @@
+Go Toolchain Example
+====================
+
+This is an example Go project that uses `rules_go`.
+
+If the Nix package manager is present in the build environment, this example will use Nix to provide the Go toolchain. Otherwise, it will use the toolchain provided by `rules_go` and not rely on Nix at all.
+
+# Usage
+
+To run the example with Nix, issue the following command:
+```
+nix-shell --command 'bazel run --config=nix :hello'
+```
+
+To run the example without Nix, make sure you have Bazel installed, and issue the following command:
+```
+bazel run :hello
+```
diff --git a/examples/toolchains/go/WORKSPACE b/examples/toolchains/go/WORKSPACE
new file mode 100644
index 000000000..93c7a499b
--- /dev/null
+++ b/examples/toolchains/go/WORKSPACE
@@ -0,0 +1,46 @@
+# Replace with http_archive: https://github.com/tweag/rules_nixpkgs/#setup
+local_repository(
+    name = "io_tweag_rules_nixpkgs",
+    path = "../../../",
+)
+
+load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
+
+http_archive(
+    name = "io_bazel_rules_go",
+    sha256 = "2b1641428dff9018f9e85c0384f03ec6c10660d935b750e3fa1492a281a53b0f",
+    urls = [
+        "https://mirror.bazel.build/github.com/bazelbuild/rules_go/releases/download/v0.29.0/rules_go-v0.29.0.zip",
+        "https://github.com/bazelbuild/rules_go/releases/download/v0.29.0/rules_go-v0.29.0.zip",
+    ],
+)
+
+load("@io_bazel_rules_go//go:deps.bzl", "go_rules_dependencies")
+
+go_rules_dependencies()
+
+load("@io_tweag_rules_nixpkgs//nixpkgs:repositories.bzl", "rules_nixpkgs_dependencies")
+
+rules_nixpkgs_dependencies()
+
+load("@io_tweag_rules_nixpkgs//nixpkgs:nixpkgs.bzl", "nixpkgs_git_repository")
+
+nixpkgs_git_repository(
+    name = "nixpkgs",
+    revision = "21.11",
+    sha256 = "c77bb41cf5dd82f4718fa789d49363f512bb6fa6bc25f8d60902fe2d698ed7cc",
+)
+
+load("@io_tweag_rules_nixpkgs//nixpkgs:toolchains/go.bzl", "nixpkgs_go_configure")
+
+nixpkgs_go_configure(
+    fail_not_supported = False,
+    repository = "@nixpkgs",
+    sdk_name = "nix_go",
+)
+
+load("@io_bazel_rules_go//go:deps.bzl", "go_register_toolchains", "go_rules_dependencies")
+
+go_rules_dependencies()
+
+go_register_toolchains(version = "1.17.1")
diff --git a/examples/toolchains/go/hello.go b/examples/toolchains/go/hello.go
new file mode 100644
index 000000000..9423f9c60
--- /dev/null
+++ b/examples/toolchains/go/hello.go
@@ -0,0 +1,7 @@
+package main
+
+import "fmt"
+
+func main() {
+    fmt.Println("Hello world!")
+}
diff --git a/examples/toolchains/go/shell.nix b/examples/toolchains/go/shell.nix
new file mode 100644
index 000000000..8443bdce4
--- /dev/null
+++ b/examples/toolchains/go/shell.nix
@@ -0,0 +1,6 @@
+{ pkgs ? import (builtins.fetchTarball {
+  url = "https://github.com/NixOS/nixpkgs/archive/21.11.tar.gz";
+  sha256 = "162dywda2dvfj1248afxc45kcrg83appjd0nmdb541hl7rnncf02";
+}) { } }:
+
+pkgs.mkShell { nativeBuildInputs = [ pkgs.bazel_4 ]; }
diff --git a/examples/toolchains/python/.bazelrc b/examples/toolchains/python/.bazelrc
new file mode 100644
index 000000000..ada692625
--- /dev/null
+++ b/examples/toolchains/python/.bazelrc
@@ -0,0 +1 @@
+build:nix --host_platform=@io_tweag_rules_nixpkgs//nixpkgs/platforms:host
diff --git a/examples/toolchains/python/BUILD b/examples/toolchains/python/BUILD
new file mode 100644
index 000000000..d102e6f9d
--- /dev/null
+++ b/examples/toolchains/python/BUILD
@@ -0,0 +1,5 @@
+py_binary(
+    name = "hello",
+    srcs = ["hello.py"],
+    main = "hello.py",
+)
diff --git a/examples/toolchains/python/README.md b/examples/toolchains/python/README.md
new file mode 100644
index 000000000..fde786306
--- /dev/null
+++ b/examples/toolchains/python/README.md
@@ -0,0 +1,15 @@
+Python Toolchain Example
+========================
+
+This is an example Python project with modules that uses `rules_python`.
+
+This example uses the Nix package manager to provide Python packages, and as such only works with Nix installed. Demonstrating other methods of providing Python packages is out of scope of this example.
+
+# Usage
+
+To run the example with Nix, issue the following command:
+```
+nix-shell --command 'bazel run --config=nix :hello'
+```
+
+To specify Python version or modules, change the `python3_attribute_path` parameter in the `nixpkgs_python_configure` call in the `WORKSPACE` file.
diff --git a/examples/toolchains/python/WORKSPACE b/examples/toolchains/python/WORKSPACE
new file mode 100644
index 000000000..10e6b4df5
--- /dev/null
+++ b/examples/toolchains/python/WORKSPACE
@@ -0,0 +1,25 @@
+# Replace with http_archive: https://github.com/tweag/rules_nixpkgs/#setup
+local_repository(
+    name = "io_tweag_rules_nixpkgs",
+    path = "../../../",
+)
+
+load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
+load("@io_tweag_rules_nixpkgs//nixpkgs:repositories.bzl", "rules_nixpkgs_dependencies")
+
+rules_nixpkgs_dependencies()
+
+load("@io_tweag_rules_nixpkgs//nixpkgs:nixpkgs.bzl", "nixpkgs_git_repository")
+
+nixpkgs_git_repository(
+    name = "nixpkgs",
+    revision = "21.11",
+    sha256 = "c77bb41cf5dd82f4718fa789d49363f512bb6fa6bc25f8d60902fe2d698ed7cc",
+)
+
+load("@io_tweag_rules_nixpkgs//nixpkgs:nixpkgs.bzl", "nixpkgs_python_configure")
+
+nixpkgs_python_configure(
+    python3_attribute_path = "python39.withPackages(ps: with ps; [ numpy opencv4 ])",
+    repository = "@nixpkgs",
+)
diff --git a/examples/toolchains/python/hello.py b/examples/toolchains/python/hello.py
new file mode 100644
index 000000000..6049744ee
--- /dev/null
+++ b/examples/toolchains/python/hello.py
@@ -0,0 +1,4 @@
+import cv2
+import numpy
+
+print("Hello world!")
diff --git a/examples/toolchains/python/shell.nix b/examples/toolchains/python/shell.nix
new file mode 100644
index 000000000..8443bdce4
--- /dev/null
+++ b/examples/toolchains/python/shell.nix
@@ -0,0 +1,6 @@
+{ pkgs ? import (builtins.fetchTarball {
+  url = "https://github.com/NixOS/nixpkgs/archive/21.11.tar.gz";
+  sha256 = "162dywda2dvfj1248afxc45kcrg83appjd0nmdb541hl7rnncf02";
+}) { } }:
+
+pkgs.mkShell { nativeBuildInputs = [ pkgs.bazel_4 ]; }
diff --git a/nixpkgs/nixpkgs.bzl b/nixpkgs/nixpkgs.bzl
index 278cc31ff..2e0289d46 100644
--- a/nixpkgs/nixpkgs.bzl
+++ b/nixpkgs/nixpkgs.bzl
@@ -1061,7 +1061,16 @@ _nixpkgs_python_toolchain = repository_rule(
     },
 )
 
-_python_nix_file_content = """
+def _python_nix_file_content(attribute_path, bin_path, version):
+    if versions.is_at_least("4.2.0", versions.get()):
+        stub_shebang = """stub_shebang = "#!${{{attribute_path}}}/{bin_path}",""".format(
+            attribute_path = attribute_path,
+            bin_path = bin_path,
+        )
+    else:
+        stub_shebang = ""
+
+    return """
 with import <nixpkgs> {{ config = {{}}; overlays = []; }};
 runCommand "bazel-nixpkgs-python-toolchain"
   {{ executable = false;
@@ -1078,11 +1087,17 @@ runCommand "bazel-nixpkgs-python-toolchain"
         name = "runtime",
         interpreter_path = "${{{attribute_path}}}/{bin_path}",
         python_version = "{version}",
+        {stub_shebang}
         visibility = ["//visibility:public"],
     )
     EOF
   ''
-"""
+""".format(
+        attribute_path = attribute_path,
+        bin_path = bin_path,
+        stub_shebang = stub_shebang,
+        version = version,
+    )
 
 def nixpkgs_python_configure(
         name = "nixpkgs_python_toolchain",
@@ -1140,7 +1155,7 @@ def nixpkgs_python_configure(
         python2_runtime = "@%s_python2//:runtime" % name
         nixpkgs_package(
             name = name + "_python2",
-            nix_file_content = _python_nix_file_content.format(
+            nix_file_content = _python_nix_file_content(
                 attribute_path = python2_attribute_path,
                 bin_path = python2_bin_path,
                 version = "PY2",
@@ -1152,7 +1167,7 @@ def nixpkgs_python_configure(
         python3_runtime = "@%s_python3//:runtime" % name
         nixpkgs_package(
             name = name + "_python3",
-            nix_file_content = _python_nix_file_content.format(
+            nix_file_content = _python_nix_file_content(
                 attribute_path = python3_attribute_path,
                 bin_path = python3_bin_path,
                 version = "PY3",