Debian Codegraph @

texmf-dist/doc/man/man1/texprofile.1

raw
1 '\" t
2 .\" Manual page created with latex2man on Tue Jan 28 17:56:46 2025
3 .\" NOTE: This file is generated, DO NOT EDIT.
4 .de Vb
5 .ft CW
6 .nf
7 ..
8 .de Ve
9 .ft R
10
11 .fi
12 ..
13 .TH "TEXPROFILE" "1" "28\-1\-2025" "Displaying TeX profiles " "Displaying TeX profiles "
14 .SH NAME
15
16 .PP
17 texprofile
18 \- Displaying the profile data collected by texprof\&.
19 .PP
20 .SH SYNOPSIS
21
22 .PP
23 texprofile
24 [Options] \fIinputfile\fP
25 .PP
26 .SH DESCRIPTION
27
28 texprofile
29 reads the binary \fIinputfile\fP
30 as produced by
31 texprof\&.
32 The extension \&.tprof
33 of the input file can be
34 omitted. It analyses the data and presents the results in a variety of
35 tables, either optimized for human readability or as CSV (comma
36 separated values) files for further processing.
37 .PP
38 The output is written to the standard output stream where it can be redirected
39 to a file or viewed immediately.
40 .PP
41 .SH OPTIONS
42
43 There are four types of options: general options, table options,
44 selection options, and formatting options.
45 .PP
46 The general options:
47 .TP
48 \fB\-?\fP \fB\-h\fP \fB\-\-help\fP
49 Display a short help text and exit the program.
50 .TP
51 \fB\-\-version\fP
52 Display the version information and exit.
53 .PP
54 The table options determine the tables that will be displayed.
55 These options all use upper case letters.
56 If no table option is given, only some global information is shown.
57 .PP
58 .TP
59 \fB\-T\fP
60 Show the table of the top 10 input lines.
61 .TP
62 \fB\-G\fP
63 Show the table of the macro call graph.
64 .TP
65 \fB\-C\fP
66 Show the table of times per TeX command.
67 .TP
68 \fB\-L\fP
69 Show the table of times per input line.
70 .TP
71 \fB\-R\fP
72 Show the table of raw time stamps.
73 .TP
74 \fB\-S\fP
75 Show the table of macro stack changes.
76 .TP
77 \fB\-F\fP
78 Show the table of all input files.
79 .TP
80 \fB\-M\fP
81 Show the table of all macros called.
82 .TP
83 \fB\-A\fP
84 Show important tables (equal to \-TGFC) tables.
85 .TP
86 \fB\-N\fP
87 Do not show the table of global information.
88 .PP
89 The selection options allow to reduce the amount of data that is shown
90 in the table by omitting table entries that contribute little to the
91 overall runtime.
92 .PP
93 .TP
94 \fB\-p\fP\fIn\fP
95 Do not show information for table entries
96 with cumulative time below \fIn\fP
97 percent. The default is 1.0 percent.
98 .TP
99 \fB\-t\fP\fIn\fP
100 Limit the number of input lines shown in the
101 table of the ``Top Ten\&'' to \fIn\fP\&.
102 This option is only useful
103 with the \fB\-T\fP
104 option.
105 .PP
106 The formatting option determine the formatting of the information in the tables
107 as well as the selection of information that is shown in the tables.
108 .PP
109 .TP
110 \fB\-i\fP
111 Add the macros file and line numbers after the macro name.
112 This option is useful to distinguish two macros that share
113 the same name.
114 .TP
115 \fB\-m\fP
116 Optimize output for machine readability. When optimized for human readability,
117 times are rounded and given in a short form adding a unit identifier:
118 s for seconds, ms for milliseconds, us for micro seconds, and ns for
119 nanoseconds. This format is inconvenient if you want to import the data
120 for example into a spread\-sheet for further processing.
121 With the \fB\-m\fP
122 option times are simply given in nano seconds without units.
123 Similar the combined time for the total time used for a macro and the
124 time used as a sub\-macro from the call graph is given in a single column
125 with a slash separating both numbers is nice for human readers.
126 With the \fB\-m\fP
127 option both numbers will simply be given in separate columns.
128 .PP
129 .TP
130 \fB\-n\fP
131 Show the time stamp numbers. This option is useful together with
132 the \fB\-R\fP
133 option, if you import the table into a database or spread\-sheet.
134 If you sort the data by various properties into different
135 categories, the time stamp number can be used to keeping the entries
136 within a category sorted by time.
137 .PP
138 .TP
139 \fB\-s\fP
140 Show the changes of the macro stack.
141 This option is useful with the \fB\-R\fP
142 option if you want to see the changes
143 in the macro stack (see \fB\-S\fP)
144 together with the timing information in
145 a single table.
146 .PP
147 .SH DATA FORMATS
148
149 .SS FILE NUMBERS
150 While texprof
151 is running, every TeX input file is given a
152 unique file number. The file name alone is often not unique because
153 two files in different directories might have the same file
154 name. Displaying the full file name with the complete path is however often
155 not very
156 convenient. So if you observe the same file name together with
157 different file numbers, you can use the option \fB\-F\fP
158 to get a table of all
159 file numbers and their full file names.
160 .PP
161 But even within the same
162 directory, TeX can read different files with the same name during one
163 run: TeX can open a file for writing, write content to the file, close
164 it, open it for reading, read it and close it again. Then TeX might
165 repeat this process a second time, or multiple times, reusing the same
166 file name over and over again. texprof
167 will assign a new file
168 number to this file each time it is opened for reading. So you can
169 tell from the sequence of file numbers which one was the first, the
170 second, or the third.
171 .PP
172 Last not least, there are some special file
173 numbers:
174 .TP
175 0 \- unknown
176 If the file is unknown, which should rarely happen,
177 the file number 0 is used.
178 .TP
179 1\- system
180 texprof
181 will map
182 time intervals that are used to execute certain system routines
183 to the ``system\&'' pseudo file
184 using the line numbers to identify the specific routine
185 like producing the output DVI file (shipout), breaking
186 a paragraph into lines (linebrk), or breaking the
187 document into pages (buildpg). These times do not depend on the
188 use of macros but simply on the size of the document.
189 .TP
190 2 \- terminal
191 TeX commands entered on the command line or interactively are mapped
192 to file number 2.
193 .PP
194 .SS TIME
195 If the option \fB\-m\fP
196 is given times are given as nanoseconds.
197 Otherwise, times are rounded to at most 4 digits precission and
198 displayed with a unit: seconds (s), milliseconds (ms), microseconds
199 (um), or nanoseconds (ns).
200 .PP
201 .SS MACRO NAMES
202 Macro names are shown with the leading backslash. Since macro names
203 are often not unique, the command line option \fB\-i\fP
204 can be used to
205 show after the macro name in square brackets the file number and the
206 line number where the macro is defined. Unless two macros with the
207 same name are defined in the same file and line this is sufficient to
208 uniquely identify a macro. A macro defined with ``let\&'' results in a
209 complet copy of the original macro. Therefore it will not reference
210 the file and line of the ``let\&'' command but the same file and line as
211 the original macro.
212 .PP
213 .SH EXAMPLES
214
215 Let\&'s assume that you issue the command texprof
216 \fB\-prof\fP
217 \fIhello.tex\fP\&.
218 This will run texprof
219 on the input file
220 \fIhello.tex\fP
221 with option \fB\-prof\fP\&.
222 The program texprof
223 will load the plain TeX format and then process hello.tex
224 to
225 produce hello.log
226 and hello.dvi\&.
227 It will execute
228 exactly the same steps that TeX would execute if you had issued the
229 command tex
230 \fIhello.tex\fP\&.
231 .PP
232 In addition to hello.log
233 and hello.dvi,
234 texprof
235 will also produce the file hello.tprof
236 containing time
237 measurements made while texprof
238 was running. The option
239 \fB\-prof\fP
240 will switch on the gathering of timing data as soon as
241 texprof
242 enters its main control procedure; The file
243 hello.tprof
244 will contain a time measurement, called a time
245 stamp, for every command that TeX executed while processing the input.
246 A binary format is used to store all that data in a simple and compact
247 form. Still the file hello.tprof
248 might become very big.
249 .PP
250 The program texprofile
251 is used to extract and analyse the data
252 contained in hello.tprof
253 and produce useful output. Here are
254 some examples:
255 .PP
256 .TP
257 texprofile \fIhello\fP
258 Without further options texprofile
259 will write some general
260 information to the standard output, like the total time measured,
261 the number of samples, the average time per sample, etc.
262 The general information is always given unless explicitely disabled
263 with the \fB\-N\fP
264 option or with the \fB\-m\fP
265 option.
266 .PP
267 .TP
268 texprofile \fB\-T\fP \fIhello\fP
269 With the option \fB\-T\fP,
270 texprofile
271 will map each time stamp
272 to a specific line of input, add up the time intervalls for each input
273 line separately, and output a table showing the ten lines that have
274 the highest cummulative time.
275 The table has the following seven columns:
276 .RS
277 .TP
278 1. file
279 The first column contains the input file number as explained above.
280 The input file name if shown in column 7.
281 .TP
282 2. line
283 The line number.
284 .TP
285 3. percent
286 The time spent in this line and file as a percentage of the total
287 time measured as given as part of the general information.
288 .TP
289 4. absolute
290 The absolute time spent in this line and file.
291 .TP
292 5. count
293 The number of times the execution path entered this line.
294 Note, that a
295 macro call usually redirects the execution path to another line
296 from where the execution will return after the macro call has completed.
297 Reentering the line after such an excursion to an other line will
298 cause this counter to be incremented. In summary, this counter might
299 reflect the number of partial executions of a line not the number
300 of full executions of the entire line.
301 .TP
302 6. average
303 The average time spent in the line is simply computed by dividing the
304 value in column 4 by the value in column 5.
305 .TP
306 7. file
307 The input file name. The corresponding file number is shown in column 1.
308 .RE
309 .RS
310 .PP
311 .RE
312 .TP
313 texprofile \fB\-G\fP \fIhello\fP
314 With the option \fB\-G\fP,
315 texprofile
316 will map each time stamp
317 either to file input or to a macro body.
318 The table shown is divided into several sections, the first section
319 is devoted to file input, each of the following sections is devoted
320 to a specific macro.
321 .br
322 Each section starts with a header. The header of the
323 first section is ``File\&'' the header of a later section is the macro name.
324 .br
325 The first line after the header gives the total time spent in the section
326 in two different formats:
327 .RS
328 .TP
329 1. time
330 Column 1 gives it as an absolut time.
331 .TP
332 3. percentage
333 Column 3 gives it as a percentage of the total time measured.
334 .RE
335 .RS
336 .PP
337 For the first section with the header ``File\&'', the absolute time
338 will be equal to the total time measured because texprof
339 did spent all the time processing the file \fIhello\fP\&.
340 And consequently the value in column 3 will be 100%\&.
341 .br
342 To accomplish a task, a macro usually calls other
343 macros that we call child macros in the following.
344 The following lines in the table will give a breakdown
345 of the time shown in the first line.
346 The breakdown starts with a line showing the time spent in the section
347 excluding the time spent in child macros. It shows in column 4 the number
348 of times the macro was called.
349 .RS
350 .RE
351 .TP
352 1. time
353 Column 1 gives the absolut time spent in the section excluding the time
354 spent in child macros
355 .TP
356 3. percentage
357 Column 3 gives the time from column 1 as a percentage of the total time
358 spent in this section as given in the previous line.
359 .TP
360 4. count/total
361 Column 4 gives the number of times the section was called.
362 .RE
363 .RS
364 .PP
365 The lines that follow in the table show the time spent in one of
366 the child macros. Column 2, 4, and 5 need some explanation.
367 .RS
368 .RE
369 .TP
370 2. loop
371 The only case where column 2 is not empty is the case of a
372 recursive macro. A recursive macro is a macro that along the
373 chain of macro calls eventually calls itself creating a
374 recursive loop. At this point, a macro becomesits own descendant
375 and at the same time its own ancestor.
376 .br
377 Therefore texprofile
378 maintains for each child macro two
379 accumulators for the elapsed time: For the time shown in
380 column 2 labeled ``loop\&'', texprofile
381 adds up the time
382 differences observed at the return of a child macro. For the
383 time shown in the column labeled ``time\&'' and ``percent\&'', it
384 subtracts from the time differences observed at the return of a
385 child macro all those time differences that were already added
386 to one of the other lines in the time breakdown: the macro itself
387 or one of the other child macros.
388 So the times shown in column 1 of line 2 and the following lines
389 will add up to the time shown in column 1 of the line 1;
390 and the percentages shown in column 3 of line 2 and the following lines
391 will add up to 100%\&.
392 The time shown in column 3 will show show the total time needed
393 to accomplish the sub task assigned to the respective child macro.
394 .TP
395 4. count/total
396 Column 4 shows two counts n/m for the macro named in column 5.
397 m is the total number of calls to the macro and n is the number of
398 calls as a child macro in the current section. The number n will
399 always be less or equal to m\&.
400 .RS
401 .PP
402 .RE
403 .TP
404 5. child
405 Column 5 shows the name of the child macro as explained above.
406 .RE
407 .RS
408 .PP
409 .RE
410 .TP
411 texprofile \fB\-G\fP \fB\-m\fP \fIhello\fP
412 This table will contain the same data as the previous example
413 but this time the \fB\-m\fP
414 option will optimize the output for
415 machine readability.
416 .RS
417 .TP
418 .B *
419 There are no column headers.
420 .TP
421 .B *
422 The times in column 1 ``time\&'' and column 2 ``loop\&''
423 are given in nanoseconds without a unit identifier.
424 .TP
425 .B *
426 The numbers n/m in column 4 are now shown in two separate
427 columns 4 and 5; the macro name moves from column 5 to column 6.
428 .RE
429 .RS
430 .PP
431 .RE
432 .TP
433 texprofile \fB\-F\fP \fIhello\fP
434 With the option \fB\-F\fP,
435 texprofile
436 outputs the table
437 of all of TeX\&'s input files using 5 columns:
438 .RS
439 .TP
440 1. file
441 The file number as explained above.
442 .TP
443 2. lines
444 The difference between the highest and the lowest
445 line number found in the profile data for this file. This is
446 usually only a subset of all the lines of the file.
447 .TP
448 3. percent
449 The percentage of the total time measured that is attibuted to the file.
450 .TP
451 4. time
452 The absolute time that is attibuted to the file.
453 .TP
454 5. name
455 The full file name of the file.
456 .RE
457 .RS
458 .PP
459 .RE
460 .TP
461 texprofile \fB\-C\fP \fIhello\fP
462 With the option \fB\-C\fP,
463 texprofile
464 outputs the table
465 of all TeX commands executed while profiling
466 using 6 columns:
467 .RS
468 .TP
469 1. cmd
470 The command code used internaly by TeX.
471 Usually the same number is used by TeX for several
472 closely related tasks.
473 There is a special command code 101 which is used to
474 for the time that is spend on system routines that are
475 mapped to the system file as explained above.
476 .TP
477 2. time
478 The total time used for the command.
479 .TP
480 3. percent
481 The percentage of the total time measured used for the command.
482 .TP
483 4. count
484 The number of times this command was executed.
485 .TP
486 5. average
487 The average time needed to execute the command.
488 This is simpy the value in column 2 divided by the value in column 4.
489 .TP
490 6. name
491 A verbal description of the command or commands that share this
492 command code.
493 .RE
494 .RS
495 .PP
496 .RE
497 .TP
498 texprofile \fB\-R\fP \fB\-m\fP \fB\-n\fP \fIhello\fP
499 With the options \fB\-R\fP
500 \fB\-m\fP,
501 texprofile
502 outputs the table
503 of raw time measurements as observed by texprof
504 optimized for machine
505 readability. The option \fB\-n\fP
506 adds a column for the number
507 of each time measurements.
508 Because of the \fB\-m\fP
509 option, the table has no column headers.
510 The table has 7 columns:
511 .RS
512 .TP
513 1. number
514 The number of the time measurment.
515 These numbers are strictly increasing but not necessarily consecutive.
516 They can be used to keep the measurements sorted in the order in which
517 they were made.
518 .TP
519 2. file
520 The file number as explained above.
521 .TP
522 3. line
523 The line number as explained above.
524 .TP
525 4. time
526 The time interval in nano seconds.
527 .TP
528 5. command
529 The command name as given in column 6 of the previous example.
530 .TP
531 6. level
532 The nesting level of the macro call stack.
533 .TP
534 7. macro
535 The macro name.
536 .RE
537 .RS
538 .PP
539 This table contains all the timing information gathered during the run
540 of texprof\&.
541 Some information about macro calls is contained in
542 column 6. More information about macro calls could be added
543 by using the \fB\-s\fP
544 option. The information about macro returns
545 can be obtained from column 6.
546 The table can be imported to a spread\-sheet or a database for further
547 analysis.
548 .RE
549 .PP
550 .SH BUGS
551
552 If the last command in a macro body is a macro call, we call this a tail call.
553 If such a tail call reads ahead to scan the following input
554 for possible arguments, the look\-ahead mechaism of TeX might push further
555 macros or new input files on TeX\&'s input stack.
556 These entries will remain on top of TeXprof\&'s macro nesting stack,
557 even if TeX backs up all these tokens on its input stack.
558 This can cause an attribution of runtime to those entries as sub entries
559 of the tail call. If this explanation sounds complicated to you, it is
560 because the situation is indeed complicated.
561 .PP
562 .SH SEE ALSO
563
564 \fItexprof\fP(1)
565 .PP
566 .SH VERSION
567
568 Version: 1.1 of 28-1-2025
569 .TP
570 Copyright
571 (C)2024, Martin Ruckert,
572 .br
573 Hochschule München, Lothstrasse 64, D\-80335 München
574 .PP
575 .TP
576 Distribution
577 texprofile
578 is distributed with TeX Live.
579 More recent versions might be found on GitHub
580 \fBhttps://github.com/ruckertm/HINT\fP\&.
581 .PP
582 .TP
583 License
584 This program can be redistributed and/or modified under the
585 terms of the MIT/X11 license.
586 .PP
587 .SH AUTHOR
588
589 Martin Ruckert
590 .br
591 Munich University of Applied Sciences
592 .br
593 Email: \[email protected]\fP
594 .br
595 .PP
596 .\" NOTE: This file is generated, DO NOT EDIT.