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