Method for accessing certain bindings not mentioned in JPM docs

[sogaiu]

This issue is a reminder to consider adding some docs to mention how to access top-level bindings from a main.janet file used to build an executable. See the references below for more details.

One possible location to add documentation is here.

---

References:

• How do I include REPL with current environment into the binary?
• Build executable with script load facility
• #general > Add new sample of static build @ 💬

[sogaiu]

Some of the existing paragraphs from the linked section above include:

It's important to remember that code at the top level will run when you invoke jpm build, not at executable runtime. This is because in order to create the executable, we marshal the main function of the app and write it to an image. In order to create the main function, we need to actually compile and run everything that it references, in the above case mylib1 and mylib2.

This has a number of benefits, but the largest is that we only include bytecode for the functions that our application uses. If we only use one function from a library of 1000 functions, our final executable will not include the bytecode for the other 999 functions (unless our one function references some of those other functions, of course). This feature, called tree-shaking, only works for Janet code. Native modules will be linked to the final executable statically in full if they are used at all. A native module is considered "used" if is imported at any time during jpm build. This may change, but it is currently the most reliable way to check if a native modules needs to be linked into the final executable.

There are some limitations to this approach. Any dynamically required modules will not always be linked into the final executable. If require or import is not called during jpm build, then the code will not be linked into the executable. The module can still be required if it is available at runtime, though.

One idea is to append a paragraph after the last one above to mention that access to bindings other than main in main.janet can be achieved by having main reference some or all of those bindings. We could provide sample code as well demonstrating that.

We might consider making use of or referring to the existing sentence:

unless our one function references some of those other functions, of course

---

# script.janet

(print pose)

(mylib1/do-thing)

# main.janet

(import mylib1)

(def pose :sit)

(def my-env (curenv))

(defn main
  [& args]
  # 1. `my-env` is referenced in `main` (i.e. this function;
  #    see the `dofile` call below) so `my-env`'s bytecode is
  #    included in the final executable.

  # 2. `my-env` refers to `mylib1/do-thing` (imported above)
  #    and `pose` (defined above) as they are part of the
  #    current environment during `jpm build`.

  # 3. `dofile` evaluates script.janet using `my-env` as an
  #    environment so it has access to `mylib1/do-thing` and
  #    `pose`.  Thus, those two bindings are available for use
  #    within script.janet (see code above).
  (dofile "script.janet" :env my-env))

[sogaiu]

There seems to be a typo in:

A native module is considered "used" if is imported at any time during jpm build.

May as well change this to:

A native module is considered "used" if it is imported at any time during jpm build.

if a PR is going to be submitted.

[sogaiu]

Here's a draft:

diff --git a/content/jpm/project.janet.mdz b/content/jpm/project.janet.mdz
index bc7d28d..e668bf9 100644
--- a/content/jpm/project.janet.mdz
+++ b/content/jpm/project.janet.mdz
@@ -98,6 +98,8 @@ variable number of parameters, the command-line arguments. It will be called as
 the entry point to your executable.
 
 @codeblock[janet]```
+# main.janet
+
 (import mylib1)
 (import mylib2)
 
@@ -125,7 +127,7 @@ library of 1000 functions, our final executable will not include the bytecode
 for the other 999 functions (unless our one function references some of those
 other functions, of course). This feature, called tree-shaking, only works
 for Janet code. Native modules will be linked to the final executable statically
-in full if they are used at all. A native module is considered "used" if is
+in full if they are used at all. A native module is considered "used" if it is
 imported at any time during @code`jpm build`. This may change, but it is
 currently the most reliable way to check if a native modules needs to be linked
 into the final executable.
@@ -139,6 +141,48 @@ at runtime, though.
 For an example Janet executable built with @code`jpm`, see
 @link[https://github.com/bakpakin/littleserver][https://github.com/bakpakin/littleserver].
 
+For another example that allows access to bindings defined in
+@code`main.janet` in a script passed to the corresponding built
+executable:
+
+@codeblock[janet]```
+# main.janet
+
+(import mylib1)
+
+(def pose :sit)
+
+(def my-env (curenv))
+
+(defn main
+  [& args]
+  (def script-path (get args 1))
+  (dofile script-path :env my-env))
+```
+
+In order to retain access to @code`mylib1/do-thing` and @code`pose` at
+the executable's runtime:
+
+@ul{@li{@p{@code`main.janet` binds @code`my-env` at the top level to
+           the return value of @code`(curenv)`, which essentially
+           captures bindings related to @code`mylib1` and
+           @code`pose`.}}
+
+   @li{@p{@code`my-env` is referenced in the @code`main` function (in
+           the call to @code`dofile`) to prevent being "tree-shaken"
+           during @code`jpm build`.}}}
+
+If the built executable is passed a script, the script can
+refer to @code`mylib1/do-thing` and @code`pose`:
+
+@codeblock[janet]```
+# script.janet
+
+(print pose)
+
+(mylib1/do-thing)
+```
+
 ### Other @code`declare-` callables
 
 Some additional @code`declare-` callables are:

[dmitrys99]

Changes look reasonable.