From e8a69cb498edc9425cdcd770baed976ae4c0c4a4 Mon Sep 17 00:00:00 2001
From: Alexander Bantyev <balsoft@balsoft.ru>
Date: Mon, 18 May 2020 14:09:40 +0300
Subject: [PATCH 1/7] Switch to nix pipelines

- Remove old pipelines
- Run nix pipelines on a private runner
---
 .gitlab-ci.yml | 399 ++++++++-----------------------------------------
 1 file changed, 60 insertions(+), 339 deletions(-)

diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index 565c2cdf1..cc87b822f 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -1,105 +1,19 @@
 # TODO: remove this as submodules aren't used anymore.
 variables:
   GIT_SUBMODULE_STRATEGY: recursive
-  build_binary_script: "./scripts/distribution/generic/build.sh"
-  package_binary_script: "./scripts/distribution/generic/package.sh"
   LIGO_REGISTRY_IMAGE_BASE_NAME: "${CI_PROJECT_PATH}/${CI_PROJECT_NAME}"
   WEBIDE_IMAGE_NAME: "registry.gitlab.com/${CI_PROJECT_PATH}/ligo_webide"
 
 stages:
-  - test
-  - build_and_package_binaries
-  - build_docker
-  - build_and_deploy
-  - ide-unit-test
-  - ide-build
-  - ide-e2e-test
-  - ide-deploy
-  - nix
-  - nix-push
+  - build
+  - push
   - versioning
 
-# TODO provide sensible CI for master
-dont-merge-to-master:
-  stage: test
-  script:
-    - "false"
-  only:
-    - master
-
-.build_binary: &build_binary
-  stage: test # To run in sequence and save CPU usage, use stage: build_and_package_binaries
-  script:
-    - export COMMIT_DATE="$(git show --no-patch --format=%ci)"
-    - $build_binary_script "$target_os_family" "$target_os" "$target_os_version"
-    - $package_binary_script "$target_os_family" "$target_os" "$target_os_version"
-  artifacts:
-    paths:
-      - dist/package/**/*
-
-.website_build: &website_build
-  stage: build_and_deploy
-  image: node:12
-  dependencies:
-    - build-and-package-debian-9
-    - build-and-package-debian-10
-    - build-and-package-ubuntu-18-04
-    - build-and-package-ubuntu-19-10
-  before_script:
-    - export COMMIT_DATE="$(git show --no-patch --format=%ci)"
-    - export TERM=dumb
-    - scripts/install_native_dependencies.sh
-    - scripts/install_opam.sh # TODO: or scripts/install_build_environment.sh ?
-    - export PATH="/usr/local/bin${PATH:+:}${PATH:-}"
-    - eval $(opam config env)
-    - scripts/setup_switch.sh
-    - eval $(opam config env)
-    - scripts/setup_repos.sh
-
-    # install deps for internal documentation
-    - scripts/install_vendors_deps.sh
-    - opam install -y odoc
-    - scripts/build_ligo_local.sh
-
-    # build with odoc
-    - dune build @doc
-
-    # copy .deb packages into website
-    - find dist -name \*.deb -exec sh -c 'cp {} gitlab-pages/website/static/deb/ligo_$(basename $(dirname {})).deb' \;
-
-    # yarn
-    - cd gitlab-pages/website
-    - yarn install
-  script:
-    - yarn build
-    # move internal odoc documentation to the website folder
-    - mv ../../_build/default/_doc/_html/ build/odoc
-  after_script:
-    - cp -r gitlab-pages/website/build public    
-    - cp -r gitlab-pages/website/sitemap.xml public/sitemap.xml
-  artifacts:
-    paths:
-      - public
-
-.docker: &docker
+.docker-image: &docker-image
   image: docker:19.03.5
   services:
     - docker:19.03.5-dind
 
-.before_script: &before_script
-  before_script:
-    # Install dependencies
-    # rsync is needed by opam to sync a package installed from a local directory with the copy in ~/.opam
-    - export COMMIT_DATE="$(git show --no-patch --format=%ci)"
-    - export TERM=dumb
-    - scripts/install_native_dependencies.sh
-    - scripts/install_opam.sh # TODO: or scripts/install_build_environment.sh ?
-    - export PATH="/usr/local/bin${PATH:+:}${PATH:-}"
-    - eval $(opam config env)
-    - scripts/setup_switch.sh
-    - eval $(opam config env)
-    - scripts/setup_repos.sh
-
 version_scheduled_job:
   stage: versioning
   script:
@@ -107,222 +21,16 @@ version_scheduled_job:
   only:
     - schedules
 
