source: project/wiki/man/4/faq @ 33354

Last change on this file since 33354 was 33354, checked in by sjamaan, 5 years ago

Synch wiki manual with 4.11.0 release manual (some small updates, plus a new Debugging chapter)

File size: 29.1 KB
Line 
1[[toc:]]
2[[tags:faq manual]]
3
4== FAQ
5
6This is the list of Frequently Asked Questions about CHICKEN Scheme.
7If you have a question not answered here, feel free to post to the chicken-users mailing list;
8if you consider your question general enough, feel free to add it to this list.
9
10=== General
11
12==== Why yet another Scheme implementation?
13
14Since Scheme is a relatively simple language, a large number of implementations exist and
15each has its specific advantages and disadvantages. Some are fast, some provide a rich
16programming environment. Some are free, others are tailored to specific domains, and so on. The reasons
17for the existence of CHICKEN are:
18
19* CHICKEN is portable because it generates C code that runs on a large number of platforms.
20
21* CHICKEN is extensible, since its code generation scheme and runtime system/garbage collector fits neatly into a C environment.
22
23* CHICKEN is free and can be freely distributed, including its source code.
24
25* CHICKEN offers better performance than nearly all interpreter based implementations, but still provides full Scheme semantics.
26
27* As far as we know, CHICKEN is the first implementation of Scheme that uses Henry Baker's [[http://home.pipeline.com/~hbaker1/CheneyMTA.html|Cheney on the M.T.A]] concept.
28
29==== What should I do if I find a bug?
30
31Fill a ticket at [[http://bugs.call-cc.org|bugs.call-cc.org]] with
32some hints about the problem, like version/build of the compiler,
33platform, system configuration, code that causes the bug, etc.
34
35
36=== Specific
37
38==== Why are values defined with {{define-foreign-variable}} or {{define-constant}} or {{define-inline}} not seen outside of the containing source file?
39
40Accesses to foreign variables are translated directly into C constructs that access the variable,
41so the Scheme name given to that variable does only exist during compile-time.
42The same goes for constant- and inline-definitions: The name is only there to tell the compiler
43that this reference is to be replaced with the actual value.
44
45==== How does {{cond-expand}} know which features are registered in used units?
46
47Each unit used via {{(declare (uses ...))}} is registered as a feature and
48so a symbol with the unit-name can be tested by {{cond-expand}} during macro-expansion-time.
49Features registered using the {{register-feature!}} procedure are only
50available during run-time of the compiled file. You can use the {{eval-when}} form
51to register features at compile time.
52
53==== Why are constants defined by {{define-constant}} not honoured in {{case}} constructs?
54
55{{case}} expands into a cascaded {{if}} expression, where the first item in each arm
56is treated as a quoted list. So the {{case}} macro can not infer whether
57a symbol is to be treated as a constant-name (defined via {{define-constant}}) or
58a literal symbol.
59
60
61==== How can I enable case sensitive reading/writing in user code?
62
63To enable the {{read}} procedure to read symbols and identifiers case sensitive, you can set the
64parameter {{case-sensitivity}} to {{#t}}.
65
66
67==== Why doesn't CHICKEN support the full numeric tower by default?
68
69The short answer is to use the [[/egg/numbers|numbers]] egg:
70
71<enscript highlight=scheme>
72% chicken-install numbers
73% csi -q
74#;1> (use numbers)
75</enscript>
76
77The long answer:
78
79There are a number of reasons for this:
80
81- For most applications of Scheme fixnums (exact word-sized integers) and flonums (64-bit floating-point
82numbers) are more than sufficient;
83
84- Interfacing to C is simpler;
85
86- Dispatching of arithmetic operations is more efficient.
87
88
89==== Does CHICKEN support native threads?
90
91Native threads are not supported for two reasons. One, the runtime
92system is not reentrant.  Two, concurrency implemented properly would
93require mandatory locking of every object that could be potentially
94shared between two threads. The garbage-collection algorithm would
95then become much more complex and inefficient, since the location of
96every object has to be accessed via a thread synchronization
97protocol. Such a design would make native threads in CHICKEN
98essentially equivalent to Unix processes and shared memory.
99
100For a different approach to concurrency, please see the
101[[/egg/mpi|mpi]] or
102[[/egg/concurrent-native-callbacks|concurrent-native-callbacks]] egg.
103
104[[http://www.stylewarning.com/blog/about|Robert Smith]] has put
105[[http://www.stylewarning.com/blog/bounties|a bounty]] on a
106release-quality implementation of native threads.
107
108==== Does CHICKEN support Unicode strings?
109
110The system does not directly support Unicode, but there is an extension for UTF-8 strings: [[/egg/utf8|utf8]].
111
112=== Why are `dynamic-wind' thunks not executed when a SRFI-18 thread signals an error?
113
114Here is what Marc Feeley, the author of [[http://srfi.schemers.org/srfi-18|SRFI-18]] has to
115say about this subject:
116
117    >No the default exception handler shouldn't invoke the after
118    > thunks of the current continuation.  That's because the
119    > exception handler doesn't "continue" at the initial
120    > continuation of that thread.  Here are the relevant words of
121    > SRFI 18:
122   
123    >
124    >  Moreover, in this dynamic environment the exception handler
125    >  is bound to the "initial exception handler" which is a unary
126    >  procedure which causes the (then) current thread to store in
127    >  its end-exception field an "uncaught exception" object whose
128    >  "reason" is the argument of the handler, abandon all mutexes
129    >  it owns, and finally terminate.
130    >
131   
132    >The rationale is that, when an uncaught exception occurs in a
133    >thread the thread is in bad shape and things have gone
134    >sufficiently wrong that there is no universally acceptable way to
135    >continue execution.  Executing after thunks could require a
136    >whole lot of processing that the thread is not in a shape to do.
137    >So the safe thing is to terminate the thread.  If the programmer
138    >knows how to recover from an exception, then he can capture the
139    >continuation early on, and install an exception handler which
140    >invokes the continuation.  When the continuation is invoked the
141    >after thunks will execute.
142
143
144=== Platform specific
145
146==== How do I generate a DLL under MS Windows (tm) ?
147
148Use {{csc}} in combination with the {{-dll}} option:
149
150{{C:\> csc foo.scm -dll}}
151
152==== How do I generate a GUI application under Windows(tm)?
153
154Invoke {{csc}} with the {{-gui}} option.  In GUI-mode, the runtime
155system displays error messages in a message box and does some
156rudimentary command-line parsing.
157
158==== Compiling very large files under Windows with the Microsoft C compiler fails with a message indicating insufficient heap space.
159
160It seems that the Microsoft C compiler can only handle files up to a certain size, and it doesn't utilize virtual memory as
161well as the GNU C compiler, for example. Try closing running applications. If that fails, try to break up the Scheme code
162into several library units.
163
164==== When I run {{csi}} inside an emacs buffer under Windows, nothing happens.
165
166Invoke {{csi}} with the {{-:c}} runtime option. Under Windows the interpreter thinks it
167is not running under control of a terminal and doesn't print the prompt and does not flush the output stream properly.
168
169==== On Windows, {{csc.exe}} seems to be doing something wrong.
170
171The Windows development tools include a C# compiler with the same name. Either invoke {{csc.exe}} with a full
172pathname, or put the directory where you installed CHICKEN in front of the MS development tool path in the {{PATH}}
173environment variable.
174
175==== On Windows source and/or output filenames with embedded whitespace are not found.
176
177There is no current workaround. Do not use filenames with embedded whitespace for code. However, command
178names with embedded whitespace will work correctly.
179=== Customization
180
181
182==== How do I run custom startup code before the runtime-system is invoked?
183
184When you invoke the C compiler for your translated Scheme source program, add the C compiler option
185{{-DC_EMBEDDED}}, or pass {{-embedded}} to the {{csc}}
186driver program, so no entry-point function will be generated ({{main()}}).
187When your are finished with your startup processing, invoke:
188
189<enscript highlight=c>
190CHICKEN_main(argc, argv, C_toplevel);
191</enscript>
192
193where {{C_toplevel}} is the entry-point into the compiled Scheme code. You
194should add the following  declarations at the head of your code:
195
196<enscript highlight=c>
197#include "chicken.h"
198extern void C_toplevel(C_word,C_word,C_word) C_noret;
199</enscript>
200
201==== How can I add compiled user passes?
202
203To add a compiled user pass instead of an interpreted one, create a library unit and recompile
204the main unit of the compiler (in the file {{chicken.scm}}) with an additional {{uses}}
205declaration. Then link all compiler modules and your (compiled) extension to create a new version of
206the compiler, like this (assuming all sources are in the
207current directory):
208
209<enscript highlight=scheme>
210  % cat userpass.scm
211  ;;;; userpass.scm - My very own compiler pass
212
213  (declare (unit userpass))
214
215  ;; Perhaps more user passes/extensions are added:
216  (let ([old (user-pass)])
217    (user-pass
218      (lambda (x)
219        (let ([x2 (do-something-with x)])
220           (if old
221               (old x2)
222               x2) ) ) ) )
223</enscript>
224
225 % csc -c -x userpass.scm
226 % csc chicken.scm -c -o chicken-extended.o -uses userpass
227 % gcc chicken-extended.o support.o easyffi.o compiler.o optimizer.o batch-driver.o c-platform.o \
228 c-backend.o userpass.o `csc -ldflags -libs` -o chicken-extended
229
230On platforms that support it (Linux ELF, Solaris, Windows + VC++), compiled code can be loaded via {{-extend}}
231just like source files (see {{load}} in the User's Manual).
232
233
234=== Macros
235
236==== Where is {{define-macro}}?
237
238With CHICKEN 4, the macro-expansion subsystem is now hygienic where old Lisp-style low-level macros
239are not available anymore. {{define-syntax}} can define hygienic macros using {{syntax-rules}}
240or low-level macros with user-controlled hygienic with ''explicit renaming'' macros. Translating
241old-style macros into ER-macros isn't that hard, see [[Macros]] for more information.
242
243==== Why are low-level macros defined with {{define-syntax}} complaining about unbound variables?
244
245Macro bodies that are defined and used in a compiled source-file are
246evaluated during compilation and so have no access to anything created with {{define}}. Use {{define-for-syntax}} instead.
247
248==== Why isn't {{load}} properly loading my library of macros?
249
250During compile-time, macros are only available in the source file in which they are defined. Files included via {{include}} are considered part of the containing file.
251
252=== Warnings and errors
253
254==== Why does my program crash when I use callback functions (from Scheme to C and back to Scheme again)?
255
256There are two reasons why code involving callbacks can crash out of no apparent reason:
257
258# It is important to use {{foreign-safe-lambda/foreign-safe-lambda*}} for the C code that is to call back into Scheme. If this is not done than sooner or later the available stack space will be exhausted.
259
260# If the C code uses a large amount of stack storage, or if Scheme-to-C-to-Scheme calls are nested deeply, then the available nursery space on the stack will run low. To avoid this it might be advisable to run the compiled code with a larger nursery setting, i.e. run the code with {{-:s...}} and a larger value than the default (for example {{-:s300k}}), or use the {{-nursery}} compiler option.  Note that this can decrease runtime performance on some platforms.
261
262==== Why does the linker complain about a missing function {{_C_..._toplevel}}?
263
264This message indicates that your program uses a library-unit, but that the
265object-file or library was not supplied to the linker. If you have the unit
266{{foo}}, which is contained in {{foo.o}} than you have to supply it to the
267linker like this (assuming a GCC environment):
268
269{{% csc program.scm foo.o -o program}}
270
271==== Why does the linker complain about a missing function {{_C_toplevel}}?
272
273This means you have compiled a library unit as an application. When a unit-declaration (as in {{(declare (unit ...))}})
274is given, then this file has a specially named toplevel entry procedure. Just remove the declaration,
275or compile this file to an object-module and link it to your application code.
276
277==== Why does my program crash when I compile a file with {{-unsafe}} or unsafe declarations?
278
279The compiler option {{-unsafe}} or the declaration {{(declare (unsafe))}} disable
280certain safety-checks to improve performance, so code that would normally
281trigger an error will work unexpectedly or even crash the running application.
282It is advisable to develop and debug a program in safe mode (without unsafe
283declarations) and use this feature only if the application works properly.
284
285==== Why don't toplevel-continuations captured in interpreted code work?
286
287Consider the following piece of code:
288
289<enscript highlight=scheme> 
290(define k (call-with-current-continuation (lambda (k) k)))
291(k k)
292</enscript>
293
294When compiled, this will loop endlessly. But when interpreted, {{(k k)}} will return
295to the read-eval-print loop! This happens because the continuation captured will eventually read the
296next toplevel expression from the standard-input (or an input-file if loading from a file). At the moment
297{{k}} was defined, the next expression was {{(k k)}}. But when {{k}}
298is invoked, the next expression will be whatever follows after {{(k k)}}.
299In other words, invoking a captured continuation will not rewind the file-position of the input source.
300A solution is to wrap the whole code into a {{(begin ...)}} expression, so all toplevel
301expressions will be loaded together.
302
303==== Why does {{define-reader-ctor}} not work in my compiled program?
304
305The following piece of code does not work as expected:
306
307<enscript highlight=scheme>
308 (eval-when (compile)
309 (define-reader-ctor 'integer->char integer->char) )
310 (print #,(integer->char 33))
311</enscript>
312
313The problem is that the compiler reads the complete source-file before doing any processing on it,
314so the sharp-comma form is encountered before the reader-ctor is defined. A possible solution is to include
315the file containing the sharp-comma form, like this:
316
317<enscript highlight=scheme>
318 (eval-when (compile)
319 (define-reader-ctor 'integer->char integer->char) )
320 
321 (include "other-file")
322</enscript>
323
324<enscript highlight=scheme>
325 ;;; other-file.scm:
326 (print #,(integer->char 33))
327</enscript>
328
329==== Why do built-in units, such as srfi-1, srfi-18, and posix fail to load?
330
331When you try to {{use}} a built-in unit such as {{srfi-18}}, you may get the following error:
332
333<enscript highlight=scheme>
334 #;1> (use srfi-18)
335 ; loading library srfi-18 ...
336 Error: (load-library) unable to load library
337 srfi-18
338 "dlopen(libchicken.dylib, 9): image not found"                ;; on a Mac
339 "libchicken.so: cannot open shared object file: No such file or directory"  ;; Linux
340</enscript>
341
342Another symptom is that {{(require 'srfi-18)}} will silently fail.
343
344This typically happens because the CHICKEN libraries have been installed in a non-standard location, such as your home directory.  The workaround is to explicitly tell the dynamic linker where to look for your libraries:
345
346 export DYLD_LIBRARY_PATH=~/scheme/chicken/lib:$DYLD_LIBRARY_PATH ;; Mac
347 export LD_LIBRARY_PATH=~/scheme/chicken/lib:$LD_LIBRARY_PATH    ;; Linux
348
349==== How can I increase the size of the trace shown when runtime errors are detected?
350
351When a runtime error is detected, CHICKEN will print the last entries from the trace of functions called
352(unless your executable was compiled with the {{-no-trace}} option.
353By default, only 16 entries will be shown.
354To increase this number pass the {{-:aN}} parameter to your executable.
355
356
357=== Optimizations
358
359==== How can I obtain smaller executables?
360
361If you don't need {{eval}} or the stuff in the {{extras}} library unit,
362you can just use the {{library}} unit:
363
364<enscript highlight=scheme>
365        (declare (uses library))
366        (display "Hello, world!\n")
367</enscript>
368
369(Don't forget to compile with the {{-explicit-use}} option)
370Compiled with Visual C++ this generates an executable of around 240 kilobytes.
371It is theoretically possible to compile something without the library, but
372a program would have to implement quite a lot of support code on its own.
373
374==== How can I obtain faster executables?
375
376There are a number of declaration specifiers that should be used to speed up
377compiled files: declaring {{(standard-bindings)}} is mandatory, since this enables
378most optimizations. Even if some standard procedures should be redefined, you can
379list untouched bindings in the declaration.
380Declaring {{(extended-bindings)}} lets the compiler choose faster versions of certain
381internal library functions. This might give another speedup. You can also use the
382the {{usual-integrations}} declaration, which is identical to declaring
383{{standard-bindings}} and {{extended-bindings}}
384(note that {{usual-integrations}} is set by default).
385Declaring {{(block)}} tells the compiler that global procedures are not changed
386outside the current compilation unit, this gives the compiler some more
387opportunities for optimization.
388If no floating point arithmetic is required, then declaring {{(number-type fixnum)}}
389can give a big performance improvement, because the compiler can now inline
390most arithmetic operations.
391Declaring {{(unsafe)}} will switch off most safety checks.
392If threads are not used, you can declare {{(disable-interrupts)}}.
393You should always use maximum optimizations settings for your C compiler.
394Good GCC compiler options on Pentium (and compatible) hardware are:
395{{-Os -fomit-frame-pointer -fno-strict-aliasing}}
396Some programs are very sensitive to the setting of the nursery (the first heap-generation). You
397should experiment with different nursery settings (either by compiling with the {{-nursery}}
398option or by using the {{-:s...}} runtime option).
399
400==== Which non-standard procedures are treated specially when the {{extended-bindings}} or {{usual-integrations}} declaration or compiler option is used?
401
402The following standard bindings are handled specially, depending on optimization options
403and compiler settings:
404
405{{*}}
406{{+}}
407{{-}}
408{{/}}
409{{<=}}
410{{<}}
411{{=}}
412{{>=}}
413{{>}}
414{{abs}}
415{{acos}}
416{{apply}}
417{{asin}}
418{{assoc}}
419{{assv}}
420{{atan}}
421{{boolean?}}
422{{c...r}}
423{{call-with-current-continuation}}
424{{call-with-values}}
425{{ceiling}}
426{{char->integer}}
427{{char-alphabetic?}}
428{{char-downcase}}
429{{char-lower-case?}}
430{{char-numeric?}}
431{{char-upcae}}
432{{char-upper-case?}}
433{{char-whitespace?}}
434{{char<=?}}
435{{char<?}}
436{{char=?}}
437{{char>=?}}
438{{char>?}}
439{{char?}}
440{{complex?}}
441{{cons}}
442{{cos}}
443{{current-input-port}}
444{{current-output-port}}
445{{eof-object?}}
446{{eq?}}
447{{equal?}}
448{{eqv?}}
449{{even?}}
450{{exact->inexact}}
451{{exact?}}
452{{exp}}
453{{floor}}
454{{for-each}}
455{{for-each}}
456{{gcd}}
457{{inexact->exact}}
458{{inexact?}}
459{{integer->char}}
460{{lcm}}
461{{length}}
462{{list-ref}}
463{{list-tail}}
464{{list?}}
465{{list}}
466{{log}}
467{{make-vector}}
468{{map}}
469{{member}}
470{{memq}}
471{{memv}}
472{{negative?}}
473{{not}}
474{{null?}}
475{{number->string}}
476{{number?}}
477{{odd?}}
478{{pair?}}
479{{positive?}}
480{{procedure?}}
481{{quotient}}
482{{rational?}}
483{{read-string}}
484{{real?}}
485{{remainder}}
486{{round}}
487{{set-car!}}
488{{set-cdr!}}
489{{sin}}
490{{sqrt}}
491{{string->number}}
492{{string-append}}
493{{string-ci=?}}
494{{string-length}}
495{{string-ref}}
496{{string-set!}}
497{{string=?}}
498{{string?}}
499{{string}}
500{{substring}}
501{{symbol?}}
502{{tan}}
503{{truncate}}
504{{values}}
505{{vector-length}}
506{{vector-ref}}
507{{vector-set!}}
508{{vector?}}
509{{vector}}
510{{write-char}}
511{{zero?}}
512
513The following extended bindings are handled specially:
514
515{{add1}}
516{{alist-cons}}
517{{any?}}
518{{arithmetic-shift}}
519{{atom?}}
520{{bit-set?}}
521{{bitwise-and}}
522{{bitwise-ior}}
523{{bitwise-not}}
524{{bitwise-xor}}
525{{blob-size}}
526{{block-ref}}
527{{block-set!}}
528{{call/cc}}
529{{current-error-port}}
530{{current-thread}}
531{{error}}
532{{f32vector->blob/shared}}
533{{f32vector-length}}
534{{f32vector-ref}}
535{{f64vector->blob/shared}}
536{{f64vector-length}}
537{{f64vector-ref}}
538{{finite?}}
539{{first}}
540{{fixnum?}}
541{{flonum?}}
542{{flush-output}}
543{{foldl}}
544{{foldr}}
545{{format}}
546{{fourth}}
547{{fp*}}
548{{fp+}}
549{{fp-}}
550{{fp/}}
551{{fp<=}}
552{{fp<}}
553{{fp=}}
554{{fp=}}
555{{fp>=}}
556{{fp>=}}
557{{fp>}}
558{{fp>}}
559{{fpabs}}
560{{fpacos}}
561{{fpasin}}
562{{fpatan2}}
563{{fpatan}}
564{{fpceiling}}
565{{fpcos}}
566{{fpexpt}}
567{{fpexp}}
568{{fpfloor}}
569{{fpinteger?}}
570{{fplog}}
571{{fpmax}}
572{{fpmin}}
573{{fpneg}}
574{{fprintf}}
575{{fpround}}
576{{fpsin}}
577{{fpsqrt}}
578{{fptan}}
579{{fptruncate}}
580{{fx*?}}
581{{fx*}}
582{{fx+?}}
583{{fx+}}
584{{fx-?}}
585{{fx-}}
586{{fx/?}}
587{{fx/}}
588{{fx=}}
589{{fx>=}}
590{{fx>}}
591{{fxand}}
592{{fxeven?}}
593{{fxior}}
594{{fxmax}}
595{{fxmin}}
596{{fxmod}}
597{{fxneg}}
598{{fxnot}}
599{{fxodd?}}
600{{fxshl}}
601{{fxshr}}
602{{fxxor}}
603{{hash-table-ref}}
604{{identity}}
605{{locative->object}}
606{{locative-ref}}
607{{locative-set!}}
608{{locative?}}
609{{make-record-instance}}
610{{not-pair?}}
611{{null-list?}}
612{{number-of-slots}}
613{{o}}
614{{pointer+}}
615{{pointer->object}}
616{{pointer-f32-ref}}
617{{pointer-f32-set!}}
618{{pointer-f64-ref}}
619{{pointer-f64-set!}}
620{{pointer-s16-ref}}
621{{pointer-s16-set!}}
622{{pointer-s32-ref}}
623{{pointer-s32-set!}}
624{{pointer-s8-ref}}
625{{pointer-s8-set!}}
626{{pointer-u16-ref}}
627{{pointer-u16-set!}}
628{{pointer-u32-ref}}
629{{pointer-u32-set!}}
630{{pointer-u8-ref}}
631{{pointer-u8-set!}}
632{{pointer=?}}
633{{print*}}
634{{printf}}
635{{print}}
636{{s16vector->blob/shared}}
637{{s16vector-length}}
638{{s16vector-ref}}
639{{s16vector-set!}}
640{{s32vector->blob/shared}}
641{{s32vector-length}}
642{{s32vector-ref}}
643{{s32vector-set!}}
644{{s8vector->blob/shared}}
645{{s8vector-length}}
646{{s8vector-ref}}
647{{s8vector-set!}}
648{{second}}
649{{signum}}
650{{sprintf}}
651{{sub1}}
652{{substring-ci=?}}
653{{substring-index-ci}}
654{{substring-index}}
655{{substring=?}}
656{{third}}
657{{thread-specific-set!}}
658{{thread-specific}}
659{{u16vector->blob/shared}}
660{{u16vector-length}}
661{{u16vector-ref}}
662{{u16vector-set!}}
663{{u32vector->blob/shared}}
664{{u32vector-length}}
665{{u32vector-ref}}
666{{u32vector-set!}}
667{{u8vector->blob/shared}}
668{{u8vector-length}}
669{{u8vector-ref}}
670{{u8vector-set!}}
671{{xcons}}
672
673==== What's the difference betweem "block" and "local" mode?
674
675In {{block}} mode, the compiler assumes that definitions in the current file
676are not visible from outside of the current compilation unit, so unused
677definitions can be removed and calls can be inlined. In {{local}} mode,
678definitions are not hidden, but the compiler assumes that they are
679not modified from other compilation units (or code evaluated at runtime),
680and thus allows inlining of them.
681
682==== Can I load compiled code at runtime?
683
684Yes. You can load compiled at code at runtime with {{load}} just as
685well as you can load Scheme source code.  Compiled code will, of
686course, run faster.
687
688To do this, pass to {{load}} a path for a shared object.  Use a form
689such as {{(load "foo.so")}} and run {{csc -shared foo.scm}} to produce
690{{foo.so}} from {{foo.scm}} (at which point {{foo.scm}} will no longer
691be required).
692
693If you have compiled code that contains a {{module}} definition, then
694executing the code will "register" the module to allow importing the
695bindings provided by the module into a running Scheme process.
696The information required to use a module is in this case embedded in
697the compiled code. Compiling another program that uses this (compiled)
698module is more difficult: the used module will not necessarily be loaded
699into the compiler, so the registration will not be executed. In this
700case the information about what bindings the compiled module exports
701must be separated from the actual code that executes at runtime.
702To make this possible, compiling a module can be done in such a
703manner that an "import library" is created. This is a file that
704contains the binding information of the module and we can use it
705to compile a file that refers to that module. An example can perhaps
706make this clearer:
707
708  ;; my-module.scm
709 
710  (module my-module (...) ...)
711
712  ;; use-my-module.scm
713
714  (import my-module)
715  ...
716
717Compile the module and generate an import library for the "my-module" module:
718
719  % csc -s my-module.scm -emit-import-library my-module
720
721Compile the program that uses the module:
722
723  % csc use-my-module.scm
724
725==== Why is my program which uses regular expressions so slow?
726
727The regular expression engine has recently been replaced by [[http://wiki.call-cc.org/users/alex shinn|alex shinn]]'s excellent
728{{irregex}} library, which is fully implemented in Scheme. Precompiling regular
729expressions to internal forms is somewhat slower than with the old PCRE-based
730regex engine. It is advisable to use {{irregex}} to precompile regular expressions
731outside of time-critical loops and use them where performance matters.
732
733
734=== Garbage collection
735
736==== Why does a loop that doesn't {{cons}} still trigger garbage collections?
737
738Under CHICKEN's implementation policy, tail recursion is achieved simply by avoiding
739returns from function calls. Since the programs are CPS converted, a continuous
740sequence of nested procedure calls is performed. At some stage the stack-space has
741to run out and the current procedure and its parameters (including the current
742continuation) are stored somewhere in the runtime system. Now a minor garbage collection
743occurs and rescues all live
744data from the stack (the first heap generation) and moves it into the the second heap
745generation. Then the stack is cleared (using
746a {{longjmp}}) and execution can continue from the saved state.
747With this method arbitrary recursion (in tail- or non-tail position) can happen,
748provided the application doesn't run out of heap-space.
749(The difference between a tail- and a non-tail call is that the tail-call has no
750live data after it invokes its continuation - and so the amount of heap-space needed stays constant)
751
752==== Why do finalizers not seem to work in simple cases in the interpeter?
753
754Consider the following interaction in CSI:
755
756 #;1> (define x '(1 2 3))
757 #;2> (define (yammer x) (print x " is dead"))
758 #;3> (set-finalizer! x yammer)
759 (1 2 3)
760 #;4> (gc #t)
761 157812
762 #;5> (define x #f)
763 #;6> (gc #t)
764 157812
765 #;7>
766
767While you might expect objects to be reclaimed and "''(1 2 3) is dead''" printed, it won't happen:
768the literal list gets held in the interpreter history, because it is the
769result value of the set-finalizer! call.
770Running this in a normal program will work fine.
771
772When testing finalizers from the interpreter, you might want to define a trivial macro such as
773
774 (define-syntax v
775   (syntax-rules ()
776     ((_ x) (begin (print x) (void)))))
777
778and wrap calls to {{set-finalizer!}} in it.
779
780=== Interpreter
781
782==== Does CSI support history and autocompletion?
783
784CSI doesn't support it natively but it can be activated with one of the
785[[http://wiki.call-cc.org/egg/readline|readline]], [[http://wiki.call-cc.org/egg/linenoise|linenoise]] or
786[[http://wiki.call-cc.org/egg/parley|parley]] eggs. Out of these three, the parley egg is
787recommended. After installing parley, add the following to your
788{{~/.csirc}} or equivalent file:
789
790<enscript highlight=scheme>
791(use parley)
792(let ((old (current-input-port)))
793  (current-input-port (make-parley-port old)))
794</enscript>
795
796Users of *nix-like systems (including Cygwin), may also want to check out [[http://utopia.knoware.nl/~hlub/rlwrap/|rlwrap]].  This program lets you "wrap" another process (e.g. {{rlwrap csi}}) with the readline library, giving you history, autocompletion, and the ability to set the keystroke set. Vi fans can get vi keystrokes by adding "set editing-mode vi" to their {{.inputrc}} file.
797
798==== Does code loaded with {{load}} run compiled or interpreted?
799
800If you compile a file with a call to {{load}}, the code will be loaded at
801runtime and, if the file loaded is a Scheme source code file
802(instead of a shared object), it will be
803interpreted (even if the caller program is compiled).
804
805==== How do I use extended (non-standard) syntax in evaluated code at run-time?
806
807Normally, only standard Scheme syntax is available to the evaluator. To
808use the extensions provided in the CHICKEN compiler and interpreter,
809add:
810
811<enscript highlight=scheme>
812(require-library chicken-syntax)
813</enscript>
814
815=== Extensions
816
817==== Where is "chicken-setup" ?
818
819{{chicken-setup}} has been rewritten from scratch and its functionality is now
820contained in the three tools {{chicken-install}}, {{chicken-uninstall}} and {{chicken-status}}.
821See the [[Extensions]] chapter for more information.
822
823==== How can I install CHICKEN eggs to a non-default location?
824
825You can just set the {{CHICKEN_REPOSITORY}} environment variable.
826It should contain the path where you want eggs to be installed:
827
828 $ export CHICKEN_REPOSITORY=~/eggs/lib/chicken/5
829 $ chicken-install -init ~/eggs/lib/chicken/5
830 $ chicken-install -p ~/eggs/ extensionname
831
832In order to make programs (including csi) see these eggs, you should set this variable when you run them. See the [[Extensions#Changing repository location|Extensions/Changing repository location]] section of the manual for more information on that.
833
834Alternatively, you can call the {{repository-path}} Scheme procedure before loading the eggs, as in:
835
836<enscript highlight=scheme>
837(repository-path "/home/azul/eggs")
838(use format-modular)
839</enscript>
840
841Note, however, that using {{repository-path}} as above hard-codes the location of your eggs in your source files.  While this might not be an issue in your case, it might be safe to keep this configuration outside of the source code (that is, specifying it as an environment variable) to make it easier to maintain.
842
843The repository needs to be initialized before use. See the documentation for the {{-init}} option
844to {{chicken-install}}, in [[Extensions]].
845
846==== Can I install chicken eggs as a non-root user?
847
848Yes, just install them in a directory you can write to by using {{CHICKEN_REPOSITORY}} (see above).
849
850==== Why does downloading an extension via {{chicken-install}} fail on Windows Vista?
851
852Possibly the Windows Firewall is active, which prevents {{chicken-install}} from opening a TCP
853connection to the egg repository. Try disabling the firewall temporarily.
854
855---
856Previous: [[Bugs and limitations]]
857
858Next: [[Acknowledgements]]
Note: See TracBrowser for help on using the repository browser.