Use built escript to execute ex_doc instead of one in PATH

[chiroptical]

Is your feature request related to a problem? Please describe.

Working on adding Erlang w/ OTP 27-rc2 to nixpkgs (https://github.com/NixOS/nixpkgs/pull/303750/files). The default shebang line for ex_doc is #! /usr/bin/env escript however this doesn't play nice with nix.

Describe the solution you'd like

I believe you could change this line to not rely on the ex_doc in the PATH and execute escript ex_doc ...

otp/make/ex_doc_wrapper

Line 8 in e6d3401

exec ex_doc "${ARGS[@]}"

That escript can be hardcoded to the one built at make time and checked to ensure it exists (telling the user you need to make first).

Describe alternatives you've considered

You could simply leave it, this is likely a pretty nix specific issue.

Additional context

I am happy to implement this but wanted to ensure the contribution is welcome. Thanks.

[garazdawi]

#! /usr/bin/env escript however this doesn't play nice with nix.

Why does it not play nice with nix? The doc build is run using PATH=$ERL_TOP/bin:$PATH which should mean that it is $ERL_TOP/bin/escript that is used.

[chiroptical]

This is a bit of a can of worms, but I think the most concise explanation is this answer on stack overflow and the most detailed answer is here on discourse

In short: I can't use /usr/bin/env in a sandboxed nix build (which is best practice when adding packages to nixpkgs).
I am currently just copying the raw ex_doc executable into the install directory and patching it. The code is here: https://github.com/NixOS/nixpkgs/blob/cde53c12dcdc559b8f918957cb6c975e22575f17/pkgs/development/interpreters/erlang/generic-builder.nix#L128-L134.

I'll admit that this is a very nix specific issue. You already have the path $ERL_TOP/bin/escript so you could choose to use directly. If you don't, my manual patching solution is working. Thanks for your time.

[chiroptical]

I was just able to test this with the rc3 nix update, this patch simplifies my build

diff --git a/make/doc.mk b/make/doc.mk
index 8425938ca9..9abdf1a196 100644
--- a/make/doc.mk
+++ b/make/doc.mk
@@ -60,7 +60,7 @@ HTML_DEPS?=$(wildcard $(APP_EBIN_DIR)/*.beam) $(wildcard *.md) $(wildcard */*.md

 $(HTMLDIR)/index.html: $(HTML_DEPS) docs.exs
 	$(gen_verbose)ERL_FLAGS="-pz $(ERL_TOP)/erts/ebin" \
-	  $(EX_DOC) $(EX_DOC_FORMATS) --homepage-url "$(INDEX_DIR)/index.html" "$(APPLICATION)" $(VSN) $(APP_EBIN_DIR) -o "$(HTMLDIR)" -c $(ERL_TOP)/make/ex_doc.exs
+	  $(ERL_TOP)/bin/escript $(EX_DOC) $(EX_DOC_FORMATS) --homepage-url "$(INDEX_DIR)/index.html" "$(APPLICATION)" $(VSN) $(APP_EBIN_DIR) -o "$(HTMLDIR)" -c $(ERL_TOP)/make/ex_doc.exs

 html: $(HTMLDIR)/index.html

[chiroptical]

This is slightly off though because of the way ex_doc_wrapper is set/works.

[garazdawi]

A patch doing that would be welcome, however it should do it using $(ESCRIPT) so that it works on windows as well.

[chiroptical]

A patch doing that would be welcome, however it should do it using $(ESCRIPT) so that it works on windows as well.

I tried doing this but it is more subtle due to the wrapper (because it is a bash script you can't execute with escript). Ideas,

1. Enforce ex_doc to exist at configure time by explaining how to download it (and remove the wrapper)
2. Don't set EX_DOC to the wrapper and run the download if EX_DOC isn't set (then set EX_DOC before generating docs)

I think I prefer "1." but maybe "2." is desirable because you only need ex_doc to build the documentation.

[chiroptical]

Okay, I am a goofball. We can just rewrite ex_doc_wrapper into erlang! That way we can just run it with escript. Testing now.

[garazdawi]

In #8596 i tried to solve this problem. Can you have a look and see if it works?

[garazdawi]

Fixed in #8596