# Frequently Asked Questions (With Answers) about &clisp;

This is a list of frequently asked questions about &clisp; on the CLISP mailing lists and the USENET newsgroup comp.lang.lisp. All the legitimate technical question are addressed in the &clisp; documentation (, ), and for such questions this list provides a link into the docs. The frequently asked political questions are answered here in full detail (meaning that no further explanations of the issues could be provided).

Please submit more questions (and answers!) to clisp-list.

## FAQ

## Meta Information

## Miscellaneous

What is FAQ fine?

We assess a nominal fine of $10 for asking a question that is answered with a link to this FAQ document. We further assess a fine of $1 for asking a question that is answered with a link to the &clisp; manual. The fines are payable to the person who answered your questions. If you consider these amounts to be exorbitant, please feel free to ignore this blatant extortion and do not pay.

This should &not-e; discourage you from asking questions, but rather encourage you to read the manual and answer questions from other users.

The official &clisp; documentation sucks - is anything better available?

As with all generic complaints, the answer to this one is PTCPatches Thoughtfully Considered.

Additionally, the nightly builds of the &clisp; implementation notes documenting the current &cvs; HEAD are available at . It contains both the documentation for the new features and the general improvements in the documentation.

License - why &gnu; &gpl;?

Because &clisp; uses &readline;.

Note that this does not necessarily prevent you from distributing your proprietary products based on &clisp;. See Note in `COPYRIGHT`.

What about &ansi-cl; compliance?

&clisp; purports to conform to the &ansi-cl; specification, so all deviations in

    &sh-prompt; clisp &opt-ansi;

from the &ansi-cl; standard are bugs and are not (yet) fixed only due to lack of resources.

On the other hand, some decisions made by the ANSI X3J13 committee were not as justified from the technical point of view as were most of them, and some of those questionable decisions were made &after-e; the alternative behavior has already been implemented in &clisp;. The &clisp; developers took pains to modify &clisp; to unconditionally comply with the &ansi-cl; specification in all cases except for a handful of situations where they believed that the committee had made a mistake, in which cases the committee behavior is still optionally available.

&clisp; does not start in the ansi mode by default for historical reasons and this is not about to change. Dumping an image or passing a command line argument are easy enough.

How do I ask for help?

&clisp;

Type &help; and hit Enter.

Human

Politely - please refer to &netiquette;.

If you have a question about &clisp;, you have the following options (listed in the order of decreasing audience size):

USENET group comp.lang.lisp

  This is the right place to ask all general Lisp questions, such as "how do I access a character in a string?"

&clisp; User Mailing List clisp-list
AKA

  This is the right place to ask user-level &clisp;-specific questions, such as "how do I save my &clisp; image?"

&clisp; Developer Mailing List clisp-devel
AKA

  This is the right place to discuss &clisp; internals, submit patches, offer help.

Individual &clisp; developers

  This is never the right thing to do, unless you want to hire this developer to do &clisp; consulting (commercial support, custom enhancements etc). This is actually for your own benefit: the &clisp; developers are very busy, they might get weeks to answer your question, and some other user may be able to help you in the meantine; as well as for the benefit of the other &clisp; users, since the mailing lists are publicly archived (you are encouraged to search them before asking).

  Please do &not-e; copy your messages to the individual developers.

## Mailing lists are member-only

To avoid spam, we require that you subscribe before you can post to a mailing list. Alternatively, you can post to the &clisp; web forum and your message will be forwarded to the clisp-list mailing list. If you read a list on Gmane and do not want to receive it also by e-mail, you can subscribe to it using the aforementioned web interface and then disable mail delivery.

Which mailing lists should I subscribe to?

Cross-posting in the &clisp; mailing lists is very actively discouraged and is virtually non-existent, thus you can subscribe to all mailing lists that are relevant to you without getting duplicate messages:

clisp-announce

  Extremely low-level moderated list, you should definitely subscribe to this list if you have any interest in &cl; or &clisp; whatsoever.

clisp-list

  Subscribe to this list of you use &clisp; and want to ask (and answer!) questions. If you subscribe to this list, you probably want to subscribe to clisp-announce too.

clisp-devel

  Subscribe to this list if you want to influence &clisp; developments; &cvs; commit notes go here (as a daily digest). If you subscribe to this list, you probably want to subscribe to clisp-list &and-e; clisp-announce too.

Why is my mail to a mailing list rejected?

&clisp; mailing lists get a lot of spam, so the maintainers have to take care to protect the users. If you get a note that your message is held for moderator's approval, you can safely assume that it went to `/dev/null` and try again, noting the following:

clisp-announce

  do not mail here without a prior discussion on clisp-devel or clisp-list

