Other Allegro CL Associated Programs

1.0 Introduction to other programs

The Allegro CL distribution includes some additional executable programs in addition to the various Lisp executables. These are utility programs that perform certain tasks better done outside of Lisp.

The programs are in the bin/ subdirectory of the distribution.

1.1 Other programs listing

• bundle
• cvdcvt and cvdcvti: programs used to create .pll files. See Creating and using pll files in miscellaneous.html.
• fasldump: Dumps the contents of a fasl file.
• faslinfo: The program prints information about its argument fasl files.
• make_shared
• plldump: this program pldump presents information about the contents of various kinds of files that go into the making of a pure-lisp-library (.pll) file, as well as the .pll file itself.

2.0 The bundle program

A standalone program to create a large file which fasl can randomly access from a collection of smaller ones.

bundle command line

bundle [-]flags [flag-arg ...] [file-arg ...]

The flag args are

The flag argumentss, if any, are supplied in the same order as the corresponding flags.

• Only one of o and x can be chosen.
• Only one of f and x can be chosen.
• If there is an x, there must be an i.
• If there is an f, there must be an i and an o.
• The i and o args cannot be the same.
• If there is an f, there can be no file-args.

And if there is an o, then the output bundle file gets all the members of the input bundle file, if any, except those that are marked for deletion in the file-args or are replaced from the file-args (see below). It also gets any fasl files marked for addition in the file-args.

File arguments

Examples:

Creating a bundle file:

% [acldir]/bin/bundle o file.bu [-d docstring] file1 file2 ...

Listing the contents of a bundle file:

% [acldir]/bin/bundle it file.bu

To update a file's contents in a bundle:

% [acldir]/bin/bundle io file.bu.in file.bu.out -R file1 file2
 
To extract all bundle members containing the string "ef-" 
in their names:

% [acldir]/bin/bundle ix file.bu -e ef-

3.0 The cvdcvt and cvdcvti programs

These programs are used to create .pll files which can hold string and codevectors. See Creating and using pll files in miscellaneous.html for more information.

4.0 The fasldump program

The fasldump program prints lots of information about the contents of a fasl file. This program is rarely useful except for debugging in exceptional circumstances (where you are asked to provide the information it produces).

fasldump command line

[acldir]/bin/fasldump -n -p

Arguments

-n: print the fasl file name on each line.

-p: include the file position numbers in the output

Example

foo:cl: (defun foo (x) (print x))

cl-user(1): :cf foo
;;; Compiling file foo.cl
;;; Writing fasl file /tmp/cfta308390746301
;;; Moving fasl file /tmp/cfta308390746301 to foo.fasl
;;; Fasl write complete
cl-user(2): 

