ToC | DocOverview | CGDoc | RelNotes | FAQ | Index | PermutedIndex
| Allegro CL version 11.0

# 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

Flag | Flag argument | Meaning
`i` | filename | The input bundle file.
`o` | filename | The output bundle file.
`d` | string | Documentaion for the bundle.
`t` |  | Verbose operation.
`x` |  | Extract fasl files from bundle.
`f` | freshen | replace each file in the bundle by the corresponding ordinary file if the ordinary file is newer.

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

Argument | Meaning
-A | Following files are to be added to the output bundle; if the bundle already has a file by that name, the conflict is reported and the one from the old bundle is retained.
-R | Following files are to replace existing members of the bundle; if the member is not found in the input bundle, the discrepancy is reported and the new file is added to the output bundle.
-N | Following files are to replace existing members if the file's timestamp indicates that the file is newer than the version in the bundle file. The timestamp is written in the file by the compiler and is copied to the bundle file when the file is placed in the bundle. The filesystem timestamp is ignored.
-D | Following files are to be excluded from the copy; if the input bundle does not have the member, the discrepancy is reported and processing continues.

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) Franz Inc. Lafayette, CA., USA. All rights reserved.

ToC | DocOverview | CGDoc | RelNotes | FAQ | Index | PermutedIndex
| Allegro CL version 11.0