Provide custom environment to assist with custom aux-/output-directory

If custom "aux_directory" or "output_directory" is specified, help toolchain
finding resources in TeX document's directory structure via custom environment
variables.

It simplifies execution of `bibtex` in basic builder or script builder, as
required environment is already set-up.

Even latexmk requires it to properly create bibliography, if -output-directory
is specified.

Author: deathaxe

docs/buildsystem.md

@@ -287,27 +287,25 @@ If [auxiliary or output directory settings](settings.md#output-directory-setting
 **BibTeX**
 
 Unlike biber, bibtex (and bibtex8) does not support an output directory parameter.
-The following workaround can be used to run BibTeX _inside_ the output / auxiliary directory while making the directory containing your main file available to the `BIBINPUTS` environment variable.
+The following workaround can be used to run BibTeX _inside_ the output / auxiliary directory.
 
 ```json
 {
 	"builder_settings": {
 		"linux": {
 			"script_commands": [
-				"cd $output_directory; BIBINPUTS=\"$file_path;$BIBINPUTS\" bibtex \"$file_base_name\"",
+				"cd $output_directory; bibtex \"$file_base_name\"",
 			]
 		},
 		"windows": {
 			"script_commands": [
-				"cd $output_directory & set BIBINPUTS=\"$file_path:%BIBINPUTS%\" & bibtex \"$file_base_name\""
+				"cd $output_directory & bibtex \"$file_base_name\""
 			]
 		}
 	}
 }
 ```
 
-**Note:** If a custom style file is used in the same directory, a similar work-around for `BSTINPUTS` environment variable needs to be applied.
-
 ### Job Name
 
 If jobname behaviour is used, `$jobname` is to be passed to relevant commands. In particular, a standard build cycle might look something like this:
@@ -556,6 +554,22 @@ class SimpleBuilder(PdfBuilder):
 
 ### Reference
 
+#### Environment
+
+If `aux_directory` or `output_directory` are specified, [$file_path](#expandable-variables) is prepended to relevant environment variables, to ensure resources are looked up relative to main TeX document's location, regardless effective working directory. 
+
+**MikTeX**
+
+Document location is assigned to `TEXINPUTS`, `BIBINPUTS`, `BSTINPUTS`
+
+**Note:** Specified values are prepended to existing variables and configurations by MikTeX.
+
+**TeXLive**
+
+Document location is assigned to `TEXMFDOTDIR`, which is prepended to all path environment variables.
+
+**Note:** Customized `TEXINPUTS`, `BIBINPUTS`, `BSTINPUTS` variables replace any other configured path in TexLive. Hence it is not recommended to customize them, directly.
+
 #### Expandable Variables
 
 The `PdfBuilder` defines an `expandvars(template: str)` method, which can be called to expand following variables in strings.

latextools/system_check.py

@@ -13,7 +13,7 @@
 from functools import lru_cache
 from functools import partial
 from shutil import which
-from typing import Callable
+from typing import cast, Callable
 
 import sublime
 import sublime_plugin
@@ -130,7 +130,7 @@ def __init__(self, view: sublime.View, on_done: Callable[[list[list]], None]):
         #  CAUTION: logic must match make_pdf's logic
         self.env = os.environ.copy()
 
-        self.builder_settings = get_setting("builder_settings", {}, view)
+        self.builder_settings = cast(dict, get_setting("builder_settings", {}, view))
         self.builder_platform_settings = self.builder_settings.get(self.platform, {})
         build_env = self.builder_platform_settings.get("env")
         if build_env is None:
@@ -141,6 +141,21 @@ def __init__(self, view: sublime.View, on_done: Callable[[list[list]], None]):
         if (texpath := get_texpath(view)) is not None:
             self.env["PATH"] = texpath
 
+        # prepand main tex document's location to all TeX related paths such as
+        # TEXINPUTS, BIBINPUTS, BSTINPUTS, etc.
+        self.tex_root = get_tex_root(self.view)
+        if self.tex_root:
+            tex_dir = os.path.dirname(self.tex_root)
+            if self.uses_miktex:
+                # MikTeX, prepends custom variables to its configuration.
+                env_vars = ("TEXINPUTS", "BIBINPUTS", "BSTINPUTS")
+            else:
+                # TeXLive overwrites its configuration with custom variables.
+                # Hence set `TEXMFDOTDIR`, which is prepended to all of them.
+                env_vars = ("TEXMFDOTDIR",)
+            for key in env_vars:
+                self.env[key] = os.pathsep.join(filter(None, (tex_dir, self.env.get(key))))
+
     def run(self):
         with ActivityIndicator("Checking system...") as activity_indicator:
             self.worker()
@@ -153,8 +168,10 @@ def worker(self):
 
         table.append(["PATH", self.env.get("PATH", "")])
 
-        for var in ("TEXINPUTS", "BIBINPUTS", "BSTINPUTS"):
-            table.append([var, self.get_tex_path_variable(var) or "missing"])
+        table.extend(
+            [var, self.get_tex_path_variable(var) or "missing"]
+            for var in ("TEXINPUTS", "BIBINPUTS", "BSTINPUTS")
+        )
 
         if self.uses_miktex:
             for var in (
@@ -339,12 +356,11 @@ def worker(self):
         # is current view a TeX file?
         view = self.view
         if view and view.match_selector(0, "text.tex.latex"):
-            tex_root = get_tex_root(view)
             tex_directives = parse_tex_directives(
-                tex_root, multi_values=["options"], key_maps={"ts-program": "program"}
+                self.tex_root, multi_values=["options"], key_maps={"ts-program": "program"}
             )
 
-            results.append([["TeX Root"], [tex_root]])
+            results.append([["TeX Root"], [self.tex_root]])
 
             results.append(
                 [
@@ -361,7 +377,7 @@ def worker(self):
             if aux_directory:
                 table.append(["aux_directory", aux_directory])
             jobname = get_jobname(view)
-            if jobname and jobname != os.path.splitext(os.path.basename(tex_root))[0]:
+            if jobname and jobname != os.path.splitext(os.path.basename(self.tex_root))[0]:
                 table.append(["jobname", jobname])
 
             if len(table) > 1:

plugins/builder/basic_builder.py

@@ -105,9 +105,15 @@ def commands(self) -> CommandGenerator:
 
         if run_bibtex:
             if use_bibtex:
+                # set-up bibtex cmd line
+                if bibtex is None:
+                    bibtex = [self.builder_settings.get("bibtex", "bibtex")]
+                elif isinstance(bibtex, str):
+                    bibtex = [bibtex]
+                bibtex.append(self.job_name)
                 yield (
-                    self.run_bibtex(bibtex),
-                    f"running {bibtex or 'bibtex'}...",
+                    self.command(bibtex, cwd=self.aux_directory_full or self.tex_dir),
+                    f"running {bibtex[0]}..."
                 )
             else:
                 yield (biber + [self.job_name], "running biber...")
@@ -122,24 +128,3 @@ def commands(self) -> CommandGenerator:
             yield (latex, f"running {engine}...")
 
         self.copy_assets_to_output()
-
-    def run_bibtex(self, cmd: CommandLine | None=None) -> Command:
-        # set-up bibtex cmd line
-        if cmd is None:
-            cmd = [self.builder_settings.get("bibtex", "bibtex")]
-        elif isinstance(cmd, str):
-            cmd = [cmd]
-        cmd.append(self.job_name)
-
-        # return default command line, if build output is tex_dir.
-        if not self.aux_directory:
-            return cmd
-
-        # to get bibtex to work with the output directory, we change the
-        # cwd to the output directory and add the main directory to
-        # BIBINPUTS and BSTINPUTS
-        env = self.env.copy()
-        # cwd is, at the point, the path to the main tex file
-        env["BIBINPUTS"] = self.tex_dir + os.pathsep + env.get("BIBINPUTS", "")
-        env["BSTINPUTS"] = self.tex_dir + os.pathsep + env.get("BSTINPUTS", "")
-        return self.command(cmd, cwd=self.aux_directory_full, env=env)

plugins/builder/pdf_builder.py

@@ -122,6 +122,18 @@ def __init__(
         self.builder_settings = builder_settings
         self.platform_settings = platform_settings
 
+        self.display_log = self.builder_settings.get("display_log", False)
+        """
+        Specifies whether to display detailed command output in log panel.
+
+        Value of `builder_settings: { display_log: ... }` setting
+        """
+
+        distro = self.platform_settings.get("distro", "")
+        self.uses_miktex = (
+            distro != "texlive" if sublime.platform() == "windows" else distro == "miktex"
+        )
+
         # if output_directory and aux_directory can be specified as a path
         # relative to self.tex_dir, we use that instead of the absolute path
         # note that the full path for both is available as
@@ -150,12 +162,20 @@ def __init__(
         if self.output_directory:
             os.makedirs(self.output_directory_full, exist_ok=True)
 
-        self.display_log = self.builder_settings.get("display_log", False)
-        """
-        Specifies whether to display detailed command output in log panel.
-
-        Value of `builder_settings: { display_log: ... }` setting
-        """
+        # Help latex toolchain find resources by prepending TeX document's location to popular
+        # environment variables. Even latexmk requires it to properly build bibliography.
+        if self.aux_directory or self.output_directory:
+            if env is None:
+                env = os.environ.copy()
+            if self.uses_miktex:
+                # MikTeX, prepends custom variables to its configuration.
+                env_vars = ("TEXINPUTS", "BIBINPUTS", "BSTINPUTS")
+            else:
+                # TeXLive overwrites its configuration with custom variables.
+                # Hence set `TEXMFDOTDIR`, which is prepended to all of them.
+                env_vars = ("TEXMFDOTDIR",)
+            for key in env_vars:
+                env[key] = os.pathsep.join(filter(None, (self.tex_dir, env.get(key))))
 
         # finally expand variables in custom environment
         self.env = {k: self.expandvars(v) for k, v in env.items()} if env else None