-local-dune-job:
-  <<: *before_script
-  stage: test
-  script:
-    - scripts/install_vendors_deps.sh
-    - scripts/build_ligo_local.sh
-    - dune runtest
-    - make coverage
-  artifacts:
-    paths:
-      - _coverage_all
-  only:
-    - merge_requests
-    - dev
-    - tags
-    - triggers
-    - /^.*-run-dev$/
-
-# Run a docker build without publishing to the registry
-build-current-docker-image:
-  stage: build_docker
-  dependencies:
-    - build-and-package-debian-10
-  <<: *docker
-  script:
-    - export COMMIT_DATE="$(git show --no-patch --format=%ci)"
-    - sh scripts/build_docker_image.sh next
-    - sh scripts/test_cli.sh
-  only:
-    - merge_requests
-
-# When a MR/PR is merged to dev
-# take the previous build and publish it to Docker Hub
-build-and-publish-latest-docker-image:
-  stage: build_and_deploy
-  <<: *docker
-  dependencies:
-    - build-and-package-debian-10
-  script:
-    - sh scripts/build_docker_image.sh $(if test "$CI_COMMIT_REF_NAME" = "dev"; then echo next; else echo next-attempt; fi)
-    - sh scripts/test_cli.sh
-    - echo ${LIGO_REGISTRY_PASSWORD} | docker login -u ${LIGO_REGISTRY_USER} --password-stdin
-    - docker push ${LIGO_REGISTRY_IMAGE_BUILD:-ligolang/ligo}:$(if test "$CI_COMMIT_REF_NAME" = "dev"; then echo next; else echo next-attempt; fi)
-  rules:
-    # Only deploy docker when from the dev branch AND on the canonical ligolang/ligo repository
-    - if: '$CI_COMMIT_REF_NAME =~ /^(dev|.*-run-dev)$/ && $CI_PROJECT_PATH == "ligolang/ligo"'
-      when: always
-
-# It'd be a good idea to generate those jobs dynamically,
-# based on desired targets
-build-and-package-debian-9:
-  <<: *docker
-  # To run in sequence and save CPU usage, use stage: build_and_package_binaries
-  stage: test
-  variables:
-    target_os_family: "debian"
-    target_os: "debian"
-    target_os_version: "9"
-  <<: *build_binary
-  only:
-    - dev
-    - tags
-    - /^.*-run-dev$/
-
-build-and-package-debian-10:
-  <<: *docker
-  # To run in sequence and save CPU usage, use stage: build_and_package_binaries
-  stage: test
-  variables:
-    target_os_family: "debian"
-    target_os: "debian"
-    target_os_version: "10"
-  <<: *build_binary
-  # this one is merge_requests and dev, because the debian 10 binary
-  # is used for build-current-docker-image and for
-  # build-and-publish-latest-docker-image
-  only:
-    - merge_requests
-    - dev
-    - tags
-    - /^.*-run-dev$/
-
-build-and-package-ubuntu-18-04:
-  <<: *docker
-  # To run in sequence and save CPU usage, use stage: build_and_package_binaries
-  stage: test
-  variables:
-    target_os_family: "debian"
-    target_os: "ubuntu"
-    target_os_version: "18.04"
-  <<: *build_binary
-  only:
-    - dev
-    - tags
-    - /^.*-run-dev$/
-
-build-and-package-ubuntu-19-10:
-  <<: *docker
-  # To run in sequence and save CPU usage, use stage: build_and_package_binaries
-  stage: test
-  variables:
-    target_os_family: "debian"
-    target_os: "ubuntu"
-    target_os_version: "19.10"
-  <<: *build_binary
-  only:
-    - dev
-    - tags
-    - /^.*-run-dev$/
-
-# Pages are deployed from dev, be careful not to override 'next'
-# in case something gets merged into 'dev' while releasing.
-pages:
-  <<: *website_build
-  rules:
-    - if: '$CI_COMMIT_REF_NAME == "dev" && $CI_PROJECT_PATH == "ligolang/ligo"'
-      when: always
-
-pages-attempt:
-  <<: *website_build
-  rules:
-    - if: '$CI_COMMIT_REF_NAME =~ /^.*-run-dev$/ && $CI_PROJECT_PATH == "ligolang/ligo"'
-      when: always
-
-# WEBIDE jobs
-
-run-webide-unit-tests:
-  stage: ide-unit-test
-  dependencies:
-    - build-and-package-debian-10
-  image: node:12-buster
-  script:
-    - mv $(realpath dist/package/debian-10/*.deb) ligo_deb10.deb
-    - apt-get update && apt-get -y install libev-dev perl pkg-config libgmp-dev libhidapi-dev m4 libcap-dev bubblewrap rsync
-    - dpkg -i ligo_deb10.deb
-    - cd tools/webide/packages/server
-    - npm ci
-    - export LIGO_CMD=/bin/ligo && npm run test
-  rules:
-    - if: '$TAG_JOB != "true"'
-      changes:
-        - tools/webide/**
-      when: always
-
-build-publish-ide-image:
-  stage: build_and_deploy
-  <<: *docker
-  script:
-    - ls -F
-    - find dist/
-    - find dist/package/ -name '*ligo_*deb'
-    - mv $(realpath dist/package/debian-10/*.deb) tools/webide/ligo_deb10.deb
-    - cp -r src/test/examples tools/webide/packages/client/examples
-    - cd tools/webide
-    - echo "${CI_BUILD_TOKEN}" | docker login -u gitlab-ci-token --password-stdin registry.gitlab.com
-    - >
-      docker build
-      -t "${WEBIDE_IMAGE_NAME}:${CI_COMMIT_SHORT_SHA}"
-      --build-arg GIT_TAG="${CI_COMMIT_SHA}"
-      --build-arg GIT_COMMIT="${CI_COMMIT_SHORT_SHA}"
-      --build-arg EXAMPLES_DIR_SRC=packages/client/examples
-      .
-    - docker push "${WEBIDE_IMAGE_NAME}:${CI_COMMIT_SHORT_SHA}"
-  rules:
-    - if: '$TAG_JOB != "true"'
-      changes:
-        - tools/webide/**
-      when: always
-      if: '$CI_COMMIT_REF_NAME == "dev"'
-      when: always
-
-run-webide-e2e-tests:
-  stage: ide-e2e-test
-  <<: *docker
-  image: tmaier/docker-compose
-  script:
-    - cd tools/webide/packages/e2e
-    - export WEBIDE_IMAGE="${WEBIDE_IMAGE_NAME}:${CI_COMMIT_SHORT_SHA}"
-    - docker-compose run e2e
-  rules:
-    - if: '$TAG_JOB != "true"'
-      changes:
-        - tools/webide/**
-      when: always
-      if: '$CI_COMMIT_REF_NAME == "dev"'
-      when: always
-
-deploy-handoff:
-  # Handoff deployment duties to private repo
-  stage: ide-deploy
-  variables:
-    IDE_DOCKER_IMAGE: "registry.gitlab.com/${CI_PROJECT_PATH}/ligo_webide"
-    LIGO_COMMIT_REF_NAME: "${CI_COMMIT_SHORT_SHA}"
-  trigger: ligolang/ligo-webide-deploy
-  rules:
-    - if: '$CI_COMMIT_REF_NAME == "dev"'
-      when: always
-
-
-##### The following jobs will replace the ones above! #####
-# TODO: add jobs for deploying the website, build a docker image and deploy it
-
 .prepare_nix: &prepare_nix
-  image: nixos/nix:latest
+  tags:
+    - nix
   before_script:
-    - nix-env -f channel:nixos-unstable -iA gnutar gitMinimal cachix
-    - export COMMIT_DATE="$(git show --no-patch --format=%ci)"
-    - echo "sandbox = true" > /etc/nix/nix.conf
-    # A temporary caching solution
-    - cachix use balsoft
-    # TODO Don't upload everything, use a post-build-hook to only upload what can't be substituted
-    - cachix push -w balsoft &
+    - find "$CI_PROJECT_DIR" -path "$CI_PROJECT_DIR/.git" -prune -o "(" -type d -a -not -perm -u=w ")" -exec chmod --verbose u+w {} ";"
+    - nix-env -f channel:nixos-unstable -iA gnutar gitMinimal
 
 # The binary produced is useless by itself
-binary-nix:
-  stage: nix
+binary:
+  stage: build
   <<: *prepare_nix
   only:
     - merge_requests
@@ -331,8 +39,8 @@ binary-nix:
   script:
     - nix-build nix -A ligo-bin
 
-doc-nix:
-  stage: nix
+doc:
+  stage: build
   <<: *prepare_nix
   only:
     - merge_requests
@@ -340,13 +48,13 @@ doc-nix:
     - /^.*-run-dev$/
   script:
     - nix-build nix -A ligo-doc
-    - cp -Lr result/share/doc result-doc
+    - cp -Lr --no-preserve=mode,ownership,timestamps result/share/doc .
   artifacts:
     paths:
-      - result-doc
+      - doc
 
-test-nix:
-  stage: nix
+test:
+  stage: build
   <<: *prepare_nix
   only:
     - merge_requests
@@ -354,14 +62,14 @@ test-nix:
     - /^.*-run-dev$/
   script:
     - nix-build nix -A ligo-coverage
-    - cp -Lr result/share/coverage result-coverage
+    - cp -Lr --no-preserve=mode,ownership,timestamps result/share/coverage .
   artifacts:
     paths:
-      - result-coverage
+      - coverage
 
 # FIXME For some reason, e2e tests can't build on CI.
-.webide-e2e-nix:
-  stage: nix
+.webide-e2e:
+  stage: build
   <<: *prepare_nix
   rules:
     - changes:
@@ -372,8 +80,8 @@ test-nix:
   script:
     - nix-build nix -A ligo-editor.e2e
 
-docker-nix:
-  stage: nix
+docker:
+  stage: build
   only:
     - merge_requests
     - dev
@@ -386,13 +94,13 @@ docker-nix:
     paths:
       - ligo.tar.gz
 
-docker-push-nix:
-  stage: nix-push
-  <<: *docker
+docker-push:
+  stage: push
+  <<: *docker-image
   dependencies:
-    - docker-nix
+    - docker
   needs:
-    - docker-nix
+    - docker
   rules:
     # Only deploy docker when from the dev branch AND on the canonical ligolang/ligo repository
     - if: '$CI_COMMIT_REF_NAME =~ /^(dev|.*-run-dev)$/ && $CI_PROJECT_PATH == "ligolang/ligo"'
@@ -400,12 +108,12 @@ docker-push-nix:
   script:
     - echo ${LIGO_REGISTRY_PASSWORD} | docker login -u ${LIGO_REGISTRY_USER} --password-stdin
     - docker load -i=./ligo.tar.gz
-    - export LIGO_REGISTRY_FULL_NAME=${LIGO_REGISTRY_IMAGE_BUILD:-ligolang/ligo}:$(if test "$CI_COMMIT_REF_NAME" = "dev"; then echo next-nix; else echo next-attempt-nix; fi)
+    - export LIGO_REGISTRY_FULL_NAME=${LIGO_REGISTRY_IMAGE_BUILD:-ligolang/ligo}:$(if test "$CI_COMMIT_REF_NAME" = "dev"; then echo next; else echo next-attempt; fi)
     - docker tag ligo "${LIGO_REGISTRY_FULL_NAME}"
     - docker push "${LIGO_REGISTRY_FULL_NAME}"
 
-webide-docker-nix:
-  stage: nix
+webide-docker:
+  stage: build
   only:
     - merge_requests
     - dev
@@ -419,13 +127,13 @@ webide-docker-nix:
       - webide.tar.gz
 
 
-webide-push-nix:
-  stage: nix-push
-  <<: *docker
+webide-push:
+  stage: push
+  <<: *docker-image
   dependencies:
-    - webide-docker-nix
+    - webide-docker
   needs:
-    - webide-docker-nix
+    - webide-docker
   rules:
     # Only deploy docker when from the dev branch AND on the canonical ligolang/ligo repository
     - if: '$CI_COMMIT_REF_NAME =~ /^(dev|.*-run-dev)$/ && $CI_PROJECT_PATH == "ligolang/ligo"'
@@ -433,33 +141,46 @@ webide-push-nix:
   script:
     - echo "${CI_BUILD_TOKEN}" | docker login -u gitlab-ci-token --password-stdin registry.gitlab.com
     - docker load -i=./webide.tar.gz
-    - docker tag ligo-editor "${WEBIDE_IMAGE_NAME}:nix${CI_COMMIT_SHORT_SHA}"
-    - docker push "${WEBIDE_IMAGE_NAME}:nix${CI_COMMIT_SHORT_SHA}"
+    - docker tag ligo-editor "${WEBIDE_IMAGE_NAME}:${CI_COMMIT_SHORT_SHA}"
+    - docker push "${WEBIDE_IMAGE_NAME}:${CI_COMMIT_SHORT_SHA}"
 
-static-binary-nix:
-  stage: nix
+static-binary:
+  stage: build
   <<: *prepare_nix
   only:
+    - merge_requests
     - dev
     - /^.*-run-dev$/
   script:
     - nix-build nix -A ligo-static
     # Check that the binary is truly static and has 0 dependencies
     - test $(nix-store -q --references ./result | wc -l) -eq 0
-    - cp -Lr result/bin result-static
+    - cp -L result/bin/ligo ligo
+    - chmod +rwx ligo
   artifacts:
     paths:
-      - result-static
+      - ligo
 
-website-nix:
-  stage: nix
+.website: &website
+  stage: build
   <<: *prepare_nix
-  only:
-    - dev
-    - /^.*-run-dev$/
   script:
     - nix-build nix -A ligo-website
-    - cp -Lr result/ result-website
+    - cp -Lr --no-preserve=mode,ownership,timestamps result/ public
   artifacts:
     paths:
-      - result-website
+      - public
+
+pages:
+  stage: build
+  <<: *website
+  rules:
+    - if: '$CI_COMMIT_REF_NAME == "dev" && $CI_PROJECT_PATH == "ligolang/ligo"'
+      when: always
+
+pages-attempt:
+  stage: build
+  <<: *website
+  only:
+    - merge_requests
+    - /^.*-run-dev$/

From f970a9a536fe1bd7be97b8bd85c319207b7d566e Mon Sep 17 00:00:00 2001
From: Alexander Bantyev <balsoft@balsoft.ru>
Date: Wed, 20 May 2020 15:33:44 +0300
Subject: [PATCH 2/7] Use extends instead of anchors in gitlab-ci.yml

---
 .gitlab-ci.yml | 44 +++++++++++++++++---------------------------
 1 file changed, 17 insertions(+), 27 deletions(-)

diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index cc87b822f..eee6f2105 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -9,7 +9,8 @@ stages:
   - push
   - versioning
 
-.docker-image: &docker-image
+.docker-image:
+  stage: push
   image: docker:19.03.5
   services:
     - docker:19.03.5-dind
@@ -21,7 +22,8 @@ version_scheduled_job:
   only:
     - schedules
 
-.prepare_nix: &prepare_nix
+.nix:
+  stage: build
   tags:
     - nix
   before_script:
@@ -30,8 +32,7 @@ version_scheduled_job:
 
 # The binary produced is useless by itself
 binary:
-  stage: build
-  <<: *prepare_nix
+  extends: .nix
   only:
     - merge_requests
     - dev
@@ -40,8 +41,7 @@ binary:
     - nix-build nix -A ligo-bin
 
 doc:
-  stage: build
-  <<: *prepare_nix
+  extends: .nix
   only:
     - merge_requests
     - dev
@@ -54,8 +54,7 @@ doc:
       - doc
 
 test:
-  stage: build
-  <<: *prepare_nix
+  extends: .nix
   only:
     - merge_requests
     - dev
@@ -69,8 +68,7 @@ test:
 
 # FIXME For some reason, e2e tests can't build on CI.
 .webide-e2e:
-  stage: build
-  <<: *prepare_nix
+  extends: .nix
   rules:
     - changes:
         - tools/webide/**
@@ -81,12 +79,11 @@ test:
     - nix-build nix -A ligo-editor.e2e
 
 docker:
-  stage: build
+  extends: .nix
   only:
     - merge_requests
     - dev
     - /^.*-run-dev$/
-  <<: *prepare_nix
   script:
     - nix-build nix -A ligo-docker
     - cp -L result ligo.tar.gz
@@ -95,8 +92,7 @@ docker:
       - ligo.tar.gz
 
 docker-push:
-  stage: push
-  <<: *docker-image
+  extends: .docker-image
   dependencies:
     - docker
   needs:
@@ -113,12 +109,11 @@ docker-push:
     - docker push "${LIGO_REGISTRY_FULL_NAME}"
 
 webide-docker:
-  stage: build
+  extends: .nix
   only:
     - merge_requests
     - dev
     - /^.*-run-dev$/
-  <<: *prepare_nix
   script:
     - nix-build nix -A ligo-editor-docker
     - cp -L result webide.tar.gz
@@ -128,8 +123,7 @@ webide-docker:
 
 
 webide-push:
-  stage: push
-  <<: *docker-image
+  extends: .docker-image
   dependencies:
     - webide-docker
   needs:
@@ -145,8 +139,7 @@ webide-push:
     - docker push "${WEBIDE_IMAGE_NAME}:${CI_COMMIT_SHORT_SHA}"
 
 static-binary:
-  stage: build
-  <<: *prepare_nix
+  extends: .nix
   only:
     - merge_requests
     - dev
@@ -161,9 +154,8 @@ static-binary:
     paths:
       - ligo
 
-.website: &website
-  stage: build
-  <<: *prepare_nix
+.website:
+  extends: .nix
   script:
     - nix-build nix -A ligo-website
     - cp -Lr --no-preserve=mode,ownership,timestamps result/ public
@@ -172,15 +164,13 @@ static-binary:
       - public
 
 pages:
-  stage: build
-  <<: *website
+  extends: .website
   rules:
     - if: '$CI_COMMIT_REF_NAME == "dev" && $CI_PROJECT_PATH == "ligolang/ligo"'
       when: always
 
 pages-attempt:
-  stage: build
-  <<: *website
+  extends: .website
   only:
     - merge_requests
     - /^.*-run-dev$/

From 85c7429f0c01e1e9ed51895be5ebe1171d80647c Mon Sep 17 00:00:00 2001
From: Alexander Bantyev <balsoft@balsoft.ru>
Date: Wed, 20 May 2020 17:07:39 +0300
Subject: [PATCH 3/7] Add documentation for nix expressions

---
 nix/README.md          | 28 ++++++++++++++++++++++++++++
 nix/docker.nix         |  1 +
 nix/ligo-editor.nix    |  6 ++++++
 nix/nodejs-overlay.nix |  1 +
 nix/ocaml-overlay.nix  | 14 ++++++++++++++
 nix/packageDeb.nix     |  1 +
 nix/pkgs.nix           |  7 ++++++-
 nix/static-overlay.nix |  3 +++
 nix/static.patch       |  1 +
 9 files changed, 61 insertions(+), 1 deletion(-)
 create mode 100644 nix/README.md

diff --git a/nix/README.md b/nix/README.md
new file mode 100644
index 000000000..83d5dc40b
--- /dev/null
+++ b/nix/README.md
@@ -0,0 +1,28 @@
+# Nix expressions for building LIGO
+
+Nix is a declarative package manager. Get it here: https://nixos.org/nix
+
+These expressions are used on CI to reproducibly build the LIGO compiler, as well as WebIDE and https://ligolang.org .
+
+If you wish to build it yourself with `nix build -f. $thing`, where `$thing` is
+
+- `ligo`: executables, libraries, documentation, coverage reports
+- `ligo-bin`: a dynamically linked binary (Linux, Mac)
+- `ligo-static`: a statically linked binary (Linux only)
+- `ligo-doc`: documentation generated by odoc
+- `ligo-editor`: WebIDE, it can be started with `result/bin/ligo-editor`
+- `ligo-website`: the website, website root is `result`
+- `ligo-docker`: a docker image with LIGO binaries
+- `ligo-editor-docker`: a docker image with webide
+- `ligo-deb`: debian package with static binaries
+
+## Quick maintenance guide
+
+- `opam-repository` and `tezos-opam-repository` are pinned. To update them when required, run `niv update` (you can get niv with `nix shell nixpkgs#niv`)
+- `ocaml` version is pinned in `ocaml-overlay.nix`. If you want to update it, go there and change the version.
+- If something fails, `nix repl pkgs.nix` can be very useful to investigate it.
+
+## Known caveats
+
+- This is not a nix flake. This will never be a flake if we want to keep this low-maintenance, because of the way `opam` sources are defined. Sometimes, the checksum is omitted there, so we have to use `fetchTarball` without the checksum, which won't work in restricted mode (which is required for flakes). The only solution would be to generate nix expressions for opam-repository separately, but it means a manual step in the process (and it's also impossible to make this work as a flake).
+- For the same reason as above, evaluation can take a while because we need to download all the sources every `tarball-ttl` seconds. This can be mitigated by setting `tarball-ttl` to a high value.
diff --git a/nix/docker.nix b/nix/docker.nix
index acda1c971..99f262282 100644
--- a/nix/docker.nix
+++ b/nix/docker.nix
@@ -1,5 +1,6 @@
 { dockerTools, writeShellScriptBin, runCommand, mcpp, bash, coreutils, ligo, name ? "ligo" }:
 let
+  # LIGO requires /tmp for compilation, which is missing in the default image
   tmp = runCommand "tmp" {} "mkdir -p $out/tmp";
 in
 dockerTools.buildLayeredImage {
diff --git a/nix/ligo-editor.nix b/nix/ligo-editor.nix
index 9a1a88920..809881904 100644
--- a/nix/ligo-editor.nix
+++ b/nix/ligo-editor.nix
@@ -2,10 +2,12 @@
 , writeShellScriptBin, makeFontsConf, buildEnv, rsync, sources
 , chromium ? null }:
 let
+  # Use a common yarn.lock for everything
   yarnLock = ../tools/webide/yarn.lock;
 
   installPhase = "mkdir $out; cp -Lr node_modules $out/node_modules";
 
+  # node_modules of the server
   server = mkYarnPackage {
     name = "webide-server";
     src = ../tools/webide/packages/server;
@@ -19,6 +21,8 @@ let
     distPhase = "true";
     inherit yarnLock installPhase;
   };
+
+  # node_modules of the client
   client = mkYarnPackage rec {
     name = "webide-client";
     src = ../tools/webide/packages/client;
@@ -42,6 +46,7 @@ let
     */
   };
 
