diff --git a/.devcontainer/README.md b/.devcontainer/README.md index 7bf63366996a8..0914bd3921e71 100644 --- a/.devcontainer/README.md +++ b/.devcontainer/README.md @@ -1,71 +1,10 @@ # 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. - -| **Codespaces: A 'Full Rebuild Container' resets the home directory!**
:information_source: This is never necessary unless you want exactly that. | -|:----------------------------------------------------------------------------------------------------------------------------------------------------| - -## 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) +See [Pandoc's Dev Containers wiki page](https://github.com/jgm/pandoc/wiki/Dev-Containers) for more information. -## Haskell Language Server (HLS) - -Choose `Manually via PATH` when asked the following question: +## License -manageHLS +The code in this directory is not part of pandoc (the software) and, with the +exceptions noted in [LICENSE](LICENSE), is distributed under the terms of the +MIT License. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4e7acb50e9883..becb36c25beb3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -428,6 +428,17 @@ If you've written a useful pandoc [lua filter](lua-filters.html), you may want to consider submitting a pull request to the [lua-filters repository](https://github.com/pandoc/lua-filters). +Dev Containers +-------------- + +A [Development Container] (or Dev Container for short) allows you to use a +container as a full‑featured development environment. + +You can run Dev Containers locally/remotely (with VS Code) or create a +[Codespace] for a branch in a repository to develop online. + +See [Pandoc's Dev Containers wiki page] for more information. + [open issues]: https://github.com/jgm/pandoc/issues [closed issues]: https://github.com/jgm/pandoc/issues?q=is%3Aissue+is%3Aclosed [latest released version]: https://github.com/jgm/pandoc/releases/latest @@ -457,3 +468,6 @@ you may want to consider submitting a pull request to the [status:more-discussion-needed]: https://github.com/jgm/pandoc/labels/status:more-discussion-needed [status:more-info-needed]: https://github.com/jgm/pandoc/labels/status:more-info-needed [stack]: https://github.com/commercialhaskell/stack +[Development Container]: https://containers.dev +[Codespace]: https://github.com/features/codespaces +[Pandoc's Dev Containers wiki page]: https://github.com/jgm/pandoc/wiki/Dev-Containers