% ./acl11.0.64/bin/fasldump ~/foo.fasl -n -p
File: /home/user/foo.fasl
/home/user/foo.fasl [0] Magic number ok (243), timestamp=0xe9a2d246: Mon Mar 18 07:46:30 2024
n/home/user/foo.fasl [5] c=0x23( 35): Comment(#): <<AcL>> foo.cl by user on gemini.franz.com at 2024-03-18T07:46:30+08\
using 11.0 [64-bit Linux (x86-64)]\
fasl version = 69\
runtime version = 39\
for non-smp lisps\
Optimization settings at wfasl time:\
((safety 1) (space 1) (speed 1) (compilation-speed 1) (debug 2))\
;\
;\

/home/user/foo.fasl [281] c=0x2a( 42): faslversion: machine id: class 0, fasl release 69, rs release 39, machine code 0xd01
/home/user/foo.fasl [289] c=0x29( 41): cversion: "11.0 [64-bit Linux (x86-64)]" size=28

[and many more lines]

5.0 The faslinfo program

The program prints information about the argument fasl files. Note that the first section of any fasl file is pure text, and can be passed through the head program to display quite a bit of information about the file separately from faslinfo.

faslinfo command line:

% [acldir]/bin/faslinfo [fasl-file]*

First we create a fasl file and use head:

CL-USER(2): (shell "cat foo.cl")
(defun foo (x)
  (car x))

0
CL-USER(3): :cf foo
;;; Compiling file foo.cl
;;; Writing fasl file /tmp/cfta70240832061
;;; Moving fasl file /tmp/cfta70240832061 to foo.fasl
;;; Fasl write complete
CL-USER(4):

% head foo.fasl  [Some unprintable characters removed and other local details X'ed out or modified]
#<<AcL>> foo.cl by XXXXX on [MACHINE] at 2019-04-12T08:32:06+08\
using [VERSION] [64-bit Linux (x86-64)] ([DATE])\
fasl version = 67\
runtime version = 37\
for non-smp lisps\
Optimization settings at wfasl time:\
((SAFETY 1) (SPACE 1) (SPEED 1) (COMPILATION-SPEED 1) (DEBUG 2))\
;\
;\

% 

Here is the faslinfo output (again we hide some information):

% bin/faslinfo foo.fasl
File: foo.fasl
==============================
timestamp = 0xe99c54ca: Wed [DATE]
Comment(#): <<AcL>> foo.cl by [USER] on [MACHINE] at [DATE]T09:37:30+08\
using [VERSION] [64-bit Linux (x86-64)]\
fasl version = 69\
runtime version = 39\
for non-smp lisps\
Optimization settings at wfasl time:\
((safety 1) (space 1) (speed 1) (compilation-speed 1) (debug 2))\
;\
;\

Table of Contents (5 elements):
 fasl file end:     2077
 number of symbols: 0
 cross-reference:   1193
 source file info:  1780
 source debug info: 0
% 

Note that However, faslinfo differs from head output in two ways:

1. faslinfo doesn't print the possibly-non-unicode characters that may come at the beginning of the fasl file and which head attempts to print.

2. faslinfo prints more info than is available in the head output:

   a. It includes the timestamp of the fasl file (note that the time written in the head output is not the timestamp of the fasl file, but of the Lisp writing the fasl file).

   b. It includes a Table of Contents. The TOC shows various aspects of the fasl file that may be useful in determining what is contained in the fasl file:

    i. The TOC shows the end of the file.  This is not necessarily
       the end of the actual *fasl* file, in the case where multiple
       *fasl* files have been concatenated.  See #3, below.
   
    ii. The TOC shows the number of symbols created.  This is the
        maximum of symbols in any of the subsequent sections of the
        file.
   
    iii. It shows starting byte (octet) locations for the
        cross-reference, source file info, and source debug info
        sections in the *fasl* file.  If any sections are missing, they
        are shown as 0.

3. faslinfo prints info for every fasl file represented in a physical file. If two or more fasl files have been concatenated together, they are all represented by faslinfo, whereas the head program only sees the first concatenated program.

6.0 The make_shared program

The make_shared program is used to create shared object file suitable for loading foreign function code into a running Lisp.

The command line is:

% make_shared -o file.so file1 [file2 ...]

See the Foreign Functions document for more information.

7.0 The plldump program

plldump presents information about the contents of various kinds of file that go into the making of a pure-lisp-library (.pll) file, as well as the .pll file itself.

*command line:

plldump [-h|-p|-t|-v] [-s section] [-m map-address] [-a fault-address]
                   [-b begin-index] [-e end-index] pllfile ...
plldump [-h|-t|-v] [-b begin-index] [-e end-index] cvsfile ...
plldump [-h|-t|-v] [-b begin-index] [-e end-index] strfile ...
plldump [-h|-t|-v] [-b begin-index] [-e end-index] gcifile ...

The four kinds of file that can be described are .pll (pure lisp library), .cvs (code-vectors file), .str (strings file) and .gci (gc-info file). The last three file types mentioned are slightly raw, and they have very little header, so not as much information is available about those files as is with the .pll file.

plldump can dump portions of an appropriate file, or it can look into a pll file (only) for an address and find the object that that address is a part of - presumably a faulting address.

When a Lisp uses a .pll file it maps the file into memory as a read-only section of memory. The mapping address can be seen by using the room function - either the call (room) or (room t) will print, among other things, the Lisp heap address, the Aclmalloc heap address, and (if it is used) the Pure space. The starting address of that space is called the map address.

The pll file has no actual Lisp pointers in it, so it can be located anywhere in memory that is valid. The pll file has no preferred map address - it is the Lisp which records an address to which the pll file had been mapped, and upon restart after a dumplisp the Lisp tries to map the pll file at the same location for the sake of the objects in its heap which are pointing to the purespace. If this can't be accomplished, the pll file is mapped wherever the system chooses, and then a relocation is performed to adjust pointers in the Lisp heap which would have pointed to objects in the pll file so that they are now pointing to the same object with the pll file at its new map address.

Multiple files can be dumped with one command, and some of the options (the -b, -e, -h, -s, -t, and -v options) carry over to all files unless/until changed by specifying them again, if appropriate. The paradigm of plldump options files options files ... is not a traditional shell style, but is available if needed, with restrictions.

Options are as follows:

• -a address: Search for address within the pll file (the fault address) and describe where it is located. If the address is within one of the object sections the object that contains the address will be described if possible. The fault address only takes effect for the next pll file on the command line; unless re-specified no fault address is assumed.

• -b begin-index: Specify the index of the object in the specification from which to begin printing. The indexing starts at 0 for whatever part(s) of the file is(are) selected. If the -s option is also specified for a pll file, the index starts at 0 for just that section. If the -b option is not specified, the beginning index is assumed to be 0.

• -e end index: Specify the index of the object one past the last object to print. If the -e option is not specified, it is assumed to be the index past the last indexed object, but if the -b option is specified, then the end index is assumed to be one past the begin index - i.e. if -b indexes an actual object then exactly that one object is printed.

• -h: Print the header of the file. For a pll file, the header consists of many slots, most of which are described. For other file types, the headers mostly consist of the file magic, a timestamp, and the number of items in the file. This option is sticky; once specified, there is no way to unspecify it for other files listed in the same command line.

• -m address: Specify where the pll file is mapped. The map address only takes effect for the next pll file on the command line; after that the map address is unspecified. If the map address is specified for a pll file, all addresses are printed as memory-mapped addressed. To decide what address to use for this option, a running lisp is required, and (room) or (room t) can be called to find the "Pure space" value given within the room output.

• -s section: For a pll file, specify the section to print from. For actual section names, only the first character of each section type is considered, so the options to choose a single section for output are c[ode...], s[tring...], or g[c-info]. The default is to include all sections of the pll file and that can be explicitly choosing all (no contractions) as the section name.

• -t: Terse mode: this is the default, unless the -a option is used. In terse mode all lists are printed one line per entry, regardless of the content of each object - even strings with explicit newlines within them are printed with "\n" instead of the newline character. Strings are truncated after a resonable length is printed to identify the string, and any elided information is indicated with elipses ("..."). Elipses are also used to indicate termination of a gc-info object, which is normally printed with a series of program-counter locations for census points within it. Code vectors are simply described in one line.

• -v: Verbose mode: With this mode, all of each object is output, regardless of how many lines it takes. Strings are printed fully, including actual newlines. gc info objects are printed with all of their census-point program counters listed in monotonic/ascending order.

Copyright (c) 2023, Franz Inc. Lafayette, CA., USA. All rights reserved.