+  # Perform the e2e tests; output is empty on purpose
   e2e = mkYarnPackage rec {
     name = "webide-e2e";
     src = ../tools/webide/packages/e2e;
@@ -61,6 +66,7 @@ let
     inherit yarnLock;
   };
 
+  # Run the WebIDE server with all the needed env variables
   ligo-editor = writeShellScriptBin "ligo-editor" ''
     set -e
     LIGO_CMD=${ligo-bin}/bin/ligo \
diff --git a/nix/nodejs-overlay.nix b/nix/nodejs-overlay.nix
index 7a5badf30..ab625530e 100644
--- a/nix/nodejs-overlay.nix
+++ b/nix/nodejs-overlay.nix
@@ -1,4 +1,5 @@
 self: super: {
+  # Note: this overlay doesn't apply to nix-npm-buildpackage
   nodejs = super.nodejs-12_x;
   nodePackages = super.nodePackages_12_x;
   nodejs-slim = super.nodejs-slim-12_x;
diff --git a/nix/ocaml-overlay.nix b/nix/ocaml-overlay.nix
index d811becad..b44cfdcef 100644
--- a/nix/ocaml-overlay.nix
+++ b/nix/ocaml-overlay.nix
@@ -1,3 +1,5 @@
+# An overlay that adds ligo to ocamlPackages
+
 { sources ? import ./sources.nix
 , CI_COMMIT_SHA ? builtins.getEnv "CI_COMMIT_SHA"
 , COMMIT_DATE ? builtins.getEnv "COMMIT_DATE" }:
@@ -6,6 +8,7 @@ let
   opam-nix = import sources.opam-nix (import sources.nixpkgs { });
   inherit (import sources."gitignore.nix" { inherit (self) lib; })
     gitignoreSource;
+  # Remove list of directories or files from source (to stop unneeded rebuilds)
   filterOut = xs:
     self.lib.cleanSourceWith {
       filter = p: type: !(builtins.elem (builtins.baseNameOf p) xs);
@@ -14,6 +17,7 @@ let
 in {
   ocamlPackages = self.ocaml-ng.ocamlPackages_4_07.overrideScope'
     (builtins.foldl' self.lib.composeExtensions (_: _: { }) [
+      # Both opam-repository and tezos-opam-repository are updated manually with `niv update`
       (opam-nix.traverseOPAMRepo' sources.opam-repository)
       (opam-nix.traverseOPAMRepo sources.tezos-opam-repository)
       (opam-nix.callOPAMPackage (filterOut [
@@ -26,19 +30,23 @@ in {
         "gitlab-pages"
       ]))
       (oself: osuper: {
+        # Strange naming in nixpkgs
         ocamlfind = oself.findlib;
         lablgtk = null;
         lwt = oself.lwt4;
 
+        # Native dependencies
         conf-gmp = self.gmp;
         conf-libev = self.libev;
         conf-hidapi = self.hidapi;
         conf-pkg-config = self.pkg-config;
 
+        # Strange problems
         bigstring = osuper.bigstring.overrideAttrs (_: { doCheck = false; });
         xmldiff = osuper.xmldiff.overrideAttrs (_: { src = sources.xmldiff; });
         getopt = osuper.getopt.overrideAttrs (_: { configurePhase = "true"; });
 
+        # Force certain versions
         ipaddr = osuper.ipaddr.versions."4.0.0";
         conduit = osuper.conduit.versions."2.1.0";
         conduit-lwt-unix = osuper.conduit-lwt-unix.versions."2.0.2";
@@ -64,6 +72,7 @@ in {
             propagatedBuildInputs = buildInputs;
           });
 
+        # A combination of executables, libraries, documentation and test coverage
         ligo = self.buildEnv {
           name = "ligo";
           paths = with oself; [
@@ -74,6 +83,7 @@ in {
           ];
         };
 
+        # LIGO executable and public libraries
         ligo-out = osuper.ligo.overrideAttrs (oa: {
           name = "ligo-out";
           inherit CI_COMMIT_SHA COMMIT_DATE;
@@ -82,6 +92,8 @@ in {
           nativeBuildInputs = oa.nativeBuildInputs
             ++ [ self.buildPackages.rakudo ];
         });
+
+        # LIGO test suite; output empty on purpose
         ligo-tests = osuper.ligo.overrideAttrs (oa: {
           name = "ligo-tests";
           src = filterOut [
@@ -98,6 +110,7 @@ in {
             ++ [ self.buildPackages.rakudo ];
           installPhase = "mkdir $out";
         });
+        # LIGO odoc documentation
         ligo-doc = osuper.ligo.overrideAttrs (oa: {
           name = "ligo-doc";
           buildInputs = oa.buildInputs
@@ -109,6 +122,7 @@ in {
           installPhase =
             "mkdir $out; cp -r _build/default/_doc/_html/ $out/doc";
         });
+        # LIGO test coverage reports
         ligo-coverage = oself.ligo-tests.overrideAttrs (oa: {
           name = "ligo-coverage";
           nativeBuildInputs = oa.nativeBuildInputs
diff --git a/nix/packageDeb.nix b/nix/packageDeb.nix
index bb5f0a57b..d7366e797 100644
--- a/nix/packageDeb.nix
+++ b/nix/packageDeb.nix
@@ -1,3 +1,4 @@
+# Create a debian package from static executable
 { stdenv, lib, writeTextFile, ligo-static, dpkg }:
 let
   project = "ligo";
diff --git a/nix/pkgs.nix b/nix/pkgs.nix
index d832dde56..23c2abe5a 100644
--- a/nix/pkgs.nix
+++ b/nix/pkgs.nix
@@ -1,20 +1,25 @@
+# nixpkgs extended with all the overlays for LIGO
 { sources ? import ./sources.nix }:
 let
   ocaml-overlay = import ./ocaml-overlay.nix { inherit sources; };
   static-overlay = import ./static-overlay.nix pkgs;
   mac-overlay = import ./mac-overlay.nix;
   nodejs-overlay = import ./nodejs-overlay.nix;
+  nix-npm-buildpackage = pkgs.callPackage sources.nix-npm-buildpackage { };
+
   pkgs = import sources.nixpkgs {
     overlays = [ ocaml-overlay nodejs-overlay ]
+    # This is done here to prevent the need for bootstrap nixpkgs
       ++ (if builtins.currentSystem == "x86_64-darwin"
           then [ mac-overlay ]
           else [ ]);
   };
+
+  # Takes $pkg/ligo and creates a new package with $pkg/bin/ligo
   separateBinary = pkg:
     pkgs.runCommandNoCC "${pkg.name}-bin" { }
     "mkdir -p $out/bin; cp -Lr ${pkg}/ligo $out/bin";
 
-  nix-npm-buildpackage = pkgs.callPackage sources.nix-npm-buildpackage { };
 in pkgs.extend (self: super: {
   inherit (self.ocamlPackages) ligo ligo-out ligo-tests ligo-doc ligo-coverage;
   ligo-bin = separateBinary self.ligo-out.bin;
diff --git a/nix/static-overlay.nix b/nix/static-overlay.nix
index 5add8718f..e16aa8646 100644
--- a/nix/static-overlay.nix
+++ b/nix/static-overlay.nix
@@ -1,3 +1,6 @@
+# An overlay that adds flags needed to build LIGO statically;
+# Supposed to be applied to pkgsMusl
+# Takes `native` as a package set that doesn't cause mass rebuilds (so that we don't have to build perl with musl)
 native: self: super:
 let dds = x: x.overrideAttrs (o: { dontDisableStatic = true; });
 in {
diff --git a/nix/static.patch b/nix/static.patch
index f4ce39a39..efe5c43b8 100644
--- a/nix/static.patch
+++ b/nix/static.patch
@@ -1,5 +1,6 @@
 diff --git a/src/bin/dune b/src/bin/dune
 index 162963b4b..29dfa5191 100644
+With this patch, a static executable is produced
 --- a/src/bin/dune
 +++ b/src/bin/dune
 @@ -34,5 +34,6 @@

From 5c2b9646ece63e2b19b8d48a303799493d286685 Mon Sep 17 00:00:00 2001
From: Alexander Bantyev <balsoft@balsoft.ru>
Date: Wed, 20 May 2020 18:04:51 +0300
Subject: [PATCH 4/7] Update nix-npm-buildpackage

---
 nix/sources.json | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/nix/sources.json b/nix/sources.json
index ec94d353f..d0d6aaf54 100644
--- a/nix/sources.json
+++ b/nix/sources.json
@@ -17,10 +17,10 @@
         "homepage": "",
         "owner": "serokell",
         "repo": "nix-npm-buildpackage",
-        "rev": "0450c7d88dc3d0a26461b05cfa36f45d551f4d63",
-        "sha256": "1w0k4jxw141win67rk66nvg323j5i3s4m1w3icf1g1f0p2zyf531",
+        "rev": "f2107f638f7df7450a5b7b77b96aaf9752b838d9",
+        "sha256": "02w8jxmmhxsq7fgzml75b8w8i9mdqxnaajia99jajg6rdiam8zfp",
         "type": "tarball",
-        "url": "https://github.com/serokell/nix-npm-buildpackage/archive/0450c7d88dc3d0a26461b05cfa36f45d551f4d63.tar.gz",
+        "url": "https://github.com/serokell/nix-npm-buildpackage/archive/f2107f638f7df7450a5b7b77b96aaf9752b838d9.tar.gz",
         "url_template": "https://github.com/<owner>/<repo>/archive/<rev>.tar.gz"
     },
     "nixpkgs": {

From 16bcee1aaddf658ab545e9081e7c4d5d3ae0f182 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Suzanne=20Dup=C3=A9ron?= <georges.duperon@nomadic-labs.com>
Date: Wed, 20 May 2020 17:27:22 +0000
Subject: [PATCH 5/7] Fixes from MR review

- Fix quoting issues in nix/README.md
- Clarify about nix flakes
---
 nix/README.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/nix/README.md b/nix/README.md
index 83d5dc40b..1072b90b6 100644
--- a/nix/README.md
+++ b/nix/README.md
@@ -18,11 +18,11 @@ If you wish to build it yourself with `nix build -f. $thing`, where `$thing` is
 
 ## Quick maintenance guide
 
-- `opam-repository` and `tezos-opam-repository` are pinned. To update them when required, run `niv update` (you can get niv with `nix shell nixpkgs#niv`)
+- `opam-repository` and `tezos-opam-repository` are pinned. To update them when required, run `niv update` (you can get niv with `nix shell 'nixpkgs#niv'`)
 - `ocaml` version is pinned in `ocaml-overlay.nix`. If you want to update it, go there and change the version.
 - If something fails, `nix repl pkgs.nix` can be very useful to investigate it.
 
 ## Known caveats
 
-- This is not a nix flake. This will never be a flake if we want to keep this low-maintenance, because of the way `opam` sources are defined. Sometimes, the checksum is omitted there, so we have to use `fetchTarball` without the checksum, which won't work in restricted mode (which is required for flakes). The only solution would be to generate nix expressions for opam-repository separately, but it means a manual step in the process (and it's also impossible to make this work as a flake).
+- This is not a [nix flake](https://gist.github.com/edolstra/40da6e3a4d4ee8fd019395365e0772e7). This will never be a flake if we want to keep this low-maintenance, because of the way `opam` sources are defined. Sometimes, the checksum is omitted there, so we have to use `fetchTarball` without the checksum, which won't work in restricted mode (which is required for flakes). The only solution would be to generate nix expressions for opam-repository separately, but it means a manual step in the process (and it's also impossible to make this work as a flake).
 - For the same reason as above, evaluation can take a while because we need to download all the sources every `tarball-ttl` seconds. This can be mitigated by setting `tarball-ttl` to a high value.

From 340622350dac1dd766c4cee24875f1838fe178f2 Mon Sep 17 00:00:00 2001
From: Alexander Bantyev <balsoft@balsoft.ru>
Date: Wed, 20 May 2020 21:59:45 +0300
Subject: [PATCH 6/7] Clarify the nix docs by pointing out the location of
 build results

---
 nix/README.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/nix/README.md b/nix/README.md
index 1072b90b6..e0c44dcb6 100644
--- a/nix/README.md
+++ b/nix/README.md
@@ -4,7 +4,7 @@ Nix is a declarative package manager. Get it here: https://nixos.org/nix
 
 These expressions are used on CI to reproducibly build the LIGO compiler, as well as WebIDE and https://ligolang.org .
 
-If you wish to build it yourself with `nix build -f. $thing`, where `$thing` is
+If you wish to build it yourself, do `nix build -f. $thing`, where `$thing` is
 
 - `ligo`: executables, libraries, documentation, coverage reports
 - `ligo-bin`: a dynamically linked binary (Linux, Mac)
@@ -16,6 +16,8 @@ If you wish to build it yourself with `nix build -f. $thing`, where `$thing` is
 - `ligo-editor-docker`: a docker image with webide
 - `ligo-deb`: debian package with static binaries
 
+The output of `nix build` can be found in `result` directory.
+
 ## Quick maintenance guide
 
 - `opam-repository` and `tezos-opam-repository` are pinned. To update them when required, run `niv update` (you can get niv with `nix shell 'nixpkgs#niv'`)

From b6aa71d6acc1160748bdc8472a7d70c296cbc177 Mon Sep 17 00:00:00 2001
From: Alexander Bantyev <balsoft@balsoft.ru>
Date: Wed, 20 May 2020 22:00:10 +0300
Subject: [PATCH 7/7] Remove /tmp from docker container

---
 nix/docker.nix | 6 +-----
 1 file changed, 1 insertion(+), 5 deletions(-)

diff --git a/nix/docker.nix b/nix/docker.nix
index 99f262282..5820717b3 100644
--- a/nix/docker.nix
+++ b/nix/docker.nix
@@ -1,11 +1,7 @@
 { dockerTools, writeShellScriptBin, runCommand, mcpp, bash, coreutils, ligo, name ? "ligo" }:
-let
-  # LIGO requires /tmp for compilation, which is missing in the default image
-  tmp = runCommand "tmp" {} "mkdir -p $out/tmp";
-in
 dockerTools.buildLayeredImage {
   inherit name;
   tag = "latest";
-  contents = [ ligo tmp bash ];
+  contents = [ ligo bash ];
   config.Entrypoint = name;
 }