clisp-devel

  subscriber-only, you &must-e; post from a subscribed address, no exceptions (see above)

clisp-list

  used to be the only open list (it is closed now), so it is filtered especially aggressively:

  - no &mime; mail (no &html; formatting, no attachments - send the URL instead)

  - the list address must be in `CC` or `TO`, not `BCC`.

  - do not mention virgin, penis or viagra in the `Subject` line.

If you do not like this policy, please volunteer to maintain the mailing lists - you will be required to go through all the held for moderator's approval mail and approve/discard as appropriate at least twice a day.

How do I report bugs?

Patiently!

How do I help?

Please read and submit your patch, together with a `src/ChangeLog` entry (see other entries there for inspiration), to clisp-devel.

See `src/CodingStyle` for the style one should follow.

If your patch is more than just a few lines, it is much preferred that you make your patch available on the web and send the link to the list.

The patch must be against the &cvs; head (reasonably recent).

How do I debug &clisp;?

## Debugging the core

    &sh-prompt; ./configure --with-debug --build build-g
    &sh-prompt; cd build-g
    &sh-prompt; gdb lisp.run ;; or lisp.exe on windows and cygwin
    (gdb) boot
    (gdb) run

## Debugging module `foo`

    &sh-prompt; ./configure --with-debug --with-module=foo --build build-g
    &sh-prompt; cd build-g
    &sh-prompt; gdb full/lisp.run ;; or lisp.exe on windows and cygwin
    (gdb) full
    (gdb) run

When debugging a &base; module, use `base` instead of `full` and `boot` above.

## The impact of generational &gc;or

