Commit | Line | Data |
---|---|---|
8996f767 MW |
1 | .\" -*-nroff-*- |
2 | .\" | |
3 | .\" Manual for `runlisp' configuration files | |
4 | .\" | |
5 | .\" (c) 2020 Mark Wooding | |
6 | .\" | |
7 | . | |
8 | .\"----- Licensing notice --------------------------------------------------- | |
9 | .\" | |
10 | .\" This file is part of Runlisp, a tool for invoking Common Lisp scripts. | |
11 | .\" | |
12 | .\" Runlisp is free software: you can redistribute it and/or modify it | |
13 | .\" under the terms of the GNU General Public License as published by the | |
14 | .\" Free Software Foundation; either version 3 of the License, or (at your | |
15 | .\" option) any later version. | |
16 | .\" | |
17 | .\" Runlisp is distributed in the hope that it will be useful, but WITHOUT | |
18 | .\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or | |
19 | .\" FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License | |
20 | .\" for more details. | |
21 | .\" | |
22 | .\" You should have received a copy of the GNU General Public License | |
23 | .\" along with Runlisp. If not, see <https://www.gnu.org/licenses/>. | |
24 | . | |
25 | .ie t \{\ | |
26 | . ds o \(bu | |
27 | . if \n(.g \{\ | |
28 | . fam P | |
29 | . ev an-1 | |
30 | . fam P | |
31 | . ev | |
32 | . \} | |
33 | .\} | |
34 | .el \{\ | |
35 | . ds o o | |
36 | .\} | |
37 | . | |
38 | .de hP | |
39 | .IP | |
40 | \h'-\w'\fB\\$1\ \fP'u'\fB\\$1\ \fP\c | |
41 | .. | |
eea3b0c7 | 42 | .ds .. \&.\|.\|. |
8996f767 MW |
43 | . |
44 | .\"-------------------------------------------------------------------------- | |
45 | .TH runlisp.conf 5 "27 August 2020" "Mark Wooding" | |
46 | .SH NAME | |
47 | runlisp.conf \- configuration files for runlisp | |
48 | . | |
49 | .\"-------------------------------------------------------------------------- | |
50 | .SH DESCRIPTION | |
51 | . | |
10427eb2 MW |
52 | .SS "Default configuration files" |
53 | By default, the | |
54 | .B runlisp | |
55 | programs read configuration from the following files. | |
56 | (Note that if a | |
57 | .RB ` \-c ' | |
58 | command-line option is given, then | |
59 | these default files are | |
60 | .I not | |
61 | read.) | |
62 | .TP | |
63 | .B @etcdir@/runlisp.d/*.conf | |
64 | If a directory named | |
65 | .B @etcdir@/runlisp.d | |
66 | exists, | |
67 | then all of the files within | |
68 | whose names end in | |
69 | .RB ` .conf ' | |
70 | are read, | |
71 | in ascending lexicographical order by name. | |
72 | This directory name can be overridden by setting the | |
73 | .B RUNLISP_SYSCONFIG_DIR | |
74 | environment variable. | |
75 | .TP | |
76 | .B @etcdir@/runlisp.conf | |
77 | The file named | |
78 | .B @etcdir@/runlisp.conf | |
79 | is read; the file must exist. | |
80 | This filename can be overridden by setting the | |
81 | .B RUNLISP_SYSCONFIG | |
82 | environment variable. | |
83 | .TP | |
84 | .B ~/.runlisp.conf | |
85 | If there is a file named | |
86 | .B .runlisp.conf | |
87 | in the user's home directory, | |
88 | then it is read. | |
89 | The home directory is determined to be | |
90 | the value of the | |
91 | .B HOME | |
92 | environment variable, or, if that is not set, | |
93 | the home directory associated with the process's real uid | |
94 | in the system password database. | |
95 | This filename can be overridden by setting the | |
96 | .B RUNLISP_USERCONFIG | |
97 | environment variable. | |
98 | .TP | |
99 | .B ~/.config/runlisp.conf | |
100 | If there is a file named | |
101 | .B runlisp.conf | |
102 | in the user's XDG configuration directory, | |
103 | then it is read. | |
104 | The XDG configuration directory is determined to be the value of the | |
105 | .B XDG_CONFIG_HOME | |
106 | environment variable, or the | |
107 | .B .config | |
108 | directory in the user's home directory | |
109 | (as determined above). | |
110 | This filename can be overridden by setting the | |
111 | .B RUNLISP_USERCONFIG | |
112 | environment variable. | |
113 | (Note, therefore, that this variable overrides | |
114 | .I both | |
115 | of the user configuration files.) | |
116 | . | |
8996f767 MW |
117 | .SS "General syntax" |
118 | In summary, | |
119 | a configuration file is structured as a collection of assignments | |
120 | .I variable | |
121 | .B = | |
122 | .IR value , | |
123 | gathered into named sections by header lines | |
124 | .BI [ section ]\fR. | |
125 | .PP | |
126 | Comments are indicated by a semicolon | |
127 | .RB ` ; ' | |
128 | in the leftmost column, | |
129 | and extend to the end of the line; | |
130 | comments and lines consisting only of whiteapace are ignored | |
131 | and have no effect whatever. | |
132 | Semicolons not in the first column do | |
133 | .I not | |
134 | introduce comments, | |
135 | and have no special meaning. | |
136 | .PP | |
137 | A | |
138 | .I name | |
139 | is a non-empty sequence of ASCII alphanumeric characters, | |
140 | or the special constituent characters | |
141 | .RB ` \- ', | |
142 | .RB ` _ ', | |
143 | .RB ` . ', | |
144 | .RB ` / ', | |
145 | .RB ` * ', | |
146 | .RB ` + ', | |
147 | .RB ` *% ', | |
148 | or | |
149 | .RB ` @ '. | |
150 | For example, | |
151 | .RB ` foo ', | |
152 | .RB ` 12345 ', | |
153 | .RB ` \-2.718 ', | |
154 | .RB ` 113/355 ', | |
155 | .RB ` image-dir ', | |
156 | .RB ` @%IMAGEDIR ', | |
157 | and | |
158 | .RB ` *organa-solo* ' | |
159 | are all names, but | |
160 | .RB ` foo:bar ' | |
161 | .RB ` happy? ' | |
162 | and | |
163 | .RB ` $3.95 ' | |
164 | are not. | |
165 | Names beginning with | |
166 | .RB ` @ ' | |
167 | are reserved for use by the | |
168 | .B runlisp | |
169 | programs; | |
170 | names beginning with | |
171 | .RB ` % ' | |
172 | or | |
173 | .RB ` @% ' | |
174 | are by convention private. | |
175 | .PP | |
176 | A | |
177 | .I section header | |
178 | is a line of the form | |
179 | .IP | |
180 | .BI [ section ] | |
181 | .PP | |
182 | where | |
183 | .I section | |
184 | is a name, as defined above. | |
185 | There may be whitespace before and after the | |
186 | .I name | |
187 | or after the | |
188 | .RB ` ] '. | |
189 | Section headers need not have distinct names. | |
190 | Subsequent assignments are applied to the section called | |
191 | .IR name , | |
192 | up until the next section header, or the end of the file. | |
193 | Assignments prior to the first section header in a file | |
194 | are applied to the | |
195 | .B @CONFIG | |
196 | section. | |
197 | .PP | |
198 | An | |
199 | .I assignment | |
200 | begins with a line of the form | |
201 | .IP | |
202 | .I variable | |
203 | .B = | |
204 | .I rest | |
205 | .PP | |
206 | where | |
207 | .I variable | |
208 | is a name, as defined above, | |
209 | and it includes all subsequent | |
210 | (non-empty, non-comment) | |
211 | lines up to, but not including, | |
212 | the next line which does | |
213 | .I not | |
214 | begin with whitespace or a semicolon, | |
215 | or the end of the input file. | |
216 | There may be space before or after the | |
217 | .RB ` = '. | |
218 | The | |
219 | .I value | |
220 | assigned consists of the text of the initial line following the | |
221 | .RB ` = ' | |
222 | character | |
223 | (shown as | |
224 | .I rest | |
225 | above), | |
226 | together with the contents of the subsequent lines; | |
227 | initial and trailing whitespace is removed from each piece, | |
228 | and the (nonempty) pieces are joined, | |
229 | separated by single spaces. | |
f8174852 | 230 | We say that an assignment |
8996f767 MW |
231 | assigns a value to the variable |
232 | in some section \(en | |
233 | namely, the section in which the assignment is applied. | |
234 | .PP | |
235 | For example, | |
236 | consider the following file. | |
237 | .IP | |
238 | .ft B | |
239 | .nf | |
240 | long = | |
241 | one | |
242 | ||
243 | two | |
244 | ; this line is a comment | |
245 | ; not a comment | |
246 | three | |
247 | ||
248 | short = just a quick note | |
249 | .fi | |
250 | .ft P | |
251 | .PP | |
252 | Then | |
253 | .B long | |
254 | is assigned the value | |
255 | .RB ` "one two ; not a comment three" ', | |
256 | and | |
ace01e71 MW |
257 | .B short |
258 | is assigned | |
8996f767 MW |
259 | .RB ` "just a quick note" '. |
260 | .PP | |
261 | The assignments applied to a section | |
262 | need not have distinct variable names. | |
263 | Only the last assignment to a particular variable name in a section is | |
264 | .IR effective ; | |
265 | the earlier assignments are simply ignored. | |
266 | If an effective assignment assigns a value to a variable in a section, | |
267 | we say that the variable is | |
268 | .I set | |
269 | to that value in the section. | |
270 | . | |
271 | .SS "Lookup and inheritance" | |
272 | A section may have zero or more | |
273 | .I parent | |
274 | sections. | |
275 | .PP | |
276 | The | |
10427eb2 | 277 | .B @BUILTIN |
8996f767 MW |
278 | and |
279 | .B @ENV | |
280 | sections have no parents. | |
281 | The | |
e8f53d29 | 282 | .B @COMMON |
8996f767 MW |
283 | section has one parent, namely |
284 | .BR @BUILTIN . | |
285 | .PP | |
286 | If the variable | |
287 | .B @parents | |
288 | is set in a section other than one of those named above, | |
44ccabcb | 289 | then it must consist of a space- and/or comma-separated list |
8996f767 MW |
290 | of names, |
291 | which name the section's parents. | |
292 | Currently, the parents need not be distinct, | |
293 | though duplicates have no effect other than slowing down lookup. | |
294 | The order in which parents are listed is not significant. | |
295 | If | |
296 | .B @parents | |
297 | is not set in a section other than one of those named above, | |
298 | then by default it has one parent, namely | |
299 | .BR @COMMON . | |
300 | .PP | |
301 | It is currently possible to build a cyclic structure of parent links. | |
302 | This is not recommended. | |
303 | If lookup (explained below) detects a cycle | |
304 | then it will report a fatal error, | |
305 | but cycles may exist without being detected. | |
306 | .PP | |
307 | A variable is | |
308 | .I "looked up" | |
309 | in a section as follows. | |
310 | .hP 1. | |
311 | If there is an effective assignment | |
312 | of a value to that variable in the section | |
313 | then lookup finds that assignment. | |
314 | .hP 2. | |
315 | If the section has no parents, | |
316 | then lookup fails. | |
317 | .hP 3. | |
318 | Otherwise, the variable is looked up in each of the section's parents. | |
319 | If none of these lookups succeeds, then the lookup fails. | |
320 | If all of the successful lookups found the | |
321 | .I "same assignment" | |
530dead4 | 322 | (not just the same value!)\& |
8996f767 MW |
323 | then lookup finds that assignment. |
324 | Otherwise, the lookup reports an error. | |
325 | . | |
326 | .SS "Expansion and word-splitting" | |
327 | A value can be | |
328 | .I expanded | |
329 | relative to some home section, | |
330 | and optionally split into words. | |
331 | .PP | |
332 | Not all values are | |
333 | .IR expandable . | |
334 | Values set by assignments in a configuration file are always expandable. | |
335 | Values set on the command line \(en in | |
336 | .B \-o | |
337 | options \(en are not expandable. | |
338 | Values in the | |
339 | .B @ENV | |
340 | section from environment variables (see below) are not expandable. | |
341 | Some values set in the | |
342 | .B @BUILTIN | |
343 | section are expandable and some are not. | |
344 | Applying expansion to a value that is not expandable | |
345 | simply results in that same value, unchanged. | |
346 | .PP | |
347 | Applying expansion to an expandable value | |
348 | produces a result string as follows. | |
349 | The value is scanned from start to end. | |
350 | .hP \*o | |
351 | A backslash | |
352 | .RB ` \e ' | |
353 | is discarded, but the immediately following character | |
354 | is copied to the output without further inspection. | |
355 | .hP \*o | |
356 | A | |
357 | .I variable substitution | |
358 | takes the form | |
359 | .BR ${ [ \c | |
360 | .IB sect : \c | |
361 | .RI ] var \c | |
362 | .RB [ | \c | |
eea3b0c7 | 363 | .IR filter ]\*(.. \c |
8996f767 MW |
364 | .RB [ ? \c |
365 | .IR alt ] \c | |
366 | .BR } . | |
367 | A variable named | |
368 | .I var | |
369 | is looked up in the section named | |
370 | .IR sect , | |
371 | or, if omitted, in the home section. | |
372 | If the lookup succeeds, | |
373 | then the value is expanded, | |
374 | processed by the | |
375 | .IR filter s | |
376 | (explained below), | |
377 | and appended to the output. | |
378 | If the lookup failed, | |
379 | and | |
380 | .BI ? alt | |
381 | is present, | |
382 | then | |
383 | .I alt | |
384 | is expanded and appended to the output. | |
385 | Otherwise, | |
386 | if the lookup fails and there is no | |
387 | .I alt | |
388 | text, then an error is reported. | |
389 | .IP | |
390 | A filter | |
391 | .B u | |
392 | causes the expanded value to be converted to uppercase; | |
393 | similarly, | |
394 | .B l | |
395 | causes the expanded value to be converted to lowercase. | |
396 | A filter | |
397 | .B q | |
398 | causes a backslash to be inserted before each | |
399 | backslash or double-quote character in the expanded value, | |
400 | so that this can be used as part of a quoted Common Lisp string. | |
401 | .hP \*o | |
402 | A | |
403 | .I conditional | |
404 | takes the form | |
405 | .BR $? [ \c | |
406 | .IB sect : \c | |
407 | .RI ] var \c | |
408 | .BI { conseq \c | |
409 | .RB [ | \c | |
410 | .IR alt ] \c | |
411 | .BR } . | |
412 | A variable named | |
413 | .I var | |
414 | is looked up in the section named | |
415 | .IR sect , | |
416 | or, if omitted, in the home section. | |
417 | If the lookup succeeds, then | |
418 | .I conseq | |
419 | is expanded and appended to the output; | |
420 | otherwise, if | |
421 | .I alt | |
422 | is present, then it is expanded and appended to the output; | |
423 | otherwise, nothing happens. | |
424 | .hP \*o | |
425 | A dollar sign which doesn't introduce one of the forms above | |
426 | is invalid, and a fatal error is reported. | |
427 | .hP \*o | |
428 | Any other characters are simply appended to the output. | |
429 | .PP | |
430 | Word-splitting is similar but more complex. | |
431 | The result is not a string, but a sequence of strings. | |
432 | At any given point in this procedure, | |
433 | there may be a partially constructed word, | |
434 | or there might not. | |
435 | .hP \*o | |
436 | Outside of quotes (see below), | |
437 | whitespace serves to separate words. | |
438 | When a whitespace character is encountered, | |
439 | if there is a word under construction, | |
440 | then it is finished and added to the output list; | |
441 | otherwise it is simply ignored. | |
442 | .hP \*o | |
443 | If a backslash is encountered, | |
444 | then a word is started if there is none currently under construction, | |
445 | and the character following the backslash is added to the current word. | |
446 | .hP \*o | |
447 | If a single-quote character | |
448 | .RB ` ' ' | |
449 | is encountered, | |
450 | then a word is started if there is none currently under construction, | |
451 | and | |
452 | .I all | |
453 | characters up to the next single quote | |
454 | are added to the current word. | |
455 | This includes double quotes, dollar signs, and backslashes. | |
456 | (Neither of the two single quotes is appended to the current word.) | |
457 | .hP \*o | |
458 | If a double-quote character | |
459 | .RB ` """" ' | |
460 | is encountered, | |
461 | then a word is started if there is none currently under construction. | |
462 | Until the next double quote is encountered, | |
ace01e71 | 463 | whitespace and single quotes are treated literally, |
8996f767 MW |
464 | and simply added to the current word; |
465 | backslashes can be used to escape characters, | |
466 | such as double quotes, | |
467 | as usual. | |
468 | .hP \*o | |
469 | If a | |
470 | .BR $ -expansion | |
471 | \(en a variable substitution or conditional (as described above) \(en | |
472 | is encountered | |
473 | and there is a current word under construction, | |
474 | then the result of the | |
475 | .BR $ -expansion | |
476 | is appended to the current word. | |
477 | If there is no current word, | |
478 | then the variable value, or consequent or alternative text, | |
479 | is subjected to word splitting in addition to expansion, | |
480 | and the resulting words appended to the output sequence. | |
481 | .hP \*o | |
482 | If any other character is encountered, | |
483 | then a word is started if there is none currently under construction, | |
484 | and the character is appended to the current word. | |
485 | .PP | |
486 | One case which deserves attention: | |
487 | if a | |
488 | .BR $ -expansion | |
489 | is encountered outside of a word, | |
490 | so that the result is subject to word splitting, | |
491 | then an error is reported if a new word is started | |
492 | without there being whitespace between the closing brace of the | |
ace01e71 | 493 | .BR $ -expansion |
8996f767 MW |
494 | and the character which started the new word. |
495 | For example, | |
496 | .IP | |
497 | .B "bad = one ${x}two" | |
498 | .PP | |
499 | would be invalid in a word-splitting context. | |
500 | . | |
10427eb2 MW |
501 | .SS "Other special variables" |
502 | In every section, the section's name | |
503 | is automatically assigned to the variable | |
504 | .BR @name . | |
505 | This variable | |
506 | .I can | |
507 | be overridden by an explicit assignment, | |
508 | but this is not recommended. | |
509 | . | |
8996f767 MW |
510 | .SS "Predefined variables in @BUILTIN" |
511 | The | |
512 | .B @BULITIN | |
ace01e71 | 513 | section has no parents. |
8996f767 | 514 | You should not override its settings in configuration files. |
ace01e71 | 515 | It holds a number of variables set by the |
8996f767 MW |
516 | .B runlisp |
517 | programs. | |
10427eb2 | 518 | . |
8996f767 MW |
519 | .TP |
520 | .B @data-dir | |
521 | The directory in which | |
522 | .BR runlisp 's | |
523 | auxiliary data files and scripts are located. | |
524 | This is determined by the | |
525 | .B RUNLISP_DATADIR | |
526 | environment variable, | |
527 | the | |
528 | .B data-dir | |
529 | variable in the | |
530 | .B @CONFIG | |
531 | section, | |
532 | or a value determined at compile time. | |
10427eb2 | 533 | . |
8996f767 MW |
534 | .TP |
535 | .B @ecl-opt | |
536 | The preferred option prefix for ECL, either | |
537 | .RB ` \- ' | |
538 | or | |
539 | .RB ` \-\- '. | |
540 | (For some reason, | |
541 | the ECL developers are changing | |
542 | the way ECL recognizes command-line options, | |
530dead4 | 543 | because they think that the minor \(aesthetic improvement |
8996f767 MW |
544 | is worth breaking everyone's scripts.) |
545 | This is determined by the | |
546 | .B ecl-opt | |
547 | variable in the | |
548 | .B @CONFIG | |
549 | section, | |
550 | or a value determined at compile time. | |
10427eb2 | 551 | . |
8996f767 | 552 | .TP |
c7af83cd MW |
553 | .B @hash |
554 | Set by | |
555 | .BR dump-runlisp-image (1) | |
556 | to the hash | |
557 | (a string of hexadecimal digits) | |
558 | identifying the versions of the Lisp code included | |
559 | \(en or to be included \(en | |
560 | in a custom image. | |
561 | This is constructed by hashing the result of evaluating the | |
562 | .B lisp-version | |
563 | expression in the system definition. | |
564 | . | |
565 | .TP | |
8996f767 MW |
566 | .B @image-dir |
567 | The directory in which | |
568 | .B runlisp | |
569 | looks for, and | |
570 | .B dump-runlisp-image | |
571 | stores, custom Lisp images. | |
572 | This is determined by the | |
573 | .B RUNLISP_IMAGEDIR | |
574 | environment variable, | |
575 | the | |
576 | .B image-dir | |
577 | variable in the | |
578 | .B @CONFIG | |
579 | section, | |
580 | or a value determined at compile time. | |
10427eb2 | 581 | . |
8996f767 | 582 | .TP |
c7af83cd MW |
583 | .B @image-link |
584 | The well-known name of the image; | |
585 | actually a symbolic link to the `real' image file, | |
586 | whose name includes a hash | |
587 | which identifies the versions of the Lisp code included in the image. | |
588 | . | |
589 | .TP | |
8996f767 MW |
590 | .B @image-new |
591 | Set by | |
592 | .BR dump-runlisp-image (1) | |
593 | to the filename that a | |
594 | .B dump-image | |
595 | command should create. | |
596 | .RB ( dump-runlisp-image | |
597 | will rename the image into place itself, | |
598 | if the command completes successfully.) | |
10427eb2 | 599 | . |
8996f767 | 600 | .TP |
c7af83cd MW |
601 | .B @image-newlink |
602 | Set by | |
603 | .BR dump-runlisp-image (1) | |
604 | to the name to use for the updated symbolic link to the image file. | |
605 | This is used internally, | |
606 | and is not expected to be useful in Lisp system definitions. | |
607 | . | |
608 | .TP | |
8996f767 MW |
609 | .B @image-out |
610 | Set by | |
611 | .BR dump-runlisp-image (1) | |
612 | to the filename of the intended output image. | |
613 | (Don't use this in | |
614 | .B dump-image | |
615 | commands: use | |
616 | .B @image-new | |
617 | instread.) | |
10427eb2 | 618 | . |
8996f767 MW |
619 | .TP |
620 | .B @script | |
621 | Set by | |
622 | .BR runlisp (1) | |
623 | to the name of the script being invoked. | |
10427eb2 | 624 | . |
8996f767 MW |
625 | .TP |
626 | .B @tmp-dir | |
627 | Set by | |
628 | .BR dump-runlisp-image (1) | |
629 | to be the name of a directory in which a | |
630 | .B dump-image | |
631 | command can put temporary files. | |
632 | . | |
10427eb2 MW |
633 | .SS "Environment variables in @ENV" |
634 | The | |
635 | .B @ENV | |
636 | section is special, | |
637 | and is used to hold a copy of the system environment. | |
638 | At startup, | |
639 | it contains an assignment for every environment variable. | |
640 | The | |
641 | .B @ENV | |
642 | section has no parents. | |
643 | The values are not expandable. | |
644 | It is possible to override | |
645 | .B @ENV | |
646 | settings in configuration files | |
647 | or on the command line, | |
8996f767 MW |
648 | but this is not recommended. |
649 | . | |
10427eb2 MW |
650 | .SS "The @COMMON section" |
651 | The | |
652 | .B @COMMON section | |
653 | is the default parent for nearly all other configuration sections | |
654 | (the exceptions being | |
655 | .B @BUILTIN | |
656 | and | |
657 | .BR @ENV , | |
658 | which have no parents, and | |
659 | .B @COMMON | |
660 | itself, whose parent is | |
661 | .BR @BUILTIN ). | |
662 | It is used in the provided configuration | |
663 | to hold various common snippets of Lisp code and other settings, | |
664 | but the | |
665 | .B runlisp | |
666 | programs themselves make no direct use of it. | |
8996f767 | 667 | . |
10427eb2 MW |
668 | .SS "Overall configuration in @CONFIG" |
669 | Variable settings in | |
670 | .B @CONFIG | |
671 | are consulted for various administrative reasons. | |
672 | .PP | |
673 | Because of the open-ended nature of this configuration mechanism, | |
674 | users can easily invent new configuration variables | |
675 | for any purpose they can imagine. | |
676 | The following variables are used by the | |
677 | .B runlisp | |
678 | programs directly, or its default configuration. | |
679 | All values are expanded before use; | |
680 | the | |
681 | .B @CONFIG | |
682 | section's parent is | |
683 | .BR @COMMON , | |
684 | as usual. | |
685 | . | |
686 | .TP | |
687 | .B data-dir | |
688 | The directory in which | |
689 | .BR runlisp 's | |
690 | auxiliary data files and scripts are located. | |
691 | There is a hardcoded default | |
692 | determined at compile-time, | |
693 | which is probably correct. | |
694 | Overridden by the | |
695 | .B RUNLISP_DATADIR | |
696 | environment variable. | |
697 | Don't refer to this setting directly: | |
698 | expand | |
699 | .B @data-dir | |
700 | from the | |
701 | .B @BUILTIN | |
702 | section instead. | |
703 | . | |
704 | .TP | |
705 | .B dump | |
706 | A comma-separated list of Lisp implementation names | |
707 | which should have custom images dumped by | |
708 | .BR "dump-runlisp-image \-a" . | |
709 | The order is not especially significant. | |
710 | The default is all of the configured implementations | |
711 | which define a | |
712 | .B dump-image | |
713 | variable | |
714 | and whose command can be found. | |
715 | . | |
716 | .TP | |
717 | .B ecl-opt | |
718 | The preferred option prefix for ECL, either | |
719 | .RB ` \- ' | |
720 | or | |
721 | .RB ` \-\- '. | |
722 | There is a hardcoded default | |
723 | determined at compile-time, | |
724 | which was correct for the system on which | |
725 | .B runlisp | |
726 | was built. | |
727 | Don't refer to this setting directly: | |
728 | expand | |
729 | .B @ecl-opt | |
730 | from the | |
731 | .B @BUILTIN | |
732 | section instead. | |
733 | . | |
734 | .TP | |
44ccabcb | 735 | .B image-dir |
10427eb2 MW |
736 | The directory in which |
737 | .B runlisp | |
738 | looks for, and | |
739 | .B dump-runlisp-image | |
740 | stores, custom Lisp images. | |
741 | Overridden by the | |
742 | .B RUNLISP_IMAGEDIR | |
743 | environment variable. | |
744 | Don't refer to this setting directly: | |
745 | expand | |
746 | .B @image-dir | |
747 | from the | |
748 | .B @BUILTIN | |
749 | section instead. | |
750 | . | |
751 | .TP | |
752 | .B prefer | |
753 | A comma-separated list of names of | |
754 | .I preferred | |
755 | Lisp implementations, | |
756 | Overridden by the | |
757 | .B RUNLISP_PREFER | |
758 | environment variable. | |
759 | . | |
760 | .SS "Lisp implementation definitions" | |
761 | A Lisp implementation is described to | |
762 | .B runlisp | |
763 | by a configuration section. | |
764 | The section's name is used to refer to the implementation, | |
765 | e.g., in | |
766 | .BR runlisp 's | |
767 | .B \-L | |
768 | option, | |
769 | or in the | |
770 | .B dump | |
771 | and | |
772 | .B prefer | |
773 | lists described above. | |
774 | .PP | |
775 | The following variable settings are used directly; | |
776 | of course, a Lisp implementation definition may contain other settings | |
777 | for internal purposes. | |
778 | . | |
779 | .TP | |
780 | .B command | |
781 | The name of the program used to invoke the Lisp implementation. | |
782 | .BR dump-runlisp-image | |
783 | looks to see whether this program is installed when invoked with the | |
784 | .B \-i | |
785 | option: | |
786 | it will fail if there is no | |
787 | .B command | |
788 | setting. | |
789 | It is also commonly | |
790 | (but not universally) | |
791 | used in the | |
792 | .B run-script | |
793 | and | |
794 | .B dump-image | |
795 | variables. | |
796 | It's conventional to set this to | |
797 | .B ${@ENV:FOO?foo} | |
798 | so that the command name can be overridden from the environment. | |
799 | . | |
800 | .TP | |
801 | .B dump-image | |
802 | The complete command to use to dump a custom image | |
803 | for this Lisp implementation. | |
804 | The value is subjected to expansion and word-splitting before use. | |
805 | It should write the newly created image to the file named by the | |
806 | .B @image-new | |
807 | setting in the | |
808 | .B @BUILTIN | |
809 | section. | |
810 | . | |
811 | .TP | |
812 | .B image-file | |
813 | The basename of the custom image file | |
814 | (i.e., not containing any | |
815 | .BR ` / ' | |
816 | characters) | |
817 | to use when invoking this Lisp implementation. | |
818 | .BR runlisp (1) | |
819 | and | |
820 | .BR dump-runlisp-image (1) | |
821 | use the presence of this setting to decide | |
822 | whether the implementation supports custom images. | |
823 | . | |
824 | .TP | |
825 | .B image-path | |
826 | The complete (but not necessarily absolute) pathname | |
827 | of the custom image file for this Lisp implementation. | |
828 | It is the (expanded) value of this variable | |
829 | which is used by | |
830 | .BR runlisp (1) | |
831 | when it checks whether a custom image exists. | |
832 | It's set to | |
833 | .B ${@image-dir}/${image-file} | |
834 | in the standard configuration file's | |
835 | .B @COMMON | |
836 | section, | |
837 | and there is probably no need to override it; | |
838 | .B @image-dir | |
839 | is set in the | |
840 | .B @BUILTIN | |
10427eb2 MW |
841 | section \(en see above \(en and |
842 | .B image-file | |
843 | must be set in this section | |
844 | (or one of its ancestors) | |
845 | before | |
846 | .BR runlisp (1) | |
847 | would not attempt to check for an image file. | |
848 | . | |
849 | .TP | |
850 | .B run-script | |
851 | The complete command to use | |
852 | to get this Lisp implementation to execute a script. | |
853 | The value is subjected to expansion and word-splitting before use. | |
854 | The script name is available as | |
855 | .B @script | |
856 | in the | |
857 | .B @BUILTIN | |
858 | section \(en see above. | |
859 | If a custom image is available, then | |
860 | .B @image | |
861 | is defined | |
862 | (to the value | |
863 | .BR t ) | |
864 | .I "in this section" | |
865 | (not in | |
866 | .BR @BUILTIN ); | |
867 | the full path to the image file to use is given by | |
868 | .B ${image-path} | |
869 | \(en see above. | |
870 | . | |
871 | .\"-------------------------------------------------------------------------- | |
8996f767 MW |
872 | . |
873 | .SH SEE ALSO | |
874 | .BR dump-runlisp-image (1), | |
875 | .BR query-runlisp-config (1), | |
876 | .BR runlisp (1). | |
877 | . | |
878 | .SH AUTHOR | |
879 | Mark Wooding, <mdw@distorted.org.uk> | |
880 | . | |
881 | .\"----- That's all, folks -------------------------------------------------- |