Debian Codegraph @

texmf-dist/doc/generic/memoize/memoize-doc.latexmkrc

raw
1 $pdf_mode = 1;
2 $pdflatex = "lualatex %O %S";
3 $bibtex = 0;
4 $do_cd = 1;
5 $silent = 1;
6 $max_repeat = 6; # we need six cycles for a fresh compilation with memoization
7
8 push @generated_exts, "cpt";
9 push @generated_exts, "mmz";
10 push @generated_exts, "memo";
11 push @generated_exts, "listing";
12
13 ######################################################################
14 ### from <texmf>/doc/support/latexmk/example_rcfiles/memoize_latexmkrc
15 ### with partially silenced output and
16 ### memoize-extract.pl --> memoize-extract.py, because the perl-based
17 ### extraction chokes on some externs.
18
19 #print "============= I am memoize's latexmkrc. John Collins 2024-03-29\n";
20
21 # This rc file shows how to use latexmk with the memoize package.
22 #
23 # The memoize package (https://www.ctan.org/pkg/memoize) implements
24 # externalization and memoization of sections of code in a TeX document.
25 # It allows the compilation of the document to reuse results of
26 # compilation-intensive code, with a consequent speeding up of runs of
27 # *latex. Such compilation intensive code is commonly encountered, for
28 # example, in making pictures by TikZ.
29 #
30 # When a section of code to be memoized is encountered, an extra page is
31 # inserted in the document's pdf file containing the results of the
32 # compilation of the section of code. Then a script, memoize-extract.pl or
33 # memoize-extract.py, is run to extract the extra parts of the the
34 # document's pdf file to individual pdf files (called externs). On the
35 # next compilation by *latex, those generated pdf files are used in place
36 # of actually compiling the corresponding code (unless the section of code
37 # has changed).
38 #
39 # This latexmkrc file supports this process by configuring latexmk so that
40 # when a compilation by *latex is done, a memoize-extract script is run
41 # immediately afterwards. If any new externs are generated, latexmk
42 # notices that and triggers a new compilation, as part of its normal mode
43 # of operation.
44 #
45 # The memoize package itself also runs memoize-extract at the start of each
46 # compilation. If latexmk has already run memoize-extract, that extra run
47 # of memoize-extract finds that it has nothing to do. The solution here is
48 # more general: (a) It handles the case where the memoize package is
49 # invoked in the .tex file with the external=no option. (b) It handles the
50 # situation where the aux and out directories are different, which is not
51 # the case for the built-in invocation. (c) It nicely matches with
52 # latexmk's general methods of determining how many runs of *latex are
53 # needed.
54 #
55 # Needs latexmk v. >= 4.84, memoize >= 1.2.0 (2024/03/15).
56 # TeX Live 2024 (or later, presumably).
57 # Tested on TeX Live 2024 on macOS, Ubuntu, Windows,
58 # with pdflatex, lualatex, and xelatex.
59 # Needs perl module PDF::API2 to be installed.
60 # On TeXLive on Windows, also put
61 # TEXLIVE_WINDOWS_TRY_EXTERNAL_PERL = 1
62 # in the texmf.cnf file in the root directory of the TeX Live installation.
63
64 # ==> However, there are some anomalies on Windows, which haven't been sorted out
65 # yet. These notably concern memoize-clean
66 #
67 # ==> Fails on MiKTeX on Windows: memoize-extract refuses to create pdf file????
68 # I haven't yet figured out the problem.
69 # ==> Also trouble on MiKTeX on macOS: the memoize-extract.pl.exe won't run.
70
71 # You can have separate build and output directories, e.g., by
72 #$out_dir = 'output';
73 #$aux_dir = 'build';
74 # or they can be the same, e.g., by
75 # $out_dir = $aux_dir = 'output';
76
77
78 # Which program and extra options to use for memoize-extract and memoize-clean.
79 # Note that these are arrays, not simple strings.
80 our @memoize_extract = ( 'memoize-extract.py' );
81 our @memoize_clean = ( 'memoize-clean.py' );
82
83 # Specification of the basic memoize files to delete in a clean-up
84 # operation. The generated .memo and .pdf files have more specifications,
85 # and we use memoize-clean to delete those, invoked by a cleanup hook.
86 push @generated_exts, 'mmz', 'mmz.log';
87
88 # Subroutine mmz_analyzes analyzes .mmz file, if it exists **and** was
89 # generated in current compilation, to determine whether there are new
90 # extern pdfs to be generated from memo files and pdf file. Communicate
91 # to subtroutine mmz_extract_new a need to make new externs by setting the
92 # variable to a non-zero value for $mmz_has_new. Let the value be the
93 # name of the mmz file; this is perhaps being too elaborate, since the
94 # standard name of the mmz file can be determined
95
96 add_hook( 'after_xlatex_analysis', \&mmz_analyze );
97 add_hook( 'after_main_pdf', \&mmz_extract_new );
98
99 # !!!!!!!!!!!!!!!!!!!! Uncomment the following line **only** if you really
100 # want latexmk's cleanup operations to delete Memoize's memoization
101 # files. In a document where these files are time-consuming to make, i.e.,
102 # in the main use case for the memoize package, the files are precious and
103 # should only need deleted when that is really needed.
104 #
105 # add_hook( 'cleanup', \&mmz_cleanup );
106
107 # Whether there are new externs to be made:
108 my $mmz_has_new = '';
109 # Scope of this variable: private, from here to end of file.
110
111
112 #-----------------------------------------------------
113
114 sub mmz_analyze {
115 use strict;
116 #print "============= I am mmz_analyze \n";
117 #print " Still to deal with provoking of rerun if directory made\n";
118
119 # Analyzes mmz file if generated on this run.
120 # Then 1. Arranges to trigger making of missing extern pdfs, if needed.
121 # 2. Sets dependencies on the extern pdfs. This ensures that, in
122 # the case that one or more extern pdfs does not currently
123 # exist, a rerun of *latex will triggered after it/they get
124 # made.
125 # Return zero on success (or nothing to do), and non-zero otherwise.
126
127 # N.B. Current (2024-03-11) hook implementation doesn't use return
128 # values from hook subroutines. Future implementation might.
129 # So I'll provide a return value.
130
131 my $base = $$Pbase;
132 my $mmz_file = "$aux_dir1$base.mmz";
133
134 # Communicate to subroutine mmz_extract_new about whether new extern
135 # pdf(s) are to be made. Default to assuming no externs are to be
136 # made:
137 $mmz_has_new = '';
138
139 if (! -e $mmz_file) {
140 #print "mmz_analyze: No mmz file '$mmz_file', so memoize is not being used.\n";
141 return 0;
142 }
143
144 # Use (not-currently-documented) latexmk subroutine to detemine
145 # whether mmz file was generated in current run:
146 if ( ! test_gen_file_time( $mmz_file) ) {
147 warn "mmz_analyze: Mmz file '$mmz_file' exists, but wasn't generated\n",
148 " on this run so memoize is not **currently** being used.\n";
149 return 0;
150 }
151
152 # Get dependency information.
153 # We need to cause not-yet-made extern pdfs to be trated as source
154 # files for *latex.
155 my $mmz_fh = undef;
156 if (! open( $mmz_fh, '<', $mmz_file ) ) {
157 warn "mmz_analyze: Mmz file '$mmz_file' exists, but I can't read it:\n",
158 " $!\n";
159 return 1;
160 }
161 my @externs = ();
162 my @dirs = ();
163 while ( <$mmz_fh> ) {
164 s/\s*$//; # Remove trailing space, including new lines
165 if ( /^\\mmzNewExtern\s+{([^}]+)}/ ) {
166 # We have a new memo item without a corresponding pdf file.
167 # It will be put in the aux directory.
168 my $file = "$aux_dir1$1";
169 #print "mmz_analyze: new extern for memoize: '$file'\n";
170 push @externs, $file;
171 }
172 elsif ( /^\\mmzPrefix\s+{([^}]+)}/ ) {
173 # Prefix.
174 my $prefix = $1;
175 if ( $prefix =~ m{^(.*)/[^/]*} ) {
176 my $dir = $1;
177 push @dirs, "$aux_dir1$1";
178
179 }
180 }
181 }
182 close $mmz_fh;
183 foreach (@dirs) {
184 if ( ! -e ) {
185 my @cmd = ( @memoize_extract, '--mkdir', $_ );
186 print "mmz_analyze: Making directory '$_' safely by running\n",
187 " @cmd\n";
188 mkdir $_;
189 }
190 }
191
192 rdb_ensure_files_here( @externs );
193
194 # .mmz.log is read by Memoize package after it does an internal
195 # extract, so it appears as an INPUT file in .fls. But it was created
196 # earlier in the same run by memoize-extract, so it's not a true
197 # dependency, and should be removed from the list of source files:
198 rdb_remove_files( $rule, "$mmz_file.log" );
199
200 if (@externs ) {
201 $mmz_has_new = $mmz_file;
202 }
203 return 0;
204 }
205
206 #-----------------------------------------------------
207
208 sub mmz_extract_new {
209 use strict;
210 #print "============= I am mmz_extract_new \n";
211
212 # If there are new extern pdf files to be made, run memoize-extract to
213 # make them.
214 # Situation on entry:
215 # 1. I'm in the context of a rule for making the document's pdf file.
216 # When new extern pdf files are to be made, the document's pdf
217 # file contains the pages to be extracted by memoize-extract.
218 # Given the rule context, the name of the document's pdf file is
219 # $$Pdest.
220 # 2. $mmz_has_new was earlier set to the name of the mmz file with
221 # the information on the files used for memoization, but only if
222 # there are new extern pdf(s) to be made.
223 # 3. If it is empty, then no extern pdfs are to be made. This covers
224 # the case that the memoize package isn't being used.
225 # Return zero on success (or nothing to do), and non-zero otherwise.
226
227 if ( $mmz_has_new eq '' ) { return 0; }
228
229 my $mmz_file = $mmz_has_new;
230 my ($mmz_file_no_path, $path) = fileparse( $mmz_file );
231 my $pdf_file = $$Pdest;
232
233 # The directory used by memoize-extract for putting the generated
234 # extern pdfs is passed in the TEXMF_OUTPUT_DIRECTORY environment
235 # variable. (The need for this way of passing information is
236 # associated with some security restrictions that apply when
237 # memoize-extract is called directly from the memoize package in a
238 # *latex compilation.)
239 local $ENV{TEXMF_OUTPUT_DIRECTORY} = $aux_dir;
240 for ('TEXMF_OUTPUT_DIRECTORY') {
241 print "mmz_extract_new : ENV{$_} = '$ENV{$_}'\n";
242 }
243 # So we should give the name of the mmz_file to memoize-extract without
244 # the directory part.
245 my @cmd = (@memoize_extract, '--format', 'latex',
246 '--pdf', $pdf_file, $mmz_file_no_path );
247
248 if ( ! -e $pdf_file ) {
249 warn "mmz_extract_new: Cannot generate externs here, since no pdf file generated\n";
250 return 1;
251 }
252 elsif ( ! test_gen_file($pdf_file) ) {
253 warn "mmz_extract_new: Pdf file '$pdf_file' exists, but wasn't\n",
254 " generated on this run. I'll run memoize-extract. Pdf file may contain\n",
255 " extra pages generated by the memoize package.\n";
256 return 1;
257 }
258 print "make_extract_new: Running\n @cmd\n";
259 return system @cmd;
260 }
261
262 #-----------------------------------------------------
263
264 sub mmz_cleanup {
265 use strict;
266 print "============= I am mmz_cleanup \n";
267 my @cmd = ( @memoize_clean, '--all', '--yes',
268 '--prefix', $aux_dir,
269 "$aux_dir1$$Pbase.mmz" );
270 print "mmz_cleanup: Running\n @cmd\n";
271 my $ret = system @cmd;
272 say "Return code $ret";
273 return $ret;
274 }
275
276 #-----------------------------------------------------