This is a running list of frequently asked questions (recommendations are very welcome)
Dynamic linking issues with npm release: "Library not loaded /opt/homebrew/.../esy_openssl-93ba2454/lib/libssl.1.1.dylib"
TLDR; Ensure that required package, in this case
esy-openssl, in present in
esy.release.includePackages property of
Binaries often rely on dynamic libraries (esp. on MacOS). HTTP servers relying on popular frameworks to implement https would often rely on openssl, which is often dynamically linked on MacOS (Linux too by default). These need to be present in the sandbox when the binary runs (example, the HTTP server). This happens easily when one runs
esy x my-http-server.exe. But, when packaged as an npm package,
esy-openssl must be present in the binary's environment.
esy already ensures present during
esy x ... is also present in binaries exported as NPM package. But it doesn't, by default, export all the packages - they have to be opted in as and when needed. To ensure such dynamically linked library packages are included in the environment of the exported NPM packages, use
includePackages property (as explained here)
"includePackages": [ "root", "esy-gmp", + "esy-openssl" ],
Why doesn't Esy support Dune operations like opam file generation or copying of JS files in the source tree?
TLDR; If you're looking to generate opam files with Dune, use
esy dune build <project opam file>. For substitution, use
esy dune substs.
Any build operation is recommended to be run in an isolated sandboxed environment where the sources are considered
immutable. Esy uses sandbox-exec on MacOS to enforce a sandbox (Linux and Windows are pending). It is always recommended
that build commands are run with
esy b ... prefix. For this to work, esy assumes that there is no inplace editing of the
source tree - any in-place editing of sources that take place in the isolated phase makes it hard for esy to bet on immutability
and hence it is not written to handle it well at the moment (hence the cryptic error messages)
Any command that does not generate build artifacts (dune subst, launching lightweight editors etc) are recommended to be run with
esy ... prefix (We call it the command environment to distinguish it from build environment)
Esy prefers immutability of sources and built artifacts so that it can provide reproducibility guarantees and other benefits immutability brings.
How to generate opam file with Dune?
esy dune build hello-reason.opam
It seems there is no way to generate opam files only in the build directory. https://discord.com/channels/436568060288172042/469167238268715021/718879610804371506
This means dune build hello-reason.opam will not treat the source tree as immutable.