CI: {.travis.yml,build.sh}: merge documentation into buildh.sh

M  .travis.yml
M  build.sh

.travis.yml

@@ -32,48 +32,26 @@ env:
     #
     # - rev=nixos-unstable
     # - NIX_PATH="nixpkgs=https://github.com/nixos/nixpkgs/archive/$rev.tar.gz"
-    # NOTE: Project/binary name
     - project='hnix'
-    # NOTE: Enable all our tests in cabal
+    # Enable all our tests in Cabal
     - ALL_TESTS='yes'
-    # NOTE: Turn all warn into err with {-Wall,-Werror}
     - failOnAllWarnings='false'
-    # NOTE: checkUnusedPackages: is `failOnAllWarnings` + `cabal sdist` to ensure all needed files are listed in the Cabal file. Uses `packunused` or GHC internals. Adds a post-build check to verify that dependencies declared in the cabal file are actually used. The first attrset argument can be used to configure the strictness of this check and a list of ignored package names that would otherwise cause false alarms.
     - checkUnusedPackages='false'
-    # NOTE: Generation and installation of a coverage report.
-    # See https://wiki.haskell.org/Haskell_program_coverage
     - doCoverage='false'
-    # NOTE: Generation and installation of haddock API documentation
     - doHaddock='false'
-    # NOTE: Escape the version bounds from the cabal file. You may want to avoid this function.
     - doJailbreak='false'
-    # NOTE: Disables Nix dependency checking, compilation and execution of test suites listed in the package description file.
     - doCheck='true'
-    # NOTE: doBenchmark: Dependency checking + compilation and execution for benchmarks listed in the package description file.
     - doBenchmark='false'
     - enableExecutableProfiling='false'
     - enableLibraryProfiling='false'
-    # NOTE: Build a source distribution tarball instead of using the source files directly. The effect is that the package is built as if it were published on hackage. This can be used as a test for the source distribution, assuming the build fails when packaging mistakes are in the cabal file.
     - buildFromSdist='false'
-    # NOTE: Build the package in a strict way to uncover potential problems. This includes buildFromSdist and failOnAllWarnings.
-    #  2020-05-26: NOTE: Currently HNix not able to pass Strict on GHC 8.8.3 due to MonalFail migration
     - buildStrictly='false'
-    # NOTE: Disable core optimizations, significantly speeds up the build
     - disableOptimization='true'
-    # NOTE: Modify a Haskell package to add shell completion scripts for the given executable produced by it. These completion scripts will be picked up automatically if the resulting derivation is installed, e.g. by `nix-env -i`.
-    # Invocation:
-    #   generateOptparseApplicativeCompletions command pkg
-    #
-    #   command: name of an executable
-    #       pkg: Haskell package that builds the executables
     - generateOptparseApplicativeCompletions='false'
-    # [ "binary1" "binary2" ] - should pass " quotes into Nix interpreter
     - executableNamesToShellComplete='[ "hnix" ]'
-    # NOTE: Don't fail at configure time if there are multiple versions of the same package in the (recursive) dependencies of the package being built. Will delay failures, if any, to compile time.
     - allowInconsistentDependencies='false'
-    # NOTE: Log file to dump GHCJS build into
+    #
     - ghcjsTmpLogFile='/tmp/ghcjsTmpLogFile.log'
-    # NOTE: Length of the GHCJS log tail (<40000)
     - ghcjsLogTailLength='10000'
 
 #  2020-05-26: NOTE: Currently newest Travis dist Ubuntu 18.04 bionic

build.sh

@@ -2,10 +2,12 @@
 
 # NOTE: Script for the CI builds, relies on `default.nix` interface, which exposes Nixpkgs Haskell Lib interface
 
-# NOTE: The most strict error checking requirements
+# The most strict error checking requirements
 set -Eexuo pipefail
 
 ### NOTE: Section handles imports from env, these are settings for Nixpkgs.
+# Some of these options implicitly switch the dependent options.
+
 
 # NOTE: If var not imported - set to the default value
 GHCVERSION=${GHCVERSION:-'ghc8101'}
@@ -24,12 +26,11 @@ rev=${rev:-'nixpkgs-unstable'}
 # If NIX_PATH not imported - construct it from `rev`
 NIX_PATH=${NIX_PATH:-"nixpkgs=https://github.com/nixos/nixpkgs/archive/$rev.tar.gz"}
 export NIX_PATH
