Add Dev Container Configuration Files

.devcontainer/.gitignore

@@ -0,0 +1,26 @@
+*
+
+!/assets/
+!/assets/screenshots/
+!/bind-mounts/
+!/conf/
+!/conf/etc/
+!/conf/etc/stack/
+!/ghc-*/
+!/scripts/
+!/scripts/usr/
+!/scripts/usr/local/
+!/scripts/usr/local/bin/
+
+!/assets/screenshots/manageHLS.png
+!/conf/etc/stack/config.yaml
+!/ghc-*/devcontainer.json
+!/scripts/usr/local/bin/*.sh
+
+!/devcontainer.json
+!/GHC.Dockerfile
+!/LICENSE
+!/README.md
+
+!.gitignore
+!.keep

.devcontainer/GHC.Dockerfile

@@ -0,0 +1,112 @@
+ARG BUILD_ON_IMAGE=glcr.b-data.ch/ghc/ghc-musl
+ARG GHC_VERSION=latest
+ARG HLS_VERSION
+ARG STACK_VERSION
+
+ARG HLS_GHC_VERSION=${HLS_VERSION:+$GHC_VERSION}
+ARG HLS_SFX=/${HLS_GHC_VERSION:-all}/hls:${HLS_VERSION:-none}
+
+ARG STACK_VERSION_OVERRIDE=${STACK_VERSION:-none}
+
+FROM ${BUILD_ON_IMAGE}:${GHC_VERSION} as files
+
+RUN mkdir /files
+
+COPY conf /files
+COPY scripts /files
+
+## Ensure file modes are correct
+RUN find /files -type d -exec chmod 755 {} \; \
+  && find /files -type f -exec chmod 644 {} \; \
+  && find /files/usr/local/bin -type f -exec chmod 755 {} \;
+
+FROM glcr.b-data.ch/commercialhaskell/ssi:${STACK_VERSION_OVERRIDE} as ssi
+
+FROM ${BUILD_ON_IMAGE}${HLS_SFX} as hls
+
+FROM glcr.b-data.ch/ndmitchell/hlsi:latest as hlsi
+
+FROM docker.io/koalaman/shellcheck:stable as sci
+
+FROM ${BUILD_ON_IMAGE}:${GHC_VERSION}
+
+COPY --from=files /files /
+
+RUN sysArch="$(uname -m)" \
+  ## Ensure that common CA certificates
+  ## and OpenSSL libraries are up to date
+  && apk upgrade --no-cache ca-certificates openssl-dev \
+  ## Install yamllint
+  && apk add --no-cache yamllint \
+  ## Install hadolint
+  && case "$sysArch" in \
+    x86_64) tarArch="x86_64" ;; \
+    aarch64) tarArch="arm64" ;; \
+    *) echo "error: Architecture $sysArch unsupported"; exit 1 ;; \
+  esac \
+  && apiResponse="$(curl -sSL \
+    https://api.github.com/repos/hadolint/hadolint/releases/latest)" \
+  && downloadUrl="$(echo "$apiResponse" | grep -e \
+    "browser_download_url.*Linux-$tarArch\"" | cut -d : -f 2,3 | tr -d \")" \
+  && echo "$downloadUrl" | xargs curl -sSLo /usr/local/bin/hadolint \
+  && chmod 755 /usr/local/bin/hadolint \
+  ## Create folders in root directory
+  && mkdir -p /root/.local/bin \
+  ## Create folders in skeleton directory
+  && mkdir -p /etc/skel/.local/bin
+
+## Update environment
+ARG USE_ZSH_FOR_ROOT
+ARG SET_LANG
+ARG SET_TZ
+
+ENV TZ=${SET_TZ:-$TZ} \
+    LANG=${SET_LANG:-$LANG}
+
+  ## Change root's shell to ZSH
+RUN if [ -n "$USE_ZSH_FOR_ROOT" ]; then \
+    apk add --no-cache zsh shadow; \
+    fix-chsh.sh; \
+    chsh -s /bin/zsh; \
+  fi \
+  ## Update timezone if needed
+  && if [ "$TZ" != "" ]; then \
+    apk add --no-cache tzdata; \
+    echo "Setting TZ to $TZ"; \
+    ln -snf "/usr/share/zoneinfo/$TZ" /etc/localtime \
+      && echo "$TZ" > /etc/timezone; \
+  fi \
+  ## Add/Update locale if needed
+  && if [ "$LANG" != "C.UTF-8" ]; then \
+    if [ -n "$LANG" ]; then \
+      apk add --no-cache musl-locales musl-locales-lang; \
+    fi; \
+    sed -i "s/LANG=C.UTF-8/LANG=$LANG/" /etc/profile.d/*locale.sh; \
+    sed -i "s/LANG:-C.UTF-8/LANG:-$LANG/" /etc/profile.d/*locale.sh; \
+    sed -i "s/LC_COLLATE=C/LC_COLLATE=$LANG/" /etc/profile.d/*locale.sh; \
+    sed -i "s/LC_COLLATE:-C/LC_COLLATE:-$LANG/" /etc/profile.d/*locale.sh; \
+  fi
+
+## Copy binaries as late as possible to avoid cache busting
+## Install Stack
+COPY --from=ssi /usr/local /usr/local
+## Install HLS
+COPY --from=hls /usr/local /usr/local
+## Install HLint
+COPY --from=hlsi /usr/local /usr/local
+## Install ShellCheck
+COPY --from=sci --chown=root:root /bin/shellcheck /usr/local/bin
+
+ARG HLS_VERSION
+ARG STACK_VERSION
+
+ARG STACK_VERSION_OVERRIDE=${STACK_VERSION}
+
+ENV HLS_VERSION=${HLS_VERSION} \
+    STACK_VERSION=${STACK_VERSION_OVERRIDE:-$STACK_VERSION}
+
+RUN if [ "${GHC_VERSION%.*}" = "9.2" ]; then \
+    if [ -f /usr/local/bin/stack ]; then \
+      mv -f /usr/local/bin/stack /usr/bin/; \
+    fi \
+  fi

.devcontainer/LICENSE

@@ -0,0 +1,35 @@
+Copyright (c) 2023 Olivier Benz
+
+The code in this directory is not part of Pandoc (the software) and, with the
+exceptions noted below, is distributed under the terms of the MIT License:
+
+  Permission is hereby granted, free of charge, to any person obtaining a copy
+  of this software and associated documentation files (the "Software"), to deal
+  in the Software without restriction, including without limitation the rights
+  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+  copies of the Software, and to permit persons to whom the Software is
+  furnished to do so, subject to the following conditions:
+
+  The above copyright notice and this permission notice shall be included in all
+  copies or substantial portions of the Software.
+
+  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+  SOFTWARE.
+
+This directory also contains code with other copyrights. The affected files,
+their copyrights and license statements are listed below.
+
+--------------------------------------------------------------------------------
+scripts/fix-chsh.sh
+Copyright (c) Microsoft Corporation. All rights reserved.
+
+Licensed under the MIT License. See
+https://github.com/devcontainers/features/blob/main/LICENSE for
+license information.
+
+--------------------------------------------------------------------------------

.devcontainer/README.md

@@ -0,0 +1,68 @@
+# Dev Containers
+
+These Dev Containers are based on the same docker images that are used to build
+the *statically linked* Linux amd64 and arm64 binary releases of pandoc.
+
+Those multi-arch (`linux/amd64`, `linux/arm64/v8`) docker images themselves are
+based on Alpine Linux and contain *unofficial* builds of GHC.
+
+Only use the GHC available in the Dev Containers, because
+
+1. the *official* GHC bindists for Alpine Linux (`x86_64`) are just too buggy.
+2. there are currently (2023-08-28) no bindists for Alpine Linux (`AArch64`).
+
+Therefore, flags `--system-ghc` and `--no-install-ghc` are set system-wide in
+`/etc/stack/config.yaml`.
+
+## Usage
+
+For use with Github Codespaces, please follow the instruction at
+[Creating a codespace for a repository](https://docs.github.com/en/codespaces/developing-in-codespaces/creating-a-codespace-for-a-repository#creating-a-codespace-for-a-repository).
+
+For local/'remote host' usage with VS Code, please follow the instructions at
+[Developing inside a Container](https://code.visualstudio.com/docs/devcontainers/containers).
+
+### Persistence
+
+Data in the following locations is persisted:
+
+1. The user's home directory (`/home/vscode`)[^1]
+2. The Dev Container's workspace (`/workspaces`)
+
+[^1]: Alternatively for the root user (`/root`). Use with Docker/Podman in
+*rootless mode*.
+
+This is accomplished either via a *volume* or *bind mount* (or *loop device* on
+Codespaces) and is preconfigured.
+
+## Install pandoc
+
+### Using cabal
+
+Addendum to [Installing pandoc > Compiling from source > Quick cabal method](../INSTALL.md#quick-cabal-method):
+
+Use
+`cabal build --ghc-options '-static -optl-static -optl-pthread' pandoc-cli` to
+build a *statically linked* `pandoc` executable that can run on any Linux
+machine of the same architecture.
+
+### Using stack
+
+See [Installing pandoc > Compiling from source > Quick stack method](../INSTALL.md#quick-stack-method)
+
+You may try
+`stack build --ghc-options '-static -optl-static -optl-pthread' pandoc-cli` to
+build a *statically linked* `pandoc` executable.  
+:information_source: This works on Alpine Linux/AArch64 but not x86_64[^2].
+
+[^2]: Most likely due to a bug in the GCC toolchain on Linux/x86_64 that was
+never fixed.  
+See [gcc - Haskell Stack Static Binary relocation R_X86_64_32 against `TMC_END' can not be used when making a shared object - Stack Overflow](https://stackoverflow.com/questions/41419102/haskell-stack-static-binary-relocation-r-x86-64-32-against-tmc-end-can-not/41427067)  
+and [Bug #640734 “crtbeginT.o needs to be recompiled with -fPIC” : Bugs : gcc-4.4 package : Ubuntu](https://bugs.launchpad.net/ubuntu/+source/gcc-4.4/+bug/640734)
+for more information.
+
+## Haskell Language Server (HLS)
+
+Choose `Manually via PATH` when asked the following question:
+
+<img width="520" alt="manageHLS" src="assets/screenshots/manageHLS.png">

.devcontainer/conf/etc/stack/config.yaml

@@ -0,0 +1,4 @@
+# Use only the GHC available on the PATH
+system-ghc: true
+# Do not automatically install GHC when necessary
+install-ghc: false

.devcontainer/devcontainer.json

@@ -0,0 +1,65 @@
+{
+  "name": "Default (for use with Stack)",
+  "build": {
+    "dockerfile": "GHC.Dockerfile",
+    "args": {
+      "GHC_VERSION": "9.4.5",
+      "HLS_VERSION": "2.1.0.0",
+      "STACK_VERSION": "2.11.1",
+      "USE_ZSH_FOR_ROOT": "unset-to-use-ash",
+      "SET_LANG": "C.UTF-8",
+      "SET_TZ": ""
+    }
+  },
+
+  "onCreateCommand": "onCreateCommand.sh",
+  "postCreateCommand": "cabal update",
+
+  "features": {
+    "ghcr.io/devcontainers/features/common-utils:2": {
+      "configureZshAsDefaultShell": true,
+      "upgradePackages": false,
+      "username": "vscode",
+      "userUid": "automatic",
+      "userGid": "automatic"
+    }
+  },
+
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "eamodio.gitlens@11.7.0",
+        "editorconfig.editorconfig",
+        "exiasr.hadolint",
+        "GitHub.vscode-pull-request-github",
+        "haskell.haskell",
+        "mhutchie.git-graph",
+        "ms-vscode.makefile-tools",
+        "mutantdino.resourcemonitor",
+        "dbaeumer.vscode-eslint",
+        "esbenp.prettier-vscode",
+        "timonwong.shellcheck"
+      ],
+      "settings": {
+        "gitlens.showWelcomeOnInstall": false,
+        "gitlens.showWhatsNewAfterUpgrades": false,
+        "haskell.manageHLS": "PATH",
+        "resmon.show.battery": false,
+        "resmon.show.cpufreq": false
+      }
+    }
+  },
+
+  // Set 'remoteUser' to 'root' to connect as root instead.
+  "remoteUser": "vscode",
+  "mounts": [
+    "source=pandoc-default-home-vscode,target=/home/vscode,type=volume"
+    // "source=${localWorkspaceFolder}/.devcontainer/bind-mounts/pandoc-default-home-vscode,target=/home/vscode,type=bind"
+  ]
+
+  // "remoteUser": "root",
+  // "mounts": [
+  //   "source=pandoc-default-root,target=/root,type=volume"
+  //   // "source=${localWorkspaceFolder}/.devcontainer/bind-mounts/pandoc-default-root,target=/root,type=bind"
+  // ]
+}

.devcontainer/ghc-9.2/devcontainer.json

@@ -0,0 +1,66 @@
+{
+  "name": "GHC 9.2 (recommended)",
+  "build": {
+    "dockerfile": "../GHC.Dockerfile",
+    "context": "..",
+    "args": {
+      "GHC_VERSION": "9.2",
+      "HLS_VERSION": "2.2.0.0",
+      "STACK_VERSION": "2.9.3.1",
+      "USE_ZSH_FOR_ROOT": "unset-to-use-ash",
+      "SET_LANG": "C.UTF-8",
+      "SET_TZ": ""
+    }
+  },
+
+  "onCreateCommand": "onCreateCommand.sh",
+  "postCreateCommand": "cabal update",
+
+  "features": {
+    "ghcr.io/devcontainers/features/common-utils:2": {
+      "configureZshAsDefaultShell": true,
+      "upgradePackages": false,
+      "username": "vscode",
+      "userUid": "automatic",
+      "userGid": "automatic"
+    }
+  },
+
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "eamodio.gitlens@11.7.0",
+        "editorconfig.editorconfig",
+        "exiasr.hadolint",
+        "GitHub.vscode-pull-request-github",
+        "haskell.haskell",
+        "mhutchie.git-graph",
+        "ms-vscode.makefile-tools",
+        "mutantdino.resourcemonitor",
+        "dbaeumer.vscode-eslint",
+        "esbenp.prettier-vscode",
+        "timonwong.shellcheck"
+      ],
+      "settings": {
+        "gitlens.showWelcomeOnInstall": false,
+        "gitlens.showWhatsNewAfterUpgrades": false,
+        "haskell.manageHLS": "PATH",
+        "resmon.show.battery": false,
+        "resmon.show.cpufreq": false
+      }
+    }
+  },
+
+  // Set 'remoteUser' to 'root' to connect as root instead.
+  "remoteUser": "vscode",
+  "mounts": [
+    "source=pandoc-ghc-9.2-home-vscode,target=/home/vscode,type=volume"
+    // "source=${localWorkspaceFolder}/.devcontainer/bind-mounts/pandoc-ghc-9.2-home-vscode,target=/home/vscode,type=bind"
+  ]
+
+  // "remoteUser": "root",
+  // "mounts": [
+  //   "source=pandoc-ghc-9.2-root,target=/root,type=volume"
+  //   // "source=${localWorkspaceFolder}/.devcontainer/bind-mounts/pandoc-ghc-9.2-root,target=/root,type=bind"
+  // ]
+}