Merge branch 'nix-run-dev' into 'dev'

Switch to nix pipelines

See merge request ligolang/ligo!628

.gitlab-ci.yml

@@ -1,105 +1,20 @@
 # 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
-  - build_and_package_binaries
+  - push
-  - build_docker
-  - build_and_deploy
-  - ide-unit-test
-  - ide-build
-  - ide-e2e-test
-  - ide-deploy
-  - nix
-  - nix-push
   - versioning
 
-# TODO provide sensible CI for master
+.docker-image:
-dont-merge-to-master:
+  stage: push
-  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
   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,223 +22,17 @@ version_scheduled_job:
   only:
     - schedules
 
-local-dune-job:
+.nix:
-  <<: *before_script
+  stage: build
-  stage: test
+  tags:
-  script:
+    - nix
-    - 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
   before_script:
-    - nix-env -f channel:nixos-unstable -iA gnutar gitMinimal cachix
+    - find "$CI_PROJECT_DIR" -path "$CI_PROJECT_DIR/.git" -prune -o "(" -type d -a -not -perm -u=w ")" -exec chmod --verbose u+w {} ";"
-    - export COMMIT_DATE="$(git show --no-patch --format=%ci)"
+    - nix-env -f channel:nixos-unstable -iA gnutar gitMinimal
-    - 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 &
 
 # The binary produced is useless by itself
-binary-nix:
+binary:
-  stage: nix
+  extends: .nix
-  <<: *prepare_nix
   only:
     - merge_requests
     - dev
@@ -331,38 +40,35 @@ binary-nix:
   script:
     - nix-build nix -A ligo-bin
 
-doc-nix:
+doc:
-  stage: nix
+  extends: .nix
-  <<: *prepare_nix
   only:
     - merge_requests
     - dev
     - /^.*-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:
+test:
-  stage: nix
+  extends: .nix
-  <<: *prepare_nix
   only:
     - merge_requests
     - dev
     - /^.*-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:
+.webide-e2e:
-  stage: nix
+  extends: .nix
-  <<: *prepare_nix
   rules:
     - changes:
         - tools/webide/**
@@ -372,13 +78,12 @@ test-nix:
   script:
     - nix-build nix -A ligo-editor.e2e
 
-docker-nix:
+docker:
-  stage: nix
+  extends: .nix
   only:
     - merge_requests
     - dev
     - /^.*-run-dev$/
-  <<: *prepare_nix
   script:
     - nix-build nix -A ligo-docker
     - cp -L result ligo.tar.gz
@@ -386,13 +91,12 @@ docker-nix:
     paths:
       - ligo.tar.gz
 
-docker-push-nix:
+docker-push:
-  stage: nix-push
+  extends: .docker-image
-  <<: *docker
   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,17 +104,16 @@ 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:
+webide-docker:
-  stage: nix
+  extends: .nix
   only:
     - merge_requests
     - dev
     - /^.*-run-dev$/
-  <<: *prepare_nix
   script:
     - nix-build nix -A ligo-editor-docker
     - cp -L result webide.tar.gz
@@ -419,13 +122,12 @@ webide-docker-nix:
       - webide.tar.gz
 
 
-webide-push-nix:
+webide-push:
-  stage: nix-push
+  extends: .docker-image
-  <<: *docker
   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 +135,42 @@ 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 tag ligo-editor "${WEBIDE_IMAGE_NAME}:${CI_COMMIT_SHORT_SHA}"
-    - docker push "${WEBIDE_IMAGE_NAME}:nix${CI_COMMIT_SHORT_SHA}"
+    - docker push "${WEBIDE_IMAGE_NAME}:${CI_COMMIT_SHORT_SHA}"
 
-static-binary-nix:
+static-binary:
-  stage: nix
+  extends: .nix
-  <<: *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:
+.website:
-  stage: nix
+  extends: .nix
-  <<: *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:
+  extends: .website
+  rules:
+    - if: '$CI_COMMIT_REF_NAME == "dev" && $CI_PROJECT_PATH == "ligolang/ligo"'
+      when: always
+
+pages-attempt:
+  extends: .website
+  only:
+    - merge_requests
+    - /^.*-run-dev$/

nix/README.md

@@ -0,0 +1,30 @@
+# 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, do `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
+
+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'`)
+- `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](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.

nix/docker.nix

@@ -1,10 +1,7 @@
 { dockerTools, writeShellScriptBin, runCommand, mcpp, bash, coreutils, ligo, name ? "ligo" }:
-let
-  tmp = runCommand "tmp" {} "mkdir -p $out/tmp";
-in
 dockerTools.buildLayeredImage {
   inherit name;
   tag = "latest";
-  contents = [ ligo tmp bash ];
+  contents = [ ligo bash ];
   config.Entrypoint = name;
 }

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 \

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;

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

nix/packageDeb.nix

@@ -1,3 +1,4 @@
+# Create a debian package from static executable
 { stdenv, lib, writeTextFile, ligo-static, dpkg }:
 let
   project = "ligo";

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;

nix/sources.json

@@ -17,10 +17,10 @@
         "homepage": "",
         "owner": "serokell",
         "repo": "nix-npm-buildpackage",
-        "rev": "0450c7d88dc3d0a26461b05cfa36f45d551f4d63",
+        "rev": "f2107f638f7df7450a5b7b77b96aaf9752b838d9",
-        "sha256": "1w0k4jxw141win67rk66nvg323j5i3s4m1w3icf1g1f0p2zyf531",
+        "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": {

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 {

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 @@