If your &clisp; was built with generational &gc;or, you will see plenty of spurious segfaults (that's how the generational &gc;or works). At the end of `src/.gdbinit` you will find the following suggested &gdb; commands:

    handle SIGSEGV noprint nostop
    break sigsegv_handler_failed

which will stop execution on a dangerous segfault. You can find out whether this is needed by examining the output of the following command:

    &sh-prompt; clisp --version | grep GENERATIONAL_GC

## Useful commands

You are encouraged to make use of commands defined in `src/.gdbinit`, such as

- `boot`
- `base`
- `full`
- `run_test`
- `run_all_tests`
- `ansi_tests`
- `xout`
- `zout`

and others.

## Macros

&clisp; makes heavy use of &cpp; macros (e.g., `pushSTACK`), which can complicate debugging in &gdb;. The macros are defined in `src/lispbibl.d`, but the maze of conditionals may be hard to navigate. If you are using &gcc;, you can do `make lispbibl.h` and then examine the definitions in the generated `lispbibl.h`. See also bottom of `src/spvw_debug.d`.

## Logo

Why is &clisp; using menorah as the logo?

Whimsical

If you must have some answer and you do not care whether it is correct or not, you may simply think that &cl; brings the Light to a programmer, and &clisp; is a vehicle that carries the Light.

Accordingly, &clisp; enables you to see the truth, thus you can pronounce it as see-lisp. Alternatively, if you are a seasoned expert, you might pronounce it as sea-lisp.

Historical

&clisp; has been using the menorah for the logo since the project was first started in the late 1980-ies by Bruno Haible and Michael Stoll. This probably reflects the authors' affection toward the Jewish people, Judaism or the State of Israel (neither of the two original authors is Jewish by birth). You may ask the original authors for details yourself. Both of them are very busy though, so do not expect a prompt reply.

Shouldn't the logo be changed now due to the current political developments in the Middle East?

The &clisp; developers, both the original creators and the current maintainers, do not subscribe to the mainstream view that blames the Jews for everything from high oil prices and Islamic extremism to El Niño and Sun spots.

Moreover, today, when Jews are being pushed out of the American and European academic institutions with various obscene boycott and divestment campaigns, it is crucial for all of us to stand together against the resurgence of Nazism.

For more information, please see:

- Committee for Accuracy in Middle East Reporting in America

- Information Regarding Israel's Security

- Middle East Media Research Institute

- YES to peace, NO to terror

- More links

Aren't there other political issues of concern?

Yes, there are! For example, in 1989 the communist government of the People's Republic of China murdered some 3000+ student human rights protesters at the Tienanmen square in Beijing, and people appear to have already forgotten this crime. A note to that effect was kept in the file `src/timezone.lisp` until 2002, when it was decided that is was not visible enough there and it was moved here.

We also oppose software patents and support other liberal (i.e., pro-liberty) causes.

Aren't you afraid of losing some users who are offended by the logo?

Do you have in mind people like this one? Good riddance!

Using software to promote a political agenda is unprofessional!

Expressing their opinion is a perfectly natural thing for the authors, be it artistic preferences, political views or religious beliefs. The use of the menorah has its roots somewhere between these areas, and the authors are proud to display it. If you are unlucky enough to have lost the freedom to express your opinion, due to the constraints of a government, society, religion, or expectations of professional relationships, the Free World condoles with you. The authors of &clisp; are not operating under such constraints. If you are unhappy about their artistic preferences, political views or religious beliefs, you are free to ignore them.

Many scientists have been doing art, politics and religion. René Descartes and Isaak Newton combined mathematics and Christianity. Albert Einstein helped the U.S. to counter the danger of an atomic bomb in the hands of the Nazis. Bram Moolenaar, the author of VIM, promotes charitable donations to Uganda.

## Running &clisp;

Where is &defun;?

Pass &opt-M; to the runtime (&lisp-run; or `lisp.exe`). Or, better yet, use the driver `clisp` (or `clisp.exe`) instead of invoking the runtime directly.

Where is the IDEIntegrated Development Environment?

## &emacs;-based

- `inferior-lisp`

- &slime;

- &ilisp;

- The Common Lisp Cookbook

## non-&emacs;-based

- VisualCLisp

- Jabberwocky

- GClisp

- &phemlock;

What are the command line arguments?

See .

How do I get out of the debugger?

See .

What &clisp; extensions are available?

Distributed with &clisp;

  Quite a few modules are included with &clisp;, pass `--with-module=...` to `configure` to build them and use the &full; &linkset;.

3rd party

  See the incomplete list of Common Lisp software running in &clisp;.

DIYDo It Yourself

  See and for information on how to interface with external &c-lang; libraries.

&http; (very Frequently Asked!)

  - &clisp; comes with `src/inspect.lisp` which implements a rudimentary &http; server

  - CLOCC/src/donc/ has an &http; server

  - CLOCC/src/cllib/ handles URLs

  - mod_lisp hooks lisp into &apache;

  - Object-Oriented HTTP server for &clisp;

  Both AllegroServe and CL-HTTP require multithreading and do not work with &clisp; yet.

Where is the init (RC) file on my platform?

Read the file `<clisp.html#opt-norc>` in your build directory or binary distribution (this is the version of the user manual for your platform).

Where are the modules with which I built &clisp;?

In the &full; &linkset;. Run &clisp; like this:

    &sh-prompt; clisp &opt-K; full

If your &clisp; was configured with option &with-dynmod;, you can instead use `(&require-my; &name-r;)` where &name-r; is a &string-t;, e.g., &rawsock-mod;.

Making &base; the default &linkset; has some advantages:

Shared Library Hell

  Avoid problems when a module requires a shared library, and that shared library is not present (or is present but with wrong version) on your system.

Smaller Images Are Faster

  Adding things to the heap increases working set size causing a slowdown, which is especially important for small to medium applications.

Uniform User Experience

  Composition of the &full; &linkset; is up to the packager, while &base; is the same on all platforms.

See clisp-list for more information (/).

How do I create a GUIGraphical User Interface for my &clisp; program?

Use module &gtk2-mod;: create `ui.glade` with &glade;, then do

    &sh-prompt; ./configure --with-module=gtk2 --build build-gtk
    &sh-prompt; ./build-gtk/clisp -K full -x '(gtk:run-glade-file "ui.glade")'

There are many other options, see "Common Lisp software running in &clisp;".

## Application Delivery

How do I create an executable file with all my code in it?

Use &savemem;, see also .

When I deliver my application with &clisp; does it have to be covered by &gnu; &gpl;?

Not necessarily.

&clisp; is Free Software, covered by the &gnu; &gpl;, with special terms governing the distribution of applications that run in &clisp;. The precise terms can be found in the `COPYRIGHT` file contained in the source and binary distributions of &clisp;. Here is an informal clarification of what these terms mean in practice. Please refer to the said `COPYRIGHT` file when in doubt.

In many cases, &clisp; does not force an application to be covered by the &gnu; &gpl;. Nevertheless, we encourage you to release your software under an open source license. The benefits of such a license for your users are numerous, in particular they are free to modify the application when their needs/requirements change, and they are free to recompile the application when they upgrade their machine or operating system.

&clisp; extensions, i.e. programs which need to access non-portable &clisp; internal symbols (in the packages &sys-pac;, &clos-pac;, &ffi-pac;, etc), must be covered by &gnu; &gpl; as well.

Other programs running in &clisp; have to or need not to be placed under &gnu; &gpl;, depending on their distribution form:

- Programs distributed as Lisp source or &fasl-file; files can be distributed without restrictions coming from &clisp;.

- Programs distributed as &clisp; &mem-image;s can be distributed only if accompanied with the non-&clisp; &fasl-file; files which make up the &mem-image;, and a &make-file; (or clear textual instructions) for rebuilding the &mem-image;.

- If you need to distribute a modified &clisp; executable (for example, incorporating additional &module;s written in &c-lang;), you must distribute its full source under &gnu; &gpl;. If you are not satisfied with this, you can instead put the additional &module;s into a separate (non-&clisp;) program, with which your Lisp program will communicate via &socket-stream;s.

## Troubles

Where is the binary distribution for my platform?

The &clisp; maintainers do not offer &clisp; binary distributions, we believe that software packagers specializing on a particular platform are in a better position to provide quality binaries. Indeed, the section Get CLISP on the &clisp;'s home page points to &clisp; packages for all major &linux; and &bsd; variants.

The only exception is &win32; for which there is no centralized packager: usually, after each &clisp; release, a &clisp; user volunteers to build a &win32; binary package, which we then distribute at .

But a previous release had a binary distribution for my platform, why does not the current one?

It was probably contributed by a user who did not (yet?) contribute a binary distribution for the current release. You can find out who contributed a specific binary distribution by looking at the release notes in the &sf; Files section.

Why does not &clisp; build on my platform?

Please see file `unix/PLATFORMS` in your source distribution for information about some known troublesome platforms as well as instructions on porting &clisp; to new platforms.

## What do charset errors mean?

What do these messages mean: `invalid byte #x94 in CHARSET:ASCII conversion` and `character #\u00B3 cannot be represented in the character set CHARSET:ASCII`?

This means that you are trying to read (invalid byte) or write (character cannot be represented) a non-&ascii; character from (or to) a character stream which has &ascii; &extfmt;. The default is described in .

This may also be caused by filesystem access. If your &path-enc; is set incorrectly, many filesystem accesses (like &load;, &directory; etc) will raise this error. Note that &load; will traverse the directories mentioned in &load-paths; - this applies to the init (RC) file too. You will need to set &path-enc; or pass &opt-E; to &clisp;. Using a 1:1 encoding, such as `ISO-8859-1`, should help you avoid this error.

Note that this error may be signaled by the Print part of the &repl; and &not-e; by the function you call. E.g., if file `"foo"` contains non-&ascii; characters, you will see such an error when you type

    (with-open-file (s "foo" :direction :input :external-format charset:iso-8859-1)
      (read-line s))

If instead you type

    (with-open-file (s "foo" :direction :input :external-format charset:iso-8859-1)
      (setq l (read-line s))
      nil)

&clisp; will just print &nil; and signal the error when you type `l`.

What does this message mean: `Display all 1259 possibilities? (y or n)`

&clisp; uses &readline; for command line editing and completion. You get this Display all 1259 possibilities message (and sometimes many screens of symbols) when you hit &tab-c; too many times in an inappropriate place. You can turn this feature off if you are using &emacs;. It is a good idea not to use &tab-c;s in your code.

Why does not command line editing work?

See .

How do I avoid stack overflow?

&clisp; has two stacks, the program stack and the lisp stack, and both may occasionally overflow.

## Avoiding stack overflow: Generic

- You will always get a stack overflow when you try to print a circular object (list or structure) and &print-circle-var; is &nil;. Just set &print-circle-var; to &t;.

- You will always get a stack overflow on infinite recursion.

- Some simple functions (like Ackermann's) recurse more than you might expect and can run out of stack on relatively small inputs.

- Compiled code uses less stack (and memory) and is faster.

- If you really do need more Lisp stack, you can increase it by telling &clisp; to pre-allocate more memory.

- If you get a segmentation fault after (or instead of) a program stack overflow message, please make sure that you had &libsigsegv; installed when you configured and built &clisp;.

## Avoiding stack overflow: Platform-specific

&win32-only;

  You have several option, use whichever is applicable to your situation:

  - modify the global `SYSTEM.INI`

  - modify the `PIF` that you use to invoke &clisp; (/)

  - or set the program stack (of the run times `base/lisp.exe` or `full/lisp.exe`, &not-e; the driver `clisp.exe`) using `editbin` (/); you can find the current stack size using `dumpbin`.

&unix-only;

  Increase program stack with `ulimit -s` (or `limit stacksize` if you are using `csh`) to at least 8 MB.

Why does my program return different values on each invocation?

The following code modifies itself:

    (let ((var '(a b c)))
      (nconc var '(1 2 3)))

and will not work as one would naively expect. (on the first invocation, it will return (a b c 1 2 3), the second invocation will produce a circular list, the third will hang trying to &nconc; a circular list).

Instead you must do

    (let ((var (copy-list '(a b c))))
      (nconc var (copy-list '(1 2 3))))

&disassemble; will show the constants in your compiled functions. See for the explanation of the &disassemble; output.

See Lisp Programming Style for more useful information.

Why is autoconf invoked during build?

When building from the &cvs; HEAD development sources, you will sometimes get errors when `make` tries to regenerate some `configure` scripts for you. This is never necessary! (and will not happen in an officially released source distribution). Please just `touch` the target, e.g.:

    &sh-prompt; touch src/configure

and re-run `make`.

You can also pass `--disable-maintainer-mode` to the top-level `configure` script (this is the default when you are &not-e; working from the &cvs;).

## Is floating point arithmetics broken?

Why don't floating point arithmetics return what I want?

    (- 1.1 0.9)
    0.20000005

This not a bug, at least not a bug in &clisp;. You may argue that this is a bug in &ieee-bfp;, but first make sure that you do know What Every Computer Scientist Should Know About Floating-Point Arithmetic.

See also clisp-list (/).

## PS

If you want exact calculations, use &rational-t;s:

    (- 11/10 9/10)
    1/5

## Is &random; broken?

Why does

    &sh-prompt; clisp &opt-x; '(&random; 1s0)'

always print the same number?

Reproducibility is important. See .

Why is an extra line break inserted by the pretty printer?

See .

For example, here you are pretty-printing two objects: a one-liner #\Q and a two-liner `CRLF`, and a line break is inserted between them so that they are printed on separate lines:

    (defparameter crlf (coerce '(#\Return #\Linefeed) 'string))
    CRLF
    (map 'list #'char-code (format nil "Q~a" crlf))
    (81 10 13 10)not (81 13 10) !

When you want &cr-c;+&lf-c;-terminated lines, use &extfmt; &dos-k; argument when opening your &stream-t;s.

How do I disable this annoying warning?

&clisp; often issues &warning-t;s when it encounters suspicious behavior. It is best to fix your code rather than to suppress them. To figure out where the warning is coming from, do

     (&setq; &break-on-signals-var; '&warning-t;)

and examine the stack (see ) to see where the warning is coming from.

If everything else fails, read the manual.

Why does &defvar; affect previously defined lexical closures?

    (defun adder (val) (lambda (x) (+ x val)))
    ADDER
    (setq add-10 (adder 10))
    ADD-10
    (funcall add-10 32)
    42as expected
    (defvar val 12)
    VAL
    (funcall add-10 0)
    12why not 10?!

Explanation

The above code does not conform to &ansi-cl;, therefore &clisp; can produce arbitrary results. See .

Remedy

Always follow the naming convention for global special variables defined by &defvar; and &defparameter; (e.g., `*FOO*`) and &defconstant; (e.g., `+BAR+`).

More

- /
- /

The error message is not helpful!

Sometimes an error message contains a compound object whose content you want to examine. Often this object will be available for &inspect-my;ion via the `Inspect` command (see ). E.g.,

    *** - READ: input stream #<INPUT STRING-INPUT-STREAM> ends within an object
    The following restarts are available:
    ABORT          :R1      ABORT
    Break 4 [1]> :i
    #<SYSTEM::SIMPLE-END-OF-FILE #x000333CB82F8>:  standard object
     type: SYSTEM::SIMPLE-END-OF-FILE
    0 [$STREAM]:  #<INPUT STRING-INPUT-STREAM>
    1 [$FORMAT-CONTROL]:
    "~S: input stream ~S ends within an object
    "
    2 [$FORMAT-ARGUMENTS]:  (READ #<INPUT STRING-INPUT-STREAM>)
    INSPECT-- type :h for help; :q to return to the REPL ---> 0
    #<INPUT STRING-INPUT-STREAM>:  atom
     type: STRING-STREAM
     class: #1=#<BUILT-IN-CLASS STRING-STREAM>
    INSPECT-- type :h for help; :q to return to the REPL ---> :d

    #<INPUT STRING-INPUT-STREAM> is an input-stream. It reads from "(foo" from 0 to 4 at 4.

Why is the function `FOO` broken?!

When confronted with unexpected behavior, try looking in the .

E.g., &clisp; &directory; is different from the &cmucl; implementation, so, to find out how to get the results you want, you should search the &clisp; implementation notes for "DIRECTORY".

Alternatively, since the implementation notes are organized in parallel to the &ansi-cl;, and &directory; belongs to the Chapter 20 in &ansi-cl;, you can just go to in impnotes and look for "DIRECTORY" there.