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 | .. | |
42 | .ds , \h'.16667m' | |
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 | |
257 | .B short is assigned | |
258 | .RB ` "just a quick note" '. | |
259 | .PP | |
260 | The assignments applied to a section | |
261 | need not have distinct variable names. | |
262 | Only the last assignment to a particular variable name in a section is | |
263 | .IR effective ; | |
264 | the earlier assignments are simply ignored. | |
265 | If an effective assignment assigns a value to a variable in a section, | |
266 | we say that the variable is | |
267 | .I set | |
268 | to that value in the section. | |
269 | . | |
270 | .SS "Lookup and inheritance" | |
271 | A section may have zero or more | |
272 | .I parent | |
273 | sections. | |
274 | .PP | |
275 | The | |
10427eb2 | 276 | .B @BUILTIN |
8996f767 MW |
277 | and |
278 | .B @ENV | |
279 | sections have no parents. | |
280 | The | |
281 | .B @CONFIG | |
282 | section has one parent, namely | |
283 | .BR @BUILTIN . | |
284 | .PP | |
285 | If the variable | |
286 | .B @parents | |
287 | is set in a section other than one of those named above, | |
288 | then it must consist of a space- or comma-separated list | |
289 | of names, | |
290 | which name the section's parents. | |
291 | Currently, the parents need not be distinct, | |
292 | though duplicates have no effect other than slowing down lookup. | |
293 | The order in which parents are listed is not significant. | |
294 | If | |
295 | .B @parents | |
296 | is not set in a section other than one of those named above, | |
297 | then by default it has one parent, namely | |
298 | .BR @COMMON . | |
299 | .PP | |
300 | It is currently possible to build a cyclic structure of parent links. | |
301 | This is not recommended. | |
302 | If lookup (explained below) detects a cycle | |
303 | then it will report a fatal error, | |
304 | but cycles may exist without being detected. | |
305 | .PP | |
306 | A variable is | |
307 | .I "looked up" | |
308 | in a section as follows. | |
309 | .hP 1. | |
310 | If there is an effective assignment | |
311 | of a value to that variable in the section | |
312 | then lookup finds that assignment. | |
313 | .hP 2. | |
314 | If the section has no parents, | |
315 | then lookup fails. | |
316 | .hP 3. | |
317 | Otherwise, the variable is looked up in each of the section's parents. | |
318 | If none of these lookups succeeds, then the lookup fails. | |
319 | If all of the successful lookups found the | |
320 | .I "same assignment" | |
321 | (not just the same value!) | |
322 | then lookup finds that assignment. | |
323 | Otherwise, the lookup reports an error. | |
324 | . | |
325 | .SS "Expansion and word-splitting" | |
326 | A value can be | |
327 | .I expanded | |
328 | relative to some home section, | |
329 | and optionally split into words. | |
330 | .PP | |
331 | Not all values are | |
332 | .IR expandable . | |
333 | Values set by assignments in a configuration file are always expandable. | |
334 | Values set on the command line \(en in | |
335 | .B \-o | |
336 | options \(en are not expandable. | |
337 | Values in the | |
338 | .B @ENV | |
339 | section from environment variables (see below) are not expandable. | |
340 | Some values set in the | |
341 | .B @BUILTIN | |
342 | section are expandable and some are not. | |
343 | Applying expansion to a value that is not expandable | |
344 | simply results in that same value, unchanged. | |
345 | .PP | |
346 | Applying expansion to an expandable value | |
347 | produces a result string as follows. | |
348 | The value is scanned from start to end. | |
349 | .hP \*o | |
350 | A backslash | |
351 | .RB ` \e ' | |
352 | is discarded, but the immediately following character | |
353 | is copied to the output without further inspection. | |
354 | .hP \*o | |
355 | A | |
356 | .I variable substitution | |
357 | takes the form | |
358 | .BR ${ [ \c | |
359 | .IB sect : \c | |
360 | .RI ] var \c | |
361 | .RB [ | \c | |
362 | .IR filter ]... \c | |
363 | .RB [ ? \c | |
364 | .IR alt ] \c | |
365 | .BR } . | |
366 | A variable named | |
367 | .I var | |
368 | is looked up in the section named | |
369 | .IR sect , | |
370 | or, if omitted, in the home section. | |
371 | If the lookup succeeds, | |
372 | then the value is expanded, | |
373 | processed by the | |
374 | .IR filter s | |
375 | (explained below), | |
376 | and appended to the output. | |
377 | If the lookup failed, | |
378 | and | |
379 | .BI ? alt | |
380 | is present, | |
381 | then | |
382 | .I alt | |
383 | is expanded and appended to the output. | |
384 | Otherwise, | |
385 | if the lookup fails and there is no | |
386 | .I alt | |
387 | text, then an error is reported. | |
388 | .IP | |
389 | A filter | |
390 | .B u | |
391 | causes the expanded value to be converted to uppercase; | |
392 | similarly, | |
393 | .B l | |
394 | causes the expanded value to be converted to lowercase. | |
395 | A filter | |
396 | .B q | |
397 | causes a backslash to be inserted before each | |
398 | backslash or double-quote character in the expanded value, | |
399 | so that this can be used as part of a quoted Common Lisp string. | |
400 | .hP \*o | |
401 | A | |
402 | .I conditional | |
403 | takes the form | |
404 | .BR $? [ \c | |
405 | .IB sect : \c | |
406 | .RI ] var \c | |
407 | .BI { conseq \c | |
408 | .RB [ | \c | |
409 | .IR alt ] \c | |
410 | .BR } . | |
411 | A variable named | |
412 | .I var | |
413 | is looked up in the section named | |
414 | .IR sect , | |
415 | or, if omitted, in the home section. | |
416 | If the lookup succeeds, then | |
417 | .I conseq | |
418 | is expanded and appended to the output; | |
419 | otherwise, if | |
420 | .I alt | |
421 | is present, then it is expanded and appended to the output; | |
422 | otherwise, nothing happens. | |
423 | .hP \*o | |
424 | A dollar sign which doesn't introduce one of the forms above | |
425 | is invalid, and a fatal error is reported. | |
426 | .hP \*o | |
427 | Any other characters are simply appended to the output. | |
428 | .PP | |
429 | Word-splitting is similar but more complex. | |
430 | The result is not a string, but a sequence of strings. | |
431 | At any given point in this procedure, | |
432 | there may be a partially constructed word, | |
433 | or there might not. | |
434 | .hP \*o | |
435 | Outside of quotes (see below), | |
436 | whitespace serves to separate words. | |
437 | When a whitespace character is encountered, | |
438 | if there is a word under construction, | |
439 | then it is finished and added to the output list; | |
440 | otherwise it is simply ignored. | |
441 | .hP \*o | |
442 | If a backslash is encountered, | |
443 | then a word is started if there is none currently under construction, | |
444 | and the character following the backslash is added to the current word. | |
445 | .hP \*o | |
446 | If a single-quote character | |
447 | .RB ` ' ' | |
448 | is encountered, | |
449 | then a word is started if there is none currently under construction, | |
450 | and | |
451 | .I all | |
452 | characters up to the next single quote | |
453 | are added to the current word. | |
454 | This includes double quotes, dollar signs, and backslashes. | |
455 | (Neither of the two single quotes is appended to the current word.) | |
456 | .hP \*o | |
457 | If a double-quote character | |
458 | .RB ` """" ' | |
459 | is encountered, | |
460 | then a word is started if there is none currently under construction. | |
461 | Until the next double quote is encountered, | |
462 | whitespace and single quotes treated literally, | |
463 | and simply added to the current word; | |
464 | backslashes can be used to escape characters, | |
465 | such as double quotes, | |
466 | as usual. | |
467 | .hP \*o | |
468 | If a | |
469 | .BR $ -expansion | |
470 | \(en a variable substitution or conditional (as described above) \(en | |
471 | is encountered | |
472 | and there is a current word under construction, | |
473 | then the result of the | |
474 | .BR $ -expansion | |
475 | is appended to the current word. | |
476 | If there is no current word, | |
477 | then the variable value, or consequent or alternative text, | |
478 | is subjected to word splitting in addition to expansion, | |
479 | and the resulting words appended to the output sequence. | |
480 | .hP \*o | |
481 | If any other character is encountered, | |
482 | then a word is started if there is none currently under construction, | |
483 | and the character is appended to the current word. | |
484 | .PP | |
485 | One case which deserves attention: | |
486 | if a | |
487 | .BR $ -expansion | |
488 | is encountered outside of a word, | |
489 | so that the result is subject to word splitting, | |
490 | then an error is reported if a new word is started | |
491 | without there being whitespace between the closing brace of the | |
492 | .B $ -expansion | |
493 | and the character which started the new word. | |
494 | For example, | |
495 | .IP | |
496 | .B "bad = one ${x}two" | |
497 | .PP | |
498 | would be invalid in a word-splitting context. | |
499 | . | |
10427eb2 MW |
500 | .SS "Other special variables" |
501 | In every section, the section's name | |
502 | is automatically assigned to the variable | |
503 | .BR @name . | |
504 | This variable | |
505 | .I can | |
506 | be overridden by an explicit assignment, | |
507 | but this is not recommended. | |
508 | . | |
8996f767 MW |
509 | .SS "Predefined variables in @BUILTIN" |
510 | The | |
511 | .B @BULITIN | |
512 | Section has no parents. | |
513 | You should not override its settings in configuration files. | |
514 | it holds a number of variables set by the | |
515 | .B runlisp | |
516 | programs. | |
10427eb2 | 517 | . |
8996f767 MW |
518 | .TP |
519 | .B @data-dir | |
520 | The directory in which | |
521 | .BR runlisp 's | |
522 | auxiliary data files and scripts are located. | |
523 | This is determined by the | |
524 | .B RUNLISP_DATADIR | |
525 | environment variable, | |
526 | the | |
527 | .B data-dir | |
528 | variable in the | |
529 | .B @CONFIG | |
530 | section, | |
531 | or a value determined at compile time. | |
10427eb2 | 532 | . |
8996f767 MW |
533 | .TP |
534 | .B @ecl-opt | |
535 | The preferred option prefix for ECL, either | |
536 | .RB ` \- ' | |
537 | or | |
538 | .RB ` \-\- '. | |
539 | (For some reason, | |
540 | the ECL developers are changing | |
541 | the way ECL recognizes command-line options, | |
542 | because they think that the minor aesthetic improvement | |
543 | is worth breaking everyone's scripts.) | |
544 | This is determined by the | |
545 | .B ecl-opt | |
546 | variable in the | |
547 | .B @CONFIG | |
548 | section, | |
549 | or a value determined at compile time. | |
10427eb2 | 550 | . |
8996f767 | 551 | .TP |
c7af83cd MW |
552 | .B @hash |
553 | Set by | |
554 | .BR dump-runlisp-image (1) | |
555 | to the hash | |
556 | (a string of hexadecimal digits) | |
557 | identifying the versions of the Lisp code included | |
558 | \(en or to be included \(en | |
559 | in a custom image. | |
560 | This is constructed by hashing the result of evaluating the | |
561 | .B lisp-version | |
562 | expression in the system definition. | |
563 | . | |
564 | .TP | |
8996f767 MW |
565 | .B @image-dir |
566 | The directory in which | |
567 | .B runlisp | |
568 | looks for, and | |
569 | .B dump-runlisp-image | |
570 | stores, custom Lisp images. | |
571 | This is determined by the | |
572 | .B RUNLISP_IMAGEDIR | |
573 | environment variable, | |
574 | the | |
575 | .B image-dir | |
576 | variable in the | |
577 | .B @CONFIG | |
578 | section, | |
579 | or a value determined at compile time. | |
10427eb2 | 580 | . |
8996f767 | 581 | .TP |
c7af83cd MW |
582 | .B @image-link |
583 | The well-known name of the image; | |
584 | actually a symbolic link to the `real' image file, | |
585 | whose name includes a hash | |
586 | which identifies the versions of the Lisp code included in the image. | |
587 | . | |
588 | .TP | |
8996f767 MW |
589 | .B @image-new |
590 | Set by | |
591 | .BR dump-runlisp-image (1) | |
592 | to the filename that a | |
593 | .B dump-image | |
594 | command should create. | |
595 | .RB ( dump-runlisp-image | |
596 | will rename the image into place itself, | |
597 | if the command completes successfully.) | |
10427eb2 | 598 | . |
8996f767 | 599 | .TP |
c7af83cd MW |
600 | .B @image-newlink |
601 | Set by | |
602 | .BR dump-runlisp-image (1) | |
603 | to the name to use for the updated symbolic link to the image file. | |
604 | This is used internally, | |
605 | and is not expected to be useful in Lisp system definitions. | |
606 | . | |
607 | .TP | |
8996f767 MW |
608 | .B @image-out |
609 | Set by | |
610 | .BR dump-runlisp-image (1) | |
611 | to the filename of the intended output image. | |
612 | (Don't use this in | |
613 | .B dump-image | |
614 | commands: use | |
615 | .B @image-new | |
616 | instread.) | |
10427eb2 | 617 | . |
8996f767 MW |
618 | .TP |
619 | .B @script | |
620 | Set by | |
621 | .BR runlisp (1) | |
622 | to the name of the script being invoked. | |
10427eb2 | 623 | . |
8996f767 MW |
624 | .TP |
625 | .B @tmp-dir | |
626 | Set by | |
627 | .BR dump-runlisp-image (1) | |
628 | to be the name of a directory in which a | |
629 | .B dump-image | |
630 | command can put temporary files. | |
631 | . | |
10427eb2 MW |
632 | .SS "Environment variables in @ENV" |
633 | The | |
634 | .B @ENV | |
635 | section is special, | |
636 | and is used to hold a copy of the system environment. | |
637 | At startup, | |
638 | it contains an assignment for every environment variable. | |
639 | The | |
640 | .B @ENV | |
641 | section has no parents. | |
642 | The values are not expandable. | |
643 | It is possible to override | |
644 | .B @ENV | |
645 | settings in configuration files | |
646 | or on the command line, | |
8996f767 MW |
647 | but this is not recommended. |
648 | . | |
10427eb2 MW |
649 | .SS "The @COMMON section" |
650 | The | |
651 | .B @COMMON section | |
652 | is the default parent for nearly all other configuration sections | |
653 | (the exceptions being | |
654 | .B @BUILTIN | |
655 | and | |
656 | .BR @ENV , | |
657 | which have no parents, and | |
658 | .B @COMMON | |
659 | itself, whose parent is | |
660 | .BR @BUILTIN ). | |
661 | It is used in the provided configuration | |
662 | to hold various common snippets of Lisp code and other settings, | |
663 | but the | |
664 | .B runlisp | |
665 | programs themselves make no direct use of it. | |
8996f767 | 666 | . |
10427eb2 MW |
667 | .SS "Overall configuration in @CONFIG" |
668 | Variable settings in | |
669 | .B @CONFIG | |
670 | are consulted for various administrative reasons. | |
671 | .PP | |
672 | Because of the open-ended nature of this configuration mechanism, | |
673 | users can easily invent new configuration variables | |
674 | for any purpose they can imagine. | |
675 | The following variables are used by the | |
676 | .B runlisp | |
677 | programs directly, or its default configuration. | |
678 | All values are expanded before use; | |
679 | the | |
680 | .B @CONFIG | |
681 | section's parent is | |
682 | .BR @COMMON , | |
683 | as usual. | |
684 | . | |
685 | .TP | |
686 | .B data-dir | |
687 | The directory in which | |
688 | .BR runlisp 's | |
689 | auxiliary data files and scripts are located. | |
690 | There is a hardcoded default | |
691 | determined at compile-time, | |
692 | which is probably correct. | |
693 | Overridden by the | |
694 | .B RUNLISP_DATADIR | |
695 | environment variable. | |
696 | Don't refer to this setting directly: | |
697 | expand | |
698 | .B @data-dir | |
699 | from the | |
700 | .B @BUILTIN | |
701 | section instead. | |
702 | . | |
703 | .TP | |
704 | .B dump | |
705 | A comma-separated list of Lisp implementation names | |
706 | which should have custom images dumped by | |
707 | .BR "dump-runlisp-image \-a" . | |
708 | The order is not especially significant. | |
709 | The default is all of the configured implementations | |
710 | which define a | |
711 | .B dump-image | |
712 | variable | |
713 | and whose command can be found. | |
714 | . | |
715 | .TP | |
716 | .B ecl-opt | |
717 | The preferred option prefix for ECL, either | |
718 | .RB ` \- ' | |
719 | or | |
720 | .RB ` \-\- '. | |
721 | There is a hardcoded default | |
722 | determined at compile-time, | |
723 | which was correct for the system on which | |
724 | .B runlisp | |
725 | was built. | |
726 | Don't refer to this setting directly: | |
727 | expand | |
728 | .B @ecl-opt | |
729 | from the | |
730 | .B @BUILTIN | |
731 | section instead. | |
732 | . | |
733 | .TP | |
734 | .B @image-dir | |
735 | The directory in which | |
736 | .B runlisp | |
737 | looks for, and | |
738 | .B dump-runlisp-image | |
739 | stores, custom Lisp images. | |
740 | Overridden by the | |
741 | .B RUNLISP_IMAGEDIR | |
742 | environment variable. | |
743 | Don't refer to this setting directly: | |
744 | expand | |
745 | .B @image-dir | |
746 | from the | |
747 | .B @BUILTIN | |
748 | section instead. | |
749 | . | |
750 | .TP | |
751 | .B prefer | |
752 | A comma-separated list of names of | |
753 | .I preferred | |
754 | Lisp implementations, | |
755 | Overridden by the | |
756 | .B RUNLISP_PREFER | |
757 | environment variable. | |
758 | . | |
759 | .SS "Lisp implementation definitions" | |
760 | A Lisp implementation is described to | |
761 | .B runlisp | |
762 | by a configuration section. | |
763 | The section's name is used to refer to the implementation, | |
764 | e.g., in | |
765 | .BR runlisp 's | |
766 | .B \-L | |
767 | option, | |
768 | or in the | |
769 | .B dump | |
770 | and | |
771 | .B prefer | |
772 | lists described above. | |
773 | .PP | |
774 | The following variable settings are used directly; | |
775 | of course, a Lisp implementation definition may contain other settings | |
776 | for internal purposes. | |
777 | . | |
778 | .TP | |
779 | .B command | |
780 | The name of the program used to invoke the Lisp implementation. | |
781 | .BR dump-runlisp-image | |
782 | looks to see whether this program is installed when invoked with the | |
783 | .B \-i | |
784 | option: | |
785 | it will fail if there is no | |
786 | .B command | |
787 | setting. | |
788 | It is also commonly | |
789 | (but not universally) | |
790 | used in the | |
791 | .B run-script | |
792 | and | |
793 | .B dump-image | |
794 | variables. | |
795 | It's conventional to set this to | |
796 | .B ${@ENV:FOO?foo} | |
797 | so that the command name can be overridden from the environment. | |
798 | . | |
799 | .TP | |
800 | .B dump-image | |
801 | The complete command to use to dump a custom image | |
802 | for this Lisp implementation. | |
803 | The value is subjected to expansion and word-splitting before use. | |
804 | It should write the newly created image to the file named by the | |
805 | .B @image-new | |
806 | setting in the | |
807 | .B @BUILTIN | |
808 | section. | |
809 | . | |
810 | .TP | |
811 | .B image-file | |
812 | The basename of the custom image file | |
813 | (i.e., not containing any | |
814 | .BR ` / ' | |
815 | characters) | |
816 | to use when invoking this Lisp implementation. | |
817 | .BR runlisp (1) | |
818 | and | |
819 | .BR dump-runlisp-image (1) | |
820 | use the presence of this setting to decide | |
821 | whether the implementation supports custom images. | |
822 | . | |
823 | .TP | |
824 | .B image-path | |
825 | The complete (but not necessarily absolute) pathname | |
826 | of the custom image file for this Lisp implementation. | |
827 | It is the (expanded) value of this variable | |
828 | which is used by | |
829 | .BR runlisp (1) | |
830 | when it checks whether a custom image exists. | |
831 | It's set to | |
832 | .B ${@image-dir}/${image-file} | |
833 | in the standard configuration file's | |
834 | .B @COMMON | |
835 | section, | |
836 | and there is probably no need to override it; | |
837 | .B @image-dir | |
838 | is set in the | |
839 | .B @BUILTIN | |
840 | section | |
841 | .RB ( @image-dir | |
842 | is set in the | |
843 | .N @BUILTIN | |
844 | section \(en see above \(en and | |
845 | .B image-file | |
846 | must be set in this section | |
847 | (or one of its ancestors) | |
848 | before | |
849 | .BR runlisp (1) | |
850 | would not attempt to check for an image file. | |
851 | . | |
852 | .TP | |
853 | .B run-script | |
854 | The complete command to use | |
855 | to get this Lisp implementation to execute a script. | |
856 | The value is subjected to expansion and word-splitting before use. | |
857 | The script name is available as | |
858 | .B @script | |
859 | in the | |
860 | .B @BUILTIN | |
861 | section \(en see above. | |
862 | If a custom image is available, then | |
863 | .B @image | |
864 | is defined | |
865 | (to the value | |
866 | .BR t ) | |
867 | .I "in this section" | |
868 | (not in | |
869 | .BR @BUILTIN ); | |
870 | the full path to the image file to use is given by | |
871 | .B ${image-path} | |
872 | \(en see above. | |
873 | . | |
874 | .\"-------------------------------------------------------------------------- | |
8996f767 MW |
875 | . |
876 | .SH SEE ALSO | |
877 | .BR dump-runlisp-image (1), | |
878 | .BR query-runlisp-config (1), | |
879 | .BR runlisp (1). | |
880 | . | |
881 | .SH AUTHOR | |
882 | Mark Wooding, <mdw@distorted.org.uk> | |
883 | . | |
884 | .\"----- That's all, folks -------------------------------------------------- |