Mercurial > hg > octave-nkf
annotate etc/README.kpathsea @ 20830:b65888ec820e draft default tip gccjit
dmalcom gcc jit import
| author | Stefan Mahr <dac922@gmx.de> |
|---|---|
| date | Fri, 27 Feb 2015 16:59:36 +0100 |
| parents | b67c2d580a25 |
| children |
| rev | line source |
|---|---|
| 4378 | 1 The code in the files |
| 2 | |
| 3 liboctave/kpse.cc | |
| 4 liboctave/kpse-xfns.h | |
| 4406 | 5 liboctave/kpse-xfns.c |
| 4378 | 6 |
| 7 was adapted from the kpathsearch library. We don't use kpathsearch | |
| 8 directly now because it has too many TeX-specific things that are not | |
| 9 necessary for Octave, and it also does not implement all the special | |
| 10 kinds of file searches that Octave needs (mainly for compatibility | |
| 11 with Matlab). | |
| 12 | |
| 13 Original authors of the kpathsearch library | |
| 14 ------------------------------------------- | |
| 15 | |
| 16 Karl Berry wrote all files not otherwise marked, with help from Kathryn | |
| 17 Hargreaves on some of the original versions. | |
| 18 | |
| 19 Thomas Esser originated most of the MakeTeX... scripts. | |
| 20 | |
| 21 The brace expansion code in expand.c was written by Brian Fox and Chet | |
| 22 Ramey for Bash, the GNU shell. | |
| 23 | |
| 24 The implementation of the link trick in pathsearch.c is taken from GNU | |
| 25 find, implemented by David MacKenzie from Matthew Farwell's suggestion. | |
| 26 | |
| 27 Debugging | |
| 28 --------- | |
| 29 | |
| 30 Kpathsea provides a number of runtime debugging options, detailed | |
| 31 below by their names and corresponding numeric values. When the files | |
| 32 you expect aren't being found, the thing to do is enable these options | |
| 33 and examine the output. | |
| 34 | |
| 35 You can set these with some runtime argument (e.g., `-d') to the | |
| 36 program; in that case, you should use the numeric values described in | |
| 37 the program's documentation (which, for Dvipsk and Xdvik, are different | |
| 38 than those below). It's best to give the `-d' (or whatever) option | |
| 39 first, for maximal output. Dvipsk and Xdvik have additional | |
| 40 program-specific debugging options as well. | |
| 41 | |
| 42 You can also set the environment variable `KPATHSEA_DEBUG'; in this | |
| 43 case, you should use the numbers below. If you run the program under a | |
| 44 debugger and set the variable `kpathsea_debug', also use the numbers | |
| 45 below. | |
| 46 | |
| 47 In any case, by far the simplest value to use is `-1', which will | |
| 48 turn on all debugging output. This is usually better than guessing | |
| 49 which particular values will yield the output you need. | |
| 50 | |
| 51 Debugging output always goes to standard error, so you can redirect it | |
| 52 easily. For example, in Bourne-compatible shells: | |
| 53 dvips -d -1 ... 2>/tmp/debug | |
| 54 | |
| 55 It is sometimes helpful to run the standalone Kpsewhich utility | |
| 56 (*note Invoking kpsewhich::.), instead of the original program. | |
| 57 | |
| 58 In any case, you can *not* use the *names* below; you must always use | |
| 59 somebody's numbers. (Sorry.) To set more than one option, just sum | |
| 60 the corresponding numbers. | |
| 61 | |
| 62 `KPSE_DEBUG_STAT (1)' | |
|
9031
1052a66078cf
Documentation cleanup of top-level Octave directory (READMEs, INSTALL)
Rik <rdrider0-list@yahoo.com>
parents:
7088
diff
changeset
|
63 Report `stat'(2) calls. This is useful for verifying that your |
| 4378 | 64 directory structure is not forcing Kpathsea to do many additional |
| 65 file tests (*note Slow path searching::., and *note Subdirectory | |
|
9031
1052a66078cf
Documentation cleanup of top-level Octave directory (READMEs, INSTALL)
Rik <rdrider0-list@yahoo.com>
parents:
7088
diff
changeset
|
66 expansion::.). If you are using an up-to-date `ls-R' database |
| 4378 | 67 (*note Filename database::.), this should produce no output unless |
| 68 a nonexistent file that must exist is searched for. | |
| 69 | |
| 70 `KPSE_DEBUG_HASH (2)' | |
| 71 Report lookups in all hash tables: `ls-R' and `aliases' (*note | |
| 72 Filename database::.); font aliases (*note Fontmap::.); and config | |
| 73 file values (*note Config files::.). Useful when expected values | |
| 74 are not being found, e.g.., file searches are looking at the disk | |
| 75 instead of using `ls-R'. | |
| 76 | |
| 77 `KPSE_DEBUG_FOPEN (4)' | |
|
9031
1052a66078cf
Documentation cleanup of top-level Octave directory (READMEs, INSTALL)
Rik <rdrider0-list@yahoo.com>
parents:
7088
diff
changeset
|
78 Report file openings and closings. Especially useful when your |
| 4378 | 79 system's file table is full, for seeing which files have been |
|
9031
1052a66078cf
Documentation cleanup of top-level Octave directory (READMEs, INSTALL)
Rik <rdrider0-list@yahoo.com>
parents:
7088
diff
changeset
|
80 opened but never closed. In case you want to set breakpoints in a |
| 4378 | 81 debugger: this works by redefining `fopen' (`fclose') to be |
| 82 `kpse_fopen_trace' (`kpse_fclose_trace'). | |
| 83 | |
| 84 `KPSE_DEBUG_PATHS (8)' | |
| 85 Report general path information for each file type Kpathsea is | |
|
9031
1052a66078cf
Documentation cleanup of top-level Octave directory (READMEs, INSTALL)
Rik <rdrider0-list@yahoo.com>
parents:
7088
diff
changeset
|
86 asked to search. This is useful when you are trying to track down |
| 4378 | 87 how a particular path got defined--from `texmf.cnf', `config.ps', |
| 88 an environment variable, the compile-time default, etc. This is | |
| 89 the contents of the `kpse_format_info_type' structure defined in | |
| 90 `tex-file.h'. | |
| 91 | |
| 92 `KPSE_DEBUG_EXPAND (16)' | |
| 93 Report the directory list corresponding to each path element | |
|
9031
1052a66078cf
Documentation cleanup of top-level Octave directory (READMEs, INSTALL)
Rik <rdrider0-list@yahoo.com>
parents:
7088
diff
changeset
|
94 Kpathsea searches. This is only relevant when Kpathsea searches |
| 4378 | 95 the disk, since `ls-R' searches don't look through directory lists |
| 96 in this way. | |
| 97 | |
| 98 `KPSE_DEBUG_SEARCH (32)' | |
| 99 Report on each file search: the name of the file searched for, the | |
| 100 path searched in, whether or not the file must exist (when drivers | |
| 101 search for `cmr10.vf', it need not exist), and whether or not we | |
| 102 are collecting all occurrences of the file in the path (as with, | |
| 103 e.g., `texmf.cnf' and `texfonts.map'), or just the first (as with | |
| 104 most lookups). This can help you correlate what Kpathsea is doing | |
| 105 with what is in your input file. | |
| 106 | |
| 107 `KPSE_DEBUG_VARS (64)' | |
| 108 Report the value of each variable Kpathsea looks up. This is | |
| 109 useful for verifying that variables do indeed obtain their correct | |
| 110 values. | |
| 111 | |
| 112 `GSFTOPK_DEBUG (128)' | |
| 113 Activates debugging printout specific to `gsftopk' program. | |
| 114 | |
| 115 `MAKETEX_DEBUG (512)' | |
| 116 If you use the optional `mktex' programs instead of the | |
| 117 traditional shell scripts, this will report the name of the site | |
| 118 file (`mktex.cnf' by default) which is read, directories created by | |
| 119 `mktexdir', the full path of the `ls-R' database built by | |
| 120 `mktexlsr', font map searches, `MT_FEATURES' in effect, parameters | |
| 121 from `mktexnam', filenames added by `mktexupd', and some | |
| 122 subsidiary commands run by the programs. | |
| 123 | |
| 124 `MAKETEX_FINE_DEBUG (1024)' | |
| 125 When the optional `mktex' programs are used, this will print | |
| 126 additional debugging info from functions internal to these | |
| 127 programs. | |
| 128 | |
| 129 Debugging output from Kpathsea is always written to standard error, | |
|
9031
1052a66078cf
Documentation cleanup of top-level Octave directory (READMEs, INSTALL)
Rik <rdrider0-list@yahoo.com>
parents:
7088
diff
changeset
|
130 and begins with the string `kdebug:'. (Except for hash table buckets, |
| 4378 | 131 which just start with the number, but you can only get that output |
|
9031
1052a66078cf
Documentation cleanup of top-level Octave directory (READMEs, INSTALL)
Rik <rdrider0-list@yahoo.com>
parents:
7088
diff
changeset
|
132 running under a debugger. See comments at the `hash_summary_only' |
| 4378 | 133 variable in `kpathsea/db.c'.) |
| 134 | |
| 135 Logging | |
| 136 ------- | |
| 137 | |
| 138 Kpathsea can record the time and filename found for each successful | |
| 139 search. This may be useful in finding good candidates for deletion when | |
| 140 your filesystem is full, or in discovering usage patterns at your site. | |
| 141 | |
| 142 To do this, define the environment or config file variable | |
| 143 `TEXMFLOG'. The value is the name of the file to append the | |
| 144 information to. The file is created if it doesn't exist, and appended | |
| 145 to if it does. | |
| 146 | |
| 147 Each successful search turns into one line in the log file: two words | |
|
9031
1052a66078cf
Documentation cleanup of top-level Octave directory (READMEs, INSTALL)
Rik <rdrider0-list@yahoo.com>
parents:
7088
diff
changeset
|
148 separated by a space. The first word is the time of the search, as the |
| 4378 | 149 integer number of seconds since "the epoch", i.e., UTC midnight 1 |
| 150 January 1970 (more precisely, the result of the `time' system call). | |
| 151 The second word is the filename. | |
| 152 | |
| 153 For example, after `setenv TEXMFLOG /tmp/log', running Dvips on | |
| 154 `story.dvi' appends the following lines: | |
| 155 | |
| 156 774455887 /usr/local/share/texmf/dvips/config.ps | |
| 157 774455887 /usr/local/share/texmf/dvips/psfonts.map | |
| 158 774455888 /usr/local/share/texmf/dvips/texc.pro | |
| 159 774455888 /usr/local/share/texmf/fonts/pk/ljfour/public/cm/cmbx10.600pk | |
| 160 774455889 /usr/local/share/texmf/fonts/pk/ljfour/public/cm/cmsl10.600pk | |
| 161 774455889 /usr/local/share/texmf/fonts/pk/ljfour/public/cm/cmr10.600pk | |
| 162 774455889 /usr/local/share/texmf/dvips/texc.pro | |
| 163 | |
| 164 Only filenames that are absolute are recorded, to preserve some | |
| 165 semblance of privacy. | |
| 7088 | 166 |
| 167 | |
| 168 John W. Eaton | |
| 9322 | 169 jwe@octave.org |
| 7088 | 170 |
| 171 Last updated: Wed, 31 Oct 2007 16:33:13 EDT |