+# NOTE: Project name, used by cachix
 project=${project:-'defaultProjectName'}
 
 # This settings expose most of the Nixpkgs Haskell.lib API: https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/haskell-modules/lib.nix
 
-# Some of these options implicitly enable other options they require, and some counterpoint options clash, obviously
-
 # Don't fail at configure time if there are multiple versions of the same package in the (recursive) dependencies of the package being built. Will delay failures, if any, to compile time.
 allowInconsistentDependencies=${allowInconsistentDependencies:-'false'}
 
@@ -40,13 +41,16 @@ doCheck=${doCheck:-'true'}
 # Just produce a SDist src tarball
 sdistTarball=${sdistTarball:-'false'}
 # Produce SDist tarball and build project from it
+# The strict packaging process as used on Hackage. Tests consistency of the Cabal file.
 buildFromSdist=${buildFromSdist:-'false'}
+# Turn all warn into err with {-Wall,-Werror}
 failOnAllWarnings=${failOnAllWarnings:-'false'}
 # `failOnAllWarnings` + `buildFromSdist`
 buildStrictly=${buildStrictly:-'false'}
 #  2020-06-02: NOTE: enableDeadCodeElimination = true: On GHC =< 8.8.3 macOS build falls due to https://gitlab.haskell.org/ghc/ghc/issues/17283
 enableDeadCodeElimination=${enableDeadCodeElimination:-'false'}
-# Disable GHC code optimizations for faster dev loops. Enable optimizations for production use or benchmarks.
+# Disabled GHC code optimizations make build/tolling/dev loops faster. Works for Haskel IDE Engine and GHCID
+# Enable optimizations for production use, and to pass benchmarks.
 disableOptimization=${disableOptimization:-'true'}
 # Use faster `gold` ELF linker from GNU binutils instead of older&slower but more versatile GNU linker. Is not available by default since macOS does not have it.
 linkWithGold=${linkWithGold:-'false'}
@@ -71,6 +75,7 @@ enableSharedExecutables=${enableSharedExecutables:-'false'}
 justStaticExecutables=${justStaticExecutables:-'false'}
 enableSeparateBinOutput=${enableSeparateBinOutput:-'false'}
 # Add a post-build check to verify that dependencies declared in the .cabal file are actually used.
+# checkUnusedPackages: is `failOnAllWarnings` + `cabal sdist` to ensure all needed files are listed in the Cabal file. Currently uses `packunused` or GHC 8.8 internals, later switches into GHC internal feature. Adds a post-build check to verify that dependencies declared in the cabal file are actually used.
 checkUnusedPackages=${checkUnusedPackages:-'false'}
 # Generation and installation of haddock API documentation
 doHaddock=${doHaddock:-'false'}
@@ -78,16 +83,20 @@ doHaddock=${doHaddock:-'false'}
 doCoverage=${doCoverage:-'false'}
 # doBenchmark: Dependency checking + compilation and execution for benchmarks listed in the package description file.
 doBenchmark=${doBenchmark:-'false'}
-# NOTE: *Oprparse* key is redifined in the code further
+# For binaries named in `executableNamesToShellComplete` list, generate and bundle-into package an automatically loaded shell complettions
 generateOptparseApplicativeCompletions=${generateOptparseApplicativeCompletions:-'false'}
+# [ "binary1" "binary2" ] - should pass " quotes into Nix interpreter
 executableNamesToShellComplete=${executableNamesToShellComplete:-'[ "defaultBinaryName" ]'}
 
 # Include Hoogle into derivation
 withHoogle=${withHoogle:-'false'}
 
+# Log file to dump GHCJS build into
 ghcjsTmpLogFile=${ghcjsTmpLogFile:-'/tmp/ghcjsTmpLogFile.log'}
+# Length of the GHCJS log tail (<40000)
 ghcjsLogTailLength=${ghcjsLogTailLength:-'10000'}
-# NOTE: If key not provided (branch is not inside the central repo) - init CACHIX_SIGNING_KEY as empty
+
+# If key not provided (branch is not inside the central repo) - init CACHIX_SIGNING_KEY as empty
 CACHIX_SIGNING_KEY=${CACHIX_SIGNING_KEY:-""}