fmtutil/tlutils: fixes from Karl: wording/doc, better dry-runmerged/fmtutil-improvements

2 files changed, 88 insertions, 64 deletions

diff --git a/Master/texmf-dist/scripts/texlive/fmtutil.pl b/Master/texmf-dist/scripts/texlive/fmtutil.pl
index 03785755c3a..2248c2040a4 100755
--- a/Master/texmf-dist/scripts/texlive/fmtutil.pl
+++ b/Master/texmf-dist/scripts/texlive/fmtutil.pl
@@ -59,6 +59,7 @@ my $sep = (win32() ? ';' : ':');
 
 my @deferred_stderr;
 my @deferred_stdout;
+# $::opt_verbosity = 3; # manually enable debugging
 
 my $first_time_creation_in_usermode = 0;
 
@@ -122,7 +123,7 @@ our @cmdline_options = (  # in same order as help message
   "sys",
   "user",
   "cnffile=s@", 
-  "dry-run=n",
+  "dry-run|n",
   "fmtdir=s",
   "no-engine-subdir",
   "no-error-if-no-engine=s",
@@ -171,8 +172,11 @@ sub main {
     $opts{'user'} = 1;
 
     my @save_argv = @ARGV;
-    GetOptions ( "help" => \$opts{'help'}, "version" => \$opts{'version'} )
-      || die "$prg: Unknown option in mktexfmt command line: @save_argv\n";
+    GetOptions (
+      "dry-run|n", \$opts{'dry-run'},
+      "help" => \$opts{'help'},
+      "version" => \$opts{'version'}
+      ) || die "$prg: Unknown option in mktexfmt command line: @save_argv\n";
 
     help() if $opts{'help'};
     if ($opts{'version'}) {
@@ -374,39 +378,43 @@ sub callback_build_formats {
   # On W32 it seems that File::Temp creates restrictive permissions (ok)
   # that are copied over with the files created inside it (not ok).
   # So make our own temp dir.
-  my $tmpdir;
-  if (win32()) {
-    my $foo;
-    my $tmp_deflt = File::Spec->tmpdir;
-    for my $i (1..5) {
-      # $foo = "$texmfvar/temp.$$." . int(rand(1000000));
-      $foo = (($texmfvar =~ m!^//!) ? $tmp_deflt : $texmfvar)
-        . "/temp.$$." . int(rand(1000000));
-      if (! -d $foo) {
-        TeXLive::TLUtils::mkdirhier($foo);
-        sleep 1;
-        if (-d $foo) {
-          $tmpdir = $foo;
-          last;
+  my $tmpdir = "";
+  if (! $opts{"dry-run"}) {
+    if (win32()) {
+      my $foo;
+      my $tmp_deflt = File::Spec->tmpdir;
+      for my $i (1..5) {
+        # $foo = "$texmfvar/temp.$$." . int(rand(1000000));
+        $foo = (($texmfvar =~ m!^//!) ? $tmp_deflt : $texmfvar)
+          . "/temp.$$." . int(rand(1000000));
+        if (! -d $foo) {
+          TeXLive::TLUtils::mkdirhier($foo);
+          sleep 1;
+          if (-d $foo) {
+            $tmpdir = $foo;
+            last;
+          }
         }
       }
+      if (! $tmpdir) {
+        die "Cannot get a temporary directory after five iterations, sorry!";
+      }
+      if ($texmfvar =~ m!^//!) {
+        # used File::Spec->tmpdir; fix permissions
+        TeXLive::TLWinGoo::maybe_make_ro ($tmpdir);
+      }
+    } else {
+      $tmpdir = File::Temp::tempdir(CLEANUP => 1);
     }
-    if (! $tmpdir) {
-      die "Cannot get a temporary directory after five iterations ... sorry!";
-    }
-    if ($texmfvar =~ m!^//!) {
-      # used File::Spec->tmpdir; fix permissions
-      TeXLive::TLWinGoo::maybe_make_ro ($tmpdir);
-    }
-  } else {
-    $tmpdir = File::Temp::tempdir(CLEANUP => 1);
   }
   # set up destination directory
   $opts{'fmtdir'} ||= "$texmfvar/web2c";
-  TeXLive::TLUtils::mkdirhier($opts{'fmtdir'}) if (! -d $opts{'fmtdir'});
-  if (! -w $opts{'fmtdir'}) {
-    print_error("format directory not writable: $opts{fmtdir}\n");
-    exit 1;
+  if (! $opts{"dry-run"}) {
+    TeXLive::TLUtils::mkdirhier($opts{'fmtdir'}) if (! -d $opts{'fmtdir'});
+    if (! -w $opts{'fmtdir'}) {
+      print_error("format directory not writable: $opts{fmtdir}\n");
+      exit 1;
+    }
   }
   # since the directory does not exist, we can make it absolute with abs_path
   # without any trickery around non-existing dirs
@@ -430,7 +438,8 @@ sub callback_build_formats {
   $ENV{'TEXFORMATS'} = "$tmpdir$sep$ENV{TEXFORMATS}";
 
   # switch to temporary directory for format generation
-  chdir($tmpdir) || die "Cannot change to directory $tmpdir: $!";
+  $opts{"dry-run"} || chdir($tmpdir)
+  || die "Cannot change to directory $tmpdir: $!";
   
   # we rebuild formats in two rounds:
   # round 1: only formats with the same name as engine (pdftex/pdftex)
@@ -783,7 +792,7 @@ sub rebuild_one_format {
 
     # Copy the log file after the program is run, so that the log file
     # is available to inspect even on failure. So we need the dest dir tree.
-    TeXLive::TLUtils::mkdirhier($destdir);
+    TeXLive::TLUtils::mkdirhier($destdir) if ! $opts{"dry-run"};
     #
     # Here and in the following we use copy instead of move
     # to make sure that in SElinux enabled cases the rules of
@@ -792,7 +801,8 @@ sub rebuild_one_format {
     if (File::Copy::copy($logfile, "$destdir/$logfile")) {
       print_info("log file copied to: $destdir/$logfile\n");
     } else {
-      print_deferred_error("cannot copy log $logfile to: $destdir\n");
+      print_deferred_error("cannot copy log $logfile to: $destdir\n")
+        unless $opts{"dry-run"};
     }
 
     # original shell script did *not* check the return value
@@ -1399,7 +1409,7 @@ sub help {
 Usage: $prg      [-user|-sys] [OPTION] ... [COMMAND]
    or: $prg-sys  [OPTION] ... [COMMAND]
    or: $prg-user [OPTION] ... [COMMAND]
-   or: mktexfmt  FORMAT.fmt|BASE.base|FMTNAME.EXT
+   or: mktexfmt  FORMAT.fmt|BASE.base|FMTNAME
 
 Rebuild and manage TeX fmts and Metafont bases, collectively called
 "formats" here. (MetaPost no longer uses the past-equivalent "mems".)
@@ -1412,7 +1422,8 @@ If the command name ends in mktexfmt, only one format can be created.
 The only options supported are --help and --version, and the command
 line must be either a format name, with extension, or a plain name that
 is passed as the argument to --byfmt (see below).  The full name of the
-generated file (if any) is written to stdout, and nothing else.
+generated file (if any) is written to stdout, and nothing else.  The
+system directories are used if they are writable, else the user directories.
 
 By default, the return status is zero if all formats requested are
 successfully built, else nonzero.
@@ -1461,7 +1472,7 @@ Explanation of trees and files normally used:
 
   If --cnffile is specified on the command line (possibly multiple
   times), its value(s) are used.  Otherwise, fmtutil reads all the
-  fmtutil.cnf files found by running \`kpsewhich -all fmtutil.cnf', in the
+  fmtutil.cnf files found by running "kpsewhich -all fmtutil.cnf", in the
   order returned by kpsewhich.  Files specified via --cnffile are
   first tried to be loaded directly, and if not found and the file names
   don't contain directory parts, are searched via kpsewhich.
@@ -1490,21 +1501,22 @@ Explanation of trees and files normally used:
   
   (where YYYY is the TeX Live release version).
   
-  According to the actions, fmtutil might write to one of the given files
-  or create a new fmtutil.cnf, described further below.
+  According to the actions, fmtutil might update one of the existing cnf
+  files or create a new fmtutil.cnf, as described below.
 
-Where formats are written:
-  
-  By default, format files are (re)written in TEXMFSYSVAR/ENGINE by
-  fmtutil-sys, and TEXMFVAR/ENGINE by fmtutil-user, where /ENGINE is a
-  subdirectory named for the engine used, such as "pdftex".  For
-  mktexfmt, TEXMFSYSVAR is used if it is writable, else TEXMFVAR.
+Where format files are written:
+
+  By default, format files are (re)written in \$TEXMFSYSVAR/ENGINE by
+  fmtutil-sys, and \$TEXMFVAR/ENGINE by fmtutil-user, where /ENGINE is
+  a subdirectory named for the engine used, such as "pdftex".
+
+  For mktexfmt, TEXMFSYSVAR is used if it is writable, else TEXMFVAR.
   
   If the --fmtdir=DIR option is specified, DIR is used instead of
   TEXMF[SYS]VAR, but the /ENGINE subdir is still used by default.
   
-  If the --no-engine-subdir option is specified, the /ENGINE subdir is
-  omitted in all cases.
+  In all cases, if the --no-engine-subdir option is specified, the
+  /ENGINE subdir is omitted.
   
 Where configuration changes are saved: 
 
@@ -1525,7 +1537,7 @@ Where configuration changes are saved:
   In general, the idea is that if a given config file is not writable, a
   higher-level one can be used.  That way, the distribution's settings
   can be overridden system-wide using TEXMFLOCAL, and system settings
-  can be overridden again in a particular user's TEXMFHOME.
+  can be overridden again in a particular user's TEXMFHOME or TEXMFCONF.
 
 Resolving multiple definitions of a format:
 
@@ -1536,11 +1548,11 @@ Disabling formats:
 
   fmtutil.cnf files with higher priority (listed earlier) can disable
   formats in lower priority (listed later) fmtutil.cnf files by
-  writing a line like
+  writing a line like this in the higher-priority fmtutil.cnf file:
     \#! <fmtname> <enginename> <hyphen> <args>
-  in the higher-priority fmtutil.cnf file.   The \#! must be at the
-  beginning of the line, with at least one space or tab afterward, and
-  there must be whitespace between each word on the list.
+  The \#! must be at the beginning of the line, with at least one space
+  or tab afterward, and there must be whitespace between each word on
+  the list.
 
   For example, you can disable the luajitlatex format by creating
   the file \$TEXMFCONFIG/web2c/fmtutil.cnf with the line
@@ -1561,7 +1573,7 @@ fmtutil-user (fmtutil -user) vs. fmtutil-sys (fmtutil -sys):
   Other locations may be used if you give them on the command line, or
   these trees don't exist, or you are not using the original TeX Live.
 
-Supporting development binaries
+Supporting development binaries:
 
   If an engine name ends with "-dev", formats are created in
   the respective directory with the -dev stripped.  This allows for
diff --git a/Master/tlpkg/TeXLive/TLUtils.pm b/Master/tlpkg/TeXLive/TLUtils.pm
index 4bc22da9fec..128902db921 100644
--- a/Master/tlpkg/TeXLive/TLUtils.pm
+++ b/Master/tlpkg/TeXLive/TLUtils.pm
@@ -4585,7 +4585,11 @@ sub mktexupd {
 }
 
 
-=item C<setup_sys_user_mode($user,$sys,$tmfc, $tmfsc, $tmfv, $tmfsv)>
+=item C<setup_sys_user_mode($prg, $optsref, $tmfc, $tmfsc, $tmfv, $tmfsv)>
+
+Return two-element list C<($texmfconfig,$texmfvar)> of which directories
+to use, either user or sys. If C<$prg> is C<mktexfmt>, and the system
+dirs are writable, use them even if we are in user mode.
 
 =cut
 
@@ -4613,7 +4617,8 @@ sub setup_sys_user_mode {
       exit(1);
     }
     if (!$optsref->{'sys'}) {
-      print STDERR "$prg [WARNING]: hidden sys mode found, switching to sys mode.\n" if (!$optsref->{'quiet'});
+      print STDERR "$prg [WARNING]: hidden sys mode found, switching to sys mode.\n"
+        if (!$optsref->{'quiet'});
       $optsref->{'sys'} = 1;
     }
   }
@@ -4623,15 +4628,21 @@ sub setup_sys_user_mode {
     # we are running as updmap-sys, make sure that the right tree is used
     $texmfconfig = $TEXMFSYSCONFIG;
     $texmfvar    = $TEXMFSYSVAR;
+    &debug("TLUtils::setup_sys_user_mode: sys mode\n");
+
   } elsif ($optsref->{'user'}) {
     $texmfconfig = $TEXMFCONFIG;
     $texmfvar    = $TEXMFVAR;
-    # mktexfmt is often run accidentally by a user with missing formats
-    # and the resulting format dumps are put into TEXMFVAR, which is
-    # one of the most common source of problems.
-    # Only for mktexfmt (but not for fmtutil, which would need to be called
-    # explicitely with fmtutil -user) we check whether TEXMFSYSVAR is writable
-    # and if yes, create formats there.
+    &debug("TLUtils::setup_sys_user_mode: user mode\n");
+
+    # mktexfmt is run (accidentally or on purpose) by a user with
+    # missing formats; we want to put the resulting format dumps in
+    # TEXMFSYSVAR if possible, so that future format updates will just
+    # work. Until 2021, they were put in TEXMFVAR, causing problems.
+    # 
+    # We only do this for mktexfmt, not fmtutil; if fmtutil is called
+    # explicitly with fmtutil -user, ok, do what they said to do.
+    #
     if ($prg eq "mktexfmt") {
       my $switchit = 0;
       if (-d "$TEXMFSYSVAR/web2c") {
@@ -4640,18 +4651,19 @@ sub setup_sys_user_mode {
         $switchit = 1;
       }
       if ($switchit) {
-        # inform about switch, but not for mktexfmt which expects output to be only the format
-        $prg eq "mktexfmt" || info("$prg: using TEXMFSYSVAR instead of TEXMFVAR since it is writable!\n");
-        $texmfvar    = $TEXMFSYSVAR;
+        $texmfvar = $TEXMFSYSVAR;
+        &ddebug("  switched to $texmfvar for mktexfmt\n");
       }
     }
   } else {
-    print STDERR "" .
+    print STDERR
       "$prg [ERROR]: Either -sys or -user mode is required.\n" .
       "$prg [ERROR]: In nearly all cases you should use $prg -sys.\n" .
       "$prg [ERROR]: For special cases see https://tug.org/texlive/scripts-sys-user.html\n" ;
     exit(1);
   }
+
+  &debug("  returning: ($texmfconfig,$texmfvar)\n");
   return ($texmfconfig, $texmfvar);
 }